FastAPI service rules

# AGENTS.md: FastAPI service

Python API built with FastAPI and Pydantic v2, managed with uv.

## Commands
- Install and sync: `uv sync`. Add a dependency: `uv add <package>` (never `pip install` into the project).
- Run locally: `uv run fastapi dev app/main.py`. Production entry point: `uv run fastapi run app/main.py`.
- Tests: `uv run pytest -q`. Lint and format: `uv run ruff check . && uv run ruff format --check .`.
- Types: `uv run mypy app` if mypy is configured in pyproject.toml.
- Before saying a change is done: tests, ruff check and ruff format all pass.

## Layout
- `app/main.py` creates the app and includes routers. One `APIRouter` per resource in `app/routers/`.
- Request and response models in `app/schemas/`; database models separate from API models.
- Settings in `app/config.py` with pydantic-settings `BaseSettings`, read from the environment. No values in code.

## Rules
- Dependencies with `Annotated[T, Depends(...)]`; define reusable aliases (`SessionDep`, `CurrentUser`).
- Every route declares its response type (return annotation or `response_model`) so output is validated and documented.
  Never return ORM objects or dicts with extra fields straight from a route.
- Use `async def` only when everything awaited inside is async. Blocking calls (most DB drivers, `requests`, file I/O)
  go in plain `def` routes, which FastAPI runs in a threadpool. Never call blocking code inside `async def`.
- Startup and shutdown in a `lifespan` context manager, not `@app.on_event`.
- Errors: raise `HTTPException` with the right status (404 missing, 409 conflict, 422 is automatic for bad input).
  Do not return 200 with an error body.
- Pydantic v2 only: `model_config = ConfigDict(...)`, `model_dump()`, `field_validator`. No v1 `class Config` or `.dict()`.
- Auth: check it in a dependency, not inside each route. Never log tokens, passwords or full request bodies.
- CORS: list exact origins. Never `allow_origins=["*"]` together with `allow_credentials=True`.

## Tests
- `TestClient(app)` for HTTP tests. Swap dependencies with `app.dependency_overrides[...]`, and clear them after.
- Every new route gets a happy-path test and at least one failure test (404, 422 or auth).
- New endpoints: use the `add-endpoint` skill.

# CLAUDE.md

@AGENTS.md

## Claude Code notes
- Skills from this loadout live in `.claude/skills/`: `add-endpoint`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "FastAPI service rules" v1.0.0 — https://loadout.jnw-it.com/loadouts/fastapi-service/ -->

# GEMINI.md

@./AGENTS.md

## Gemini CLI notes
- Skills from this loadout live in `.agents/skills/`: `add-endpoint`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "FastAPI service rules" v1.0.0 — https://loadout.jnw-it.com/loadouts/fastapi-service/ -->

---
name: add-endpoint
description: Add a FastAPI endpoint with typed request and response models, an Annotated dependency and tests for success and failure. Use when adding or changing a route.
---

# Add an endpoint

1. Read `app/main.py` and the router for the resource. If there is no router yet, start from `references/items.py`.
2. Define models: a `Create` model for input and a `Public` model for output. Output models never include secrets or
   internal fields.
3. Write the route with a return annotation, the right status code (`status_code=201` for creation) and dependencies via
   `Annotated[..., Depends(...)]`. Plain `def` if it calls blocking code.
4. Raise `HTTPException(status_code=404, ...)` for missing items. Let FastAPI return 422 for invalid input.
5. Include the router in `app/main.py` if new: `app.include_router(items.router)`.
6. Tests, following `references/test_items.py`: success, 404, 422, and a dependency override instead of real storage.
7. Run `uv run pytest -q`, `uv run ruff check .` and `uv run ruff format --check .`. Report the results.

"""Example router: typed models, an Annotated dependency, correct status codes."""

from typing import Annotated

from fastapi import APIRouter, Depends, HTTPException, status
from pydantic import BaseModel, ConfigDict, Field


class ItemCreate(BaseModel):
    name: str = Field(min_length=1, max_length=100)
    price_pence: int = Field(ge=0)


class ItemPublic(BaseModel):
    model_config = ConfigDict(from_attributes=True)

    id: int
    name: str
    price_pence: int


class ItemStore:
    """In-memory store. Replace with the project's database session dependency."""

    def __init__(self) -> None:
        self.items: dict[int, ItemPublic] = {}

    def add(self, data: ItemCreate) -> ItemPublic:
        item = ItemPublic(id=len(self.items) + 1, **data.model_dump())
        self.items[item.id] = item
        return item


_store = ItemStore()


def get_store() -> ItemStore:
    return _store


StoreDep = Annotated[ItemStore, Depends(get_store)]

router = APIRouter(prefix="/items", tags=["items"])


@router.post("", status_code=status.HTTP_201_CREATED)
def create_item(data: ItemCreate, store: StoreDep) -> ItemPublic:
    return store.add(data)


@router.get("/{item_id}")
def read_item(item_id: int, store: StoreDep) -> ItemPublic:
    item = store.items.get(item_id)
    if item is None:
        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Item not found")
    return item

"""Tests for the items router: success, 404, 422, with the store swapped by a dependency override."""

import pytest
from fastapi.testclient import TestClient

from app.main import app
from app.routers.items import ItemStore, get_store


@pytest.fixture
def client():
    store = ItemStore()
    app.dependency_overrides[get_store] = lambda: store
    with TestClient(app) as c:
        yield c
    app.dependency_overrides.clear()


def test_create_and_read(client):
    r = client.post("/items", json={"name": "Tea", "price_pence": 250})
    assert r.status_code == 201
    item = r.json()
    assert item == {"id": 1, "name": "Tea", "price_pence": 250}
    assert client.get(f"/items/{item['id']}").json() == item


def test_missing_item_is_404(client):
    assert client.get("/items/999").status_code == 404


def test_invalid_input_is_422(client):
    assert client.post("/items", json={"name": "", "price_pence": -1}).status_code == 422