DocsGPT: Instructions file for Codex

AGENTS.md

• Read CONTRIBUTING.md before making non-trivial changes.
• For day-to-day development and feature work, follow the development-environment workflow rather than defaulting to setup.sh / setup.ps1.
• Avoid using the setup scripts during normal feature work unless the user explicitly asks for them. Users configure .env usually.
• Try to follow red/green TDD

Check existing dev prerequisites first

For feature work, do not assume the environment needs to be recreated.

• Check whether the user already has a Python virtual environment such as venv/ or .venv/.
• Check whether Postgres is already running and reachable via POSTGRES_URI (the canonical user-data store).
• Check whether Redis is already running.
• Reuse what is already working. Do not stop or recreate Postgres, Redis, or the Python environment unless the task is environment setup or troubleshooting.

MongoDB is not required for the default install. It is only needed if the user opts into the Mongo vector-store backend (VECTOR_STORE=mongodb) or is running the one-shot scripts/db/backfill.py to migrate existing user data from the legacy Mongo-based install. pymongo is not a dependency or an extra: install it separately with uv pip install 'pymongo>=4.6' (a later uv sync removes it again). The vector store needs Atlas $vectorSearch, not a plain mongo container.

Normal local development commands

Use these commands once the dev prerequisites above are satisfied.

Backend

uv sync                    # deps from uv.lock + the dev group (test tools, ruff) + docsgpt itself, editable
source .venv/bin/activate  # macOS/Linux
# pip instead: pip install -r docsgpt/requirements.txt -r tests/requirements.txt && pip install -e .
# Optional extras (not installed by default); name every extra you want, `uv sync` removes the others:
# uv sync --extra docling   # docling parser engine (OCR backend, structured output)
# uv sync --extra milvus    # VECTOR_STORE=milvus
# pip: pip install -r docsgpt/requirements-docling.txt (or requirements-milvus.txt); each file = core + the extra.
# `uv pip install -r docsgpt/requirements-docling.txt` needs UV_INDEX_STRATEGY=unsafe-best-match
# (the file adds the PyTorch CPU index; prefer `uv sync --extra docling`).