Quick start
Prerequisites
- uv for Python environment management
- Docker + Docker Compose for the full stack
- (optional, for local math without Docker)
brew install libqalculate
Development server
The orchestrator can run on its own; the data API must be up separately or via Docker:
uv run python run.py # http://localhost:5000
Data API only:
cd data_api && uvicorn data_api.main:app --reload --port 8000
Note
The qalc binary is only present in the Docker image. Run qed-data
via Docker (or install libqalculate locally) before testing math
tools outside the container.
Full stack
docker compose up --build # Orchestrator: :8850, Data API: :8800
Tests
Unit tests run standalone in under a second — grammars, classifier scoring, entity resolution, validators, dispatcher, cache, i18n and the WL→qalc translator:
uv run python -m pytest tests/unit -q
Integration tests hit the full pipeline over HTTP, so the stack must be running first:
QED_BASE_URL=http://localhost:8850 uv run python -m pytest tests/ -v # docker
QED_BASE_URL=http://localhost:5000 uv run python -m pytest tests/ -v # dev
Integration tests sleep 2.1 s between requests to stay under the 30 requests/minute rate limiter.
test_wolfram_fixtures.py compares responses against scraped Wolfram Alpha
fixtures and is expected to have many xfail results. Promote a fixture to
a passing test by adding its slug to KNOWN_PASSING.
Data bootstrap
Some connectors ship with minimal seed data until their databases are bootstrapped:
uv run python scripts/bootstrap_food.py # nutrition database
Connector data files (CIA Factbook, HJP dictionary, food facts) are
configured via HJP_DB_PATH, CIA_DB_PATH and FOOD_DB_PATH — see
Configuration.
Lint & format
uv run ruff check .
uv run ruff format .