AGENTS.md

Scope

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

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.

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.

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.

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.

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.