Lesson 11 — Structured Output

Introduction

This lesson turns raw model text into typed, validated objects with Pydantic v2 schemas. Entity and StructuredResponse enforce allowed entity types, confidence bounds, and optional follow-ups. parse_structured() uses model_validate_json so invalid JSON and schema violations fail loudly. MetricsStore tracks OK/FAIL parses, entities, follow-ups, and latency; the FastAPI dashboard polls /metrics. POST /demo runs five mixed payloads so every counter leaves zero after one click.

Highlights

• Pydantic v2 field_validator clamps confidence and rejects invalid entity types.

• model_validate_json replaces deprecated parse_raw paths.

• Demo mixes three valid and two invalid payloads for full validation coverage.

• Live dashboard shows parse OK/FAIL, entities, follow-ups, and throughput.

• Docker lifecycle on port 8090 via start.sh, demo.sh, and run_tests.sh.

What We Build

• structured/ package: models.py, parser.py, metrics.py, service.py.

• FastAPI (app.py): /parse, /demo, /metrics, /health, /dashboard.

• CLI demo (main.py) printing OK/FAIL outcomes for each payload.

• DEMO_RAW_PAYLOADS covering location, org/date, follow-up, bad type, and non-JSON.

Connection to Previous Lesson

Day 10 assembled prompts and routed categories. Day 11 assumes that text may be JSON and proves it against a contract before any downstream agent trusts fields.

Enables Next Lesson

Validated structures become reliable inputs for Day 12’s agent state machine: transitions consume typed answers and entities, not free-form strings.

Architecture Context

• Where this component sits: between raw LLM/text ingress and business handlers that need typed fields.

• Why it exists: production systems cannot treat model prose as trustworthy data.

• Problem solved: schema enforcement with measurable OK/FAIL rates and operator-visible events.