Instrument fusion, rerank scores, and fallbacks

Instrumentation should explain behavior without collecting raw material unnecessarily. For this artifact, record enough to calculate or monitor nDCG@5 improves by at least 0.05 versus vector-only while added p95 latency stays under 120 ms. Include version or configuration identifiers so two runs can be compared. A log line is useful only if it answers a debugging question.

Log candidate IDs before/after fusion, rerank scores, fallback flag, model version, and duration. Cache only scores keyed by query hash, chunk hash, model version, and tenant.

The artifact's user-facing goal is specific: put the most query-relevant evidence first for mixed exact-ID and paraphrase questions. Its accepted input is a query string plus lexical and vector candidate lists with stable chunk IDs. Those statements are intentionally narrower than “build an AI system.” Narrow scope lets us inspect every input and expected result, and it prevents a toy result from being presented as a production claim. System shape for this chapter: a lexical retriever preserves exact identifiers such as ERR-502, a vector retriever catches paraphrases, reciprocal-rank fusion creates twenty unique candidates, and a cross-encoder jointly reads each query-chunk pair before the prompt receives the best five. Keep model calls behind adapters, keep authorization and validation in deterministic code, and carry stable IDs and versions through every response. That separation lets you decide whether a bad result came from input handling, retrieval, inference, validation, or deployment. This page's job is the testing and observability step: instrumentation should explain behavior without collecting raw material unnecessarily. Setup baseline for the chapter (run once per machine, not secrets in git):

python -m venv .venv && source .venv/bin/activate
pip install sentence-transformers rank-bm25 numpy

If hardware or a hosted provider differs, preserve the interface and expected behavior. Do not present provider syntax as universal—when a vendor adapter is unavoidable, keep it behind a thin boundary and test with a fake first. The deliverable is not “it ran once”; it is a reproducible artifact another developer can inspect, including expected output and one deliberate failure related to exact SKU miss or silent duplicate candidates. Operationally, write down the owner of this stage, the command you ran, the observed output, and the next page's dependency on that output. If you cannot point to a file, fixture, metric, or config key, the stage is not done. Prefer small, reviewable increments: one contract, one path, one metric, one failure, one gate. When tradeoffs appear—latency versus quality, hit rate versus false hits, local privacy versus cloud quality—record both numbers instead of moving the threshold until the report looks green. The chapter ships only when evidence for nDCG@5 improves by at least 0.05 versus vector-only while added p95 latency stays under 120 ms and a rehearsed recovery path exist beside cross-encoder re-ranker with canary traffic and RERANK_ENABLED kill switch.

Save this as lesson.py and run python3 lesson.py. Prefer the standard library or the pinned packages from the setup block so the example stays reproducible.

event={"stage":"rerank","candidate_ids_in":["a","b","c"],"ids_out":["a","c"],"fallback":False,"ms":88,"model":"mini-ce-v1"}
print(event)

Expected output: event showing ids_in and ids_out. Exact floating-point formatting may vary slightly, but the asserted behavior must not. Read the output as evidence about this stage, not merely proof that the interpreter started.

Compare two events from different versions on the same fixture. Divergent IDs or statuses need an eval note before traffic moves. At the testing and observability stage, save the smallest failing fixture beside the expected result. Change one cause at a time and rerun the exact command printed above; that makes the repair reviewable and keeps this chapter's progressive artifact reproducible.

Dashboards or reports should slice by version pins. Alerts should fire on safety failures immediately. For this testing and observability page, preserve the fixture and result as evidence for the next page. Label observations separately from conclusions: a passing assertion establishes the behavior it names, while broader usefulness requires the chapter's full evaluation set and stated operating limits. Primary metrics for the chapter remain nDCG@5 improves by at least 0.05 versus vector-only while added p95 latency stays under 120 ms.