gh-cskiro-claudex-api-tools/skills/json-outputs-implementer/reference/use-cases.md

Common Use Cases

Use Case 1: Data Extraction

Scenario: Extract invoice data from text/images

from pydantic import BaseModel
from typing import List

class LineItem(BaseModel):
    description: str
    quantity: int
    unit_price: float
    total: float

class Invoice(BaseModel):
    invoice_number: str
    date: str
    customer_name: str
    line_items: List[LineItem]
    subtotal: float
    tax: float
    total_amount: float

response = client.beta.messages.parse(
    model="claude-sonnet-4-5",
    betas=["structured-outputs-2025-11-13"],
    max_tokens=2048,
    messages=[{"role": "user", "content": f"Extract invoice:\n{invoice_text}"}],
    output_format=Invoice,
)

invoice = response.parsed_output
# Insert into database with guaranteed types
db.insert_invoice(invoice.model_dump())

Use Case 2: Classification

Scenario: Classify support tickets

class TicketClassification(BaseModel):
    category: str  # "billing", "technical", "sales"
    priority: str  # "low", "medium", "high", "critical"
    confidence: float
    requires_human: bool
    suggested_assignee: Optional[str] = None
    tags: List[str]

response = client.beta.messages.parse(
    model="claude-sonnet-4-5",
    betas=["structured-outputs-2025-11-13"],
    messages=[{"role": "user", "content": f"Classify:\n{ticket}"}],
    output_format=TicketClassification,
)

classification = response.parsed_output
if classification.requires_human or classification.confidence < 0.7:
    route_to_human(ticket)
else:
    auto_assign(ticket, classification.category)

Use Case 3: API Response Formatting

Scenario: Generate API-ready responses

class APIResponse(BaseModel):
    status: str  # "success" or "error"
    data: dict
    errors: Optional[List[dict]] = None
    metadata: dict

response = client.beta.messages.parse(
    model="claude-sonnet-4-5",
    betas=["structured-outputs-2025-11-13"],
    messages=[{"role": "user", "content": f"Process: {request}"}],
    output_format=APIResponse,
)

# Directly return as JSON API response
return jsonify(response.parsed_output.model_dump())