Lesson 30 — Beginner

Structured Outputs — JSON & Schemas

Production code ko chahiye guaranteed parse-able data — JSON jo hamesha schema fit ho. Is lesson mein hum "sirf JSON do" prompt ki limit, schema-constrained generation, JSON mode, Pydantic schemas aur generate → validate → repair workflow dekhenge.

Structured output kya hai

Level teen hain: prompt-level ("sirf JSON likho" — koi guarantee nahi), JSON mode (syntax valid hoga, schema nahi), schema-constrained (jawab diye gaye schema mein hi banega). Production ke liye aakhri wala.

Schemas — JSON Schema aur Pydantic

from pydantic import BaseModel, Field
from typing import Optional
from enum import Enum

class Urgency(str, Enum):
    low = "low"
    medium = "medium"
    high = "high"

class Ticket(BaseModel):
    ticket_id: str                       # required
    category: str                        # required
    urgency: Urgency                     # enum — sirf 3 values chalengi
    summary: str
    needs_human: bool = False            # optional with default
    tags: list[str] = []                 # list
    customer: Optional[dict] = None      # nested, optional

print(Ticket.model_json_schema())       # provider ko yahi chahiye

• JSON Schema common language hai — Pydantic, provider SDK aur LangChain sab isi format se schema bhejte hain.
• Required vs optional: required fields ke bina model ko majboori hai value deni; optional mein default chal sakta hai.
• Enums values ko rokte hain — "urgent" jaisi apni value model nahi bana payega jab high/medium/low hi diye hain.
• Nested objects aur lists bhi schema mein aate hain — extraction tasks mein yehi structure tumhare DB tables jaisa hota hai.
• Schema define ek hi jagah karo — validation, API call aur docs teeno usi se bante hain (single source of truth).

JSON mode vs schema-constrained

# LEVEL 2 — JSON mode: syntax valid JSON milega, schema ki guarantee nahi
resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=messages,
    response_format={"type": "json_object"},
)

# LEVEL 3 — schema-constrained: jawab diye gaye schema mein hi banega
schema = Ticket.model_json_schema()
resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=messages,
    response_format={
        "type": "json_schema",
        "json_schema": {"name": "ticket", "schema": schema, "strict": True},
    },
)

# LANGCHAIN — same cheez ek line mein
structured_llm = llm.with_structured_output(Ticket)
ticket = structured_llm.invoke("Refund wala ticket: ORD-4821, urgent")

• JSON mode bhi useful hai — garbled prose ke bajaye kam se kam parse-able JSON toh aayega. Schema validation phir bhi chahiye.
• Schema-constrained mode strict hota hai — galat type, missing required key, enum se bahar value generate hi nahi hoti.
• Exact parameter naming provider-wise alag hoti hai — apni provider ki docs mein response_format / structured output section padho, ratte mat maaro.
• LangChain ka with_structured_output wahi kaam karta hai — niche wahi schema call jaati hai.

Generate → validate → accept / repair / reject

from pydantic import ValidationError

def generate_ticket(text, retries=2):
    messages = [{"role": "user", "content": f"Classify: {text}"}]
    for attempt in range(retries + 1):
        raw = call_structured(messages)               # schema-forced call
        try:
            return Ticket.model_validate_json(raw)     # ACCEPT
        except ValidationError as e:
            if attempt == retries:
                break                                  # REJECT
            messages.append({"role": "assistant", "content": raw})
            messages.append({"role": "user", "content":
                f"Ye JSON schema se match nahi hua:\n{e}\nSahi karo."})  # REPAIR
    raise ValueError("schema ke bahar jawab — fallback bhejo")

• Accept sirf tab jab Pydantic parse ho jaye — warna raw string ko kabhi DB mein mat ghusao.
• Repair = validation error de kar dobara mangwana. Chhote errors par yeh aksar ek hi attempt mein theek ho jaata hai.
• Reject = retries khatam, fallback path chalao (canned response, human queue) — infinite retry kabhi nahi.
• Syntactic ke baad semantic checks bhi likho: business rules jo schema mein nahi aate (order id ka prefix, amount ka limit).

Exercise

Common mistakes

• Sirf prompt mein "sirf JSON" likh dena: — kabhi kabhi poora explanation aa jaata hai, kabhi extra text ke saath JSON. API ka JSON/schema mode use karo; prompt sirf last line of defence hai.
• Syntactic validity ko truth maanna: — valid JSON ke andar galat values ho sakti hain (wrong amount, invented date). Business-rule validation alag se likho.
• Validation ke bina data DB mein daal dena: — parse fail par pipeline crash ya silent garbage. Try/except rakho, raw output log karo, phir hi aage badho.
• Schema aur code do alag jagah rakhna: — schema badla, validation code purana reh gaya. Pydantic model ko hi source of truth banao, dono isi se generate karo.

# Chitthi (prompt-only): tum khud padho, tum khud guess karo
line = "Urgency high hai, billing issue, jaldi dekho"

# Form (schema): har box ka naam aur type fix
form = {"ticket_id": "T-42", "category": "BILLING", "urgency": "high"}
Ticket.model_validate(form)   # box ke bahar kuch nahi ja sakta