Models, Reasoning, and Output Contracts

The model makes proposals from the context it receives. Reliable systems improve the decision environment and verify outputs instead of treating eloquence as truth.

Mission

By the end, you can choose a model by measured task performance, request machine-checkable outputs, and get useful explanations without collecting private hidden reasoning.

Prerequisites: Module 1. Basic JSON helps but is explained. Build artifact: a versioned decision contract and a small model-selection experiment. Time: 60-75 minutes.

Before you read: Predict → Commit → Connect

Two models answer 100 support tasks:

• Model A gets 92 correct, costs $8, and takes 40 seconds at the 95th percentile.
• Model B gets 88 correct, costs $1, and takes 4 seconds at the 95th percentile.

Which is better? Write your answer and list the information missing from the comparison.

A model is a conditional generator

At a practical level, a language model generates an output conditioned on the input context and its training. It is exceptionally good at patterns in language and code, but it does not query a built-in database of guaranteed facts. A fluent sentence and a grounded claim can look identical.

For an agent system, the model may produce one of three broad outputs:

1. a user-facing response;
2. a structured decision, classification, or extraction;
3. a proposed tool call.

The surrounding application decides how to validate and use that output.

Probabilistic does not mean uncontrollable

Exact wording and sometimes decisions can vary. Reliability comes from constraining the task, improving context, using structured contracts, validating with code, limiting actions, and measuring across a dataset.

Do not demand impossible determinism from the model. Do demand deterministic enforcement of permissions, invariants, budgets, and transactions.

Choose a model with a test, not a leaderboard

The best model is the least expensive and fastest option that clears the quality and safety thresholds for your task.

Evaluate candidates on:

• task success and critical-error rate;
• tool-choice and argument accuracy;
• instruction and policy adherence;
• performance on long, noisy, multilingual, or adversarial inputs;
• supported modalities and context size;
• structured-output and tool-calling behavior;
• latency distribution, not only average;
• input, cached-input, output, and tool costs;
• rate limits, availability, geography, retention, and enterprise controls;
• version stability and deprecation policy.

A common architecture uses different models for different steps. A small fast model may classify intent; a stronger model may handle ambiguous investigation; deterministic code validates the result. Routing itself must be evaluated because a cheap wrong route can erase all savings.

Return to the opening comparison

Neither model is “better” without thresholds and error severity. If the missed 8-12 cases are harmless drafts, Model B may dominate. If Model B misses more fraudulent refund attempts, Model A—or a redesigned system—may be necessary. We also need confidence intervals, repeated runs, task mix, failure categories, reviewer agreement, and total workflow cost.

Reasoning: ask for outcomes you can inspect

Some models and settings spend more computation on difficult reasoning. Use that capability for planning, coding, constraint satisfaction, or multi-source synthesis when evaluation shows a gain. Do not assume “more reasoning” always improves a simple classification; it can add latency and cost.

You usually do not need private hidden chain-of-thought. Ask for inspectable artifacts instead:

• a concise answer;
• evidence or citations;
• assumptions;
• calculations or code that can be checked;
• a short decision summary;
• an uncertainty label;
• the proposed next action and why it satisfies the policy;
• a verification checklist.

These artifacts are useful to people and evaluators. A long stream of internal reasoning can include sensitive context, be misleading as an explanation, and encourage operators to judge rhetoric instead of outcomes.

Misconception repair: A rationale is not proof. Verify the cited evidence, calculations, tool receipts, and final state.

Output schemas are contracts

Suppose Northstar needs a decision about what happens next. Free text such as “Looks refundable—go ahead” is ambiguous. Define a schema:

{
  "decision": "search_again | ask_user | propose_options | escalate",
  "user_message": "string",
  "search": {
    "date": "YYYY-MM-DD",
    "refundable_only": true,
    "max_price_cad": 900
  },
  "evidence_refs": ["string"],
  "uncertainty": "low | medium | high"
}

In a real schema, conditionally required fields would be encoded precisely—for example, search is required only when decision is search_again. Use enumerations, bounds, formats, and additionalProperties: false where the platform supports them.

Four levels of validity

Structured output can pass one level and fail the next:

1. Syntax: valid JSON.
2. Schema: correct fields, types, and allowed values.
3. Semantics: the date exists, evidence IDs refer to actual observations, price is in range.
4. Policy: the current actor and task are allowed to take the proposed action.

Only the first two are primarily formatting. Never equate schema-valid with safe or true.

Design schemas for safe evolution

Treat model-facing contracts like APIs:

• give actions distinct names and descriptions;
• avoid overlapping tools such as find_trip, search_trip, and lookup_trip unless the difference is sharp;
• prefer enums and constrained objects over prose fields;
• require the fewest arguments necessary;
• separate proposal from commitment;
• version material changes;
• log validation failures by schema version;
• keep a compatibility window during upgrades;
• include no secrets the model does not need.

A schema too loose merely moves ambiguity into JSON. A schema too complex increases generation and repair failures. Simplify the action space first.

I do: turn prose into a decision contract

Requirement: “If there are good flights, show them; otherwise try something nearby, unless the request is weird.”

This contains undefined terms. Clarify:

• “good” = refundable, date matches, price ≤ CAD 900, ≤ 1 stop;
• “show” = return up to three option IDs with a comparison, never book;
• “nearby” = depart within ±3 hours, not a different airport;
• “weird” = missing route/date, conflicting constraints, or search service integrity warning;
• repeated search = at most one revised query;
• unresolved case = ask one question or escalate.

Now the model chooses among a small enum while code verifies constraints against tool data.

We do: separate prediction from authority

Imagine a model emits:

{"eligible": true, "refund_cents": 42500, "explanation": "Policy permits it."}

Which fields should the model own?

• It may extract relevant facts and point to policy passages.
• It may draft an explanation.
• A deterministic policy service should compute eligibility and amount from authenticated booking facts and versioned rules.

A stronger contract is therefore a case summary and evidence list sent to a policy service, not a model-authored financial decision.

You do: LAB-4 — Contract before prompt

Choose one model decision in your architecture memo.

1. Write three ambiguous free-text outputs it might produce.
2. Create a JSON-shaped contract with an action enum, bounded arguments, evidence references, and uncertainty.
3. Write checks for syntax, schema, semantics, and policy.
4. Create ten cases: six ordinary, two edge, and two adversarial.
5. Compare at least two candidate configurations, or simulate their outputs if no API is available.
6. Record task success, critical errors, validation failures, latency, and estimated cost.
7. Choose only after defining minimum thresholds.

Done when: a validator can reject a fluent but impermissible proposal without interpreting its prose.

Pause & Recall

1. What are the four levels of output validity?
2. Why is a schema-valid output not necessarily safe?
3. What should you request instead of hidden chain-of-thought?
4. Why might a smaller model be the production winner?
5. Which decisions belong in deterministic services?

Production lens

Pin model versions where the provider supports it, record the actual model and configuration on each trace, and run regression evaluations before changes. A provider alias, safety update, tool-calling change, or context shift can change behavior even when your prompt did not.

Treat fallback models as distinct systems. Evaluate them independently, ensure they support the same contract, and decide which tasks may degrade versus stop. “Automatically use any available model” is not a continuity plan.

Chapter compression

• Choose models on representative task thresholds, critical errors, latency, and total cost.
• Request inspectable evidence and concise decision summaries, not private reasoning traces.
• Validate syntax, schema, semantics, and policy separately.
• Structure does not create truth or authorization.
• Put exact business rules and consequential calculations in deterministic code.
• Version and evaluate model-output contracts like APIs.

Memory hook: Fluency proposes; contracts constrain; evidence decides.

Retrieval deck

• Q: What is the right model-selection question?
  A: Which least costly, sufficiently fast candidate clears task-specific quality and safety thresholds?
• Q: What should replace requests for hidden reasoning?
  A: Concise conclusions, evidence, assumptions, checkable work, uncertainty, and proposed actions.
• Q: What are four validity layers?
  A: Syntax, schema, semantics, policy.
• Q: What does structured output guarantee?
  A: Only the supported structural contract—not factual correctness, authorization, or safety.

Spaced review

• Now: convert one free-text tool decision into an enum.
• +1 day: recall the four validity layers.
• +3 days: design a case where schema passes and policy fails.
• +7 days: write a model-selection threshold before viewing scores.
• +14 days: check whether one model or SDK fact in your notes has changed.

Sources and further study

• OpenAI, Structured Outputs
• OpenAI, Function Calling
• OpenAI, Models
• NIST, AI 600-1: Generative AI Profile