Structured Output

Any feature that does something with a model's answer eventually needs to read that answer in code. Pulling an amount out of a sentence with a regular expression works until the phrasing moves, and the phrasing will move. The alternative is to ask for a defined structure and then check that what came back matches it.

Two separate steps, and both are needed. Asking makes the right shape likely. Validating is what lets you rely on it. A prompt is a request, not a constraint, and the same is true of a schema you describe in words.

import logging
from typing import Literal
from pydantic import BaseModel, Field, ValidationError

log = logging.getLogger(__name__)

class ClaimFields(BaseModel):
    category: Literal["travel", "meals", "software", "equipment"]
    amount_pence: int = Field(ge=0)
    receipt_required: bool
    policy_note: str = Field(max_length=200)

def extract_claim(description: str) -> ClaimFields | None:
    messages = [
        {"role": "system", "content": SYSTEM_WITH_SCHEMA},
        {"role": "user", "content": f"DESCRIPTION\n{description}"},
    ]

    for attempt in (1, 2):
        raw = call_model(messages, response_format={"type": "json_object"})
        try:
            return ClaimFields.model_validate_json(raw)
        except ValidationError as error:
            log.warning(
                "claim extraction rejected",
                extra={"attempt": attempt, "errors": error.errors()},
            )
            messages.append({"role": "assistant", "content": raw})
            messages.append({
                "role": "user",
                "content": f"That reply was rejected: {error}. Reply with corrected JSON only.",
            })

    return None

• The Pydantic model is the schema in executable form. Literal restricts category to four values, ge=0 rejects a negative amount, and max_length stops a 4,000-character essay arriving in a field sized for a note.
• response_format asks the provider to constrain the reply to valid JSON. Where a provider supports a full schema mode, use it — it removes the whole class of "not valid JSON" failures. It says nothing about whether the values are right.
• model_validate_json parses and checks in one call, and the ValidationError names the field that failed. That specificity is what makes the retry worth attempting.
• The retry sends the model its own rejected reply plus the validation error, as a new turn rather than by editing the original description. Keeping the correction out of the data block matters: the description is data, the correction is an instruction, and merging them undoes the separation from the previous lesson.
• Two attempts, then None. A loop that retries until success is how a transient provider problem turns into a large bill. Returning None also forces the caller to decide what happens when there are no usable fields — a review queue, not a guess.