Enforcing Schema Constraints: The Pydantic Shield

In Module 13.1, we introduced "JSON Mode." But simply asking for JSON isn't enough. Models often "Create" their own keys or add conversational keys like "message": "Here is your JSON:". These "Ghost Keys" waste tokens and crash your parsers.

Pydantic is the key to building Deterministic AI. By defining a strict schema, you force the model to stick to the pre-approved keys, ensuring and token efficiency.

In this lesson, we learn how to use Pydantic + Instructor to build "Gated" outputs that are guaranteed to use the minimum required tokens.

---

1. What is Schema Hallucination?

When a model is unsure, it fills the space with "Semantic Junk."

• Expected: {"sku": 123} (10 tokens).
• Hallucinated: {"SKU_ID": 123, "description": "This is the SKU for the blue shirt.", "confidence": 0.99} (50 tokens).

Pydantic prevents this by providing a strict template that the model uses during the "Token Generation" weighting process (if using response_format).

---

2. Defining "Minimal" Schemas

Treat your Pydantic models like Infrastructure code.

Wasteful Model:

from pydantic import BaseModel

class User(BaseModel):
    first_name: str
    last_name: str
    biography_summary: str # 500 words of bloat

Efficient Model:

from pydantic import BaseModel, constr

class User(BaseModel):
    f: str # First Name
    l: str # Last Name
    s: constr(max_length=50) # Summary (Capped!)

By adding Constraints (max_length), you mathematically prevent the model from spending more than its allotted token budget on any specific field.

---

3. Implementation: Using 'Instructor' (Python)

The Instructor library is the industry standard for mapping LLMs to Pydantic.

Python Code: Forced Brevity with Instructor

import instructor
from openai import OpenAI

client = instructor.patch(OpenAI())

class TaskSummary(BaseModel):
    # Enforcing strict types and lengths saves tokens
    status: Literal["DONE", "PENDING", "ERROR"]
    id: int
    msg: constr(max_length=20)

# The model is now FORCED to follow this schema
# It cannot output conversational fluff because 'Instructor' 
# uses the schema to guide the token probability.
summary = client.chat.completions.create(
    model="gpt-4o",
    response_model=TaskSummary,
    messages=[{"role": "user", "content": "Did I finish the job?"}]
)

print(summary.status)

---

4. The "Zero-Key" Strategy for Booleans

If you only need a Yes/No answer, don't use JSON. Inefficient: {"answer": true} (7 tokens). Efficient: 1 (1 token).

Use Pydantic to map 1 and 0 back into Pythonic Booleans. Across 1 million classifications, this simple "Binary Mapping" saves 6 million tokens.

---

5. Summary and Key Takeaways

1. Schemas are Speed: Strict templates prevent the model from "Exploring" new tokens.
2. Minify keys: Use single letters for keys to save on every turn.
3. Pydantic Constraints: Use constr(max_length=X) to put a hard cap on field verbosity.
4. Tool-Schema Alignment: Ensure your Internal Code and your AI Prompts use exactly the same "Minified" keys.

In the next lesson, Handling Malformed Output Efficiently, we look at چگونه to handle the errors without starting a 10,000-token retry loop.

---

Exercise: The Schema Squeeze

1. Take a requirement to extract "Name, Email, and Phone" from a signature.
2. Design a Pydantic Model.
3. Apply max_length and min_length constraints.
4. Test: Paste a signature that includes a 500-word disclaimer.
5. Analyze: Did the model extract the data correctly? Did it ignore the disclaimer?

• Result: Pydantic usually acts as a "Filter," focusing the model's energy only on the fields defined in the code.

---

Congratulations on completing Module 13 Lesson 3! You are now a schema scientist.