energietools 0.7.5

Austrian energy market calculations: electricity tariffs, grid fees per postcode, deterministic and with a full calculation path

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, 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.

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 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 (wie erhoben + validiert) und 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:

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.

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

python -m energietools list
python -m energietools grid_fees --json '{"verbrauch_kwh": 3500}'
python -m energietools finance --json '{"investition_eur": 9000, "jaehrlicher_ertrag_eur": 850, "nutzungsdauer_jahre": 15, "diskontrate": 0.04}'

Installation

pip install energietools            # Kern
pip install energietools[all]       # alle optionalen Abhängigkeiten
pip install energietools[analysis]  # FDA-Anomalien, Spotpreise
pip install energietools[pdf]       # PDF-Rechnungs-Parsing
pip install energietools[search]    # Web-Suche
pip install energietools[excel]     # Excel-Support

energietools bündelt keinen LLM/OCR-Client. Der Rechnungs-Scan (invoice_parser.parse_invoice) ist hier deterministisch: er liest durchsuchbare Text-PDFs per Regex aus und liefert die Felder mit einem auditierbaren rechenweg. Die nicht-deterministische Vision-/LLM-Extraktion (eingescannte PDFs, Fotos) lebt in der aufrufenden Anwendung (gridbert) und übergibt ihre strukturierten Felder an die deterministische Zusammenführung (tariff_advice).

Vertrauen & Herkunft

• METHODIK.md - wie die Daten erhoben und validiert werden: First-Party- + gesetzliche Quellen, der Cross-Check gegen die Systemnutzungsentgelte-Verordnung (BGBl. II Nr. 305/2025), Fail-open-Disziplin, Reviewer-Checkliste.
• NETZKOSTEN_UND_GEBUEHREN.md - die Wissens-Referenz: wie sich ein österreichischer Strompreis zusammensetzt (Netzkosten, Abgaben, Steuern), mit Rechenweg und Beispiel.

Grenze offen / proprietär

Öffentlich (MIT): Wissen, deterministische Rechnung, Daten-Snapshots. Proprietär (bleibt in gridbert): Beschaffung, Scraper, Pipelines, Credentials, Produkt. Connectoren gehören nicht in den öffentlichen Kern.

Lizenz & Attribution

MIT - siehe LICENSE. Teile des Simulationsbaukastens (Batterie-Dispatch, Wärmepumpen-COP) sind aus pvtool portiert; Finanz- und Netzentgelt-Logik sind Clean-Room-Reimplementierungen. Herkunft und Mit-Autorschaft: siehe CREDITS.md.

Offene Punkte und Platzhalter: TODO.md.