# AGENTS.md

## Scope

- This repo uses `backend/app/` for the backend and `frontend/` for the Vite React app.

## Real Entrypoints

- Current backend app entrypoint is `backend/app/main.py`, exporting `app` from `app.api.main`.
- Current backend dev start command is `python -m uvicorn app.main:app --reload` with `PYTHONPATH=backend`.
- `dev.sh start api --foreground` is the repo script flow that encodes the expected backend startup behavior.
- Frontend dev server is `frontend` Vite on port `5173`, proxying `/api` to `http://localhost:8000`.

## Commands

- Backend install: `pip install -r backend/requirements.txt`
- Backend run from repo root: `PYTHONPATH=backend uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload`
- Frontend install: `cd frontend && npm install`
- Frontend dev: `cd frontend && npm run dev`
- Frontend build: `cd frontend && npm run build`
- Frontend lint: `cd frontend && npm run lint`

## Infra And Env

- Backend settings load from root `.env`, not `backend/.env`, because `backend/app/config/settings.py` uses `env_file = ".env"`.
- Docker infra is defined in `docker/docker-compose.yml`; it starts Milvus, MinIO, Redis, and PostgreSQL.
- Default local service ports: Milvus `19530`, MinIO `9000/9001`, Redis `6379`, PostgreSQL `5432`, backend `8000`, frontend `5173`.
- LLM base URLs in `.env.example` point at a shared remote gateway (`http://6.86.80.4:30080/v1`); do not assume offline/local-only LLM execution.

## Verification

- Root pytest config in `pyproject.toml` points at root `tests/`, and those tests import from `backend/app` via `PYTHONPATH` setup.
- For frontend-only changes, run `npm run lint` and `npm run build` in `frontend`.
- For backend changes, prefer focused import/startup verification against `backend/app`, and run root `tests/` when the environment supports it.

## Gotchas

- Backend settings load from root `.env`, not `backend/.env`, because `backend/app/config/settings.py` uses `env_file = ".env"`.
- The root `pyproject.toml` is the active Python package manifest for the repo.