RagzMQR update / 2026.09
Updated architecture reference / implementation + evidence

Ragz MQR architecture update

How bounded multi-query retrieval changes the original one-query Ragz path: where the extra search lanes come from, how they stay inside the same tenant and ACL boundary, what the benchmark actually measured, and which performance ideas are still only safe behind development controls.

MQR branch analyzed Query expansion ≤ 2 alternatives Dense + sparse + RRF Default off Benchmark is directional
3maximum total query lanes
0.60best large-books Recall@5
35.7×Q1 warm query-cache speedup
57.6%benchmark expansion delta at low reasoning
OFFrecommended MQR production default
01 / Executive delta

What is new, and what it means

The original atlas described one user query feeding one dense vector and one sparse vector. The MQR branch keeps that path as the safe baseline, then adds a bounded, workspace-scoped fan-out that changes candidate coverage and cost without changing who is allowed to see a document.

One-sentence architecture

MQR changes the query representation, not the authorization model: one original question may become up to three retrieval lanes, but every lane enters the same filtered Qdrant search and the generated alternatives never become evidence.

The original query is always lane one. A designated utility model may produce at most two self-contained alternatives. Ragz batches their dense embeddings, computes one sparse vector per lane, fuses all dense/sparse rankings with Qdrant RRF, deduplicates chunks, and optionally reranks once using the original user wording.

01Safe baseline. MQR is workspace-scoped, default-off, and exposed only through a superadmin control.
02Bounded fan-out. One utility call, two alternatives, three total lanes; malformed output falls back to the original query.
03Same security seam. Tenant, workspace, current-version, metadata, ACL-group, and security-projection filters apply to every lane.
04Quality trade-off. Extra lanes can improve coverage, but can displace the first relevant item and add latency.
05Evidence boundary. The measured large-books result selects Q1/no-rerank; it does not prove MQR is useless on every corpus.
Implementation fact

Workspace switch

multi_query_enabled is persisted with a false server default. The settings UI only permits a superadmin to change it.

Implementation fact

Utility expansion

The utility model receives a delimited data block and must return JSON containing no more than two alternative search queries.

Measured, not shipped

Query cache seam

The report’s fast cache is a bounded process-local benchmark seam. Production still needs invalidation, sharing policy, telemetry, and retention.

Separate work

Response CAG

The newer Redis response-cache work is development-only, separate from MQR, disabled by default, and not yet safely wired into authenticated SSE chat.

02 / System landscape

Where MQR sits in Ragz

This is the architecture view that the original atlas used: actors and channels on the left, the Ragz application boundary in the middle, and platform services and model integrations on the right. The violet retrieval plane is the new MQR-aware seam.

Ragz MQR system architecture Browser, API, bot, and identity actors connect to React and FastAPI. The MQR retrieval plane expands queries, batches dense and sparse vectors, applies the tenant and ACL filter, fuses Qdrant results with RRF, and optionally reranks. Domain modules connect to PostgreSQL, Redis, MinIO, LiteLLM, TEI, parsers, model providers, and outbound adapters. RAGZ APPLICATION BOUNDARY PLATFORM SERVICES / INTEGRATIONS ACTORS & CHANNELS HTTPS REST / SSE OpenAI API OIDC services retrieve / compare MQR seam enqueue module calls SQL / audit broker / cache vectors objects gateway local ML parse / OCR OIDC provider API parser API Browser usersadmin · knowledge user API clientsREST · OpenAI compatible Bot usersTelegram · Slack · Discord Identity providerOIDC · Dex smoke target React web applicationVite · TypeScript · Routerworkspace MQR controlSSE client · response blocks FastAPI processmiddleware → route policyTenantContext → quotaschat + eval routesSSE / RFC 9457 errors MQR retrieval planeoriginal + ≤2 alternativesdense batch + sparse lanessame tenant / ACL filterQdrant RRF → dedupeoptional rerank / thresholdgenerated text ≠ evidence Celery workers + outboxinteractive / default / maintenanceparse · chunk · embed · upsertdelete · reindex · evallate ack · idempotent retries domain moduleschat · retrieval · documents · tenancy · evals core servicesdb · crypto · storage · config · metrics PostgreSQL 16system of record · settings · auditasync SQLAlchemy / Alembic Redis 7broker · rate limits · quota cacheseparate response-cache plane in dev Qdrant 1.18model-specific dense + sparseinline tenant / ACL filters MinIO / S3source files · parse artifactsephemeral chat attachments LiteLLM gatewaychat · utility · hosted embedprovider routing + usage TEI model serversbge-m3 dense embeddingsbge-reranker-v2-m3 ML / parsersLiteParse · Docling · OCR Dex / enterprise IdPoptional OIDC LLM providersOpenAI · AnthropicGemini · Ollama · vLLM Parser APIsAnydoc · LlamaParseoptional cloud path Outboundweb · bot · SMTP / SES
Actor Frontend API / MQR / modules Worker / ingestion Data store External / optional
How to read the new plane: the MQR box is not a new data store and does not bypass the domain module boundary. It is the retrieval service’s bounded query fan-out: utility expansion, batched embeddings, filtered Qdrant lanes, RRF fusion, dedupe, optional rerank, and score-space-specific no-answer logic.
03 / Runtime flow

The current MQR request path

Read left to right. The important security property is that expansion happens before vector search, while the authorization decision remains inside the retrieval module and is repeated defensively after the Qdrant read.

01 · input

Original question

The exact user query is retained as lane one and remains the reranker’s query.

02 · expand

Utility model

Generate up to two alternatives. Blank, duplicate, overlong, non-string, malformed, or failed output is discarded.

03 · encode

Batch vectors

Dense embeddings are produced in one batch; FastEmbed makes one sparse representation per valid lane.

04 · authorize

One filter seam

Every lane uses the same tenant, workspace, current-version, metadata, ACL, and security-projection filters.

05 · retrieve

RRF fusion

Qdrant fuses dense and sparse rankings across all lanes. Incomparable raw scores are never added linearly.

06 · refine

Dedupe + rerank

Parent/HQ hits collapse once. Optional cross-encoder reranking runs once against the original wording.

07 · answer

Threshold + citations

Return chunks and provenance. No-answer uses reranker space or the best dense cosine, depending on the active path.

Generated alternatives: retrieval aids, never citations query_count: observable retrieval metadata, max 3 failure posture: original-query retrieval continues if expansion fails

What is still the same

  • Qdrant remains the vector index with named dense and sparse vectors.
  • RRF remains the fusion mechanism; the system still treats retrieval as hybrid search.
  • Chunks are still page/version-aware evidence objects with citations.
  • ACL checks stay in the vector filter; application post-filtering cannot grant access.
  • Reranker outage degrades to pre-rerank fusion order rather than failing the request.

What now has more work

  • One question can invoke a utility-model call plus multiple embedding inputs.
  • Qdrant receives 2 × lane-count dense/sparse prefetches before one RRF fusion.
  • No-answer probing checks the best dense score across valid lanes.
  • Usage accounting adds a query_expansion ledger feature.
  • Latency budgets must distinguish expansion, embedding, vector search, rerank, and provider throttling.
04 / Implementation delta

Where the branch changed

These are implementation-level changes found on codex/multi-query-retrieval. The shared checkout is still on main; this page intentionally labels the branch boundary so the architecture is not mistaken for a merged production state.

modules/tenancy/models.py
migrations/6a8d2c4f1b90_*

Workspace-scoped control

Each workspace can opt into MQR without making the entire deployment multi-query.

  • Boolean field with database false default.
  • Partial workspace update preserves untouched settings.
  • Superadmin-only UI exposure; ordinary users do not gain authority from UI visibility.
modules/retrieval/query_expansion.py

Bounded query expander

A dedicated LiteLLM client turns one question into a small, validated tuple of retrieval queries.

  • Original query is always first.
  • At most two distinct alternatives survive normalization.
  • Prompt-injection-resistant data block and JSON parsing.
  • Expansion tokens are returned for ledger accounting.
modules/retrieval/service.py
retrieve()

One fused retrieval path

The service remains the single owner of vector access; MQR changes its lane construction rather than creating a second retrieval implementation.

  • Dense vectors batch across lanes.
  • Sparse vectors are computed per lane.
  • One Qdrant call fuses every prefetch.
  • Current-version, ACL, metadata, and projection rules remain in-filter.
modules/retrieval/service.py
rerank.py

Rerank after fusion

Reranking is not repeated per alternative. The cross-encoder scores the fused candidate set against the original user wording.

  • Candidate pool is 50 when reranking is enabled.
  • Final output is top_k.
  • min_score changes meaning to reranker score space when active.
  • Provider failure keeps fusion order.
modules/retrieval/service.py
metrics + quotas

Stage visibility

Stage timings and usage rows make the extra work attributable instead of hiding it inside one “retrieval latency” number.

  • Expansion, embedding, vector search, authorization, dedupe, rerank, and no-answer stages are separable.
  • Expansion prompt/completion tokens are billed separately.
  • Embedding and rerank accounting stay once per retrieval call.
frontend/src/features/workspaces/*
tests + ADR-0007

Operator-facing contract

The setting is explained as a recall/latency trade-off, not as a universal quality switch.

  • Control text warns about the extra model call and retrieval latency.
  • ADR records default-off, three-lane, fallback, security, and accounting decisions.
  • Isolation and query-expansion tests protect the behavior.
Important boundary: The benchmark’s query-embedding cache is not the same feature as the development-only Redis response cache being built in the shared worktree. One reuses vectors; the other replays complete answers. Neither should be described as a production MQR response cache today.
05 / Adjacent branch delta

Other changes the old atlas would miss

The MQR branch also carries broader architectural work. These changes are not MQR itself, but they affect the current system picture, the operational boundaries, and how a fair architecture review should describe the branch.

Reliability

Transactional outbox

Ingestion, deletion, reindex, and evaluation intent can commit with the domain change, then dispatch at least once with retry/backoff and idempotent consumers. Dispatched events are retained for seven days.

Workers

Queue separation

Interactive, default, and maintenance queues separate request-sensitive work from heavy jobs. Late acknowledgements, prefetch one, time limits, and one event loop/database engine per worker process constrain blast radius.

Chat structure

Decomposed chat lifecycle

Chat lifecycle, message/tree operations, attachments, analytics, and audit logic have moved into focused modules. The large orchestration surface is smaller than the old atlas reported.

Ingestion

Bounded uploads + parsing

Uploads are measured and hashed incrementally instead of fully buffered. The silent parser page ceiling is raised to a bounded configured limit, preserving page-aware large-document ingestion.

Observability

Prometheus is implemented

HTTP and retrieval-stage metrics now exist. /metrics is disabled unless a metrics token is configured and requires a bearer token. OpenTelemetry/tracing is still not implemented.

Deployment

Production Compose path

deploy/compose.prod.yaml adds migration, API, workers, beat, frontend, health gates, read-only containers, non-root runtime, dropped capabilities, and least-privilege credentials. It remains single-node, not HA.

Chat reliability

Opening-turn recovery

First messages are persisted server-side, and an unanswered opening turn can be resumed through a message-specific answer route instead of losing the user’s initial request.

Evaluation

Safe single-vs-multi compare

The workspace evaluation comparison route can run single and multi-query variants sequentially using request-scoped overrides, without changing the saved workspace setting or creating a chat.

Model-specific vector planes

Workspaces resolve their embedding model, dimension, provider, and collection instead of relying on one hard-coded vector collection. This matters for MQR because every generated lane must live in the same selected embedding space, and it matters for evaluation because two workspace models are not interchangeable just because both produce vectors.

Agentic retrieval caveat

MQR is attached to the retrieval service, not to one whole chat turn. If agentic chat invokes retrieval repeatedly, expansion and lane retrieval can happen per retrieval-tool call. A user-visible “one chat request” can therefore contain more than one MQR expansion unless the caller’s control flow prevents repeated searches.

Atlas correction: the original page treated Prometheus and OpenTelemetry as planned observability. On the reviewed MQR branch, token-gated Prometheus metrics are implemented; OpenTelemetry remains planned. The two should not be grouped together.
06 / Security & failure posture

More lanes, same trust boundary

MQR is safe only because query fan-out is downstream of the existing retrieval policy. The generated text can be noisy or adversarial; it cannot redefine the tenant filter or become a source in the answer.

BoundaryCurrent behaviorWhy it mattersFailure result
Tenant + workspaceEvery dense and sparse prefetch carries the shared tenant/workspace filter.A synonym or alternative cannot broaden the corpus.Access is denied or results are empty; no permissive fallback.
ACL groupsAllowed group IDs are part of the Qdrant filter for every lane.Semantic similarity never sees unauthorized chunks.Only authorized candidates survive; post-query recheck can remove more.
Current document versioncurrent_only remains part of the vector filter.Old versions cannot re-enter through a broadened query.Stale points are excluded at search time.
Security projectionUnprojected document IDs are excluded before the query; a second read drops newly unprojected hits.Closes the read-then-query race without using post-filtering as authorization.Race direction is fail-closed: needless denial, not access grant.
Prompt injectionUser question is placed in a delimited data block; expansion instructions say not to follow commands inside it.Alternative generation cannot turn document/user text into model instructions.Malformed or hostile output is discarded; original query remains.
Expansion outageUpstreamError, missing utility model, or malformed JSON degrades to the original query.MQR is an optimization, not a new availability dependency.One-lane retrieval continues and the request does not fail solely because MQR failed.
Reranker outageExisting RRF order is preserved; dense no-answer logic remains available.Reranking is an optional quality layer.Lower refinement, not a blank answer or authorization bypass.
Generated alternativesOnly retrieval uses them; sources and citations come from retrieved chunks.Model-generated wording is not evidence.Alternatives cannot be cited as if they were documents.
Preserve

Filter before similarity

The correct query filter is the primary authorization mechanism. A Python rejection after a permissive query would not be equivalent.

Watch

Threshold calibration

The same min_score field is interpreted in dense-cosine space without reranking and reranker-score space with reranking. Thresholds must be calibrated per score space.

Observe

Cost attribution

Expansion tokens, query-embedding tokens, rerank search units, and queue/provider wait should remain distinguishable in usage and telemetry.

07 / Benchmark results

What the large-books run actually says

The frozen protocol covered three public PDFs, 4,412 physical pages, 18,734 chunks, 24 questions, and one observation per query/configuration. It is useful for a conservative decision, not a universal statistical verdict.

Default recommendation
Q1 / OFF

One original query, no reranker. Best tested combination of recall, nDCG, groundedness, and latency.

Best MRR variant
Q1 / P50

MRR 0.4917, only +0.015 over Q1/no-rerank, while recall fell and provider time rose.

MQR=3 off
0.6000

Recall matched Q1, but MRR, nDCG, answer relevance, correctness, and p95 did not improve.

MQR=5 off
0.5500

Five lanes reduced recall and most answer-quality components; extra coverage was not free.

ConfigurationRecall@5MRR@5nDCG@5Context rel.GroundednessAnswer rel.Correctnessp95 ms
Q1, rerank off0.60000.47670.50740.89100.97550.84750.78801,188.25
Q1, P=100.45000.40000.41310.91950.97200.85600.73401,626.73
Q1, P=200.55000.46000.48240.96050.88200.79950.81351,661.23
Q1, P=500.55000.49170.50650.88350.95700.81100.75651,894.29
Q3, rerank off0.60000.46420.49740.91750.95350.80300.70201,612.95
Q3, P=100.55000.46000.48240.89600.88500.84000.73002,026.98
Q3, P=200.50000.45000.46310.87700.97200.77250.72051,832.80
Q3, P=500.55000.49170.50650.90650.92500.85400.80302,010.90
Q5, rerank off0.55000.45170.47590.81050.96700.76300.70201,298.69
Q5, P=100.60000.47000.50180.92200.92800.81900.73202,544.96
Q5, P=200.50000.45000.46310.90700.95150.81200.73501,872.42
Q5, P=500.50000.47500.48150.95100.96600.82100.74502,164.79

P means pre-rerank candidate pool, not nucleus sampling. Retrieval p95 removes only the benchmark’s Cohere account-throttle wait; it still includes embeddings, ACL work, Qdrant, RRF, reranker/provider time where applicable, and local processing.

Decision: Q1/no-rerank dominates the tested MQR configurations on the safer production trade-off. Q1/P=50 is an opt-in experiment for its small MRR gain, not the default.
Do not overread: one observation per question/configuration over 24 questions cannot establish corpus-independent superiority or infer statistical significance.
Additional observationMeasured resultInterpretation
Citation validity1.0 for all 12 configurationsEvery citation had valid structure; this does not mean it pointed to the exact benchmark reference page.
Exact-page citation precision / recall0.44–0.56 / 0.45–0.55Grounded text and structurally valid citations can still miss the exact qrel page.
Abstention F10.6154–0.7273Retrieval min_score=0 cannot abstain by itself; the answer model abstained on all four off-corpus queries but also on some answerable ones.
RAG-Triadcontext relevance, groundedness, answer relevanceThese are judged answer/context dimensions, not substitutes for retrieval rank metrics.
08 / Cache, latency & cost

Where the time goes

The benchmark exposed an important architecture fact: local Qdrant/RRF work is not the dominant cost. Hosted query embedding owns most no-rerank retrieval time; expansion and Cohere reranking can add separate provider waits.

Q1 query-cache warm hit
19.00 ms

Versus 678.47 ms cache-off mean: 35.70× faster, with 24/24 scored hits.

Q3 query-cache warm hit
42.80 ms

Versus 940.83 ms cache-off mean: 21.98× faster; more lanes mean more cached vectors to retrieve.

Q5 query-cache warm hit
54.78 ms

Versus 928.84 ms cache-off mean: 16.96× faster; speedup is still large but not a quality change.

Default Q1/no-rerank atomic latency

StageMeanp95Share
OpenAI dense embedding801.85 ms1,165.13 ms95.5%
Qdrant hybrid search / RRF10.31 ms12.47 ms1.2%
Dense no-answer probe5.97 ms7.13 ms0.7%
Sparse BM25 embedding4.69 ms*0.60 ms0.6%
ACL prefilter2.93 ms5.78 ms0.3%
Retrieval total839.50 ms1,188.25 ms100%

*A sparse outlier raises the mean; sparse median and p95 remain sub-millisecond. Removing ACL or Qdrant safety work would save little and weaken the product.

Q1/P=50 rerank path

StageMeanp95
OpenAI dense embedding799.30 ms817.21 ms
Cohere provider710.70 ms1,038.93 ms
Qdrant candidate search15.73 ms24.38 ms
Intrinsic retrieval1,539.09 ms1,894.29 ms
Account-throttle wait876.31 ms2,604.27 ms
Observed rate-gated retrieval2,415.40 ms4,012.09 ms

The trial account was empirically about 9–10 requests/minute; a final repair succeeded at 6 RPM. Provider time and queue/throttle wait must be reported separately.

Expansion A/B: provider-default reasoning vs low

DefaultLowChange
Mean6,635.31 ms2,814.25 ms−57.6%
p9521,559.85 ms3,580.19 ms−83.4%
First attempt19/2424/24+5
Fallback lanes40−4
Completion tokens5,3004,002−24.5%
Cost$0.00784$0.00628lower

This validates latency and schema completion for expansion. The quality matrix reused a frozen alternative set, so it does not prove the newly generated alternatives improve retrieval quality.

Answer path and benchmark accounting

  • User-facing pathQ1/no-rerank retrieval + answer generation was about 3,902 ms in this run.
  • Benchmark-only judgeMean Luna generation 3,062.64 ms; separate judge 2,537.46 ms. The judge is not user-facing.
  • Provider usage288 answers + 288 judges used 551,995 Luna input, 51,764 Luna output, 591,895 judge input, and 68,083 judge output tokens.
  • Observed costAnswer + judge usage-derived cost was $0.92281055 against a historical $5 hard cap.
  • InterpretationGeneration, TTFT, context budgeting, and answer caching matter more to user experience than shaving a few milliseconds from local retrieval.
Cache distinction to keep: the MQR benchmark’s query-embedding cache reuses vector encodings. The separate development CAG/response-cache module replays complete answers only after much stricter identity, freshness, authorization, persistence, and SSE requirements are met. A warm vector lookup is not authenticated cached-chat latency.
09 / Reference glossary

Technical terms in plain language

Use this section as a quick reference. For every metric, the useful question is not simply “is the number high?” but “what behavior does it reward, and what can it miss?”

Reading rule: retrieval metrics score ranked evidence; RAG-Triad metrics score context and answer behavior; neither category alone proves factual correctness or authorization safety.

MQR / multi-query retrieval feature

Turn one user question into several retrieval queries, then combine their results. It can recover vocabulary or viewpoint mismatches, but it adds model, embedding, and search work and can lower the rank of the first relevant result.

Query lane unit

One query variant entering retrieval. In this design, lane one is always the original question and lanes two and three are optional generated alternatives.

Dense embedding representation

A fixed-length vector produced by an embedding model. Similar meanings tend to be near one another even when they use different words. Ragz’s benchmark used OpenAI text-embedding-3-large at 1,024 dimensions.

Sparse embedding / BM25-style search representation

A mostly-empty vector whose non-zero entries represent words or terms. It is good at exact names, numbers, acronyms, and rare vocabulary. Ragz computes it with FastEmbed and combines it with dense search.

Hybrid retrieval search

Use dense semantic search and sparse lexical search together. The goal is to cover both “same meaning, different wording” and “exact token matters” cases.

RRF / reciprocal rank fusion fusion

A rank-combination method. A result receives roughly 1 / (constant + rank) from each list, and the contributions are added. It combines rankings without pretending dense and sparse raw scores mean the same thing.

Reranking second pass

Retrieve a broad candidate pool first, then ask a cross-encoder to score each candidate against the original question. It may improve order, but the provider call can dominate latency and cost.

top_k and candidate pool cutoff

top_k is how many chunks the answer path finally keeps. P in the benchmark is the pre-rerank pool size, such as P=50. P is not nucleus sampling and does not mean top_p.

Recall@k retrieval quality

Of the questions with a known relevant item, how often did at least one relevant item appear in the first k results? A Recall@5 of 0.60 means 60% of the benchmark questions had a relevant result in the top five.

MRR@k / mean reciprocal rank retrieval quality

Look only at the first relevant result. Score it as 1 / rank: rank 1 = 1.0, rank 2 = 0.5, rank 3 = 0.333, and no relevant result in the cutoff = 0. Higher MRR means the first useful result appears earlier.

nDCG@k retrieval quality

Measures ranked quality when relevance can have grades, not just relevant/not relevant. Higher-ranked items count more, then the score is normalized against an ideal ordering. 1.0 is the ideal for the judged cutoff.

Qrels / relevance judgments evaluation data

A table saying which retrieved unit is relevant for each query. In this report the retrieval qrel unit was the exact physical PDF page. Changing qrels, chunking, or corpus changes what the metric means.

Context relevance RAG-Triad

Does the retrieved context contain information that is useful and necessary for answering? High context relevance does not guarantee the model used it correctly or that the answer is complete.

Groundedness / “groundness” RAG-Triad

Are the answer’s claims supported by the supplied retrieved context? High groundedness means the answer stays close to evidence; it does not prove the evidence itself is the correct reference page or that the answer covers every part of the question.

Answer relevance RAG-Triad

Does the answer address what the user asked, rather than wandering or answering a neighboring question? A relevant answer can still be factually wrong or weakly supported.

Correctness answer quality

How closely the answer matches the reference facts or expected answer. Correctness is distinct from groundedness: a model can faithfully quote the wrong retrieved passage, or answer correctly with insufficient citation evidence.

Abstention F1 refusal quality

A balance of precision and recall for refusing questions the corpus cannot answer while answering questions it can. It combines false refusals and missed refusals into one harmonic-mean score; it is not the same as a product “no answer” flag.

Citation precision and citation recall provenance

Citation precision asks how many citations point to the correct evidence unit; citation recall asks how much of the required evidence was cited. A structurally valid citation can still miss the exact qrel page.

p50 / p95 / p99 latency percentiles

p50 is the median: half of requests are faster. p95 means 95% are faster and 5% are slower. p99 exposes the long tail. Percentiles are not averages and should be reported with sample size and boundary conditions.

TTFT / time to first token streaming

Time from request start until the first streamed answer token arrives. It measures perceived responsiveness, not total completion time. A benchmark cache lookup or retrieval microbenchmark is not authenticated chat TTFT.

Cold, warm, hit, miss cache vocabulary

A cold or cache-off request computes the expensive value. A hit reuses it. “Warm” describes a populated cache, not necessarily a user-facing answer replay. The query-vector cache and complete-response cache are different layers.

Cache invalidation and freshness correctness

When source documents, ACLs, prompts, models, or retrieval policy change, an old cached value may no longer be safe. A production cache needs versioned keys or authoritative epochs, bounded retention, and authorization checks before reuse.

Pareto frontier decision tool

A configuration is on the frontier if no other configuration is at least as good on every chosen dimension and strictly better on one. Here the report maximized Recall, MRR, nDCG and minimized throttle-adjusted retrieval p95.

Provider throttle / quota wait latency boundary

A provider or account rate limit can make a request wait or return 429. That queue time is not model computation. Report it separately, honor Retry-After, and do not call the observed throttled latency intrinsic model latency.

Reasoning effort model setting

A model-control setting that trades internal deliberation and latency. The supplied benchmark report says Luna expansion was pinned to low, but the reviewed branch’s query_expansion.py does not currently send an explicit reasoning_effort field. Treat the A/B as benchmark evidence from its stated revision, not as a confirmed current-code contract.

Utility model control-plane role

A designated inexpensive or fast model used for supporting work such as query expansion. It is not necessarily the answer model. If it is missing, the MQR path falls back to the original query.

No-answer threshold / score space decision

Ragz compares the best available score against min_score. Without reranking that is dense-cosine space; with reranking it is cross-encoder score space. The same numeric threshold is not automatically equivalent across those spaces.

RAG-Triad evaluation family

A three-part answer evaluation commonly framed as context relevance, groundedness, and answer relevance. It complements retrieval metrics; it does not replace exact evidence matching, correctness review, security tests, or latency measurements.

10 / Decision & roadmap

What should happen next

The measured answer is conservative: preserve the secure hybrid path, keep MQR opt-in, and spend engineering effort where the atomic timings show the largest leverage.

Recommended now

Ship the safe baseline

  • Keep one query/no reranker as default.
  • Keep MQR behind the superadmin control.
  • Reproduce and explicitly wire the low-reasoning expansion setting before treating it as a current production control.
  • Use three total lanes before five if a workspace evaluation supports MQR.
  • Run original-query retrieval immediately and fuse alternatives only before a strict deadline.
Productionize carefully

Prioritize high-leverage work

  • Version query-vector cache keys by model, provider, dimension, and normalized query.
  • Add TTL/size bounds, privacy-safe hashes, telemetry, and shared/per-replica semantics.
  • Make RRF ties deterministic with a stable secondary key.
  • Reuse an application-scoped LiteLLM client.
  • Run the no-answer probe concurrently with fused search.
  • Cache unchanged document embeddings and batch incrementally.
Do not claim yet

Keep evidence boundaries visible

  • Do not call the query-vector benchmark seam a production response cache.
  • Do not call Redis CAG response replay production-ready; it is development-only and disabled by default.
  • Do not claim universal MQR quality gains from 24 questions.
  • Do not compare systems across different corpora as one winner table.
  • Do not remove ACL rechecks or hybrid retrieval to chase a shorter path.

Evidence needed before changing defaults

Evaluation breadthAt least 100 answerable and 30 adversarial off-corpus questions, with repeated counterbalanced runs.open
StatisticsPaired deltas, bootstrap intervals, and correction for multiple comparisons; do not tune on frozen labels.open
Security racesTest ACL/group/membership revocation, document replacement/deletion, current-version changes, and concurrent cache reads.open
Real user latencyMeasure authenticated SSE TTFT, total stream time, provider queue time, concurrency, and cache-hit persistence behavior.open
Production CAGAuthoritative PostgreSQL epochs, live principal/source authorization, freshness checks, normal message/SSE persistence, and fenced fills must land together before enablement.not ready
11 / Traceability

Source map & reading boundaries

This update combines the supplied architecture atlas, the supplied benchmark report, and the current MQR branch implementation. Paths below are intentionally labeled by revision so readers can distinguish shared-checkout evidence from branch evidence.

ragz-architecture.htmlOriginal atlas UI and baseline architecture: one-query hybrid retrieval, existing data planes, security boundaries, and deployment model. RAGZ_MQR_RERANK_CACHE_REPORT_2026-08-24.mdMeasured MQR/rerank/cache matrix, atomic latency, RAG-Triad, comparison boundaries, findings, and improvement order.
MQR branch: backend/src/ragz/modules/retrieval/query_expansion.pyBounded expander, prompt data block, JSON validation, alternative normalization, usage extraction, and LiteLLM request behavior. Branch: codex/multi-query-retrieval @ d349eeb.
MQR branch: backend/src/ragz/modules/retrieval/service.pyWorkspace control, batched vectors, one filtered multi-lane Qdrant query, authorization recheck, dedupe, reranking, and multi-lane no-answer probing.
MQR branch: docs/adr/ADR-0007-multi-query-retrieval.mdAccepted design decision for default-off MQR, three-lane cap, fallback, filter reuse, RRF, accounting, and generated-query evidence boundaries.
Shared worktree: docs/handoffs/2026-09-08-cag-benchmark.mdSeparate development-only response-cache state, dedicated Redis service, incomplete authenticated SSE integration, and preserved benchmark constraints.
MQR branch: modules/outbox + worker/outbox.pyTransactional work intent, at-least-once dispatch, retry/backoff, idempotent consumers, and retention boundaries.
MQR branch: core/metrics.py + api/routes/health.pyPrometheus HTTP/retrieval metrics, token-gated metrics endpoint, and the explicit boundary that tracing remains unimplemented.
MQR branch: deploy/compose.prod.yamlSingle-node production-oriented process/container definition, health gates, non-root runtime, capability drops, and least-privilege credentials.
main: retrieval/service.pyShared-checkout baseline retrieval code. This path is not the MQR branch implementation unless the reader is viewing the MQR worktree. docs/prd.mdProduct requirements and non-functional context for tenant isolation, retrieval, chat, and operations. AGENTS.mdCurrent preservation, security, benchmark, CAG, model-routing, and verification constraints used for this analysis.
Revision note. The shared checkout at the time of this document is main at 90bb3b1, with user-owned dirty changes preserved. The MQR implementation analyzed here is on the existing codex/multi-query-retrieval worktree at d349eeb. The supplied benchmark report is a navigation copy whose provenance names an earlier canonical report revision. Treat implementation facts, benchmark facts, and recommendations as separate evidence classes.