‹ All views

Tech stack & ingredients · WattIQ EPM Decision Agent

Every layer, and every library it's built on

The whole ingredient list — the exact Python packages, the JavaScript libraries, the platform services, the data formats, and the model. Deliberately dependency-light: a small Python surface, zero npm / no frontend framework (vanilla JS + a handful of CDN libraries), and a learning store that swaps backends with one environment variable.

10 runtime Python packages 6 browser libraries 0 npm / build step Python 3.11 (Docker runtime) 6 platform/runtime services

Backend — Python (runtime)

poc/requirements.txt

The live service. Every package here is imported at runtime on Render.

PackageVersionRole
fastapi≥ 0.111The web framework — routes, request/response, the auth-gate middleware, SSE streaming.
uvicorn[standard]≥ 0.30The ASGI server that runs FastAPI (with the standard extras: httptools, websockets, uvloop where available).
openai≥ 1.40Client for the OpenAI model endpoint — the tool-calling reasoning loop in agent.py / llm.py.
pandas≥ 2.0Reads and shapes the EPM workbook sheets into the comparison matrices the tools return.
openpyxl≥ 3.1The engine pandas uses to open the .xlsx EPM workbooks.
python-dotenv≥ 1.0Loads poc/.env locally (secrets come from Render's env store in production).
python-multipart≥ 0.0.9Parses form posts — the login form and the dataset-upload endpoint.
azure-storage-blob≥ 12.19The durable learning store (INSIGHT_STORE=blob). Imported lazily, shipped so the switch is real.
gdxpds≥ 1.4Native reader path for EPM .gdx symbols in datasource.py; requires GAMS runtime libraries on the host.
pyyaml≥ 6.0Parses country context source registries (poc/context/*/sources.yaml) for governed context retrieval.

+ Python standard library (no install)

The rest leans on the stdlib — no extra dependencies:

hmachashlibjsonre uuidtimedatetimethreading pathlibsubprocessloggingoscollections

Dev & test

poc/requirements-dev.txt

Not shipped in the image — used by CI and locally.

PackageVersionRole
pytest≥ 8.0The test suite (84 tests) — access gate, feedback, skills, provenance, data tools, and learning store; run in GitHub Actions CI.
httpx≥ 0.27Backs FastAPI's TestClient for endpoint tests.

Browser — JavaScript libraries

loaded from jsDelivr CDN

The frontend is vanilla JavaScript — no React/Vue, no bundler, no package.json. Six libraries are pulled straight from the jsDelivr CDN at page load.

LibraryVersionRole
echarts@5Every chart — spotlight bars/lines, contrast/delta/share, small-multiples, discrete outlier heatmap, donut, treemap, frontier-bubble, and the theater slides.
markedlatestRenders the model's Markdown answer to HTML.
dompurify@3Sanitises that HTML before it hits the DOM — XSS-safe rendering of model output.
jszip@3Builds the ZIP containers that DOCX and PPTX files actually are.
jspdf@2Generates the branded PDF exports (cover, header, pagination) client-side.
pptxgenjslatestGenerates the PowerPoint (.pptx) decks client-side.

Also in the browser (no library)

Hand-written vanilla JS across 8 files (app, turn, charts, theater, skill engine, export, brand-export, report), the native fetch + Server-Sent Events for streaming, and inline SVG for icons and the title illustration. The browser layer now also includes the Charting Station gallery, story-mode first-chart rendering, and scene-aware export shaping. Fonts: Inter Sora Manrope, colours in OKLCH with hex fallbacks.

Platform & services

ServiceKindRole
Docker3.11-slimBase image python:3.11-slim; bakes in code, the EPM workbooks, and the system prompt; runs uvicorn.
RenderStarterHosts the Docker web service; auto-deploys from GitHub, health-checks /api/health, deploy history = rollback.
GitHubgit + ActionsSource, tag-based releases & rollback, CI tests, the scheduled learning-docs refresh.
Azure Blob Storageappend blobThe durable learning corpus (learning container). Portable to Azure Cosmos / Foundry by one env var.
LLM endpointgpt-5.5OpenAI API (api.openai.com) running gpt-5.5 — set via OPENAI_BASE_URL + MODEL; the openai SDK also supports Azure OpenAI.
GAMS runtimeserver-nativeRequired on the server for native .gdx parsing. Without it, the app falls back to exported output_csv symbols.

APIs consumed

runtime integrations

External APIs currently called by the running system. Country web-retrieval APIs are governed in prompt/docs but not yet wired as live runtime calls.

APIProtocolRole
OpenAI-compatible chat APIHTTPS JSONModel inference and tool-calling via the openai SDK (OPENAI_BASE_URL, OPENAI_API_KEY, MODEL).
Azure Blob Storage APIHTTPS (SDK)Durable insight/question store when INSIGHT_STORE=blob; implemented via azure-storage-blob.
Render service health APIHTTP GETPlatform health probing on /api/health for deploy/startup monitoring.

Data & formats

FormatWhereRole
.xlsxinputThe World Bank–ESMAP EPM workbooks in data/ — the grounding source of truth.
.gdxinputRaw EPM run databases for native symbol reads through datasource.py when server GAMS runtime is available.
.zip (output_csv)inputPortable upload path for exported model symbols (output_csv/*.csv) when native GDX read is unavailable.
.yamlcontextCountry source registries (poc/context/*/sources.yaml) for governed external-context retrieval.
.jsonlstateinsights.jsonl + questions.jsonl — the append-only learning corpus (local or Azure Blob).
.mddocs + exportLiving docs (changelog, question bank, digest, ADRs) and Markdown answer export.
DOCX / PDF / PPTXexportBranded decision-brief, Country-Report, and gallery exports, built client-side with scene labels and stronger decision endings.
PNG / HTMLexportSingle-chart image and a self-contained portable HTML answer.