eryao/backend/AGENTS.md

Backend Domain Rules

This file governs backend/** only. Keep it minimal, enforceable, and non-duplicative.

Scope & Precedence

• Inherits root AGENTS.md and workspace runtime rules.
• If rules conflict, apply the stricter one.
• Keep backend-only constraints here; do not duplicate root routing logic.

Runtime & Commands

• Python commands must use uv (uv run, uv add).
• Backend startup/shutdown must use ./infra/scripts/app.sh.
• Check runtime logs from ./logs/*.log.
• Docker Compose usage: see infra/docker/README.md for environment-based service activation.

Code Quality Baseline

• Do not bypass lint/type gates (ruff, basedpyright).
• Use project logging (core.logging), never print() in runtime code.
• HTTP errors must follow RFC 7807 (application/problem+json).

HTTP Error Contract (Must)

• Backend must construct error payload using RFC7807 fields plus stable extension fields: code and optional params.
• code must be machine-readable UPPER_SNAKE_CASE; do not use free-text detail as the only contract.
• Error code registry source of truth: docs/protocols/common/http-error-codes.md.
• Any create/modify/deprecate of error codes must update docs/protocols/common/http-error-codes.md in the same change.
• Keep response media type as application/problem+json.
• Long-term layering target: HTTP transport details stay in routers/global handlers; service/repository/dependencies should raise domain errors (ApiProblemError or domain-specific exceptions), not HTTPException.
• When refactoring existing code, prefer replacing HTTPException in service/repository/dependencies with ApiProblemError while preserving status/code semantics.

Configuration & Secrets

• Read env only through core.config.settings (Settings / config).
• Do not use os.getenv/manual env parsing in backend runtime.
• Never hardcode keys/tokens/passwords.

Architecture Rules

• Use schema -> repository -> service layering.
• Repository: CRUD + query composition only; no auth decisions, no transaction boundary.
• Service: authz + business logic + transaction boundary.
• owner_id must come from verified JWT (sub), never from client payload.

Schema & Contract Rules

• Schema-first for new/changed data contracts.
• Strong typing required at boundaries (Pydantic/dataclass); avoid weak untyped payload contracts.
• Protocol/data contract changes must stay aligned with docs/protocols/.

Database Rules

• Supabase Auth is identity source; backend enforces business authorization.
• Use service-role DB access only in backend.
• Soft delete uses deleted_at; reads must exclude deleted records by default.
• Alembic is the only schema migration source of truth.
• Database migrations use ./infra/scripts/dev-migrate.sh:
  • migrate - run migrations only
  • init-data - seed data only
  • bootstrap - migrate + init-data

Agent Runtime & Tools

• AG-UI protocol is mandatory for agent loop behavior.
• ToolAgentOutput.result is the canonical tool result field.
• Tool results must be machine-oriented and include IDs/outcomes needed for chaining.

Tool Schema Rules for Small Models (e.g., qwen3.5-flash)

• Prefer operations: list[OperationModel] over parallel arrays.
• Validate tool args with strict Pydantic models (extra="forbid").
• Keep payloads JSON-native (objects/lists), shallow, and deterministic.
• Make action-specific required fields explicit and fail with structured errors.
• Return per-item outcomes (success/failed, identifiers, partial status) for self-correction.
• Avoid broad entry-point coercion fallbacks; fix schema/prompt alignment first.
• Do not pass provider request fields with None values (avoid upstream 400 blocking tool calls).

Testing

• Follow TDD for feature/bugfix work when practical.
• Prioritize regression tests for changed logic/contracts.
• Real DB tests must use settings.test.*; never hardcode test credentials.
• Integration tests that call live HTTP APIs must start backend via ./infra/scripts/app.sh first.
• For integration suites under backend/tests/integration, use ./infra/scripts/app.sh restart as precondition before uv run pytest.