Development setup

Everything below assumes a clone of the repository and runs from the sdk/ directory — the package’s own root, not the monorepo’s. ui/ and dashboard/ are separate projects with their own setup.

git clone https://github.com/AgrospAI/fastrag.git
cd fastrag/sdk
uv sync --all-groups --all-extras   # or: task setup

uv sync installs fastrag itself in editable mode, so changes under src/ are picked up without reinstalling.

The Compose stack

The SDK ships its own stack so it does not collide with the root stack — Traefik forwards host port 5433 to PostgreSQL’s internal port 5432:

cp .env.example .env
docker compose up -d
docker compose ps          # STATUS must read "healthy"

docker-compose.yaml at the sdk/ root includes three files from compose/ — PostgreSQL, Milvus (with its etcd/MinIO backing services and the Attu console on :8000), and Ollama, which is also pre-pulled with FASTRAG_CHAT_MODEL by a one-shot ollama-pull service — plus a docs service that serves the live-reloading documentation on :8001. Those are the services the numbered examples/ need. .env.example documents service settings. The numbered scripts accept execution-time endpoint/input/schema/collection overrides; see Examples. AgrospAI fetching has explicit CLI/environment configuration.

pgAdmin is available as an opt-in: it is commented out in compose/docker-compose.postgres.yaml (together with its named volume). Uncomment both to get it on http://localhost:5050 — compose/servers.json and compose/pgpass preconfigure the connection to the stack’s PostgreSQL. compose/ holds nothing else: the backends this SDK has no code for (Chroma, Redis, RustFS, SeaweedFS, standalone MinIO) were removed.

The cache and chat-store schemas are self-managed — PostgresCache and PostgresChatStore create their own tables on __aenter__ — so there is no migration step for the new tree.

Day to day

task lint        # ruff check + ruff format --check, whole repo (src tests examples docs)
task format      # ruff check --fix + ruff format
task typecheck   # ty check src examples
task index       # uv run python examples/05_indexing.py
task serve       # uv run python examples/14_serving.py
task ask         # uv run python examples/15_asking.py
task docs-serve  # live-reloading docs on :8001
task test        # starts isolated SDK services, then runs pytest on the host
task e2e         # the same suite inside Compose — Docker is the only prerequisite

Run the numbered examples/*.py against the same stack — see Examples.

Running the docs locally

task docs           # one-shot build into docs/build/html, warnings are errors
task docs-serve      # live reload on http://localhost:8001, watching src/ too
task docs-linkcheck  # verify every external link resolves

task docs-docker builds and serves the documentation image on :8080 — useful when a build difference is suspected between a local Sphinx install and the container’s. CI does not use that image: its docs job runs task docs-check directly and uploads docs/build/html as a workflow artifact.

For other Sphinx targets, run task from docs/ to list them, then use task html, task linkcheck, or another target. docs/Taskfile.yaml accepts SPHINXBUILD, SPHINXOPTS, O, SOURCEDIR, and BUILDDIR overrides; for example, task html -- -W --keep-going passes extra options to Sphinx.

See also

Architecture for the package map; Documentation standard for where a new paragraph belongs before you write it.

Isolated example workflow

Use the SDK-owned service stack and original-main smoke runner to validate all 20 scripts with fixture sources and deterministic protocol providers:

.venv/bin/python scripts/test_services.py start
.venv/bin/python scripts/test_services.py probe
.venv/bin/python scripts/example_smoke.py

This uses PostgreSQL on loopback 55433 and Milvus on 19531, unique owned namespaces and automatic teardown; it does not modify the parent project’s services. Model2Vec weights and optional Playwright browsers must already be installed. Provider fixture responses prove protocol behavior, not model quality. See Examples for individual script selection, browser mode and all runtime override names.