FinLedger

Ein lokales Finanzhauptbuch mit drei Leseoberflächen und einem MCP-Server, damit ein Agent sie abfragen kann:

• expenses: Ausgabenkonten, abgeglichen mit Peer-Erstattungen

• investments: Brokerage-Salden, Bestände und Aktivitäten

• income: Gehaltsabrechnungen (brutto, Abzüge, netto)

Expenses und investments teilen sich einen Speicher und sonst nichts. Ein Konto trägt eine explizite domain, und jede Expense-Abfrage wird darüber verknüpft, sodass ein Aktienkauf den Erstattungs-Matcher nicht erreichen kann.

Der Matcher ist regelbasiert. Er enthält sich, wenn er unsicher ist. Ein Mensch oder Agent bestätigt, bevor ein Treffer die Nettoausgaben reduziert.

Echte Transaktionen, Gehaltsabrechnungen und API-Schlüssel verbleiben auf Ihrem Rechner (~/.finledger/ledger.db, .env). Dieses Repository enthält nur Code und einen synthetischen Eval-Datensatz.

Installation

Python 3.10+. Das Hauptbuch, der Matcher, die MCP-Schleife und die Eval-Infrastruktur sind Standardbibliothek. pypdf ist optional und wird nur zum Importieren von Gehaltsabrechnungs-PDFs benötigt.

pip install -e .

Related MCP server: MCP Agent - AI Expense Tracker

MCP-Server

python3 -m finledger.mcp_server --db ~/.finledger/ledger.db

18 Tools in den Namensräumen expenses_*, investments_* und income_*, plus savings_rate, accounts, sync und reconcile.

Cursor-Beispiel (~/.cursor/mcp.json):

{
  "mcpServers": {
    "finledger": {
      "command": "python3",
      "args": ["-m", "finledger.mcp_server"]
    }
  }
}

Der Standardpfad für das Hauptbuch ist ~/.finledger/ledger.db.

CLI

finledger sync
finledger reconcile
finledger review
finledger serve

finledger serve öffnet ein lokales Desk unter :8770. Unter macOS können Sie auch scripts/Expense Desk.command doppelklicken.

Optionale Live-Quellen (Zugangsdaten in .env eintragen, niemals committen):

Kopieren Sie .env.example nach .env.

Öffentliches Eval

Der veröffentlichte Golddatensatz ist synthetisch. Er wird von scripts/make_sample_data.py erzeugt und liegt in data-sample/. Jede Transaktionszeile ist mit synthetic: true markiert. Es ist ein Abdeckungsdatensatz für Matcher-Verhaltensweisen (sauberer Treffer, Fan-in, Bündelung, Peer-Outbound-Eltern, Händlergutschriften, schwache Notizen, quellenübergreifende Zwillinge). Es handelt sich nicht um anonymisierte echte Daten.

python3 scripts/eval_public.py
# equivalent:
python3 -m reconcile.eval --matcher rules_v0

Zahlen, die Sie anhand dieses Repos reproduzieren können

Gemessen an data-sample/ mit rules_v0 (Fenster ±90 Tage, Auto-Match-Schwelle 0.75):

Führen Sie python3 scripts/eval_public.py erneut aus, um diese Werte zu aktualisieren. Zwei verbleibende False Positives in der Stichprobe sind echte Matcher-Schwächen, einschließlich der zu weit greifenden Emoji-Recall-Lift-Regel.

Was nicht in diesem Repo enthalten ist

Während der Entwicklung wurde ein privater Golddatensatz mit etwa 92 beschrifteten Beispielen verwendet. Er nennt echte Personen und echte Käufe und ist nicht veröffentlicht. Behandeln Sie die Stichprobenzahlen nicht als Reproduktion dieses Datensatzes. Anderes Korpus, andere Größe, andere Ergebnisse.

Dieses Repository erhebt keinen Anspruch auf 100 % Auto-Match-Präzision.

Matcher

Siehe reconcile/README.md. Kurzfassung:

Beschriften Sie das Beispielkorpus mit python3 labeling/app.py (Standard: data-sample/).

Lizenz

MIT