# 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 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.