energietools

# energietools

energietools is an MIT-licensed Python library for Austrian energy market
calculations. It carries the grid fees of all 14 Austrian network areas, resolved
down to postcode level, and an open snapshot of the electricity tariff catalogue,
currently 119 tariffs from 57 suppliers, collected from supplier websites rather
than bought from a feed. Every calculation is deterministic and returns its full
calculation path, so any number can be checked by hand.

It is the calculation core behind [Gridbert](https://www.gridbert.at), an MCP
service that gives AI agents like Claude and ChatGPT access to these tools. The
catalogue Gridbert runs on is larger and rebuilt every night; the snapshot in
this repository is the part published openly.

```bash
pip install energietools
```

---

Ein Open-Source-Toolkit (MIT) für den österreichischen Energiemarkt. energietools
ist der **auditierbare Kern**: Wissen, Daten und Rechnung, die von außen
nachvollziehbar sein sollen. Die Beschaffung (Scraper, Pipelines, Credentials, das
Produkt) bleibt proprietär; hier liegen nur das kuratierte Wissen, die publizierten
Daten-Snapshots und die deterministische Rechnung.

## Was energietools sein soll

Ein Agent-Toolkit aus **vier Schichten**, die ein Agent orchestriert, statt selbst
zu rechnen:

- **Wissen (Second Brain).** Ein nach Andrej Karpathys LLM-Wiki gebautes
  Markdown-Wiki (`energietools/wiki/`). Es erklärt, was die Dinge *bedeuten*: wie sich
  Gesamtenergiekosten zusammensetzen, wie Energiegemeinschaften funktionieren, was
  die Netzebenen sind. Kuratiert und verdichtet, kein Daten-Dump. Wird per
  `get_knowledge`-Capability ausgeliefert (deterministische Text-Auslieferung).
- **Daten (Open Data).** Datierte, gequellte Snapshots öffentlich verfügbarer Daten
  (`energietools/data/`): Tarife, Netzentgelte, aktive Förderungen. Jeder Snapshot
  trägt Stand-Datum und Quelle.
- **Rechnen (Simulationsbaukasten + Capabilities).** Verschaltbare physikalische
  Komponenten (PV, Batterie, E-Auto, Wärmepumpe, Gaskessel), die man zu einem System
  zusammensteckt und über einen konfigurierbaren Optimierer rechnet - plus die
  auditierbaren Capabilities (Tarifvergleich, Netzentgelt, Finanzkennzahlen).
- **Prozesse (Gesprächsleitfäden).** Versionierte YAML-Definitionen
  (`energietools/prozesse/`), die Wissen und Rechnen für einen konkreten
  Anwendungsfall orchestrieren (z. B. Erstkontakt, Rechnungsanalyse): Ziel,
  benötigte Daten, Fragenreihenfolge, Tool-Mapping (gegen die Capability-Registry
  gelintet), Abbruch-/Caveat-Regeln.

**Der rote Faden:** der Agent liest *Wissen*, zieht den passenden *Daten*-Snapshot,
rechnet deterministisch über den *Baukasten* - ein *Prozess* gibt vor, in welcher
Reihenfolge und mit welchen Caveats das für einen konkreten Anwendungsfall passiert.
Kein Rechnen im LLM, wo es still falsch wird. Das Wiki sagt, was etwas bedeutet; die
Daten liefern die aktuelle Zahl; der Baukasten rechnet sie nachvollziehbar; der
Prozess hält die Reihenfolge und die ehrlichen Caveats fest.

> **Audit-Prinzip.** Jede produzierte Zahl ist nachrechenbar: datierte, gequellte
> Snapshots statt Live-Scrape, ein lückenloser `Rechenweg` pro Ergebnis, keine
> stillen Defaults (fehlende Eingaben werfen einen `CapabilityError`). Schätzungen
> sind als solche gekennzeichnet, nicht als Abrechnung ausgegeben.

## Die vier Schichten im Gebrauch

### Wissen - `energietools/wiki/`
Ein Ordner aus Markdown-Seiten, **kein Server**. Zeig einen Agenten (oder dich
selbst) auf `energietools/wiki/index.md` bzw. den maschinenlesbaren Index
`energietools/wiki/llms.txt`. Jede Seite erklärt ein Konzept selbst-enthalten, mit
Querlinks, `Berechnet von` (Link zur zuständigen Capability) und `Quellen` + `Stand`.
Einstieg: [`energietools/wiki/netz/netzentgelte.md`](energietools/wiki/netz/netzentgelte.md)
als ausgearbeitete Vorlage. Liegt bewusst **innerhalb** des Python-Packages (nicht am
Repo-Root), damit `wiki/` als Package-Data mit jedem `pip install energietools`
mitgeliefert wird - ein Gateway, der energietools nur als gepinnte Dependency zieht,
bekommt den Wiki-Baum sonst nicht zu Gesicht (Prüfpunkt aus D7, gelöst per
`pyproject.toml`). Ausgeliefert wird eine Seite deterministisch über die
`get_knowledge`-Capability (`thema`-Enum wird aus `llms.txt` gebaut, Result =
Seiteninhalt + Stand + Quellenverweis - reine Text-Auslieferung, kein Rechen-Result).

### Daten - `energietools/data/`
Versionierte First-Party-Snapshots: der Tarifkatalog (`data/tariffs/`), die
Netzentgelt-/Abgaben-Parameter (`data/netz/`) und aktive Förderungen
(`data/foerderungen.json`). Jeder Snapshot hat ein `MANIFEST.json` mit Provenance,
`Stand`, Lizenz und Verweisen auf [METHODIK.md](METHODIK.md) (wie erhoben +
validiert) und [NETZKOSTEN_UND_GEBUEHREN.md](NETZKOSTEN_UND_GEBUEHREN.md) (was die
Zahlen bedeuten). Die Scraper, die diese Daten erzeugen, sind **nicht** Teil dieses
Repos.

### Rechnen - Library + Baukasten
`pip install` und losrechnen - mit Rechenweg:

```python
from energietools.capabilities.tariff_compare import vergleiche_tarife, CatalogTariffSource

# Vergleiche deinen Tarif gegen den Open-Data-Katalog - offline, auditierbar.
result = vergleiche_tarife(
    plz="1060",
    jahresverbrauch_kwh=3200,
    aktueller_lieferant="Wien Energie",
    aktueller_energiepreis_brutto_ct_kwh=25.0,   # brutto, aus deiner Rechnung
    aktuelle_grundgebuehr_brutto_eur_monat=6.0,  # brutto
    tariff_source=CatalogTariffSource(),
)
print(f"Max Ersparnis: {result.max_ersparnis_eur:.0f} EUR / Jahr")
# Jeder Tarif trägt einen vollständigen Rechenweg:
print(result.beste_fix[0].rechenweg.model_dump())
```

## Simulationsbaukasten (Schicht „Rechnen")

Drei Bausteine, verschaltbar:

1. **Komponenten** (`energietools/components/`) - jede mit gemeinsamer
   Schnittstelle (Energie rein/raus, Zustand): PV und Batterie mit echtem
   Verhalten; E-Auto, Gaskessel und der Wärmepumpen-Dispatch als erkennbare
   Platzhalter (das COP-Modell der Wärmepumpe ist real).
2. **System** (`energietools/system/`) - steckt Komponenten zusammen und
   bilanziert den Energiefluss diskret.
3. **Optimierer** (`energietools/optimizer/`) - konfigurierbare Zielfunktion
   (ökonomisch, Eigenverbrauch, Autarkie). Bewerten geht; der Löser für
   nicht-triviale Optima ist Platzhalter.

```python
from energietools.components import PVSystem, Battery, StepContext
from energietools.system import EnergySystem

system = EnergySystem([PVSystem(kwp=5.0), Battery.new(10.0)])
res = system.run([4000.0], [StepContext(dt_hours=8760.0)])
print(f"Eigenverbrauch {res.self_consumption_rate:.0%}, Autarkie {res.self_sufficiency_rate:.0%}")
```

Erste Auflösung ist **diskret** (eine Ingenieursrechnung, keine Zeitreihen); die
Komponenten-Schnittstelle ist so angelegt, dass die spätere Zeitreihen-Variante ein
Superset ist - ein Skalar ist ein Ein-Punkt-Profil.

### Prozesse - `energietools/prozesse/`

Ein Prozess ist ein versioniertes YAML (`meta`, `ziel`, `benoetigte_daten`, `fragen`,
`tool_mapping`, `datenqualitaet_abbruch`, `caveats`) - ein Gesprächsleitfaden für
einen konkreten Anwendungsfall, kein Freitext-Prompt. `energietools/prozesse/MANIFEST.json`
listet jeden Prozess mit `prozess_version` (SemVer). v1: `erstkontakt.yaml`
(Orientierung beim ersten Kontakt) und `rechnungsanalyse.yaml`
(Rechnung → Tarifvergleich mit Rechenweg).

Ein **Struktur-Linter** (`energietools.prozesse.linter`) prüft deterministisch: jede
`tool_mapping`-Capability existiert (in `default_registry()` bei `quelle: energietools`,
in einer dokumentierten Extern-Liste bei `quelle: extern` - Engram-Vault-/
Gridbert-Domänen-Tools, die nicht Teil dieses Repos sind), jeder Pflicht-Input der
Capability ist durch `benoetigte_daten`/`fragen` gedeckt, `prozess_version` ist SemVer,
Pflichtblöcke (`tool_mapping`, `caveats`) sind nicht leer. Anonymisierte
Beispiel-Dialoge (`energietools/prozesse/beispiele/*.json`) fixieren erwartete
Tool-Calls und Pflicht-Caveats je Prozess.

Ein deterministischer **Renderer** (`energietools.prozesse.renderer`) übersetzt
`prozesse/<id>.yaml` in ein SKILL.md (YAML-Frontmatter + Markdown, ausgeliefert über
den engram-`GET /skills`-Mechanismus) sowie eine Kurzform für die MCP-
`initialize.instructions` bzw. Tool-Beschreibungen - Chat-Clients installieren keine
Skills, sie sehen nur diese Kurzform. Gerenderte Artefakte liegen unter `skills/`
(Drift-Guard-Test: `tests/test_prozesse_renderer.py` rendert neu und vergleicht).

## Capabilities

Jede Fähigkeit hat eine Form - `run(**kwargs) -> CapabilityResult` - und
registriert sich selbst in der CLI. Auflisten: `python -m energietools list`.

| Capability | Beschreibung |
|------------|--------------|
| `tariff_catalog` / `tariff_compare` / `tariff_advice` | Open-Data-Tarifkatalog abfragen, Tarif vergleichen, Rechnung → Vergleich (mit Rechenweg) |
| `netzkosten` / `gesamtkosten` / `netz_verfuegbar` / `tarifvergleich_inkl_netz` | Regulierte Netz-/Gesamtkosten je PLZ, Verfügbarkeit, Vergleich inkl. Netz |
| `grid_fees` | Netzentgelt je Betreiber/Land (per kWh), §16b-Speicherbefreiung, voller Rechenweg |
| `finance` | Investitionskennzahlen ROI/NPV/LCOE (Standard-Finanzformeln) |
| `scenarios` | Batterie-Größen-Sweep mit Eigenverbrauchs-Dispatch + ROI (ersetzt das alte `battery_sim`) |
| `heatpump` | Heizkostenvergleich Wärmepumpe vs. Gas (Carnot-COP, diskret) |
| `community_metrics` | Energiegemeinschafts-Kennzahlen (Eigenverbrauch/Autarkie/Reststrom/Überschuss) |
| `validate_invoice_facts` / `finalize_invoice` | Rechnungs-Fakten strikt validieren (Rejection-Semantik) bzw. validieren + deterministisch aufrechnen (`jahreskosten_brutto_eur`, voller Rechenweg) |
| `get_knowledge` | Liefert eine kuratierte Wiki-Seite (WISSEN-Schicht) als reinen Text + Stand + Quellenverweis - `thema`-Enum wird zur Buildzeit aus `wiki/llms.txt` erzeugt, kein Rechen-Result |
| `pv_sim` / `spot_analysis` / `load_profile` / `energy_monitor` / `beg_advisor` / `web_search` | Weitere deterministische Werkzeuge |

```bash
python -