Capstone: research bot with citations
Set corpus trust and disclosure boundaries
Page 7 advances one concrete citation-first research assistant: explain the decision, run the code, inspect failure, measure evidence, and keep only what is ready to ship.
Before you start
Why this matters
Predict whether a client-supplied authority field can safely drive the citation-first research assistant. Which negative test proves the boundary?
1Learn the idea
Read
Build focus
Before release, define what the artifact refuses to do. Validate ranges, minimize retained data, pin the reviewed configuration, and assign an owner who can disable the feature. Safety is implemented at the boundary and release process; it is not a warning paragraph placed after an unsafe function.
Only trusted corpus sources enter ingestion. Disclose uncertainty. Users should see evidence pointers, not a fake bibliography.
The artifact's user-facing goal is specific: map every factual claim to retrieved chunk IDs and abstain when evidence is missing. Its accepted input is a research question plus a trusted, versioned document corpus with immutable 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: an ingestion path normalizes trusted documents into immutable chunks; retrieval selects evidence; an answer model emits structured claims with chunk IDs; a deterministic verifier rejects unknown IDs and unsupported quotations before the API responds. 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 safety and operations step: before release, define what the artifact refuses to do. Setup baseline for the chapter (run once per machine, not secrets in git):
python -m venv .venv && source .venv/bin/activate
pip install pydantic fastapi uvicorn
mkdir -p corpus fixtures
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 fluent answer with invented or mismatched citations. 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 citation validity ≥ 0.99, unsupported-claim rate ≤ 0.02, correct abstention on no-evidence questions and a rehearsed recovery path exist beside structured research API that returns claims, evidence IDs, or an explicit abstention.
Read
Run the example
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 allow_corpus_doc(source_trust):
return source_trust in {"internal-policy","reviewed-pdf"}
print(allow_corpus_doc("random-web"))
Expected output: False for untrusted web source. 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.
Read
Debug the stage
Run a negative authorization or safety test. A perfect quality score with a broken boundary must still fail the release. At the safety and operations 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.
Read
Evaluate before continuing
Security and ops gates are blockers. Missing controls fail the ship checklist even when demos look good. For this safety and operations 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 citation validity ≥ 0.99, unsupported-claim rate ≤ 0.02, correct abstention on no-evidence questions.
Continue learning · glossary & guides
- [ ] Is there a concrete release blocker and named owner?
- [ ] Are data range, retention, and rollback rules executable?
- [ ] Can the reviewed version be identified after release?
- [ ] What does the citation-first research assistant refuse to do?
How-to: add citations to RAG answers · Glossary: groundedness · Cheatsheet: research bot ship