stack-knowledge

Stack Knowledge

This skill provides stack-specific patterns for agents making architectural and implementation decisions.

FastAPI

• Async route handlers by default — use async def for all endpoints
• Dependency injection with Depends() for database sessions, auth, shared logic
• Pydantic V2 models for all request/response schemas — never return raw dicts
• Use lifespan context manager for startup/shutdown (DB connections, ML model loading)
• Router organization: src/api/routes/ with one router per domain
• Error handling: HTTPException for expected errors, exception handlers for unexpected
• Consistent error shape: { "error": str, "message": str, "details": dict }
• Background tasks with BackgroundTasks for non-blocking operations

PostgreSQL + SQLAlchemy

• SQLAlchemy 2.0 style — use select(), insert(), update(), delete() statements
• Async engine with create_async_engine() and async_sessionmaker()
• Connection string via DATABASE_URL env var
• Models in src/models/ with one file per entity
• Use mapped_column() with explicit types — no implicit column inference
• Index every column used in WHERE, JOIN, or ORDER BY
• Relationship loading: use selectinload() for collections, joinedload() for single relations
• Session management: request-scoped sessions via Depends(get_db)

Alembic Migrations

• Config in alembic.ini, env in alembic/env.py
• Development: alembic revision --autogenerate -m "description"
• Production: manually reviewed migrations, never autogenerate blindly
• Always test migrations both up and down (rollback)
• One migration per logical change — don't batch unrelated schema changes

PyTorch / ML

• Models in src/models/ml/ — separate from SQLAlchemy ORM models
• Training scripts in src/training/
• Inference endpoints load models at startup via lifespan, not per-request
• Reproducibility: set seeds (torch.manual_seed, numpy.random.seed), log hyperparameters
• Model versioning: save checkpoints with metadata (epoch, metrics, config)
• Data pipelines in src/pipelines/ — pandas for ETL, torch DataLoaders for training