native_vector_search

Search document indexes using vector similarity and keyword search. Supports three modes: local SQLite (.swsearch files), local PostgreSQL via pgvector, and remote search servers. Indexes are built with the sw-search CLI tool.

Tools: search_knowledge (default, customizable via tool_name)

Requirements: Search extras installed (pip install "signalwire-sdk[search]")

Multi-instance: Yes

Core Parameters

index_file

str

Path to the .swsearch index file (SQLite backend only).

tool_name

strDefaults to search_knowledge

Custom function name for this skill instance. Required when using multiple instances.

build_index

boolDefaults to False

Whether to build the index from source files on startup.

source_dir

str

Directory containing documents to index. Required when build_index=True.

remote_url

str

URL of a remote search server for network mode (e.g., http://localhost:8001).

index_name

strDefaults to default

Name of the index on a remote server. Only used with remote_url.

Search Parameters

count

intDefaults to 5

Number of search results to return (1–20).

similarity_threshold

floatDefaults to 0.0

Minimum similarity score for results (0.0–1.0).

keyword_weight

float

Accepted for compatibility and currently ignored. Scoring is always max-signal-wins with an agreement boost, so the value has no effect on the results.

model_name

strDefaults to mini

Embedding model. Shortcuts: "mini" (fastest, 384 dims), "base" or "large" (768 dims). Full model names also accepted.

Content Parameters

global_tags

list[str]Defaults to []

Tags applied to all documents when building the index.

file_types

list[str]

File extensions to include when building the index.

exclude_patterns

list[str]

Glob patterns to exclude when building the index.

max_content_length

intDefaults to 32768

Maximum total response size in characters.

Response Parameters

no_results_message

str

Message returned when no results are found. Supports {query} placeholder.

response_prefix

str

Text prepended to the search response.

response_postfix

str

Text appended to the search response.

response_format_callback

callable

Optional callback to format the response. Must return a string.

description

strDefaults to Search the knowledge base for information

Description of the tool presented to the AI.

hints

list[str]Defaults to []

Additional speech recognition hints for the tool.

NLP Parameters

nlp_backend

strDefaults to basic

NLP backend for query processing: "basic", "spacy", or "nltk". Deprecated — use query_nlp_backend and index_nlp_backend instead.

query_nlp_backend

str

NLP backend for query expansion: "basic", "spacy", or "nltk".

index_nlp_backend

str

NLP backend for indexing: "basic", "spacy", or "nltk".

Backend Parameters

backend

strDefaults to sqlite

Storage backend: "sqlite" or "pgvector". Ignored when remote_url is set.

connection_string

str

PostgreSQL connection string. Required when backend="pgvector".

collection_name

str

PostgreSQL collection name. Required when backend="pgvector".

Other Parameters

verbose

boolDefaults to False

Enable verbose logging during indexing and search.

overwrite

boolDefaults to False

Overwrite existing pgvector collection when building the index.

from signalwire import AgentBase
class MyAgent(AgentBase):
    def __init__(self):
        super().__init__(name="assistant", route="/assistant")
        self.set_prompt_text("You are a helpful assistant.")
        self.add_skill("native_vector_search", {
            "index_file": "/path/to/knowledge.swsearch",
            "tool_name": "search_docs"
        })
agent = MyAgent()
agent.serve()