Skip to content

AGENTS.md

Latest commit

 

History

History
69 lines (49 loc) · 2.92 KB

AGENTS.md

File metadata and controls

69 lines (49 loc) · 2.92 KB
Raw

AI Customer Agent — Agent Instructions

AI Customer Agent for Apex Finance. Python 3.12+ / FastAPI / asyncio, deployed on Docker/EC2. Three components: Python backend (src/), Next.js admin panel (admin-panel/), Next.js showcase (showcase-web/).

Commit Attribution

AI commits MUST include:

Co-Authored-By: Pi <noreply@pi.dev>

Package Managers

  • Backend: uv — uv sync, uv run pytest, uv run ruff check, uv run mypy --strict
  • Frontends: npm — npm run dev, npm run build, npm run lint
  • Full check: make check (lint + typecheck + test + module sizes)

File-Scoped Commands

Task Command
Test file uv run pytest tests/path/to/test_file.py -v
Lint file uv run ruff check src/path/to/file.py
Typecheck file uv run python -m mypy src/path/to/file.py --strict
Frontend lint cd admin-panel && npm run lint / cd showcase-web && npm run lint

Docs

docs/ is reference documentation — read the relevant section, not the whole tree.

Doc Use for
docs/architecture.md Component design, integration contracts, data flow
docs/API.yaml HTTP request/response schemas, error codes
docs/ai-customer-agent-srd.md Security requirements (SR-001–SR-045)
docs/apexpay-app-integration.md ApexPay channel — menu contracts, event types

Python Conventions

  • Full type hints; Pydantic v2 models (model_validator, not ad-hoc validation)
  • typing.Protocol for interfaces — never ABC
  • structlog.get_logger() for all logging — never print() or stdlib logging
  • async/await for all I/O; bind request_id, session_id, channel at request entry
  • Never log raw PII
  • ErrorResponse per docs/API.yaml; never expose internals in error responses
  • Error codes: VALIDATION_ERROR, AUTH_TOKEN_EXPIRED, AUTH_TOKEN_INVALID, SESSION_CONFLICT, SESSION_NOT_FOUND, RATE_LIMIT_EXCEEDED, SERVICE_UNAVAILABLE, INTERNAL_ERROR

Testing

  • pytest-asyncio; markers: unit, integration, e2e, security, load, audit
  • Test name pattern: test_<ac_id>_<short_description> (e.g. test_ac_009_01_loan_balance_returns_correct_balance)
  • Mock external boundaries only (Redis → fakeredis, HTTP → respx, SMTP → aiosmtplib mock); do not mock internal components
  • Tests assert behavior, not implementation details

Rules

  • Never hardcode secrets — use env vars (.env in dev, Secrets Manager in prod)
  • Do not modify docs/ unless explicitly asked — flag spec discrepancies, don't silently fix them
  • Run make check (or file-scoped equivalents) before claiming a change is complete