Volt-AI

Energy intelligence for Colombia. Volt-AI ingests the public data of the national power market (XM), forecasts electricity demand and spot price with uncertainty bands, detects anomalies, explains what drives each forecast and offers an AI analyst that answers questions using real data.

Live demo: https://voltia-xi-five.vercel.app/en · Español · For business · Requirements · Architecture · Model card · Decisions · Runbook

What it does

• Forecasts daily demand 30 days ahead and spot price 14 days ahead, with calibrated P10/P50/P90 bands.
• Backtests honestly with rolling-origin evaluation against seasonal-naive and ETS baselines, and publishes every result with its margin of error.
• Explains each forecast with SHAP drivers in plain language.
• Watches hydrology and El Niño: reservoir level, inflows and the ONI index.
• Detects anomalies such as the 2020 lockdown and the El Niño years.
• Prices a purchase: a calculator turns the price forecast into the cost range of buying a volume on the spot market, and the chance of paying more than a contract. Its range is checked in the backtest (80 % nominal, 78 to 84 % measured).
• Answers questions through an AI analyst limited to typed, validated tools. It never runs free-form SQL, and it still answers from fixed summaries when the model is unavailable.
• Writes a daily briefing in both languages from the day's figures.
• Exposes a REST API under /api/v1 with an OpenAPI specification.
• Works in Spanish and English, in light and dark themes.

Results, as measured

Rolling-origin backtest, 50 origins on a fixed calendar (21 days apart), 80 % intervals (full tables and method in the model card):

Target	Against seasonal naive	Against ETS	P10–P90 coverage (nominal 80 %)
Demand, 30 days	MASE 42.3 % lower, wins 46 of 50 origins	MASE 42.7 % lower, wins 45 of 50	0.82
Spot price, 14 days	MASE 33.3 % lower, wins 42 of 50	14.2 % lower, but the interval of the difference includes zero; clearly better only in the first days	0.81

In plain percentage error (MAPE), the demand forecast misses by 1.9 % on average against 3.4 % for the references, and the price forecast 1 to 3 days ahead misses by 10.7 % against 15.3 % for ETS and 29.8 % for the seasonal-naive reference. Beyond a week the price model stays level with ETS, so the site presents the price as a calibrated range.

Stack

Layer	Technology
Pipeline	Python 3.12, uv, pandas, pandera, LightGBM, statsmodels, SHAP, SQLAlchemy
Database	PostgreSQL on Neon (free tier); read-only role for the web
Web	Next.js 16, TypeScript, Tailwind CSS 4, Apache ECharts
AI	Gemini Flash with Flash-Lite fallback through the Vercel AI SDK (optional)
Delivery	GitHub Actions (CI and the daily pipeline) and Vercel

Everything runs on free tiers.

Quality

• Pipeline: ruff, mypy and 142 tests at 97 % coverage, no network in CI.
• Web: eslint, tsc, vitest, a production build and 75 Playwright checks with axe accessibility scans in both themes.
• Security: strict CSP and security headers, a database role that cannot write (except the rate-limit table), an Origin check, body-size cap and per-client limits on the chat, no secrets in the repository.
• Reproducible: lockfiles for both sides and actions pinned by commit.

Run it locally

# pipeline (SQLite is used when DATABASE_URL is unset)
cd pipeline && uv sync
uv run voltia backfill && uv run voltia train --predict && uv run voltia anomalies && uv run voltia brief

# web (fixtures when no database is configured)
cd web && npm ci && npm run dev

Deployment, secrets and the daily schedule are in docs/deployment.md; what to do when something breaks is in docs/runbook.md.

Repository layout

pipeline/   Python package: sources, validation, features, models, briefing, CLI
web/        Next.js application and REST API
db/         Versioned SQL migrations
docs/       Requirements, architecture, ADRs, model card, deployment guide, runbook

Data sources

XM public API, Open-Meteo, NOAA Climate Prediction Center (ONI) and Colombian public holidays. Details and terms are in docs/requirements.md.

License

MIT. See LICENSE.