From e0554aaf92db504a437c93c78e1408734f8612a1 Mon Sep 17 00:00:00 2001 From: Raghvendra Singh Date: Mon, 3 Aug 2026 16:04:13 +0530 Subject: [PATCH] Add comprehensive guidance for AI coding agents in AGENTS.md --- AGENTS.md | 85 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 85 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..4d6dec7 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,85 @@ +# AGENTS.md + +Guidance for AI coding agents working in the Tailr monorepo. Read this before editing code. + +## Repository layout + +- `apps/backend/` — Python FastAPI service (the API). Not a classic flat FastAPI app; it uses a layered/clean architecture (see below). +- `apps/frontend/` — Next.js 16 app. **Read `apps/frontend/AGENTS.md` before writing frontend code** — this is Next.js 16, which has breaking changes vs. older versions, and it is explicitly NOT the Next.js from common training data. +- `.github/workflows/ci.yml` — CI pipeline. Run the same checks locally. +- `docker-compose.yml` — runs **Redis only** (Postgres and Qdrant are external/cloud). +- `netlify.toml` — frontend deploys to Netlify. + +## Backend + +### Commands (from CI, run in `apps/backend/`) + +```sh +pip install -r requirements-dev.txt # runtime + dev deps +ruff check . # lint +mypy . --ignore-missing-imports || true # type check (non-blocking in CI) +pytest -v --tb=short # tests (CI sets continue-on-error) +uvicorn main:app --reload # dev server +``` + +- CI and the Dockerfile use **Python 3.12**. Local `.venv` may be 3.13; prefer 3.12 for parity. +- `requirements.txt` is intentionally stripped to 17 pinned runtime deps. Do not add `--no-deps` installs; pin exact versions to avoid pip resolver backtracking. +- Entrypoint is `apps/backend/main.py`: `from app.app import create_app; app = create_app()`. + +### Configuration + +- `config/settings.py` (pydantic-settings, `case_sensitive=True`, reads `.env`) requires `DATABASE_URL` and `GEMINI_API_KEY`. Copy `apps/backend/.env.example` to `.env` for defaults. +- Key defaults: `API_PREFIX=/api/v1`, `GEMINI_MODEL=gemini-2.5-flash`, `QDRANT_COLLECTION=tailr-documents`, CORS allows `http://localhost:3000`. +- On startup, `app/lifespan.py` runs readiness checks against PostgreSQL, Redis, Qdrant, and Gemini. All four services are required; the app logs warnings for offline services but does not crash. + +### Architecture + +Layered structure, follow existing patterns when adding code: + +- `api/routes/` — FastAPI routers + `api/routes/*_schemas.py`. Everything lives under `/api/v1`. +- `application/` — use-case services (`auth/`, `resume/`, `job_description/`, `workflow/`, `guardrails/`). +- `domain/` — entities, repositories, shared exceptions (`domain/shared/`). +- `infrastructure/` — adapters: `database/` (SQLAlchemy async), `redis/`, `langchain/` (LLM provider + health), `llamaindex/` (parser, extractors, vector store), `repositories/`. +- `workflows/` — LangGraph pipeline (state → nodes → graph): `retrieve_context → plan → rewrite → guardrails → validation → ats_analysis → render`. +- `guardrails/` — custom guardrail engine (`base.py`, `pipeline.py`) with profiles `rewrite_strict`, `analysis_standard`, `validation_paranoid` and validators in `guardrails/validators/`. +- `validators/` — additional validation engine (`engine.py`, `citation_validator.py`, `rule_validator.py`). +- `prompts/` — versioned prompt templates in subfolders with `metadata.yaml` and `system_v1.txt`/`user_v1.txt`; registry at `prompts/registry.py`. +- `telemetry/` — structured logging (request context, filters, formatters). +- `alembic/` — migrations; currently a single squashed initial migration (`73cab716e7e3_initial.py`). + +### Key dependencies (pinned, `requirements.txt`) + +- `fastapi[standard]==0.140.7`, `uvicorn[standard]==0.30.0`, `pydantic==2.13.4`, `SQLAlchemy`, `alembic`, `asyncpg`, `psycopg2-binary` +- `langchain==0.3.18`, `langchain-google-genai==2.0.4`, `langgraph==0.2.60` (pinned; do not bump to langchain 1.x — `langchain-google-genai` 2.x and `langgraph` 0.2.x depend on the 0.3.x line) +- `qdrant-client==1.18.0`, `redis`, `llama-cloud==2.13.0`, `python-jose`, `bcrypt`, `python-json-logger` + +### Auth + +- JWT via `python-jose`, passwords hashed with `bcrypt`. Router dependency in `api/dependencies/auth.py`. +- Frontend stores the token in `localStorage["tailr_token"]` and sends `Authorization: Bearer`. + +## Frontend + +See `apps/frontend/AGENTS.md` (already in-repo) — read it before touching frontend code. Key scripts (run in `apps/frontend/`): + +```sh +npm run dev # local dev server +npm run build # production build +npm run lint # eslint +npm run type-check # tsc --noEmit +``` + +- API base from `NEXT_PUBLIC_API_BASE` (default `http://localhost:8000/api/v1`); production is `https://tailr-backend.onrender.com/api/v1` via `netlify.toml`. +- `NEXT_PUBLIC_API_BASE` is an `env.local`-style build-time var; set it before `npm run build`. + +## Testing + +- No `apps/backend/tests/` directory currently exists; CI runs `pytest` with `continue-on-error: true`. +- Frontend has no test runner configured (lint + type-check + build only). + +## Gotchas + +- `models/gemini-embedding-001` in `infrastructure/llamaindex/vector_store.py` embeds to **3072 dims** — Qdrant collection dimension must match. +- `docker-compose.yml` starts Redis only; Postgres and Qdrant must be provided externally (check `apps/backend/.env` for URLs). +- When changing pinned dependency versions, verify against CI Python 3.12, not a local 3.13 venv. +- Working tree is usually kept clean on `dev`; don't leave `.env` or `tsconfig.tsbuildinfo` staged (`.gitignore` already covers them).