energietools

energietools is an MIT-licensed Python library for Austrian energy market
calculations. It knows over 100 electricity tariffs from 60 suppliers (the
catalogue is rebuilt daily from supplier websites, not bought from a feed) and
the grid fees of all 14 Austrian network areas, resolved down to postcode level.
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.

pip install git+https://github.com/BMoer/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.tariffs import compare_against_catalog

# Vergleiche deinen Tarif gegen den Open-Data-Katalog - offline, auditierbar.
result = compare_against_catalog(
    verbrauch_kwh=3200,
    aktueller_lieferant="Wien Energie",
    aktueller_energiepreis_ct_kwh=25.0,   # brutto, aus deiner Rechnung
    aktuelle_grundgebuehr_eur_monat=6.0,  # brutto
    gebrauchsabgabe_rate=0.07,            # Wien
    plz="1060",
)
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.

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.