Type Hints and Typed Response Models

Unit 6 of this course introduced Structured Outputs — asking the model to return data that matches a fixed schema instead of freeform text. That unit focused on getting the model to produce structured data reliably. This lesson focuses on the other half of the problem: once structured data arrives, how should a well-engineered Python application represent, validate, and pass it around internally? The answer is typed response models, built on Python's type-hint system.

Why Raw Dictionaries Are Not Enough

A very common (and very fragile) way to handle structured data from the SDK looks like this:

def get_ticket_summary(client, ticket_text: str) -> dict:
    response = client.responses.create(
        model="gpt-5.6-terra",
        input=f"Extract a summary and priority (low/medium/high) from:\n\n{ticket_text}",
    )
    return {"summary": "...", "priority": "medium"}  # simplified for illustration

Every caller of get_ticket_summary now has to remember that the returned dictionary has exactly the keys "summary" and "priority", with no compiler or tool ever checking that. A typo like result["priorty"] fails only at runtime, possibly deep inside a code path that is rarely exercised in tests. A typed response model turns this class of bug into something caught immediately, either by your editor or by running the code once.

What a Type Hint Is

A type hint is an annotation attached to a variable, function parameter, or return value that states what type of data is expected there:

def add(a: int, b: int) -> int:
    return a + b

Here, a: int and b: int declare that both parameters should be integers, and -> int declares that the function returns an integer. Python does not enforce these hints at runtime by itself — calling add("1", "2") will not raise an error just because the hints say int. Type hints are read by external tools: your editor (for autocomplete and inline warnings), static type checkers like mypy or pyright (for catching mismatches before running the code), and libraries like Pydantic (for runtime validation, covered below).

This matters because it clarifies what type hints are for: documentation that tools can check, not a runtime guarantee on their own. Runtime enforcement requires an explicit validation step, which is exactly what typed response models provide.

Building a Typed Response Model with a Dataclass

For simple, immutable data with no validation requirements, Python's built-in dataclasses module is often enough:

from dataclasses import dataclass


@dataclass(frozen=True)
class TicketSummary:
    summary: str
    priority: str


def get_ticket_summary(client, ticket_text: str) -> TicketSummary:
    response = client.responses.create(
        model="gpt-5.6-terra",
        input=f"Extract a summary and priority (low/medium/high) from:\n\n{ticket_text}",
    )
    # In a real integration, this step parses the model's structured output
    # (for example, JSON matching a schema) into the fields below.
    return TicketSummary(summary="Customer reports duplicate charge.", priority="medium")

frozen=True makes instances immutable after creation — attempting ticket.summary = "new value" later raises an error. This is a deliberate choice for data that represents a fact retrieved once: nothing downstream should be able to silently mutate a summary that was already computed, which would make debugging inconsistent state far harder.

With this model, result.summary and result.priority are checked by static type checkers and by your editor's autocomplete — result.priorty is flagged immediately as an unknown attribute, instead of failing only when that line finally executes.

Building a Typed Response Model with Pydantic

Dataclasses check types only with external tools; they do not validate data at runtime. Pydantic (already used in Unit 6 for Structured Outputs schemas) adds runtime validation: constructing a model with invalid data raises an exception immediately.

from pydantic import BaseModel, field_validator


class TicketSummary(BaseModel):
    summary: str
    priority: str

    @field_validator("priority")
    @classmethod
    def priority_must_be_known(cls, value: str) -> str:
        allowed = {"low", "medium", "high"}
        if value not in allowed:
            raise ValueError(f"priority must be one of {allowed}, got {value!r}")
        return value

def get_ticket_summary(client, ticket_text: str) -> TicketSummary:
    response = client.responses.create(
        model="gpt-5.6-terra",
        input=f"Extract a summary and priority (low/medium/high) from:\n\n{ticket_text}",
    )
    raw_priority = "urgent"  # simplified stand-in for a parsed model field
    return TicketSummary(summary="Customer reports duplicate charge.", priority=raw_priority)

Calling get_ticket_summary with the raw_priority value "urgent" raises a pydantic.ValidationError immediately, at the point the model is constructed — not later, when some downstream code tries to route the ticket based on an unrecognized priority value and fails in a confusing way. This is the core value of runtime validation: catch bad data as close as possible to where it entered the system, since that is where the error message is most useful.

Why This Matters When the Data Comes From a Model

Type hints matter for any Python code, but they matter more when data originates from an LLM, for a specific reason: the model is not a database schema. Even with Structured Outputs constraining the shape of the response, values within fields (an enum-like string field, a numeric range) can still be wrong in ways a fixed-schema database column cannot be. A typed model with validation is the layer that turns "the model technically returned valid JSON" into "the application received data it can safely act on."

Parsing Structured Outputs Directly Into a Model

When Structured Outputs is used (Unit 6), the SDK can often be pointed directly at a Pydantic model, so the model's own class becomes the schema definition, and the response is returned already parsed:

from openai import OpenAI
from pydantic import BaseModel


class ExtractedTicket(BaseModel):
    summary: str
    priority: str


def extract_ticket(client: OpenAI, ticket_text: str) -> ExtractedTicket:
    response = client.responses.parse(
        model="gpt-5.6-terra",
        input=f"Extract a summary and priority (low/medium/high) from:\n\n{ticket_text}",
        text_format=ExtractedTicket,
    )
    return response.output_parsed

Note: The exact method name and parameter used to request a parsed, schema-bound response (shown here as responses.parse with text_format) is SDK-version-specific. Confirm the current method and parameter names against the installed SDK version before relying on this pattern in production code.

This connects Structured Outputs directly to this lesson's topic: the schema you define for the API request and the type used inside your application become the same class, eliminating a separate manual parsing step and the bugs that step could introduce.

Common Mistakes

Returning dict from every function "for flexibility." This defers every type-related bug to runtime, in whatever code happens to consume the dictionary — often far from where the data originated, making the root cause harder to trace.

Assuming a type hint enforces anything by itself. def f(x: int) does not stop someone from calling f("hello") in plain Python. Enforcement requires either a static type checker in CI, or runtime validation via Pydantic (or manual checks).

Validating in the wrong place. Checking that priority is one of three allowed values deep inside a rendering function, long after the value was extracted, means bad data has already traveled through multiple layers before being caught. Validate at the boundary, in the model itself.

Best Practices

Choose dataclass for simple, trusted internal data; choose Pydantic when data crosses a boundary (from the API, from user input, from a file). The extra validation overhead of Pydantic is worth paying exactly where data can be wrong.

Make models immutable where the data represents a fact already retrieved. frozen=True dataclasses and Pydantic's immutability options (model_config = {"frozen": True}) prevent accidental mutation bugs.

Run a static type checker (mypy or pyright) in CI. Type hints without an enforcing tool are documentation only; a type checker turns them into an automated safety net that catches mismatches before the code ships.

Keep response models close to the service class that produces them. A TicketSummary model belongs next to TicketClassifierService, not in a generic models.py shared by unrelated features — this keeps the model's meaning tied to the code that actually creates it.