search | SignalWire

Perform a hybrid search combining vector similarity, keyword matching, filename search, and metadata search. Candidates from all strategies are merged, scored, filtered, and ranked.

The search pipeline works in three stages:

Candidate collection — run vector, filename, metadata, and keyword searches in parallel
Scoring — combine signals using max-signal-wins with agreement boosts
Ranking — apply diversity penalties, exact-match boosts, and tag filtering

Parameters

query_vector

list[float]Required

Embedding vector for the query, produced by encoding the query text with the same model used to build the index.

enhanced_text

strRequired

Preprocessed query text for keyword and full-text search. Typically the output of preprocess_query().

count

intDefaults to 3

Maximum number of results to return.

similarity_threshold

floatDefaults to 0.0

Minimum combined score for a result to be included. Results below this threshold are filtered out.

keyword_weight

Optional[float]

Manual weight for keyword vs. vector scoring. When not set, the engine uses its internal max-signal-wins scoring.

original_query

Optional[str]

The original unprocessed query string. Used for exact-match boosting.

Returns

list[dict] — A list of result dictionaries, each containing:

content (str) — the chunk text
score (float) — the final combined score
metadata (dict) — chunk metadata including filename, section, tags
search_type (str) — the primary search strategy that found the result

Example

1 from signalwire.search import SearchEngine, preprocess_query
2 
3 engine = SearchEngine(backend="sqlite", index_path="./docs.swsearch")
4 enhanced = preprocess_query("How do I configure an agent?", vector=True)
5 results = engine.search(
6     query_vector=enhanced["vector"],
7     enhanced_text=enhanced["enhanced_text"],
8     count=5,
9     original_query="How do I configure an agent?",
10 )
11 
12 for result in results:
13     print(f"[{result['score']:.3f}] {result['metadata']['filename']}")
14     print(f"  {result['content'][:120]}...")