DocumentResponse

interface DocumentResponse {
  id: string;           // Document UUID
  team_id: string;      // Team UUID that owns this document
  filename: string;     // Original filename
  size_bytes: number;   // File size in bytes
  created_at: string;   // ISO 8601 timestamp
}

DocumentList

interface DocumentList {
  items: DocumentResponse[];  // List of documents
  total: number;              // Total count
  skip: number;               // Offset
  limit: number;              // Page size
}

JobCreate

interface JobCreate {
  document_id: string;         // UUID of the document to process (required)
  question: string;            // Question to ask about the document (required)
  config?: JobConfig | null;   // Optional processing configuration (default: null)
}

JobConfig

interface JobConfig {
  verify_citations?: boolean;              // Default: true. Whether to verify citations.
  output_schema?: OutputSchemaConfig | null; // Structured output schema configuration
  reasoning_effort?: "auto" | "low" | "high"; // Default: "auto".
                                           // "auto": AI decides analysis depth
                                           // "low": fast, for simple questions
                                           // "high": thorough, for complex analysis
}

OutputSchemaConfig

interface OutputSchemaConfig {
  schema: object;              // JSON Schema (draft-07) defining the output structure (required)
  strict?: boolean;            // Default: true. If true, fail if schema cannot be satisfied;
                               // if false, return partial data.
  include_citations?: boolean; // Default: true. Include citations array in response.
  include_raw_answer?: boolean; // Default: false. Include raw text answer for debugging.
}

Citation

interface Citation {
  page: number;         // Page number
  quote: string;        // Quoted text from the document
  type: string;         // Default: "text". Citation type.
}

JobResult

interface JobResult {
  answer: string;                          // Answer text
  confidence: "high" | "medium" | "low" | "not_found";
  citations: Citation[];                   // Default: []. Supporting citations.
  structured_output?: object | null;       // Default: null. Conforms to the provided
                                           // output_schema if one was given.
}

UsageInfo

interface UsageInfo {
  total_cost_cents: number;  // Total cost in cents.
  llm_cost_cents: number;    // LLM token cost in cents.
  fixed_fee_cents: number;   // Per-call fixed fee in cents.
}

JobResponse

interface JobResponse {
  id: string;                        // Job UUID
  document_id: string;               // Document UUID
  question: string;                  // Question asked
  success: boolean;                  // Whether processing succeeded
  result: JobResult | null;          // Present if success=true
  error: string | null;              // Error message if failed
  processing_time_ms: number;        // Processing time in milliseconds
  usage: UsageInfo | null;           // Cost information
  created_at: string;                // ISO 8601 timestamp
}

JobList

interface JobList {
  items: JobResponse[];   // List of jobs
  total: number;          // Total count
  skip: number;           // Offset
  limit: number;          // Page size
}

SSE Stream Event Types

// Base event
interface StreamEvent {
  event: string;
  message?: string;
}

// Download progress
interface DownloadingEvent extends StreamEvent {
  event: "downloading";
  progress?: number;     // 0-100
}

// Processing progress
interface ProcessingEvent extends StreamEvent {
  event: "processing";
  progress?: number;     // 0-100
  pages_done?: number;
  total_pages?: number;
}

// Agent reasoning
interface ThinkingEvent extends StreamEvent {
  event: "thinking";
  iteration?: number;
}

// Tool execution (also sent as "tool_exec")
interface StepEvent extends StreamEvent {
  event: "step";
}

// Citation verification
interface VerifyingEvent extends StreamEvent {
  event: "verifying";
}

// Final result
interface CompleteEvent extends StreamEvent {
  event: "complete";
  result: object;        // Full processing result
}

// Error
interface ErrorEvent extends StreamEvent {
  event: "error";
  error_code?: string;   // Machine-readable error code
  result?: object;       // Error result details
}

Pagination

All list endpoints follow the same pagination pattern:

• Use skip for offset-based pagination
• Use limit to control page size
• Response includes total for calculating total pages

Example: Fetching page 3 with 10 items per page

GET /api/v1/documents?skip=20&limit=10

Error Response Format

All error responses follow this structure:

{
  "detail": "Error message describing what went wrong"
}

UUID Format

All IDs use UUID v4 format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Timestamps

All timestamps are returned in ISO 8601 format with timezone: 2026-02-02T10:30:00.000Z

Constructor Parameters

Context Managers

Always use a context manager or call close explicitly to release HTTP connections.

# Recommended: context manager
with PuddingClient(access_token="pk_...") as client:
    ...  # client is automatically closed

# Or close manually
client = PuddingClient(access_token="pk_...")
try:
    ...
finally:
    client.close()

# Async equivalent
async with AsyncPuddingClient(access_token="pk_...") as client:
    ...
# or: await client.aclose()

Retry Behavior

The SDK automatically retries on transient failures. Client errors (4xx) are never retried.

DocumentResponse

class DocumentResponse(BaseModel):
    id: str                # Document UUID
    team_id: str           # Team UUID
    filename: str          # Original filename
    size_bytes: int        # File size in bytes
    created_at: datetime   # Creation timestamp

DocumentList

class DocumentList(BaseModel):
    items: list[DocumentResponse] = []
    total: int
    skip: int
    limit: int

HealthResponse / ReadinessResponse

class HealthResponse(BaseModel):
    status: str       # "healthy"
    version: str      # API version
    environment: str  # "production", "staging", etc.

class ReadinessResponse(BaseModel):
    status: str       # "ready" or "not_ready"
    database: str     # "connected" or error message

JobConfig

class JobConfig(BaseModel):
    verify_citations: bool = True                    # Whether to verify citations
    reasoning_effort: str = "auto"                    # "auto", "low", or "high"
    output_schema: OutputSchemaConfig | None = None   # Structured output config

OutputSchemaConfig

class OutputSchemaConfig(BaseModel):
    schema_: dict[str, Any]  # JSON Schema (draft-07). Alias: "schema"
    strict: bool = True              # Fail if schema can't be satisfied
    include_citations: bool = True   # Include citations in response
    include_raw_answer: bool = False # Include raw text answer (debugging)

    # Both work in Python:
    # OutputSchemaConfig(schema={"type": "object", ...})
    # OutputSchemaConfig(schema_={"type": "object", ...})

Citation

class Citation(BaseModel):
    page: int          # Page number
    quote: str         # Quoted text from document
    type: str = "text" # Citation type

JobResult

class JobResult(BaseModel):
    answer: str                                # Answer text
    confidence: str                            # "high", "medium", "low", "not_found"
    citations: list[Citation] = []             # Supporting citations
    structured_output: dict[str, Any] | None = None  # Present when output_schema was provided

UsageInfo

class UsageInfo(BaseModel):
    total_cost_cents: float   # Total cost in cents
    llm_cost_cents: float     # LLM token cost in cents
    fixed_fee_cents: float    # Per-call fixed fee in cents

JobResponse

class JobResponse(BaseModel):
    id: str                          # Job UUID
    document_id: str                 # Document UUID
    question: str                    # Question asked
    success: bool                    # Whether processing succeeded
    result: JobResult | None         # Present if success=True
    error: str | None                # Present if success=False
    processing_time_ms: int          # Processing time in milliseconds
    usage: UsageInfo | None          # Cost information
    created_at: datetime             # Creation timestamp

JobList

class JobList(BaseModel):
    items: list[JobResponse] = []
    total: int
    skip: int
    limit: int

Stream Event Types

# Base class for all stream events
class StreamEvent(BaseModel):
    event: str            # Event type
    message: str = ""     # Event message

class DownloadingEvent(StreamEvent):
    event: str = "downloading"
    progress: int | None = None   # Download progress 0-100

class ProcessingEvent(StreamEvent):
    event: str = "processing"
    progress: int | None = None   # Processing progress 0-100
    pages_done: int | None = None # Pages processed so far
    total_pages: int | None = None # Total pages in document

class ThinkingEvent(StreamEvent):
    event: str = "thinking"
    iteration: int | None = None  # Reasoning iteration number

class StepEvent(StreamEvent):
    event: str = "step"           # Also mapped from "tool_exec" SSE events

class VerifyingEvent(StreamEvent):
    event: str = "verifying"

class CompleteEvent(StreamEvent):
    event: str = "complete"
    result: dict[str, Any]        # Full processing result

class ErrorEvent(StreamEvent):
    event: str = "error"
    error_code: str | None = None      # Machine-readable error code
    result: dict[str, Any] | None = None  # Error result details

Upload and Query a Document

from pudding import PuddingClient

with PuddingClient(access_token="pk_...") as client:
    # Upload
    doc = client.documents.upload(file_path="contract.pdf")
    print(f"Uploaded {doc.filename} (id: {doc.id})")

    # Query
    job = client.jobs.create(
        document_id=doc.id,
        question="What is the termination clause?"
    )

    if job.success:
        print(f"\nAnswer ({job.result.confidence} confidence):")
        print(job.result.answer)
        print(f"\nCitations:")
        for c in job.result.citations:
            print(f"  p.{c.page}: \"{c.quote}\"")

Paginate Through All Documents

from pudding import PuddingClient

with PuddingClient(access_token="pk_...") as client:
    skip = 0
    limit = 50
    while True:
        page = client.documents.list(skip=skip, limit=limit)
        for doc in page.items:
            print(f"{doc.filename} - {doc.created_at}")
        if skip + limit >= page.total:
            break
        skip += limit

Stream Processing Progress

from pudding import (
    PuddingClient,
    DownloadingEvent, ProcessingEvent, ThinkingEvent,
    StepEvent, VerifyingEvent, CompleteEvent, ErrorEvent
)

with PuddingClient(access_token="pk_...") as client:
    doc = client.documents.upload(file_path="large-report.pdf")

    for event in client.jobs.create_stream(
        document_id=doc.id,
        question="List all action items mentioned in the report"
    ):
        match event:
            case DownloadingEvent():
                print(f"⬇️  Downloading: {event.progress}%")
            case ProcessingEvent():
                print(f"📄 Reading pages: {event.pages_done}/{event.total_pages}")
            case ThinkingEvent():
                print(f"🤔 Reasoning (iteration {event.iteration})...")
            case StepEvent():
                print(f"⚙️  {event.message}")
            case VerifyingEvent():
                print(f"🔍 Verifying citations...")
            case CompleteEvent():
                print(f"✅ Done!")
                print(event.result)
            case ErrorEvent():
                print(f"❌ {event.error_code}: {event.message}")

Extract Structured Data

from pudding import PuddingClient, JobConfig, OutputSchemaConfig

with PuddingClient(access_token="pk_...") as client:
    doc = client.documents.upload(file_path="invoice.pdf")

    job = client.jobs.create(
        document_id=doc.id,
        question="Extract the invoice details",
        config=JobConfig(
            output_schema=OutputSchemaConfig(
                schema={
                    "type": "object",
                    "properties": {
                        "invoice_number": {"type": "string"},
                        "date": {"type": "string", "format": "date"},
                        "total_amount": {"type": "number"},
                        "currency": {"type": "string"},
                        "line_items": {
                            "type": "array",
                            "items": {
                                "type": "object",
                                "properties": {
                                    "description": {"type": "string"},
                                    "quantity": {"type": "integer"},
                                    "unit_price": {"type": "number"}
                                }
                            }
                        }
                    },
                    "required": ["invoice_number", "total_amount", "currency"]
                }
            )
        )
    )

    if job.success:
        inv = job.result.structured_output
        print(f"Invoice #{inv['invoice_number']}")
        print(f"Total: {inv['currency']} {inv['total_amount']}")
        for item in inv.get("line_items", []):
            print(f"  {item['description']}: {item['quantity']} x {item['unit_price']}")

Robust Error Handling

from pudding import (
    PuddingClient,
    AuthenticationError,
    ValidationError,
    NotFoundError,
    TimeoutError,
    GatewayError,
    PuddingError,
)

def process_document(api_key: str, file_path: str, question: str):
    with PuddingClient(access_token=api_key, max_retries=5) as client:
        # Upload with validation handling
        try:
            doc = client.documents.upload(file_path=file_path)
        except ValidationError as e:
            print(f"Invalid file: {e.message}")
            return
        except AuthenticationError:
            print("Check your API key")
            return

        # Process with retry-aware error handling
        try:
            job = client.jobs.create(
                document_id=doc.id,
                question=question,
                timeout=600  # 10 minutes
            )
        except TimeoutError:
            print("Processing timed out — document may be too large")
            return
        except GatewayError:
            print("Processing service unavailable — please retry later")
            return
        except PuddingError as e:
            print(f"Unexpected error [{e.status_code}]: {e.message}")
            return

        if job.success:
            return job.result
        else:
            print(f"Job failed: {job.error}")
            return None

Async Batch Processing

import asyncio
from pudding import AsyncPuddingClient

async def ask_questions(doc_id: str, questions: list[str]):
    async with AsyncPuddingClient(access_token="pk_...") as client:
        tasks = [
            client.jobs.create(document_id=doc_id, question=q)
            for q in questions
        ]
        results = await asyncio.gather(*tasks, return_exceptions=True)

        for question, result in zip(questions, results):
            if isinstance(result, Exception):
                print(f"Q: {question} → Error: {result}")
            elif result.success:
                print(f"Q: {question} → {result.result.answer[:80]}...")

asyncio.run(ask_questions(
    doc_id="...",
    questions=[
        "What is the executive summary?",
        "What are the key risks?",
        "What is the financial outlook?",
    ]
))