Repository navigation
Asking and Searching
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
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 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"]
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"]
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 aspageandtotal_pages, for example{"page": "3"}.
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.2QUERY_REWRITE_PROVIDER=openai_compatible
QUERY_REWRITE_BASE_URL=http://127.0.0.1:11434/v1
QUERY_REWRITE_MODEL=llama3.2Small 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.
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"]
| 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".
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.
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
Stored queries are scrubbed of IBANs, BICs and account numbers unless LEARNING_STORE_RAW_QUERIES=true.
Getting started
Using StrataKB
Reference
Help