Configuration & extending

Environment variables

Variable	Default	Description
DATA_API_URL	http://qed-data:8000	FastAPI data service URL (http://localhost:8000 for local dev)
ANTHROPIC_API_KEY	—	When set, the LLM planner uses the Anthropic API
ANTHROPIC_MODEL	claude-opus-5	Model for the Anthropic planner path
LLM_API_URL	http://host.docker.internal:1234	OpenAI-compatible LLM endpoint (fallback path)
LLM_MODEL	qwen3.5-27b	Model name for the OpenAI-compatible path
REDIS_URL	redis://localhost:6379/0	Falls back to bounded in-memory LRU if unavailable
FLASK_DEBUG	0	Set to 1 for dev mode with reloader
SQLITE_PATH	instance/qed.db	Entity resolver aliases + app state
HJP_DB_PATH	/data/hjp.db	Croatian dictionary connector data
CIA_DB_PATH	/data/cia.db	CIA World Factbook connector data
FOOD_DB_PATH	/data/food.db	Nutrition connector data
QED_BASE_URL	http://localhost:8850	Used by the integration test suite

Without either ANTHROPIC_API_KEY or a reachable LLM_API_URL, Stage 2/3 degrades gracefully: it falls back to grammar-extracted parameters when available, otherwise returns an error pod.

Connector data

The entity resolver requires a seeded database — instance/qed.db with the entity_aliases table (seeded by app/data/seed_aliases.py, loaded once at startup). Connector databases are populated by the scripts/bootstrap_*.py scripts into ./data/.

Extending QED

New grammar

Add a Grammar(...) to ENGLISH_KEYWORD_GRAMMARS (translatable keywords) or NEUTRAL_GRAMMARS (syntax-driven) in app/nlp/stage1/grammars.py — specific patterns first. Add a unit test in tests/unit/test_grammars.py. For i18n coverage add per-language patterns in app/i18n/grammar_triggers.py.

New tool

1. Create app/tools/my_tool.py (use _client.call_data_api for HTTP backends).
2. Register it in app/tools/registry.py.
3. Add it to the LLM system prompt in app/nlp/stage2/planner.py.
4. Add a JSON Schema entry in app/schemas/validators.py.
5. Add pod logic in app/assembler/pod_builder.py.

If the tool needs a compute backend, add a router in data_api/routers/ and include it in data_api/main.py.

New data source

One DataConnector subclass in data_api/connectors/ plus one registry.register(...) line in its __init__.py.

Common gotchas

• High-confidence grammars bypass NER/entity scoring entirely — if a ≥ 0.95 grammar routes wrongly, check classifier.py:score().
• The entity resolver needs a seeded DB — if entities don't resolve, ensure instance/qed.db has the entity_aliases table.
• qalc lives only in the Docker image — run qed-data via Docker or install libqalculate locally.