hive-skills 0.1.0

package/assets/skills/authored/python-api/composable/BUNDLE.md

@@ -0,0 +1,389 @@
+<!-- GENERATED by tools/hive.py compile. Do not hand-edit. -->
+# python-api: Compiled Skill Bundle (v1.0.0)
+
+All composable mini-skills for `python-api` concatenated in index order, frontmatter stripped. Regenerate with `tools/hive.py compile <skill-dir>`. Do not edit by hand.
+
+---
+<!-- module: 01-project-structure.md -->
+
+# Project Structure & Hygiene
+
+Organize by feature, not by layer, once past a handful of endpoints:
+
+```
+app/
+  main.py            # create_app(), mount routers, middleware
+  core/config.py     # Settings (pydantic-settings)
+  core/security.py   # hashing, JWT helpers
+  db/session.py      # engine, SessionLocal, get_db dependency
+  api/deps.py        # shared dependencies
+  api/v1/users.py    # APIRouter per resource
+  models/            # SQLAlchemy ORM models
+  schemas/           # Pydantic request/response models
+  services/          # business logic, no framework imports
+tests/
+```
+
+Keep business logic out of route handlers. A handler parses input, calls a service function, and shapes the response. Services stay framework-agnostic and unit-testable, which is what makes the codebase maintainable and lets you test logic without spinning up HTTP.
+
+Use `pydantic-settings` so config is typed and validated at startup, failing fast on missing vars:
+
+```python
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env")
+    database_url: str
+    jwt_secret: str
+    jwt_expire_minutes: int = 30
+
+settings = Settings()  # raises on missing required vars
+```
+
+Hygiene checklist:
+- Pin dependencies (`requirements.txt` with hashes, or `pyproject.toml` + lockfile).
+- Never commit `.env` or secrets; load them from the environment.
+- Run `ruff` (lint/format) and `mypy` (types) in CI.
+- Keep one responsibility per module; avoid mutable global state shared across requests.
+- Version the API under a path prefix (`/api/v1`) so you can evolve it without breaking clients.
+
+Layer-first layouts (`controllers/`, `services/`, `models/` each holding every feature) force you to touch many directories per change and scale badly as the app grows; feature-aware grouping keeps related code together.
+
+The payoff of this structure: routes stay thin, services are pure and testable, schemas are reusable, and configuration errors surface at boot rather than at request time.
+
+---
+<!-- module: 02-routing-and-app.md -->
+
+# App Creation & Routing
+
+Prefer an application factory plus one `APIRouter` per resource, versioned under a path prefix:
+
+```python
+from fastapi import FastAPI, APIRouter, Depends
+
+def create_app() -> FastAPI:
+    app = FastAPI(title="My API", version="1.0.0")
+    app.include_router(users.router, prefix="/api/v1")
+    return app
+
+router = APIRouter(prefix="/users", tags=["users"])
+
+@router.post("", response_model=UserOut, status_code=201)
+def create_user(payload: UserCreate, db: Session = Depends(get_db)):
+    ...
+```
+
+**Always set `response_model`.** It filters output so you never leak internal fields (like a password hash), documents the schema in OpenAPI, and validates what you return.
+
+**Status code discipline:**
+- `201` for creation, `204` for deletes with no body, `200` for normal reads/updates.
+- `400` malformed request, `401` unauthenticated, `403` authenticated-but-forbidden, `404` not found, `409` conflict (e.g. duplicate email), `422` validation, `429` rate limit, `500` unexpected.
+
+**Resource naming:** use plural nouns for collections (`/users`, `/users/{id}`), not verbs. Nest sub-resources sparingly (`/users/{id}/orders`). Use path params for identity, query params for filtering/pagination.
+
+Group related routes on one router with a shared `prefix` and `tags` (tags drive OpenAPI grouping). Mount routers in the factory rather than decorating a global `app`, so tests can build a fresh app instance and swap dependencies.
+
+Keep handlers thin: parse the validated `payload`, call a service, return an object the `response_model` can serialize. Push branching, DB work, and business rules into services. A handler that is more than ~15 lines is usually doing too much: the logic belongs in a framework-agnostic service you can unit-test and reuse from a CLI or worker.
+
+Prefer building the app in a factory over decorating a module-level global `app`. The factory lets tests construct a fresh instance and override dependencies per test, and keeps import-time side effects out of your modules.
+
+---
+<!-- module: 03-pydantic-models.md -->
+
+# Pydantic Models: Request vs Response
+
+Separate input and output models. Never accept your ORM model directly, and never expose it raw.
+
+```python
+from pydantic import BaseModel, EmailStr, Field
+
+class UserCreate(BaseModel):
+    email: EmailStr
+    password: str = Field(min_length=8, max_length=128)
+    full_name: str = Field(min_length=1, max_length=200)
+
+class UserOut(BaseModel):
+    model_config = {"from_attributes": True}  # read from ORM objects
+    id: int
+    email: EmailStr
+    full_name: str
+```
+
+Key patterns:
+- `from_attributes=True` (Pydantic v2) lets `response_model` read ORM instances directly, so you can `return user` and get a filtered `UserOut`.
+- Use rich types (`EmailStr`, `HttpUrl`, `conint`, `Field(gt=0)`) so validation is declarative and lives in the schema.
+- **Constrain everything:** string lengths, numeric bounds, list sizes. Unbounded input is a DoS and data-quality risk.
+- The input/output split is also your security boundary: a field that only exists on `UserCreate` (password) can never accidentally appear in `UserOut`.
+
+**Partial updates (PATCH):** make every field `Optional` with a default, then apply only what the client sent:
+
+```python
+class UserUpdate(BaseModel):
+    email: EmailStr | None = None
+    full_name: str | None = Field(default=None, min_length=1, max_length=200)
+
+data = payload.model_dump(exclude_unset=True)  # only fields the client provided
+for k, v in data.items():
+    setattr(user, k, v)
+```
+
+`exclude_unset=True` distinguishes "field omitted" from "field set to null", which is essential for correct PATCH semantics. For nested structures, define nested models rather than accepting free-form `dict`, so each level is validated.
+
+Why the strict split matters in practice: your ORM model is a database concern that changes for storage reasons; your response model is an API contract clients depend on. Coupling them means a schema migration can silently change your public API or leak a newly-added internal column. Keeping `UserCreate`, `UserUpdate`, and `UserOut` distinct from the ORM `User` gives you three independent contracts you can evolve safely.
+
+---
+<!-- module: 04-validation-and-errors.md -->
+
+# Validation & Error Semantics
+
+FastAPI auto-returns `422` with a structured body for schema violations, so don't fight it. Add cross-field checks with validators.
+
+**Field validator** (single field):
+```python
+from pydantic import field_validator
+
+@field_validator("password")
+@classmethod
+def strength(cls, v: str) -> str:
+    if v.isalnum():
+        raise ValueError("password needs a symbol")
+    return v
+```
+
+**Model validator** (cross-field):
+```python
+from pydantic import model_validator
+
+class DateRange(BaseModel):
+    start: date
+    end: date
+
+    @model_validator(mode="after")
+    def check_order(self):
+        if self.start > self.end:
+            raise ValueError("start must be <= end")
+        return self
+```
+
+**Business errors** use `HTTPException` with the right status and a clear detail:
+
+```python
+user = db.get(User, user_id)
+if user is None:
+    raise HTTPException(status_code=404, detail="User not found")
+```
+
+**Status discipline:** `400` malformed, `401` unauthenticated, `403` forbidden, `404` missing, `409` conflict, `422` validation, `429` rate-limited, `500` unexpected.
+
+**Consistent error shape + safe fallback.** Add a handler so uncaught errors are logged server-side and clients never see a stack trace:
+
+```python
+@app.exception_handler(Exception)
+async def unhandled(request, exc):
+    logger.exception("unhandled error")
+    return JSONResponse(status_code=500, content={"detail": "Internal error"})
+```
+
+Catch integrity errors at the boundary and translate them (`IntegrityError` → `409`) rather than letting them 500. Never swallow exceptions silently: either handle them meaningfully or let them propagate to the logging handler. Keep `detail` messages user-facing and free of internal identifiers, SQL, or secrets.
+
+Prefer letting FastAPI/Pydantic reject malformed input with its automatic `422` over hand-writing validation in the handler, since declarative constraints on the schema are less error-prone and self-document in OpenAPI. Reserve `HTTPException` for business-rule failures the schema can't express (resource not found, permission denied, duplicate). Return the same error envelope everywhere so clients can parse failures uniformly.
+
+---
+<!-- module: 05-dependencies-and-auth.md -->
+
+# Dependencies, Authentication & Authorization
+
+Dependencies are FastAPI's core reuse mechanism: DB sessions, auth, pagination. Use a generator dependency for resources needing teardown:
+
+```python
+def get_db():
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()
+```
+
+`Depends` results are cached within a request, so `get_current_user` runs once even if several dependencies need it. Compose dependencies to build up context.
+
+Scope the session to the request (one per request via the generator), and manage transactions explicitly: commit once at the end of a successful unit of work and roll back on error, so a partial multi-step mutation never persists. Don't commit after each step, and never share a session across requests in a module-level global: it isn't thread-safe and leaks state between callers. The `finally` block closes it on every path.
+
+**Auth: OAuth2 password flow + JWT bearer tokens.** Hash passwords with bcrypt/argon2 via `passlib`: never plaintext, never a fast hash like SHA-256.
+
+```python
+from passlib.context import CryptContext
+from jose import jwt, JWTError
+
+pwd = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+def make_token(sub: str) -> str:
+    exp = datetime.utcnow() + timedelta(minutes=settings.jwt_expire_minutes)
+    return jwt.encode({"sub": sub, "exp": exp}, settings.jwt_secret, algorithm="HS256")
+```
+
+Current-user dependency decodes, validates, and loads the user:
+
+```python
+oauth2 = OAuth2PasswordBearer(tokenUrl="/api/v1/auth/token")
+
+def get_current_user(token: str = Depends(oauth2), db: Session = Depends(get_db)) -> User:
+    exc = HTTPException(401, "Invalid credentials", {"WWW-Authenticate": "Bearer"})
+    try:
+        payload = jwt.decode(token, settings.jwt_secret, algorithms=["HS256"])
+    except JWTError:
+        raise exc
+    user = db.get(User, int(payload["sub"]))
+    if user is None:
+        raise exc
+    return user
+```
+
+Rules:
+- **Always pass `algorithms=[...]` on decode**: omitting it enables `alg=none` token forgery.
+- Keep tokens short-lived; pair with refresh tokens.
+- **Authentication ≠ authorization.** Enforce ownership/roles in handlers or dependencies. Write a factory `require_role("admin")` returning a dependency that checks `current_user` and raises `403`; don't rely on authentication alone. The classic bug is an endpoint that verifies the caller is logged in but never checks the requested object belongs to them.
+
+Dependency injection is also what makes the app testable: in tests you override `get_db` with a test session and `get_current_user` with a fake user, exercising real routes without real auth or a real database.
+
+---
+<!-- module: 06-pagination-filtering.md -->
+
+# Pagination, Filtering & Sorting
+
+Never return an unbounded collection. Offer limit/offset for simple cases, keyset (cursor) for large or fast-changing data.
+
+**Limit/offset:**
+```python
+class Page(BaseModel):
+    limit: int = Field(20, ge=1, le=100)
+    offset: int = Field(0, ge=0)
+
+@router.get("", response_model=PageOut[UserOut])
+def list_users(p: Page = Depends(), db: Session = Depends(get_db)):
+    q = select(User).order_by(User.id)
+    total = db.scalar(select(func.count()).select_from(User))
+    rows = db.scalars(q.limit(p.limit).offset(p.offset)).all()
+    return {"items": rows, "total": total, "limit": p.limit, "offset": p.offset}
+```
+
+Note the `le=100` cap: clients can't request unbounded pages.
+
+**Keyset pagination** avoids the deep-offset performance cliff (offset scans and discards skipped rows): `WHERE id > :cursor ORDER BY id LIMIT :n`, returning the last id as the next cursor. Use it for large tables and infinite scroll.
+
+**Deterministic ordering is mandatory.** Always apply an `ORDER BY` with a unique tiebreaker (e.g. `ORDER BY created_at, id`). Without it, rows can shift between pages and clients see duplicates or gaps.
+
+**Safe filtering & sorting** (the security-critical part):
+- Expose an explicit allowlist of filter fields as typed query params. Never build SQL from raw client strings and never `eval` a filter expression.
+- Map sort keys through a whitelist dict to columns:
+
+```python
+SORTABLE = {"email": User.email, "created": User.created_at}
+col = SORTABLE.get(sort_key)
+if col is None:
+    raise HTTPException(400, "invalid sort field")
+q = q.order_by(col.desc() if descending else col.asc())
+```
+
+This prevents SQL injection and stops clients sorting by or filtering on private columns. Always use parameterized queries / the ORM, never string interpolation.
+
+**Response metadata.** Return enough for the client to navigate: the items plus `limit`/`offset` (or a `next_cursor`), and a `total` only when it's cheap: a `COUNT(*)` over a huge filtered table can cost as much as the page query itself, so for large datasets prefer cursor pagination with a `has_more` flag and omit the total. Cap the maximum page size server-side (`le=100`) regardless of what the client asks for, so no single request can pull the whole table.
+
+---
+<!-- module: 07-async-performance.md -->
+
+# Async, Performance & the Event Loop
+
+FastAPI runs `async def` handlers on the event loop and plain `def` handlers in a threadpool. Understanding this split is essential for performance.
+
+**The cardinal sin:** calling blocking I/O inside an `async def` handler (a sync DB driver, `requests`, `time.sleep`, or any CPU-heavy loop). It stalls the entire event loop, so every concurrent request stalls with it. Fixes:
+- Make the handler plain `def` (FastAPI runs it in a threadpool), **or**
+- Use async libraries: `httpx.AsyncClient` instead of `requests`, async SQLAlchemy / async drivers, `asyncio.sleep` instead of `time.sleep`.
+
+Don't mix them: a `def` handler calling async code, or an `async def` handler calling blocking code, are both wrong.
+
+**Database performance:**
+- Use connection pooling (configure pool size to match worker count).
+- Prevent N+1 queries with eager loading (`selectinload`, `joinedload`) when you access relationships in a loop.
+- Push filtering/aggregation into SQL rather than loading rows and processing in Python.
+
+**Outbound calls:**
+- Reuse a single HTTP client with connection pooling; don't create a client per request.
+- **Set timeouts on every outbound call**: a hung dependency without a timeout ties up a worker indefinitely.
+
+**Caching:** add caching for hot read paths, using HTTP `ETag`/`Cache-Control` headers for client/proxy caching, or Redis for shared server-side caching. Cache computed or expensive-to-fetch data with a sensible TTL and clear invalidation rules.
+
+**General:** avoid mutable default arguments and shared global mutable state across requests (each request should get its own state). Profile before optimizing; most latency is I/O (DB and downstream calls), not Python CPU.
+
+**Production concurrency model:** run multiple worker processes (`uvicorn`/`gunicorn`, sized roughly to cores for CPU-bound apps, higher for I/O-bound) behind a process manager. Each worker has its own event loop; scaling out processes is how you use multiple cores, since one Python process is GIL-bound for CPU work. Offload genuinely heavy or long-running work (report generation, image processing, third-party fan-out) to a background task queue (Celery, RQ, `arq`) and return `202 Accepted` with a status URL, rather than blocking a request worker for seconds.
+
+---
+<!-- module: 08-testing.md -->
+
+# Testing with pytest + TestClient
+
+Test through the API with `TestClient` (sync) or `httpx.AsyncClient` (async). Override dependencies to inject a test DB and fake auth: this is the payoff of dependency injection.
+
+```python
+from fastapi.testclient import TestClient
+
+@pytest.fixture
+def client():
+    app.dependency_overrides[get_db] = lambda: test_session
+    with TestClient(app) as c:
+        yield c
+    app.dependency_overrides.clear()
+
+def test_create_user(client):
+    r = client.post("/api/v1/users", json={"email": "a@b.com",
+                    "password": "s3cret!!", "full_name": "A"})
+    assert r.status_code == 201
+    assert "password" not in r.json()   # sensitive field must not leak
+
+def test_rejects_short_password(client):
+    r = client.post("/api/v1/users", json={"email": "a@b.com",
+                    "password": "x", "full_name": "A"})
+    assert r.status_code == 422
+```
+
+**Test the contract, not the implementation:**
+- Status codes for success and each error path.
+- Response shape, and that sensitive fields (password hashes, internal ids) are absent.
+- Auth enforced: unauthenticated returns `401`, wrong-user/role returns `403`.
+- Validation rejects bad input (`422`); pagination bounds hold (`limit` cap respected).
+
+**Isolation & data:**
+- Use a fresh transactional DB per test: create schema then wrap each test in a rollback, or use a disposable SQLite / testcontainers Postgres.
+- `pytest.fixture` for setup/teardown; `parametrize` for edge cases.
+- Build test data with factories (`factory_boy` or plain builder functions), not copy-pasted dicts.
+
+Keep tests fast and isolated. Mock only external services (payment gateways, third-party APIs); never mock your own code, or you test the mock instead of the behavior. A test that passes against a mock of your service proves nothing about the service.
+
+Cover the full contract deliberately: a happy-path test per endpoint, plus one test per error branch (404, 409, 422), an auth test (401 unauthenticated, 403 wrong role/owner), and a pagination test asserting the `limit` cap is enforced. Prefer many small focused tests over a few sprawling ones: when a focused test fails, its name tells you what broke.
+
+---
+<!-- module: 09-middleware-observability.md -->
+
+# Middleware, CORS, Observability & Rate Limiting
+
+Cross-cutting concerns belong in middleware and app-level config, not scattered through individual handlers.
+
+**CORS.** If a browser front-end on another origin calls the API, configure `CORSMiddleware` with an explicit allowlist of origins. Never combine `allow_origins=["*"]` with `allow_credentials=True`: it is both insecure and rejected by browsers. List the exact front-end origins, methods, and headers you actually need.
+
+```python
+from fastapi.middleware.cors import CORSMiddleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.cors_origins,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+```
+
+**Request logging & correlation.** Add middleware that assigns each request a correlation id (from an incoming `X-Request-ID` header or a freshly generated UUID), binds it to the logger, and logs method, path, status code, and duration. Structured JSON logs make a request traceable across services. Never log request bodies that may carry secrets or PII.
+
+**Rate limiting.** Protect auth and expensive endpoints with rate limits (a library like `slowapi`, or an upstream API gateway). Limit by client identity or IP, return `429` with a `Retry-After` header when a caller exceeds the limit, and apply stricter limits to login/token endpoints to blunt credential-stuffing attacks.
+
+**Health & readiness.** Expose a lightweight `/health` (the process is up) and a `/ready` (dependencies are reachable) endpoint for orchestrators and load balancers. Keep `/health` dependency-free so a slow database doesn't make the instance look dead and get killed. Emit basic metrics (request count, latency, error rate) for monitoring dashboards and alerts.
+
+**Timeouts everywhere.** Set request and outbound-call timeouts so a slow client or hung downstream can't hold a worker indefinitely. Combined with rate limiting, this is your first line of defense against both accidental overload and abuse.

package/assets/skills/authored/python-api/composable/INDEX.md

@@ -0,0 +1,13 @@
+# Python REST API (FastAPI): Mini-Skill Index
+
+Loading policy: read this menu, then load 00-core (if present) plus the minis relevant to your task. If most of this skill is relevant, load BUNDLE.md (or a matching presets/*.md) in one read instead.
+
+- `01-project-structure.md` - Layout, settings, hygiene. Load when scaffolding a project or organizing modules/config.
+- `02-routing-and-app.md` - App factory, APIRouter, status codes, resource naming. Load when defining endpoints or wiring routers.
+- `03-pydantic-models.md` - Request/response models, from_attributes, PATCH. Load when designing schemas or shaping I/O.
+- `04-validation-and-errors.md` - Field/model validators, HTTPException, status-code discipline, handlers. Load when handling bad input or errors.
+- `05-dependencies-and-auth.md` - Depends, DB session, OAuth2/JWT, password hashing, roles. Load when adding auth or injection.
+- `06-pagination-filtering.md` - Limit/offset, keyset cursors, safe filtering/sorting. Load when listing collections.
+- `07-async-performance.md` - Event loop, blocking I/O, N+1, caching, timeouts. Load when tuning or writing async handlers.
+- `08-testing.md` - TestClient, dependency overrides, fixtures, contract tests. Load when writing API tests.
+- `09-middleware-observability.md` - CORS, request logging, rate limiting, health checks, timeouts. Load when wiring cross-cutting concerns or hardening for production.

package/assets/skills/authored/python-api/composable/VERSION

@@ -0,0 +1 @@
+1.0.0

package/assets/skills/authored/python-api/composable/mini/01-project-structure.md

@@ -0,0 +1,44 @@
+# Project Structure & Hygiene
+
+Organize by feature, not by layer, once past a handful of endpoints:
+
+```
+app/
+  main.py            # create_app(), mount routers, middleware
+  core/config.py     # Settings (pydantic-settings)
+  core/security.py   # hashing, JWT helpers
+  db/session.py      # engine, SessionLocal, get_db dependency
+  api/deps.py        # shared dependencies
+  api/v1/users.py    # APIRouter per resource
+  models/            # SQLAlchemy ORM models
+  schemas/           # Pydantic request/response models
+  services/          # business logic, no framework imports
+tests/
+```
+
+Keep business logic out of route handlers. A handler parses input, calls a service function, and shapes the response. Services stay framework-agnostic and unit-testable, which is what makes the codebase maintainable and lets you test logic without spinning up HTTP.
+
+Use `pydantic-settings` so config is typed and validated at startup, failing fast on missing vars:
+
+```python
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env")
+    database_url: str
+    jwt_secret: str
+    jwt_expire_minutes: int = 30
+
+settings = Settings()  # raises on missing required vars
+```
+
+Hygiene checklist:
+- Pin dependencies (`requirements.txt` with hashes, or `pyproject.toml` + lockfile).
+- Never commit `.env` or secrets; load them from the environment.
+- Run `ruff` (lint/format) and `mypy` (types) in CI.
+- Keep one responsibility per module; avoid mutable global state shared across requests.
+- Version the API under a path prefix (`/api/v1`) so you can evolve it without breaking clients.
+
+Layer-first layouts (`controllers/`, `services/`, `models/` each holding every feature) force you to touch many directories per change and scale badly as the app grows; feature-aware grouping keeps related code together.
+
+The payoff of this structure: routes stay thin, services are pure and testable, schemas are reusable, and configuration errors surface at boot rather than at request time.

package/assets/skills/authored/python-api/composable/mini/02-routing-and-app.md

@@ -0,0 +1,38 @@
+---
+pairs-with:
+  - 03-pydantic-models.md
+  - 04-validation-and-errors.md
+---
+
+# App Creation & Routing
+
+Prefer an application factory plus one `APIRouter` per resource, versioned under a path prefix:
+
+```python
+from fastapi import FastAPI, APIRouter, Depends
+
+def create_app() -> FastAPI:
+    app = FastAPI(title="My API", version="1.0.0")
+    app.include_router(users.router, prefix="/api/v1")
+    return app
+
+router = APIRouter(prefix="/users", tags=["users"])
+
+@router.post("", response_model=UserOut, status_code=201)
+def create_user(payload: UserCreate, db: Session = Depends(get_db)):
+    ...
+```
+
+**Always set `response_model`.** It filters output so you never leak internal fields (like a password hash), documents the schema in OpenAPI, and validates what you return.
+
+**Status code discipline:**
+- `201` for creation, `204` for deletes with no body, `200` for normal reads/updates.
+- `400` malformed request, `401` unauthenticated, `403` authenticated-but-forbidden, `404` not found, `409` conflict (e.g. duplicate email), `422` validation, `429` rate limit, `500` unexpected.
+
+**Resource naming:** use plural nouns for collections (`/users`, `/users/{id}`), not verbs. Nest sub-resources sparingly (`/users/{id}/orders`). Use path params for identity, query params for filtering/pagination.
+
+Group related routes on one router with a shared `prefix` and `tags` (tags drive OpenAPI grouping). Mount routers in the factory rather than decorating a global `app`, so tests can build a fresh app instance and swap dependencies.
+
+Keep handlers thin: parse the validated `payload`, call a service, return an object the `response_model` can serialize. Push branching, DB work, and business rules into services. A handler that is more than ~15 lines is usually doing too much: the logic belongs in a framework-agnostic service you can unit-test and reuse from a CLI or worker.
+
+Prefer building the app in a factory over decorating a module-level global `app`. The factory lets tests construct a fresh instance and override dependencies per test, and keeps import-time side effects out of your modules.

package/assets/skills/authored/python-api/composable/mini/03-pydantic-models.md

@@ -0,0 +1,45 @@
+---
+pairs-with:
+  - 04-validation-and-errors.md
+---
+
+# Pydantic Models: Request vs Response
+
+Separate input and output models. Never accept your ORM model directly, and never expose it raw.
+
+```python
+from pydantic import BaseModel, EmailStr, Field
+
+class UserCreate(BaseModel):
+    email: EmailStr
+    password: str = Field(min_length=8, max_length=128)
+    full_name: str = Field(min_length=1, max_length=200)
+
+class UserOut(BaseModel):
+    model_config = {"from_attributes": True}  # read from ORM objects
+    id: int
+    email: EmailStr
+    full_name: str
+```
+
+Key patterns:
+- `from_attributes=True` (Pydantic v2) lets `response_model` read ORM instances directly, so you can `return user` and get a filtered `UserOut`.
+- Use rich types (`EmailStr`, `HttpUrl`, `conint`, `Field(gt=0)`) so validation is declarative and lives in the schema.
+- **Constrain everything:** string lengths, numeric bounds, list sizes. Unbounded input is a DoS and data-quality risk.
+- The input/output split is also your security boundary: a field that only exists on `UserCreate` (password) can never accidentally appear in `UserOut`.
+
+**Partial updates (PATCH):** make every field `Optional` with a default, then apply only what the client sent:
+
+```python
+class UserUpdate(BaseModel):
+    email: EmailStr | None = None
+    full_name: str | None = Field(default=None, min_length=1, max_length=200)
+
+data = payload.model_dump(exclude_unset=True)  # only fields the client provided
+for k, v in data.items():
+    setattr(user, k, v)
+```
+
+`exclude_unset=True` distinguishes "field omitted" from "field set to null", which is essential for correct PATCH semantics. For nested structures, define nested models rather than accepting free-form `dict`, so each level is validated.
+
+Why the strict split matters in practice: your ORM model is a database concern that changes for storage reasons; your response model is an API contract clients depend on. Coupling them means a schema migration can silently change your public API or leak a newly-added internal column. Keeping `UserCreate`, `UserUpdate`, and `UserOut` distinct from the ORM `User` gives you three independent contracts you can evolve safely.

package/assets/skills/authored/python-api/composable/mini/04-validation-and-errors.md

@@ -0,0 +1,59 @@
+---
+pairs-with:
+  - 03-pydantic-models.md
+  - code-review/05-error-handling.md
+---
+
+# Validation & Error Semantics
+
+FastAPI auto-returns `422` with a structured body for schema violations, so don't fight it. Add cross-field checks with validators.
+
+**Field validator** (single field):
+```python
+from pydantic import field_validator
+
+@field_validator("password")
+@classmethod
+def strength(cls, v: str) -> str:
+    if v.isalnum():
+        raise ValueError("password needs a symbol")
+    return v
+```
+
+**Model validator** (cross-field):
+```python
+from pydantic import model_validator
+
+class DateRange(BaseModel):
+    start: date
+    end: date
+
+    @model_validator(mode="after")
+    def check_order(self):
+        if self.start > self.end:
+            raise ValueError("start must be <= end")
+        return self
+```
+
+**Business errors** use `HTTPException` with the right status and a clear detail:
+
+```python
+user = db.get(User, user_id)
+if user is None:
+    raise HTTPException(status_code=404, detail="User not found")
+```
+
+**Status discipline:** `400` malformed, `401` unauthenticated, `403` forbidden, `404` missing, `409` conflict, `422` validation, `429` rate-limited, `500` unexpected.
+
+**Consistent error shape + safe fallback.** Add a handler so uncaught errors are logged server-side and clients never see a stack trace:
+
+```python
+@app.exception_handler(Exception)
+async def unhandled(request, exc):
+    logger.exception("unhandled error")
+    return JSONResponse(status_code=500, content={"detail": "Internal error"})
+```
+
+Catch integrity errors at the boundary and translate them (`IntegrityError` → `409`) rather than letting them 500. Never swallow exceptions silently: either handle them meaningfully or let them propagate to the logging handler. Keep `detail` messages user-facing and free of internal identifiers, SQL, or secrets.
+
+Prefer letting FastAPI/Pydantic reject malformed input with its automatic `422` over hand-writing validation in the handler, since declarative constraints on the schema are less error-prone and self-document in OpenAPI. Reserve `HTTPException` for business-rule failures the schema can't express (resource not found, permission denied, duplicate). Return the same error envelope everywhere so clients can parse failures uniformly.

package/assets/skills/authored/python-api/composable/mini/05-dependencies-and-auth.md

@@ -0,0 +1,60 @@
+---
+requires:
+  - code-review/02-security-review.md
+pairs-with:
+  - 08-testing.md
+---
+
+# Dependencies, Authentication & Authorization
+
+Dependencies are FastAPI's core reuse mechanism: DB sessions, auth, pagination. Use a generator dependency for resources needing teardown:
+
+```python
+def get_db():
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()
+```
+
+`Depends` results are cached within a request, so `get_current_user` runs once even if several dependencies need it. Compose dependencies to build up context.
+
+Scope the session to the request (one per request via the generator), and manage transactions explicitly: commit once at the end of a successful unit of work and roll back on error, so a partial multi-step mutation never persists. Don't commit after each step, and never share a session across requests in a module-level global: it isn't thread-safe and leaks state between callers. The `finally` block closes it on every path.
+
+**Auth: OAuth2 password flow + JWT bearer tokens.** Hash passwords with bcrypt/argon2 via `passlib`: never plaintext, never a fast hash like SHA-256.
+
+```python
+from passlib.context import CryptContext
+from jose import jwt, JWTError
+
+pwd = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+def make_token(sub: str) -> str:
+    exp = datetime.utcnow() + timedelta(minutes=settings.jwt_expire_minutes)
+    return jwt.encode({"sub": sub, "exp": exp}, settings.jwt_secret, algorithm="HS256")
+```
+
+Current-user dependency decodes, validates, and loads the user:
+
+```python
+oauth2 = OAuth2PasswordBearer(tokenUrl="/api/v1/auth/token")
+
+def get_current_user(token: str = Depends(oauth2), db: Session = Depends(get_db)) -> User:
+    exc = HTTPException(401, "Invalid credentials", {"WWW-Authenticate": "Bearer"})
+    try:
+        payload = jwt.decode(token, settings.jwt_secret, algorithms=["HS256"])
+    except JWTError:
+        raise exc
+    user = db.get(User, int(payload["sub"]))
+    if user is None:
+        raise exc
+    return user
+```
+
+Rules:
+- **Always pass `algorithms=[...]` on decode**: omitting it enables `alg=none` token forgery.
+- Keep tokens short-lived; pair with refresh tokens.
+- **Authentication ≠ authorization.** Enforce ownership/roles in handlers or dependencies. Write a factory `require_role("admin")` returning a dependency that checks `current_user` and raises `403`; don't rely on authentication alone. The classic bug is an endpoint that verifies the caller is logged in but never checks the requested object belongs to them.
+
+Dependency injection is also what makes the app testable: in tests you override `get_db` with a test session and `get_current_user` with a fake user, exercising real routes without real auth or a real database.