v1.0.0

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:

  1. Input: tenant_id, a nonempty question, and an optional request_id.
  2. Authorized evidence: only documents where document.tenant_id == tenant_id or the document is explicitly public.
  3. Output: JSON object with answer (string), citations (list of document IDs), and abstained (boolean).
  4. Grounding rule: every cited ID must be among the retrieved, authorized documents. This is a necessary check, not proof the text supports the claim.
  5. Abstention rule: if no authorized evidence can answer the question, do not invent a policy.
  6. 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

json
{"tenant_id":"acme","question":"Can I refund an annual plan after 20 days?"}
json
{"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.

Download the lab kit

Knowledge check

Which is an enforceable software invariant?
Why must a schema check be separate from grounding?

References