NativeVectorSearchSkill

Search documents using vector similarity and keyword matching. Supports three modes:

In-memory (TF-IDF) — supply a documents array in config; the skill tokenizes and indexes at startup (TypeScript-specific fast path).
Local (SQLite) — point index_file at a .swsearch index, or set build_index: true and source_dir to index at startup.
Remote (network) — point remote_url at a search server and optionally name the index via index_name. Validated by the SSRF guard before each request; health check uses a 5-second timeout.

Class: NativeVectorSearchSkill

Tools: search_knowledge (default — tool_name override supported)

Env vars: None

Multi-instance: yes (distinguished by tool_name + index_file)

Core Parameters

tool_name

stringDefaults to search_knowledge

Custom tool name for this skill instance. Required when registering multiple instances on the same agent.

index_file

string

Path to a local .swsearch SQLite index file.

build_index

booleanDefaults to false

Whether to build the index from source files at startup.

source_dir

string

Directory containing documents to index. Required when build_index is true.

remote_url

string

URL of a remote search server (network mode). Validated by the SSRF guard — private, loopback, and cloud-metadata endpoints are rejected.

index_name

stringDefaults to default

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

documents

object[]

In-memory array of documents to index (TypeScript-specific). Each entry has id (string), text (string), optional metadata (object), and optional tags (string[]).

Search Parameters

count

integerDefaults to 5

Number of search results to return (range 1-20).

similarity_threshold

numberDefaults to 0.0

Minimum similarity score for results (0.0 — no limit, 1.0 — exact match).

keyword_weight

number

Manual keyword weight in the hybrid TF-IDF + keyword score (range 0.0-1.0). Overrides the automatic default of 0.3.

model_name

stringDefaults to mini

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

Content Parameters

global_tags

string[]Defaults to []

Tags applied to every document at index-build time.

file_types

string[]Defaults to ["md", "txt", "pdf", "docx", "html"]

File extensions to include when building an index from source_dir.

exclude_patterns

string[]

Glob patterns excluded from index builds. Defaults include **/node_modules/**, **/.git/**, **/dist/**, **/build/**.

max_content_length

integerDefaults to 32768

Maximum total response size in characters (distributed across all results).

Response Parameters

no_results_message

stringDefaults to No information found for '{query}'

Message returned when no results match. Supports a {query} placeholder that is substituted with the user’s query text.

response_prefix

string

Text prepended to the search response.

response_postfix

string

Text appended to the search response.

response_format_callback

function

Optional callback to transform the final response. Receives { response, agent, query, results, args, count, skill } and must return a string.

description

stringDefaults to Search the knowledge base for information

Description of the search tool presented to the AI.

hints

string[]Defaults to []

Additional speech recognition hints for the tool.

NLP Parameters

nlp_backend

stringDefaults to basic

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

query_nlp_backend

string

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

index_nlp_backend

string

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

Backend Parameters

backend

stringDefaults to sqlite

Storage backend for local database mode: "sqlite" or "pgvector". Ignored when remote_url is set. SQLite and pgvector backends require native Python-only dependencies; configurations written for the Python SDK remain valid but the TypeScript SDK only exercises the in-memory (documents) and remote (remote_url) paths.

connection_string

string

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

collection_name

string

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

Other Parameters

verbose

booleanDefaults to false

Enable verbose logging during indexing and search.

overwrite

booleanDefaults to false

Overwrite existing pgvector collection when building the index.

Example — in-memory documents

1 import { AgentBase, NativeVectorSearchSkill } from '@signalwire/sdk';
2 
3 const agent = new AgentBase({ name: 'kb-bot', route: '/kb' });
4 agent.setPromptText('Answer questions from the knowledge base.');
5 
6 await agent.addSkill(new NativeVectorSearchSkill({
7   tool_name: 'search_kb',
8   documents: [
9     { id: 'faq-1', text: 'Hours are 9am to 5pm Monday to Friday.', tags: ['hours'] },
10     { id: 'faq-2', text: 'Returns are accepted within 30 days.', tags: ['returns'] },
11   ],
12   count: 3,
13   similarity_threshold: 0.1,
14   keyword_weight: 0.5,
15 }));
16 
17 agent.run();

Example — remote server

1 await agent.addSkill(new NativeVectorSearchSkill({
2   remote_url: 'https://search.internal.example.com',
3   index_name: 'support-kb',
4   count: 3,
5   similarity_threshold: 0.4,
6   tags: ['public'],
7 }));