Python and FastAPI Rules

When to use this

Place this file at the root of a Python backend service using FastAPI and Pydantic. It establishes strict typing rules, test requirements, and asynchronous function conventions for AI agent sessions.

The template

# AGENTS.md

## Project Context

Python 3.12+ backend API service powered by FastAPI, Pydantic v2, and SQLAlchemy 2.0 async ORM.

## Commands

- `uvicorn app.main:app --reload` start local API server
- `pytest` run the full automated test suite
- `pytest tests/test_api.py` run specific API test file
- `mypy app` run strict static type checking
- `ruff check .` run linting and style checks

Run `mypy app` and `pytest` before reporting work as complete.

## Conventions

- Use type hints on all function signatures. Never use untyped functions.
- All request and response DTOs must inherit from `pydantic.BaseModel`.
- Async endpoints must use native `async def` and non-blocking database sessions.
- Dependencies are injected via FastAPI `Depends()`. Avoid global singletons.
- Keep business logic inside domain service modules, not in route handlers.

## Strict Restrictions

- Do not use raw SQL queries. Use SQLAlchemy ORM or expression builder.
- Do not catch generic `Exception` without logging or re-raising context.
- Do not edit Alembic migrations manually once applied to production.

## Approval Required

- Adding new third-party PyPI dependencies.
- Database schema changes or new Alembic migration files.
- Modifying authentication or security middleware.

Customization Guide

Update the Python version and database ORM references to match your specific project stack. Add any domain-specific error handling rules to the restrictions block.