Skip to content

Asking and Searching

boudou edited this page Nov 5, 2026 · 17 revisions

Asking and Searching

Which tool

flowchart TD
    q{"What are you looking for?"} -->|"A question in plain language"| ask["strata_ask"]
    q -->|"An exact term, code or identifier"| search["strata_search"]
    q -->|"Only chunks with certain metadata"| search
Loading
strata_ask strata_search
Use it for Questions in plain language Exact terms and identifiers: pacs.008, AC04, an error code
Query rewriting Yes, when a provider is set up (see Query rewriting) No
Searches Several in parallel, one per rewritten query One
Reranking Cross-encoder (RERANKING_ENABLED, on by default) No
Default results 10 per query 5
Filters layers layers, metadata_filter

Both run the same hybrid search. It combines vector similarity, which finds passages with the same meaning, with PostgreSQL full-text search, which finds the exact words. The two rankings are merged with Reciprocal Rank Fusion. A passage found only by its words would rank below every passage found by meaning, so the best full-text matches keep HYBRID_KEYWORD_SLOTS places (1 by default, 0 turns it off): an exact term such as a reason code or a message name still comes back when the embedding misses it.

Results quote the document's own text. Each one carries its similarity, how close the question and the passage are in meaning (cosine, up to 1), next to the fused rank score.

When routing finds too little

When you give no layers, routing picks them. If the routed search returns fewer results than top_k, or only low-confidence ones, it runs again across all layers, and the response says so:

"routing_fallback": {"reason": "insufficient_results", "searched_layers": "all"}

The reason is insufficient_results or low_confidence. Layers you name yourself are never broadened.

flowchart LR
    q["Question, no layers"] --> r["Search the routed layers"]
    r --> c{"Fewer than top_k results,<br/>or confidence low?"}
    c -->|no| out["Results"]
    c -->|yes| all["Search all layers"] --> out2["Results +<br/>routing_fallback"]
Loading

strata_ask runs these steps:

flowchart TD
    q["Question"] --> r{"layers given?"}
    r -->|no| route["Route: layer patterns<br/>+ learned affinity"]
    r -->|yes| rw
    route --> rw["Rewrite: learned rewrite or synonyms,<br/>else the language model (optional)"]
    rw --> par["One search per rewritten query"]
    subgraph hs ["Hybrid search, per query"]
        cache{"In cache?"} -->|no| vec["Vector (HNSW)"] & fts["Full-text"]
        vec & fts --> rrf["Merge with RRF"]
    end
    par --> cache
    rrf --> dd["Deduplicate"]
    cache -->|yes| dd
    dd --> rr["Cross-encoder rerank<br/>(unless RERANKING_ENABLED=false)"]
    rr --> out["Chunks + sources + confidence"]
Loading

Parameters

strata_ask(question, layers=None, include_sources=True, top_k=10)

strata_search(query, layers=None, top_k=5, metadata_filter=None)

  • layers: a list of layer names. Leave it out to let routing choose.
  • top_k: 1 to 50. Keep it low; large results fill the client's context.
  • metadata_filter: exact matches on chunk metadata, such as page and total_pages, for example {"page": "3"}.

Query rewriting

strata_ask can turn a question into several searches in the layer's own terms. A language model does the rewriting, and only when a provider is set up; otherwise the question is searched as written. A rewrite proven by earlier use skips the model (see What the server learns).

Provider Settings What leaves this machine
anthropic (the default) ANTHROPIC_API_KEY; QUERY_REWRITE_MODEL is optional Questions and layer descriptions, to Anthropic
openai_compatible QUERY_REWRITE_PROVIDER=openai_compatible, QUERY_REWRITE_BASE_URL (ending in /v1) and QUERY_REWRITE_MODEL; QUERY_REWRITE_API_KEY only if the endpoint asks for one Questions and layer descriptions, to that endpoint

The openai_compatible provider works with any endpoint that speaks the OpenAI chat API, such as Ollama, LM Studio, vLLM, Azure OpenAI or Groq. QUERY_REWRITE_MODEL must name a model the endpoint serves; OPENAI_API_KEY is never sent there. For a local Ollama:

ollama pull llama3.2
QUERY_REWRITE_PROVIDER=openai_compatible
QUERY_REWRITE_BASE_URL=http://127.0.0.1:11434/v1
QUERY_REWRITE_MODEL=llama3.2

Small models often wrap their answer in prose or a code fence; StrataKB takes the first JSON list of strings from the reply. When a reply has none, the question is searched as written and the server logs query_rewrite_json_error. With STRATA_LOCAL_ONLY=true only an endpoint on this machine is allowed; see Where your data goes.

Confidence

Each strata_ask response carries a confidence level and the scale it was judged on, basis:

  • rerank (reranking on, the default): the reranker's relevance probability for each passage, from 0 to 1.
  • similarity (reranking off): the cosine similarity between the question and each passage.
flowchart TD
    t{"Best score >= high and<br/>3+ results >= medium?"} -->|yes| high["high"]
    t -->|no| m{"Best score >= medium?"}
    m -->|yes| med["medium"]
    m -->|no| low["low + warning"]
Loading
Basis high medium
rerank 0.8 0.5
similarity 0.6 0.45
Level Means
high The best match reaches the high mark, and at least three results reach the medium mark
medium The best match reaches the medium mark
low Nothing reaches the medium mark. The response includes a warning; try other terms or another layer

These thresholds are provisional until the evaluation suite measures them. Confidence stored for questions asked before this scale was introduced is on the old one.

Treat low as "the knowledge base probably doesn't cover this".

Feedback

With learning on (LEARNING_ENABLED, the default), every response has an interaction_id. Pass it to strata_feedback to say how the results did:

strata_feedback(interaction_id, helpful=True)
strata_feedback(interaction_id, helpful=False, correct_layer="sepa", better_query="SCT Inst reject codes")
strata_feedback(interaction_id, helpful=True, chunk_feedback={"<chunk_id>": "outdated"})

chunk_feedback values are useful, wrong or outdated.

What the server learns

With LEARNING_ENABLED=true (the default), StrataKB records each search and learns from it:

  • Rephrased questions. A question asked again in other words soon after is a hint that the first wording missed.
  • Layer switches. A question repeated in another layer teaches routing.
  • Explicit feedback. Ratings from strata_feedback.

From these it learns synonyms, query rewrites that worked, and which layers a kind of question belongs to. A proven rewrite is reused without calling the language model. strata_learning_stats shows what has been learned, and strata_reset_learning (admin) clears it.

flowchart LR
    i["Each ask and search<br/>is recorded"] --> sig["Signals: rephrasing,<br/>layer switch, follow-up, feedback"]
    sig --> pr["Promoter<br/>every 50 interactions"]
    pr --> lr["Learned rewrites<br/>+ synonyms"]
    pr --> af["Layer affinities"]
    pr --> dc["Decay of stale rewrites"]
    lr -->|"used by"| rw["Query rewriting"]
    af -->|"used by"| ro["Routing"]
    rw & ro --> i
Loading

Stored queries are scrubbed of IBANs, BICs and account numbers unless LEARNING_STORE_RAW_QUERIES=true.

Clone this wiki locally