fastapi-therapist

Diagnose FastAPI codebases for security, performance, correctness, and architecture issues. Outputs a 0–100 health score.

Installation

pip install fastapi-therapist

Usage

# Full scan with verbose output
fastapi-therapist . --verbose

# Only scan changed files (git diff vs base branch)
fastapi-therapist . --diff

# Only scan staged files (pre-commit hook)
fastapi-therapist . --staged

# Output only the score (useful for CI)
fastapi-therapist . --score

# Audit mode — ignore inline suppressions, reveal hidden issues
fastapi-therapist . --audit

# CI: GitHub Actions annotations inline on PR diff
fastapi-therapist . --annotations

# CI: machine-readable JSON output
fastapi-therapist . --json

# Include ruff linting results
fastapi-therapist . --ruff

# Include dead code detection
fastapi-therapist . --vulture

# Install skill for AI coding agents
fastapi-therapist install

Configuration

Suppress rules or skip files via pyproject.toml or fastapi-therapist.config.json:

[tool.fastapi-therapist]
ruff = true           # always include ruff
failOn = "warning"    # strict CI gate

[tool.fastapi-therapist.ignore]
rules = ["fastapi-therapist/FASTT012", "fastapi-therapist/FASTT016"]
files = ["migrations/**", "seed.py"]

[[tool.fastapi-therapist.ignore.overrides]]
files = ["app/routers/health.py"]
rules = ["fastapi-therapist/FASTT001"]

[[tool.fastapi-therapist.ignore.overrides]]
files = ["tests/**"]
# omit 'rules' to suppress all rules for these files

Inline Suppression

@app.post("/items")  # fastapi-therapist-disable-line FASTT070

# fastapi-therapist-disable-next-line FASTT002
@router.put("/items/{id}")
async def update_item(...):
    ...

return user  # fastapi-therapist-disable-line (all rules)

File Ignores

Respects existing project ignore files automatically:

Rules

Async/Sync Correctness

Security & Data Leaks

Architecture

Performance

Pydantic Usage

Dependency Injection

Dead Code (via vulture)

Enable with --vulture or vulture = true in config.

HTTP Correctness

Agent Installer

fastapi-therapist install         # interactive
fastapi-therapist install --yes   # non-interactive
fastapi-therapist install --dry-run  # preview

Score

100 - (unique error rules × 1.5) - (unique warning rules × 0.75)

• 75–100 Great
• 50–74 Needs work
• 0–49 Critical

Contributing

See CONTRIBUTING.md in the repo root — it covers setup and the rule-authoring pattern in detail.

License

MIT