AIRegulation/AIRegulation-DocAnalysis
7
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
091a02c5229b7b8f70047ba6b47b940e9984fcb7
AIRegulation-DocAnalysis/AGENTS.md
ash66 091a02c522 Add AgentSessionService and refactor agent routes 
Move session-related responsibilities into a new application-layer AgentSessionService (and AgentSessionFeedbackResult dataclass), provide a bootstrap factory (get_agent_session_service), and update agent API routes to call the service instead of accessing ConversationStore directly. Routes now translate ValueError into 404 responses and use service methods for get/list/history/delete/feedback. Also update package exports and docs/READMEs to declare the backend architecture authority, enforce api -> application -> domain ports -> infrastructure boundaries, and call out legacy services/workflows as migration-only. These changes centralize session logic in the application layer and tighten architecture guidance for future backend work.
2026-05-22 09:50:30 +08:00

4.3 KiB
Raw Blame History

AGENTS.md

Scope

  • Backend code lives under backend/app/; frontend is the Vite app in frontend/.

Entrypoints

  • Backend entrypoint is backend/app/main.py, which re-exports app from app.api.main.
  • FastAPI mounts the real API under /api/v1; health endpoints are GET /health and GET /.
  • Frontend API calls use relative /api URLs from frontend/src/api/index.ts.
  • Current Vite dev proxy in frontend/vite.config.ts forwards /api to http://6.86.80.8:8000, not the local backend.

Preferred Commands

  • Prefer the repo scripts over ad hoc startup commands: ./dev.sh ... on Unix, dev.bat ... on Windows.
  • First-time local setup: ./dev.sh setup or dev.bat setup.
  • Backend foreground dev server: ./dev.sh start api --foreground or dev.bat start api --foreground.
  • Equivalent direct backend run from repo root: PYTHONPATH=backend uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload.
  • Python tooling must use the repo-root .venv environment; do not use the global python.
  • Prefer uv-managed execution from the repo root, for example uv run --python .venv\\Scripts\\python.exe python ... or other uv run ... forms that resolve within the project environment.
  • Frontend dev: npm --prefix frontend run dev.
  • Frontend verification: npm --prefix frontend run lint and npm --prefix frontend run build.
  • Use npm, not pnpm; the checked-in scripts run npm install even though frontend/pnpm-lock.yaml also exists.

Env And Infra

  • Backend settings must resolve env files from the repo root only. The supported files are root .env and optional root .env.development; files under backend/ must not be treated as authoritative env sources.
  • The dev scripts read API_HOST, API_PORT, FRONTEND_PORT, and FRONTEND_MODE from root .env first, then root .env.development as an override; all other backend config comes from the repo-root env files via Pydantic settings.
  • Docker infra is docker/docker-compose.yml; it brings up milvus, minio, redis, and postgres.
  • Default ports from config/scripts: backend 8000, frontend 5173, Milvus 19530, MinIO 9000/9001, Redis 6379, PostgreSQL 5432.
  • .env.example points embedding/LLM base URLs at a shared remote gateway http://6.86.80.4:30080/v1; do not assume model inference is local.

Verification

  • Root pyproject.toml is the active Python manifest and pytest config; testpaths = ["tests"].
  • Tests under tests/ insert backend/ into sys.path themselves, so targeted runs can be launched from the repo root.
  • tests/test_milvus.py and tests/verify_mvp.py require Milvus and model/runtime dependencies; they are not cheap smoke tests.
  • tests/verify_mvp.py also expects the BGEM3Embedder stack to be available and explicitly mentions FlagEmbedding.
  • For backend-only changes, prefer focused import/startup checks unless you know the external services and model dependencies are available.

Backend Architecture Authority

  • docs/architecture/backend-project-architecture.md is the authoritative backend architecture document for ongoing backend development.
  • New backend business logic must follow api -> application -> domain ports -> infrastructure.
  • Treat backend/app/shared/bootstrap.py as the current composition root for backend dependency wiring.
  • Do not add new business orchestration to backend/app/services/* or backend/app/workflows/* unless the task is explicitly a migration step.
  • API routes must not directly access ConversationStore; session access should go through application services.
  • Legacy files may be patched for compatibility or bug fixes, but should not gain new long-term responsibilities.

Backend Commenting Standard

  • All comments and docstrings in backend/**/*.py must be written in English.
  • Every Python file under backend must include a module-level explanation and at least one meaningful # code comment.
  • Every function and method must include a docstring.
  • Files without functions, including __init__.py, schemas, enums, dataclasses, and export-only modules, must still include a module docstring, class docstrings when applicable, and at least one meaningful # code comment.
  • Comments must explain intent, assumptions, invariants, or non-obvious logic; do not add empty, placeholder, or restatement-only comments.