Nowcasting-agentti-energiahuoltovarmuuteen

Nowcast-huoltovarmuus

Nowcast-agentti Suomen energiahuoltovarmuudelle. Tuottaa reaaliaikaisen estimaatin sähköhuoltovarmuusmittarista korkeampifrekvenssisistä avoimista indikaattoreista, päivittää sitä uutta dataa saapuessa ja tuottaa LLM-selityksen muutoksen syistä.

Live-dashboard: tommiantero.github.io/Nowcasting-agentti-energiahuoltovarmuuteen (docs/-kansio, päivittyy 6h välein GitHub Actions -workflowsta).

Tekninen briiffi: nowcast_huoltovarmuus_brief.md.

Käyttöönotto

Vaatimukset: uv (Python-pakettienhallinta). Jos puuttuu:

& "$env:USERPROFILE\AppData\Local\anaconda3\python.exe" -m pip install uv

Asennus + virtuaaliympäristö:

uv sync

Aseta API-avaimet kopioimalla template:

Copy-Item .env.example .env
# muokkaa .env: lisää oikeat FINGRID_API_KEY ym.

Aja testit:

uv run pytest

Hakemistorakenne

src/
  collectors/      # Avoimen datan hakijat (Tilastokeskus, Fingrid, ...)
  preprocessing/   # X13-ARIMA-SEATS, mixed-frequency alignment   (tulossa)
  model/           # nowcast_lstm wrapper + ARMA-benchmark         (tulossa)
  agents/          # LangGraph-orkestrointi + Explainer-agentti    (tulossa)
  ui/              # Streamlit-dashboard                            (tulossa)
data/
  raw/             # API:lta haettu raakadata (gitignored)
  processed/       # Kausitasattua dataa (gitignored)
  models/          # Talletetut LSTM-mallit (gitignored)
tests/             # Pytest-yksikkötestit
notebooks/         # Tutkimusmuistikirjat

Päivän 1 tila (collectorit, vahvistettu live-API:ta vasten 2026-05-15)

Tilastokeskus PxWeb — src/collectors/tilastokeskus.py

• Yksi taulu: ehk/statfin_ehk_pxt_12su.px (Sähkön hankinta ja kokonaiskulutus, monthly 1992M01–).
• Palauttaa kaksi saraketta: tk_kokonaiskulutus_gwh ja tk_nettotuonti_gwh.
• Live-haku 2026-05-15: 408 riviä, päättyy 2025-12-31 (~5 kk lag).
• Briiffi oletti A:n olevan kvartaalisarja — sama muuttuja on saatavilla kuukausittain samasta taulusta, joten käytetään monthlya.

Fingrid Open Data — src/collectors/fingrid.py

• 10 datasettiä: kulutus, tuotanto (kokonais + tuuli/ydin/vesi + aurinko-ennuste), rajasiirrot 4 yhteydestä (FI-EE Estlink, FI-SE1 AC, FI-SE3 Fenno-Skan, FI-NO).
• Throttling 1 req/2 s ja paginaatio (≤20 000 riviä / sivu).
• x-api-key-header, avain ympäristömuuttujasta FINGRID_API_KEY.
• Live-haku 2026-05-15: 15-min datapisteet, real-time saatavuus.
• Aurinkovoima: Fingrid julkaisee vain ennusteen, ei toteumaa (hajautettu PV on mittaamatonta) — sarakkeen nimi on tästä syystä fg_solar_forecast.

Verifiointiskriptit kansiossa scripts/:

• verify_tilastokeskus.py — testaa PxWeb-kysely toimii
• verify_fingrid.py — listaa kunkin datasetti-ID:n metadata
• search_fingrid_datasets.py — etsii Fingridin katalogista avainsanan perusteella
• smoke_test.py — end-to-end live-haku molemmista lähteistä
• refresh_dashboard_data.py — kirjoittaa docs/data/*.json GitHub Pages -dashboardille
• validate_dashboard_json.py — tarkistaa että JSON-snapshotit parsivat oikein

Frontend kansiossa docs/:

• index.html + css/style.css + js/app.js — vanilla HTML/CSS/JS + Chart.js CDN:stä
• data/*.json — collectorien tuottamat snapshotit, päivittyy refresh-dashboard-data -workflowsta 6h välein (cron 17 */6 * * *)

Käyttöönotto GitHub Pages + Actions:

1. Settings → Pages → Source: Deploy from a branch → main → /docs
2. Settings → Secrets and variables → Actions → New repository secret: FINGRID_API_KEY = (avaimesi data.fingrid.fi -profiilista)
3. Actions → “refresh-dashboard-data” → Run workflow manually kerran ensimmäistä päivitystä varten (cron alkaa siitä eteenpäin)

Ei vielä toteutettu (briiffin sektion 6 aikataulun mukaan): ENTSO-E, Nord Pool, GPR-indeksi, AIS, Polymarket, X13-kausitasaus, malli, Explainer-agentti, UI.

Kehittäjäkomennot

uv run pytest               # Aja kaikki testit
uv run pytest -k tilastokeskus  # Aja yksi tiedosto
uv run ruff check .         # Lintaa
uv run ruff format .        # Muotoile
uv add <paketti>            # Lisää runtime-riippuvuus
uv add --dev <paketti>      # Lisää dev-riippuvuus

Lähteet ja perustelut

Tieteellinen pohja briiffin luvun 2 mukaan: Hopp (2021) UNCTAD No. 62, Kong et al. (2019) IEEE Trans. Smart Grid, Caldara & Iacoviello GPR-indeksi.