Define the product contract
Before making a model call, decide exactly what a correct answer means.
Estimated study time: 35 minutes
Progress is stored on this device.
Learning outcomes
- Translate a vague chatbot idea into explicit service requirements
- Identify failure classes and measurable acceptance criteria
- Specify a response contract independent of any model provider
The application you will build
Meet DocDesk, a fictional assistant answering questions about a company’s internal support policy. You will build it through six modules. Its job is narrow: answer a user’s question only from documents the user is permitted to see, cite the documents, and admit when evidence is missing. It must be measurable and diagnosable.
Starting with a narrow task matters. “Be helpful” is not an acceptance criterion. “On 20 reviewed test questions, at least 18 answers cite an authorized document that supports their claims” is one. Even that number is a course target, not a general industry standard. You must validate your own targets against real risk and user needs.
Write a behavior contract
For DocDesk we will use this contract:
- Input:
tenant_id, a nonemptyquestion, and an optionalrequest_id. - Authorized evidence: only documents where
document.tenant_id == tenant_idor the document is explicitly public. - Output: JSON object with
answer(string),citations(list of document IDs), andabstained(boolean). - Grounding rule: every cited ID must be among the retrieved, authorized documents. This is a necessary check, not proof the text supports the claim.
- Abstention rule: if no authorized evidence can answer the question, do not invent a policy.
- Failure rule: invalid input fails before a provider call; transient provider failures are bounded and surfaced; private document content is not logged by default.
The task contains both ordinary software invariants (field types, authorization, timeouts) and probabilistic quality properties (the answer is correct and genuinely supported). Do not confuse the two. A perfect schema does not make a fabricated answer true.
Model the request path
A question passes through authentication, authorization-aware retrieval, context assembly, a model call, output validation, and a response. The model is one replaceable dependency, not your application’s entire architecture.
Example request and response
{"tenant_id":"acme","question":"Can I refund an annual plan after 20 days?"}{"answer":"Annual plans are refundable within 30 days.","citations":["acme-refunds"],"abstained":false}The second object is only correct if that document really contains that policy and belongs to that tenant. Field validity is the beginning of verification, not the end.
Design negative cases first
A useful spec includes an unanswered question, a cross-tenant document, malformed provider JSON, an invented citation, a delayed response, and a malicious instruction hidden in a document. For each, describe the observable result. Without negative tests, the system looks excellent right up to its first actual user.
| Situation | Required result | Test layer |
|---|---|---|
| Question is empty | Reject with validation error | Unit |
| Only another tenant has the answer | Abstain | Authorization + integration |
Provider returns citations: "doc-1" |
Reject invalid type | Unit |
| Citation refers to unseen document | Reject or abstain | Integration |
| Model produces fluent but false claim | Mark incorrect in reviewed eval | Quality eval |
Decision checkpoint
Write a one-page contract before implementing features. Which outcomes are fatal errors, which can be safe abstentions, and which can be returned to the user? Keep those categories separate, because operations and evaluations will depend on them later.
Hands-on lab
Open `labs/README.md`, inspect the six policy documents, and write `docs/product-contract.md` with five invariants, five failure cases, and three measurable acceptance criteria. Run `python -m docdesk demo` to inspect the baseline behavior.