Build the first working offline eval runner

Now implement the shortest complete path for the RAG golden-question release gate. Keep every intermediate value available for inspection; hiding it behind a heavy framework would make this lesson harder to reason about. The output should be deterministic for the fixture (or schema-deterministic when a model is involved). Only after this path works should you generalize.

Run retrieval metrics before any LLM judge. Deterministic recall and citation validity give a trustworthy floor. Keep the runner offline-capable with recorded retrieved IDs for unit tests.

The artifact's user-facing goal is specific: block a release when expected evidence or citations regress on a fixed suite. Its accepted input is JSONL rows with question, expected_chunk_ids, and optional forbidden claims. 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 versioned JSONL dataset feeds the same retriever and answer service used in production; deterministic retrieval metrics run first, an evidence-support check runs second, and a report separates retrieval misses from generation failures. 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 implementation step: now implement the shortest complete path for the rag golden-question release gate. Setup baseline for the chapter (run once per machine, not secrets in git):

python -m venv .venv && source .venv/bin/activate
pip install pytest
mkdir -p evals/gold reports

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 retrieval miss mislabeled as model hallucination. 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 recall@5, citation validity, and faithfulness above agreed thresholds on the suite and a rehearsed recovery path exist beside CI eval gate with versioned dataset and HTML/JSON report artifacts.

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.

def recall_at_k(expected, retrieved, k=5):
    return float(any(e in retrieved[:k] for e in expected))
print(recall_at_k(["runbook-7"], ["runbook-2","runbook-7"], 5))

Expected output: 1.0 recall for a hit in top five. 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.

Print intermediate IDs, scores, or statuses before the user-visible answer. Fluent wrong outputs usually start as a wrong intermediate. At the implementation 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.

After the happy path works, freeze the fixture as a regression oracle before adding queues, caches, or fancy UX. For this implementation 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 recall@5, citation validity, and faithfulness above agreed thresholds on the suite.