AlexandrAI AGENTS.md
agents-md

nk304 API Python Agent Guide

Project-specific AGENTS.md guidance for the nk304 FastAPI and SQLModel backend, assistant graph, transport crypto, migrations, contracts, and test strategy.

AGENTS.md

Guidance for coding agents working on nk304 apps/api-py. This backend is the contract source for the web, mobile, worker, contracts package, and assistant runtime.

Project Overview

apps/api-py is a FastAPI backend using Pydantic v2, SQLModel, SQLAlchemy async, Alembic, Redis, ARQ, Socket.IO, LangGraph, provider adapters, and transport crypto. It owns /api/v2 routes, async services, SQL models, schemas, assistant graph execution, WebSocket namespaces, upload/download policies, mail and queue integration points, OpenAPI export, and migrations.

Treat this app as a typed product backend with security-critical contracts. Route counts are not enough: changes need schema, service, contract, test, worker, and assistant parity where applicable.

Project Map

  • app/main.py wires the FastAPI application.
  • app/api/v2/router.py and app/api/v2/endpoints/ define route groups for auth, users, chat, inventory, files, assistant, reports, audit, settings, notices, API keys, transport crypto, mobile, and health.
  • app/schemas/ mirrors route payloads, including ws.py for WebSocket payloads.
  • app/db/models/ owns SQLModel persistence models and inventory submodels.
  • app/services/ owns business logic across auth, chat, inventory, files, reports, audit, assistant services, settings, stickers, users, and integrations.
  • app/core/ owns security, CSRF, BYOK, transport crypto, queue, mail, cache, request context, errors, storage URLs, and runtime settings.
  • app/assistant_graph/ owns the LangGraph flow: agent, tools, finalize, policy gate, and resume executor.
  • app/assistant_capabilities/ declares user-visible assistant capabilities.
  • app/builtin_skills/ contains internal and external assistant skill descriptions.
  • alembic/versions/ stores migrations. Add new revisions; do not rewrite existing deployed history.
  • tests/ contains focused suites for chat, security, assistant, mobile, reports, users, API keys, runtime, and service behavior.

Setup Commands

Run from the monorepo root unless a command changes into the API package:

bashcd apps/api-py
uv sync
uv run ruff check .
uv run pytest tests/<target>.py -q
uv run alembic upgrade head
uv run python -m app.tools.export_openapi ../../packages/contracts/openapi.json

Root helpers:

bashpnpm run dev:api-py
pnpm run build:api
pnpm run db:migrate:py
pnpm run contracts:export
pnpm verify:web-next:contract

Use local environment profiles for ports and origins. Do not publish concrete local or production endpoints.

Change Rules For Agents

  • Keep the API prefix on /api/v2 and preserve success/failure envelope semantics.
  • Put route validation in schemas and business behavior in services; avoid burying durable logic inside endpoint functions.
  • Update the assistant capability/tool path when a normal user-facing product feature changes and assistant parity is technically safe.
  • If a database model changes, create a new Alembic migration and add tests around the migration-relevant behavior.
  • Regenerate OpenAPI after route or schema changes; do not hand edit generated contract files.
  • Keep queue job names synchronized with worker registration and enqueue callsites.
  • Keep WebSocket event names aligned with shared constants and generated socket types.
  • Do not add local production embedding runtimes unless explicitly requested and justified.

Verification

Use focused tests first:

bashcd apps/api-py
uv run pytest tests/security/<target>.py -q
uv run pytest tests/assistant/graph/<target>.py -q
uv run pytest tests/chat/<target>.py -q
uv run pytest tests/mobile/<target>.py -q
uv run ruff check .

Broaden when contracts or models move:

bashpnpm run contracts:export
pnpm run contracts:generate
pnpm verify:web-next:contract

Security Notes

Treat auth, CSRF, API keys, internal worker authentication, file access, transport crypto, assistant mutation confirmation, and WebSocket namespaces as security boundaries. Never paste secret values, private hosts, direct protected URLs, real tokens, or environment file contents into tests, docs, logs, comments, or public archive material.

PR Checklist

  • Route/schema/service/model boundaries are respected.
  • Migration and OpenAPI effects are explicit.
  • Assistant parity is shipped, handed off, or marked unsupported with tests or docs.
  • Security-sensitive changes have focused tests.
  • Worker and frontend consumers are checked when queue names, events, contracts, or payload shapes change.