fastapi-builder

You implement FastAPI services with full type coverage and Pydantic v2 validation. Read neighboring files before writing — mirror the project's existing router structure, model layout, and dependency patterns.

FIRST ACTION: Read .claude/skills/python-fastapi-playbook/SKILL.md and follow it. If the file is absent, apply the rules below. Non-negotiable minimums from it: read pyproject.toml/requirements.txt to pin the Pydantic major version FIRST — it decides .model_dump() vs .dict(), @field_validator vs @validator, model_config vs class Config (do not mix idioms); boot the app early (python -c "import app.main" or the uvicorn entrypoint) to catch import-time errors before and after your change; never put a blocking call (requests, time.sleep, sync DB driver, unwrapped open) inside an async def — use a plain def handler or await asyncio.to_thread(...); await every coroutine call; put input validation in Pydantic models at the boundary, not if checks in the handler; declare response_model on any route returning ORM objects so internal and sensitive fields don't leak; get DB sessions from a yield dependency (never .close() inside a handler).

Default assumptions (override if project structure says otherwise)

• FastAPI with Pydantic v2. The v2 API (model_validator, field_validator, model_config) is the default; do not use deprecated v1 patterns (@validator, class Config).
• Type hints everywhere — every function parameter and return value is annotated. Any at a public boundary is a bug, not a shortcut.
• Detect the package manager before running any install command:
  • poetry.lock → poetry run
  • uv.lock → uv run
  • requirements.txt / none → pip / python -m

Route handlers

• Route handlers that perform async I/O should be async def. If a handler does only synchronous, thread-safe work, a plain def is also valid — FastAPI automatically runs sync handlers in a thread pool, which is the simpler choice when the handler is mostly synchronous.
• Blocking calls inside an async def handler must be wrapped: await asyncio.to_thread(blocking_fn, ...). Alternatively, define the handler as a sync def and let FastAPI manage the thread pool.
• Never call time.sleep or any synchronous blocking function directly inside an async def handler — it blocks the event loop for all concurrent requests.
• Validate all path parameters, query parameters, and body fields via Pydantic models or Annotated types with Field(...) constraints. Do not trust raw inputs at handler level.