{"title":"Type Hints and Pydantic","description":"","content":"AI systems move data across boundaries you do not fully control: user input, provider APIs, JSON files, queues, databases, tool calls, and model-generated structured output. Type hints make the expected shape of that data visible in code. Pydantic checks real data at runtime.\n\nType hints do not make Python a statically typed language. They document intent, improve editor help, and let tools such as mypy or pyright catch many mistakes before you run the code. Pydantic uses similar annotations to validate actual input, which is what you need when a request body, environment variable, or model response may not match your expectations.\n\nThis chapter covers practical type hints and Pydantic v2 patterns for AI applications.\n\n---\n\n# Python Type Hints: The Basics\n\nType hints were introduced in Python 3.5 through PEP 484. They are optional, and ordinary Python does not reject a value just because it violates an annotation.\n\nThey are still worth using because your tools understand them. IDEs use type hints for autocomplete and inline help. Static analyzers use them to catch likely mistakes before runtime. Libraries such as Pydantic and FastAPI use them as the basis for validation and API schemas.\n\n### Annotating Variables and Functions\n\nThe syntax is straightforward. A colon after a variable or parameter name, followed by the type:\n\n\n**main.py**\n\n```python\nname: str = \"large-model\"\ntemperature: float = 0.7\nmax_output_tokens: int = 1024\nis_streaming: bool = False\n\ndef format_prompt(system_message: str, user_query: str) -> str:\n return f\"System: {system_message}\\nUser: {user_query}\"\n\ntemperature = \"hot\" # No error, but mypy will flag it\n```\n\n\nThe `-> str` after the parameter list is the return type annotation. It tells readers and tools what the function is expected to return.\n\n### Collection Types\n\nFor lists, dicts, sets, and tuples, annotate the contents too. Since Python 3.9, you can use the built-in collection types directly.\n\n\n**main.py**\n\n```python\ntags: list[str] = [\"rag\", \"embeddings\", \"retrieval\"]\ntoken_counts: dict[str, int] = {\"input\": 150, \"output\": 320}\nunique_models: set[str] = {\"large-model\", \"small-model\", \"local-model\"}\ncoordinates: tuple[float, float] = (37.7749, -122.4194)\n\nfrom typing import List, Dict, Set, Tuple\ntags: List[str] = [\"rag\", \"embeddings\", \"retrieval\"]\n```\n\n\nThe key difference from untyped code is that `list[str]` tells tools every element should be a string. That helps autocomplete, static checks, and reviews.\n\n---\n\n# Optional, Union, and None Types\n\nIn production AI code, values are often missing. A model response might omit a field. A configuration value might be unset. You need a way to say, \"this may be a string, or it may be `None`.\"\n\n### Optional\n\n`Optional[str]` means `str` or `None`.\n\n\n**main.py**\n\n```python\nfrom typing import Optional\n\ndef call_llm(\n prompt: str,\n system_message: Optional[str] = None,\n temperature: Optional[float] = None,\n) -> str:\n if system_message is not None:\n messages = [{\"role\": \"system\", \"content\": system_message}]\n else:\n messages = []\n messages.append({\"role\": \"user\", \"content\": prompt})\n\n return \"response\"\n```\n\n\n### Union\n\n`Optional[str]` is shorthand for `Union[str, None]`. `Union` is more general: it works with any combination of accepted types.\n\n\n**main.py**\n\n```python\nfrom typing import Union\n\ndef normalize_token_count(value: Union[int, str]) -> int:\n if isinstance(value, str):\n return int(value)\n return value\n```\n\n\n### Python 3.10+ Syntax\n\nStarting with Python 3.10, you can use the pipe operator `|` instead of `Union`. It is shorter and easier to read:\n\n\n**main.py**\n\n```python\ndef normalize_token_count(value: int | str) -> int:\n if isinstance(value, str):\n return int(value)\n return value\n\nsystem_message: str | None = None\n```\n\n\nUse the `|` syntax when your project targets Python 3.10 or newer. Use `Optional` and `Union` when you need compatibility with older Python versions.\n\n---\n\n# Type Aliases, TypeVar, and Generics\n\nAs annotations get more complex, they can start to hide the code they are meant to clarify. Type aliases and generics help keep them readable.\n\n### Type Aliases\n\nA type alias gives a name to a type. Use it when the same shape appears in several places:\n\n\n**main.py**\n\n```python\nfrom typing import TypeAlias\n\ndef process(messages: list[dict[str, str | list[dict[str, str]]]]) -> None:\n ...\n\nMessage: TypeAlias = dict[str, str | list[dict[str, str]]]\n\ndef process(messages: list[Message]) -> None:\n ...\n```\n\n\nIn Python 3.12 and newer, the `type` statement is the newer way to define aliases. In code that still targets Python 3.10 or 3.11, `TypeAlias` remains common. AI code often creates aliases for chat messages, embedding vectors, token sequences, and similar repeated shapes:\n\n\n**main.py**\n\n```python\nEmbedding: TypeAlias = list[float]\nChatMessage: TypeAlias = dict[str, str]\nTokenSequence: TypeAlias = list[int]\n```\n\n\n### TypeVar and Generics\n\n`TypeVar` lets you write reusable functions while preserving a relationship between input and output types.\n\n\n**main.py**\n\n```python\nfrom typing import TypeVar\n\nT = TypeVar(\"T\")\n\ndef first_element(items: list[T]) -> T:\n return items[0]\n\nname: str = first_element([\"large-model\", \"small-model\"])\ncount: int = first_element([100, 200, 300])\n```\n\n\nYou can also constrain a `TypeVar` to specific types:\n\n\n**main.py**\n\n```python\nfrom typing import TypeVar\n\nModelId = TypeVar(\"ModelId\", str, int)\n\ndef normalize_model_id(value: ModelId) -> ModelId:\n return value\n```\n\n\n### Generic Classes\n\nYou can also create generic classes. This pattern shows up in libraries that return the same kind of container for different data types:\n\n\n**main.py**\n\n```python\nfrom typing import Generic, TypeVar\n\nT = TypeVar(\"T\")\n\nclass BatchResult(Generic[T]):\n def __init__(self, items: list[T], total: int) -> None:\n self.items = items\n self.total = total\n\n def first(self) -> T:\n return self.items[0]\n\nstring_batch = BatchResult[str](items=[\"hello\", \"world\"], total=2)\nint_batch = BatchResult[int](items=[42, 99], total=2)\n```\n\n\nYou do not need to master generics on day one. It is enough to recognize the pattern when you see it in SDKs, frameworks, and type checker output.\n\n---\n\n# Pydantic: Runtime Validation from Type Hints\n\nType hints alone are advisory. Pydantic changes that at the boundary where you instantiate or validate a model. It reads your annotations, checks incoming data, applies its configured parsing rules, and raises structured errors when something does not match.\n\nThat is why Pydantic appears so often in Python AI systems. FastAPI uses it for request and response models. AI SDKs and orchestration libraries use it for configuration, tool schemas, and structured outputs. If data crosses a trust boundary, a Pydantic model is often a good place to validate it.\n\n\n```shell\npip install pydantic\n```\n\n\n### Defining a Model\n\nA Pydantic model is a class that inherits from `BaseModel`. Each field is a class attribute with a type annotation:\n\n\n**main.py**\n\n```python\nfrom pydantic import BaseModel\n\nclass LLMConfig(BaseModel):\n model: str\n temperature: float\n max_output_tokens: int\n stream: bool = False\n\nconfig = LLMConfig(\n model=\"large-model\",\n temperature=0.7,\n max_output_tokens=1024,\n)\nprint(config.model) # \"large-model\"\nprint(config.temperature) # 0.7\nprint(config.stream) # False\n```\n\n\nSo far, this looks similar to a dataclass. The difference shows up when incoming data does not match the declared types.\n\n### Automatic Validation and Coercion\n\nPydantic validates each field against its type annotation. If data does not match, you get a detailed error. By default, Pydantic also parses common input forms, such as `\"1024\"` into `1024` for an integer field:\n\n\n**main.py**\n\n```python\nconfig = LLMConfig(\n model=\"large-model\",\n temperature=\"0.7\",\n max_output_tokens=\"1024\",\n)\nprint(type(config.temperature)) # \n\ntry:\n bad_config = LLMConfig(\n model=\"large-model\",\n temperature=\"hot\",\n max_output_tokens=1024,\n )\nexcept Exception as e:\n print(e)\n```\n\n\nThis matters because AI applications receive data from many sources: users, API responses, config files, environment variables, queues, databases, and model outputs. Each source has its own quirks. Pydantic gives you one place to parse and validate that data before the rest of the application trusts it.\n\nHere is how the validation pipeline works:\n\n\n```mermaid\nflowchart LR\n A[Raw Input
dict, JSON, kwargs]:::orange --> B[Type Checking
& Coercion]:::primary\n B --> C{Valid?}:::primary\n C -->|Yes| D[Typed Pydantic
Model Instance]:::green\n C -->|No| E[ValidationError
with Details]:::red\n D --> F[model_dump
to dict]:::teal\n D --> G[model_dump_json
to JSON string]:::teal\n\n classDef primary fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n classDef red fill:#ff8787,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n```\n\n\nRaw input enters from the left. Pydantic checks fields and applies parsing rules. If everything passes, you get a model instance with typed attributes. If not, you get a `ValidationError` that points to the field that failed. Once you have a model instance, you can serialize it back to a dict or JSON string.\n\n### Field() for Constraints and Metadata\n\nThe `Field()` function gives you more control over a field: defaults, validation constraints, descriptions, and schema metadata.\n\n\n**main.py**\n\n```python\nfrom pydantic import BaseModel, Field\n\nclass LLMConfig(BaseModel):\n model: str = Field(description=\"The model identifier.\")\n temperature: float = Field(\n default=0.7,\n ge=0.0,\n le=2.0,\n description=\"Sampling temperature. Higher = more creative.\"\n )\n max_output_tokens: int = Field(\n default=1024,\n ge=1,\n le=128000,\n description=\"Maximum output tokens in the response.\"\n )\n system_prompt: str = Field(\n default=\"You are a helpful assistant.\",\n min_length=1,\n max_length=10000,\n description=\"The system prompt sent to the model.\"\n )\n\ntry:\n config = LLMConfig(model=\"large-model\", temperature=5.0)\nexcept Exception as e:\n print(e)\n```\n\n\nCommon Field constraints:\n\n\n| Constraint | Applies To | Meaning |\n|------------|-----------|---------|\n| `ge`, `gt` | Numbers | Greater than or equal / greater than |\n| `le`, `lt` | Numbers | Less than or equal / less than |\n| `min_length`, `max_length` | Strings, Lists | Minimum / maximum length |\n| `pattern` | Strings | Regex pattern the value must match |\n| `default` | Any | Default value if not provided |\n| `description` | Any | Human-readable description (shows up in JSON Schema) |\n\n\nDescriptions are useful because they become part of the JSON Schema generated from the model. Structured-output systems can use that schema to describe the expected fields.\n\n---\n\n# Nested Models\n\nReal data is rarely flat. A model response may contain messages, tool calls, token usage, citations, or safety metadata. Pydantic handles nesting naturally: use one model as a field type inside another.\n\n\n**main.py**\n\n```python\nfrom pydantic import BaseModel, Field\n\nclass Message(BaseModel):\n role: str\n content: str\n\nclass TokenUsage(BaseModel):\n prompt_tokens: int\n completion_tokens: int\n total_tokens: int\n\nclass Choice(BaseModel):\n index: int\n message: Message\n finish_reason: str\n\nclass LLMResponse(BaseModel):\n id: str\n model: str\n choices: list[Choice]\n usage: TokenUsage\n created: int\n\nresponse = LLMResponse(\n id=\"chatcmpl-abc123\",\n model=\"large-model\",\n choices=[\n {\n \"index\": 0,\n \"message\": {\"role\": \"assistant\", \"content\": \"Hello!\"},\n \"finish_reason\": \"stop\",\n }\n ],\n usage={\"prompt_tokens\": 10, \"completion_tokens\": 5, \"total_tokens\": 15},\n created=1700000000,\n)\n\nprint(response.choices[0].message.content) # \"Hello!\"\nprint(response.usage.total_tokens) # 15\n```\n\n\nYou can pass raw dictionaries for nested models, and Pydantic converts them into model instances. This is especially useful when parsing JSON responses from APIs.\n\n---\n\n# Custom Validators\n\nSometimes type checking and field constraints are not enough. You may need to normalize text, reject unsupported values, or check that two fields make sense together. Pydantic provides validators for that.\n\n### Field Validators\n\nA `@field_validator` runs for one field. It receives the value and can return a cleaned value or raise an error:\n\n\n**main.py**\n\n```python\nfrom pydantic import BaseModel, field_validator\n\nclass EmbeddingRequest(BaseModel):\n text: str\n model: str\n dimensions: int = 1536\n\n @field_validator(\"text\")\n @classmethod\n def text_must_not_be_empty_or_whitespace(cls, v: str) -> str:\n if not v.strip():\n raise ValueError(\"text must contain non-whitespace characters\")\n return v.strip()\n\n @field_validator(\"model\")\n @classmethod\n def model_must_be_supported(cls, v: str) -> str:\n supported = {\"text-embedding-3-small\", \"text-embedding-3-large\"}\n if v not in supported:\n raise ValueError(f\"model must be one of {sorted(supported)}\")\n return v\n```\n\n\nThe validator returns the value Pydantic should store. If it raises a `ValueError`, Pydantic includes that message in the validation error.\n\n### Model Validators\n\nA `@model_validator` can run on the whole model. This is useful for cross-field validation:\n\n\n**main.py**\n\n```python\nfrom typing import Self\n\nfrom pydantic import BaseModel, model_validator\n\nclass GenerationConfig(BaseModel):\n temperature: float = 0.7\n top_p: float = 1.0\n top_k: int | None = None\n\n @model_validator(mode=\"after\")\n def check_sampling_consistency(self) -> Self:\n if self.temperature == 0 and self.top_p < 1.0:\n raise ValueError(\n \"When temperature is 0 (greedy), top_p should be 1.0 \"\n \"since sampling is disabled.\"\n )\n return self\n```\n\n\nThe `mode=\"after\"` validator runs after fields are validated and receives the model instance. Pydantic also supports `mode=\"before\"` validators for working with raw input before field validation.\n\n---\n\n# Serialization: Getting Data Out\n\nGetting data into Pydantic models is only half the story. You also need to get data out as dictionaries for database inserts, JSON strings for API responses, or validated model instances from raw data.\n\n### model_dump() and model_dump_json()\n\n\n**main.py**\n\n```python\nfrom pydantic import BaseModel\n\nclass ChunkMetadata(BaseModel):\n source: str\n page: int\n chunk_index: int\n token_count: int\n\nmetadata = ChunkMetadata(\n source=\"architecture_patterns.pdf\",\n page=42,\n chunk_index=7,\n token_count=256,\n)\n\nd = metadata.model_dump()\nprint(d)\n\nj = metadata.model_dump_json()\nprint(j)\n\nd = metadata.model_dump(exclude={\"chunk_index\"})\nprint(d)\n```\n\n\n### model_validate() and model_validate_json()\n\nGoing the other direction, use `model_validate()` for dictionaries and `model_validate_json()` for JSON strings:\n\n\n**main.py**\n\n```python\ndata = {\"source\": \"notes.pdf\", \"page\": 1, \"chunk_index\": 0, \"token_count\": 128}\nmetadata = ChunkMetadata.model_validate(data)\n\njson_str = '{\"source\": \"notes.pdf\", \"page\": 1, \"chunk_index\": 0, \"token_count\": 128}'\nmetadata = ChunkMetadata.model_validate_json(json_str)\n```\n\n\nThis pattern is common: receive JSON from an API, validate it into a model, work with typed attributes, then serialize it back out when needed.\n\n---\n\n# Pydantic Settings for Configuration\n\nAI applications have a lot of configuration: API keys, model names, temperature defaults, chunk sizes, database URLs, and vector-store endpoints. Pydantic Settings loads these values from environment variables and `.env` files with validation.\n\n\n```shell\npip install pydantic-settings\n```\n\n\n\n**main.py**\n\n```python\nfrom pydantic_settings import BaseSettings, SettingsConfigDict\nfrom pydantic import Field, SecretStr\n\nclass AppSettings(BaseSettings):\n api_key: SecretStr\n\n default_model: str = \"large-model\"\n\n embedding_model: str = \"text-embedding-3-small\"\n\n chunk_size: int = Field(default=512, ge=100, le=8000)\n chunk_overlap: int = Field(default=50, ge=0)\n temperature: float = Field(default=0.7, ge=0.0, le=2.0)\n\n database_url: str = \"sqlite:///app.db\"\n qdrant_url: str = \"http://localhost:6333\"\n\n model_config = SettingsConfigDict(\n env_file=\".env\",\n env_file_encoding=\"utf-8\",\n case_sensitive=False,\n )\n\nsettings = AppSettings()\nprint(settings.chunk_size)\n\napi_key = settings.api_key.get_secret_value()\n```\n\n\nThis replaces scattered `os.getenv()` calls with one validated settings object. `SecretStr` hides the raw secret in logs and `repr()` output. If a required API key is missing, startup fails with a clear validation error instead of a `None` value surfacing later in the pipeline.\n\nYour `.env` file looks like this:\n\n\n```shell\nAPI_KEY=sk-your-key-here\nDEFAULT_MODEL=large-model\nCHUNK_SIZE=1024\nTEMPERATURE=0.3\n```\n\n\n---\n\n# Structured LLM Output Schema\n\nA common AI engineering pattern is to define a Pydantic model for the structure you want back from an LLM, then use that schema for structured output and validation.\n\nHere is an example: extracting structured information from a technical document.\n\n\n**main.py**\n\n```python\nfrom pydantic import BaseModel, Field\n\nclass CodeExample(BaseModel):\n language: str = Field(description=\"Programming language of the code snippet.\")\n code: str = Field(description=\"The code snippet.\")\n explanation: str = Field(description=\"What the code does, in one sentence\")\n\nclass KeyConcept(BaseModel):\n name: str = Field(description=\"Name of the concept.\")\n definition: str = Field(description=\"Clear, one-paragraph definition.\")\n relevance: str = Field(\n description=\"Why this concept matters in practice.\",\n )\n\nclass DocumentAnalysis(BaseModel):\n title: str = Field(description=\"Title or main topic of the document.\")\n summary: str = Field(\n description=\"Two or three sentence summary of the document.\",\n min_length=20,\n )\n key_concepts: list[KeyConcept] = Field(\n description=\"The three to five most important concepts discussed.\",\n min_length=1,\n max_length=5,\n )\n code_examples: list[CodeExample] = Field(\n default_factory=list,\n description=\"Code examples found in the document, if any.\",\n )\n difficulty_level: str = Field(\n description=\"One of: beginner, intermediate, advanced.\",\n )\n prerequisites: list[str] = Field(\n default_factory=list,\n description=\"Topics the reader should know beforehand.\",\n )\n```\n\n\nYou can pass this schema to an LLM using a structured-output API. The field descriptions document the expected output, and the constraints (`min_length`, `max_length`) are checked when the response is parsed.\n\nHere is how this model looks with the OpenAI Python SDK's Responses API:\n\n\n**main.py**\n\n```python\nfrom openai import OpenAI\n\nclient = OpenAI()\n\nresponse = client.responses.parse(\n model=\"gpt-5.5\",\n input=[\n {\"role\": \"system\", \"content\": \"Analyze the given document.\"},\n {\"role\": \"user\", \"content\": document_text},\n ],\n text_format=DocumentAnalysis,\n)\n\nanalysis: DocumentAnalysis = response.output_parsed\nprint(analysis.title)\nprint(analysis.key_concepts[0].name)\nprint(analysis.model_dump_json(indent=2))\n```\n\n\nThe SDK parses the model output into the `DocumentAnalysis` schema. Pydantic validates it, and your application receives a typed object with attribute access and serialization. You still need application-level handling for refusals, empty inputs, and domain-specific quality checks, but you are no longer parsing free-form text with regular expressions.\n\nThis pattern is useful for tool arguments, extraction pipelines, evaluators, and any workflow that expects structured model output.\n\n---\n\n# Quiz\n\n---\n\n### References\n\n- [PEP 484 - Type Hints](https://peps.python.org/pep-0484/) - The original Python type hints specification\n- [Pydantic Documentation](https://docs.pydantic.dev/latest/) - Official Pydantic v2 docs with full API reference\n- [Pydantic Settings Documentation](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) - Loading config from environment variables and .env files\n- [mypy Documentation](https://mypy.readthedocs.io/en/stable/) - Static type checker for Python\n- [Python typing Module](https://docs.python.org/3/library/typing.html) - Standard library typing reference","pageType":"ai-engineering"}

Get Premium