Skip to content

Pydantic-First Development

  • The Law

    Everything starts in tribrid_config_model.py. If it’s not there, it does not exist.

  • Generate Types

    uv run scripts/generate_types.py produces web/src/types/generated.ts.

  • Derivation Chain

    Pydantic → generated.ts → stores → hooks → components.

Get started Configuration API

Workflow

  • Add/modify fields in Pydantic with Field() constraints and descriptions.
  • Generate TS types.
  • Use types in stores/hooks/components.
  • Implement backend behavior that uses those fields.

Constraints

Use Field(ge=..., le=..., description=...) everywhere. Descriptions power docs and UI tooltips.

No Adapters

Never write client-side adapters to change response shapes. Fix the Pydantic model instead and regenerate.

Derivation Chain

flowchart TB
    P["Pydantic\ntribrid_config_model.py"] --> G["pydantic2ts\n(generate_types.py)"]
    G --> T["generated.ts"]
    T --> Z["Zustand Stores"]
    Z --> H["Hooks"]
    H --> C["Components"]
    P --> A["FastAPI Schemas"]

Commands (Annotated)

import subprocess

# Generate TS types from Pydantic (1)
subprocess.check_call(["uv", "run", "scripts/generate_types.py"])  # (1)

# Validate sync (2)
subprocess.check_call(["uv", "run", "scripts/validate_types.py"])  # (2)

# Run locally with Python; no direct curl equivalent

// After generation, import from generated.ts (3)
import type { TriBridConfig } from '../web/src/types/generated'; // (3)
  1. Generate TypeScript types from Pydantic models
  2. Validate that generated types match current models
  3. Consume generated types exclusively

Ralph Loop (Verification-Based Development)

  • Start from repo root
  • For each iteration: pick first unchecked TODO, implement end-to-end
  • Verification sequence:
  • uv run scripts/check_banned.py
  • uv run scripts/validate_types.py
  • uv run pytest -q
  • Only mark TODO complete when verification passes
flowchart TB
    Iteration["Ralph Loop Iteration"] --> TODO["Read TODO.md"]
    TODO --> Implement["Implement Feature"]
    Implement --> Verify["Run Verification"]
    Verify -->|pass| Next["Next Iteration"]
    Verify -->|fail| Fix["Fix Exact Failure"]
Testing Discipline
  • GUI changes: Playwright tests with real interactions
  • API changes: pytest with real request/response assertions
  • Retrieval logic: verify relevance in results