Ship and explain the reversible cache rollout

The final artifact is semantic cache with TTL, versioned keys, and SEMANTIC_CACHE_ENABLED kill switch. A reviewer should be able to reproduce the demo from one command, see the expected result, run the checks, and find the known limitations. Shipping means the intended case is measurable, failures are legible, and the previous working artifact remains recoverable.

Ship behind SEMANTIC_CACHE_ENABLED, canary by traffic, and disable instantly if false hits appear. Versioned keys make stale reuse visible.

The artifact's user-facing goal is specific: reuse answers for paraphrases only when tenant, policy key, and similarity thresholds all match. Its accepted input is normalized question, tenant, policy key, corpus version, and embedding vector. 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 request normalizer derives policy fields, an embedding model maps the question to a vector, a tenant-scoped cache retrieves the nearest entry, and a threshold plus exact policy-key match decides hit or miss before the normal LLM path stores a versioned result. 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 mastery and shipping step: the final artifact is semantic cache with ttl, versioned keys, and semantic_cache_enabled kill switch. Setup baseline for the chapter (run once per machine, not secrets in git):

python -m venv .venv && source .venv/bin/activate
pip install numpy
export CACHE_THRESHOLD=0.92 CACHE_TTL_SECONDS=3600

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 false hit that reuses the wrong policy answer. 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 false-hit rate 0 on high-risk intents in the test set, with measured hit rate and token savings and a rehearsed recovery path exist beside semantic cache with TTL, versioned keys, and SEMANTIC_CACHE_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.

release={"SEMANTIC_CACHE_ENABLED":True,"threshold":0.92,"false_hit_rate":0.0,"rollback":"SEMANTIC_CACHE_ENABLED=false"}
print(release)

Expected output: release record with kill switch. 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.

Rehearse rollback and readiness. If app code rolls back but model/index/adapter pins do not, the release unit was incomplete. At the mastery and shipping 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.

Ship only when checks, evidence, and rollback rehearsal are green on the same pins. For this mastery and shipping 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 false-hit rate 0 on high-risk intents in the test set, with measured hit rate and token savings.