leftbrain

Die linke Gehirnhälfte für deinen KI-Agenten. Exakte, deterministische Antworten für alles, worin Sprachmodelle schlecht sind — Arithmetik und Analysis, Daten und Zeitzonen, Einheitenumrechnung, proportionales Skalieren, Zählen, Sortieren, Validierung, Zufall, Hashes — plus optionale Live-Daten (Wetter, Wechselkurse) und Datei-Tools (PDF-Text, Bild → base64).

Nutze es als einfache Python-Bibliothek oder als MCP-Server (stdio oder HTTPS) mit Claude Code, Claude Desktop, Cursor, Windsurf, Zed oder einem beliebigen MCP-Client.

pip install "leftbrain[all]"
claude mcp add leftbrain -- leftbrain          # Claude Code, one line

Warum

Modelle sind rechtshirnig: flüssig, intuitiv und falsch bei 9.11 < 9.9, der Anzahl der r in strawberry, welcher Tag heute ist, wie viele Arbeitstage vor einer Frist verbleiben und ob der 03.04.2025 der 3. April oder der 4. März ist. Jede dieser Fragen hat eine exakte Antwort. leftbrain ist eine kleine, gut beschriebene Tool-Sammlung, die dem Modell diese Antwort liefert, statt es raten zu lassen.

Designregeln:

1. Nur deterministisch. Gleiche Eingabe, gleiche Ausgabe. Kein LLM-im-Tool.

2. Mehrdeutigkeit verweigern statt raten. IST, 03/04/2025, ton, oz, KB — jede dieser Eingaben liefert die konkreten Optionen statt einer stillen Annahme.

3. Jede Interpretation sichtbar machen. Jede Antwort enthält assumptions[] („als TT/MM gemäß Gebietsschema IN gelesen") und warnings[] („Tag auf Monatsende begrenzt").

4. Exakt und dezimal, zusammen. sqrt(2)/2 und 0.7071…, 7/4 und 1.75, damit das Modell nie neu rundet.

5. Wenige Tools, viele Modi. 13 Kern-Tools, jedes mit einem mode-Parameter, damit die Tool-Liste bei jedem Turn günstig bleibt.

6. Beschreibungen sagen wann, nicht was. Der übliche Fehler ist, dass das Modell das Tool nicht aufruft.

Related MCP server: Euclid

Tools

Kern (leftbrain, offline, reine Funktionen)

Extern (leftbrain-external, Netzwerk, schlüssellose öffentliche APIs)

Dateien (leftbrain-files, optional)

Für benutzerdefinierte Agenten-Schleifen, die selbst keine Dateien öffnen können (gehostete Agenten wie Claude Code können das bereits). pdf_text, pdf_info, image_info, image_to_base64 (Größe ändern/komprimieren auf ein Byte-Budget; liefert fertige Anthropic- und OpenAI-Bildblöcke), base64_to_file, file_info, read_text, list_dir. Der Zugriff ist auf LEFTBRAIN_FILE_ROOTS beschränkt.

Der Vertrag

Jedes Tool liefert denselben Umschlag:

{"ok": true,  "result": {...}, "assumptions": ["read as DD/MM per locale IN"], "warnings": []}
{"ok": false, "error": "ambiguous", "message": "...", "needs": {"field": "locale", "options": [...]}}
{"ok": false, "error": "invalid_input" | "unsupported" | "timeout" | "needs_rates" | "internal", "message": "..."}

result ist nie null. Wenn needs vorhanden ist, wähle eine Option und rufe erneut auf.

Installation

pip install leftbrain                 # library only
pip install "leftbrain[mcp]"          # + MCP servers (stdio)
pip install "leftbrain[all]"          # + external (httpx), files (pypdf, Pillow), HTTP server (uvicorn)

Python 3.11+. Keine API-Schlüssel.

Verwendung aus Python

import leftbrain as lb

lb.math_tool("eval", expr="(3+4i)*(1-2i)")["result"]["decimal"]      # '11 - 2i'
lb.math_tool("solve", equations=["x^2+1=0"])                          # ±i
lb.datetime_tool("convert_tz", value="2026-03-08 09:30", from_tz="Asia/Kolkata", to_tz="America/New_York")
lb.datetime_tool("parse", value="03/04/2025")                         # ok: False, needs.options = DD/MM or MM/DD
lb.datetime_tool("business_days", start="2026-10-01", end="2026-10-31", region="IN")
lb.scale_tool(from_qty=4, to_qty=7, entities=[{"name": "flour", "qty": "2.5", "unit": "cup"}])
lb.convert_tool(value=2, from_unit="ton", to_unit="kg")               # ambiguous: metric / short / long
lb.numbers_tool("allocate", total=100, parts=3)                       # 33.34 / 33.33 / 33.33
lb.numbers_tool("to_words", value=123456.5, system="indian", currency="INR")
lb.validate_tool("id", kind="gstin", value="27AAPFU0939F1ZV")
lb.validate_tool("assert", data=doc, rules=[{"path": "leave.days", "op": "lte", "value": 2}])

lb.TOOLS bildet Tool-Namen auf Funktionen ab, wenn du sie in OpenAI-Funktionsaufrufe, LangChain oder deine eigene Schleife einbinden möchtest — kein MCP erforderlich.

Verwendung als MCP-Server (stdio)

Claude Code

claude mcp add leftbrain -- leftbrain
claude mcp add leftbrain-external -- leftbrain-external
claude mcp add leftbrain-files -e LEFTBRAIN_FILE_ROOTS=/path/to/docs -- leftbrain-files

Claude Desktop / Cursor / Windsurf (claude_desktop_config.json, .cursor/mcp.json):

{
  "mcpServers": {
    "leftbrain":          { "command": "leftbrain" },
    "leftbrain-external": { "command": "leftbrain-external" }
  }
}

Keine Installation nötig: "command": "uvx", "args": ["--from", "leftbrain[all]", "leftbrain"].

Verwendung über HTTPS (gehostet)

Ein Prozess bedient jedes Tool-Set mit Streamable HTTP:

pip install "leftbrain[server]"
LEFTBRAIN_API_KEY=your-secret leftbrain-serve --port 8080
# core:      http://localhost:8080/mcp
# external:  http://localhost:8080/external/mcp
# files:     add --files (and set LEFTBRAIN_FILE_ROOTS)

Er läuft standardmäßig zustandslos und skaliert daher horizontal hinter jedem Load Balancer. TLS wird von der Plattform davor terminiert:

• Docker: docker build -t leftbrain . && docker run -p 8080:8080 -e LEFTBRAIN_API_KEY=… leftbrain

• Railway / Render / Fly.io: auf das Repo zeigen; die Dockerfile und $PORT werden automatisch übernommen, HTTPS wird bereitgestellt.

• Self-hosted: Caddy oder nginx davor setzen (reverse_proxy localhost:8080) oder einen Cloudflare Tunnel.

Dann einen Client mit der öffentlichen URL verbinden:

claude mcp add --transport http leftbrain https://leftbrain.example.com/mcp \
  --header "Authorization: Bearer your-secret"

Health: GET /healthz. Service-Beschreibung: GET /.

Pro-Benutzer-API-Schlüssel (öffentlicher kostenloser Tarif)

Damit andere Personen deine Bereitstellung mit eigenen Schlüsseln, Kontingenten und Ratenlimits nutzen können, aktiviere den Schlüsselspeicher zusätzlich zum (oder statt des) statischen Schlüssels:

LEFTBRAIN_KEYS_DB=/data/keys.sqlite3 leftbrain-serve     # or --keys-db

Der Speicher spricht SQLite (ein Pfad, für eine Instanz mit Volume) oder Postgres (LEFTBRAIN_KEYS_URL=postgres://…, pip install "leftbrain[postgres]") für Plattformen ohne persistenten Speicher. Die DSN wird aus LEFTBRAIN_KEYS_URL, dann DATABASE_URL, dann LEFTBRAIN_KEYS_DB gelesen — also wird die von Northflank/Render/Railway injizierte DATABASE_URL automatisch übernommen.

Mit einem konfigurierten Speicher bekommt leftbrain-serve auch eine Website:

• / — Landingpage (Browser) oder die JSON-Service-Beschreibung (Accept: application/json)

• /login — GitHub-OAuth; Schlüssel gehören zur verifizierten primären E-Mail des Kontos

• /dashboard — bis zu 3 aktive Schlüssel mit einer Lebensdauer von 30 / 90 / 365 Tagen (oder nie, mit einer Warnung) erstellen, heutige Nutzung und Ablaufdatum jedes Schlüssels sehen, einen Schlüssel erneut anzeigen, widerrufen

• /docs — Schnellstart mit Windows PowerShell / macOS / Linux-Tabs, MCP-Client-Einrichtung

• POST /demo/{numbers|convert|datetime|text} — schlüssellose Demo, 30 Anfragen/min pro IP

und die Schlüssel-API verhält sich so:

• Self-Service-Anmeldung: POST /keys/signup {"email": "dev@example.com"} → {"key": "lblz_…", "daily_quota": 1000, "rpm": 60}. Auf 3 Anmeldungen pro IP pro Tag und 3 aktive Schlüssel pro E-Mail begrenzt. Anonyme Anmeldung ist aus, außer LEFTBRAIN_OPEN_SIGNUP=1; mit der Website melden sich Personen stattdessen unter /login an.

• Jede Anfrage wird gemessen: X-RateLimit-Remaining-Today, X-RateLimit-Limit-Day, X-RateLimit-Limit-Minute-Header; 429 mit Retry-After, wenn ein Limit erreicht ist; 403 für einen deaktivierten Schlüssel und 403 {"error": "expired", "message": "key expired on 2026-11-25; create a new one at /dashboard"} sobald die Lebensdauer eines Schlüssels abgelaufen ist. Abgelaufene Schlüssel zählen nicht mehr zum Limit von 3 aktiven.

• Selbstprüfung des Aufrufers: GET /keys/me mit dem Schlüssel → Besitzer, Kontingent, heute verbraucht, expires_at.

Umgebung: GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, LEFTBRAIN_SECRET (Cookie-Signierung, 32+ zufällige Zeichen), LEFTBRAIN_BASE_URL (z. B. https://leftbrain.idlesync.in, für den OAuth-Callback) und LEFTBRAIN_TRUSTED_PROXY_HOPS (Standard 1) – wie viele Proxys hängen X-Forwarded-For vor dem Prozess an, sodass Pro-IP-Limits auf den Eintrag Ihres Proxys basieren und nicht auf dem vom Aufrufer gelieferten linkesten. Ein Reverse-Proxy (Northflank, Render, Fly, nginx) ist 1; Cloudflare davor ergibt 2; 0 bedeutet, dass kein Proxy davor ist und kein Forwarding-Header berücksichtigt wird.

Standardwerte stammen aus LEFTBRAIN_DEFAULT_DAILY_QUOTA (1000), LEFTBRAIN_DEFAULT_RPM (60), LEFTBRAIN_SIGNUPS_PER_IP_PER_DAY (3). Die Authentifizierung vergleicht immer nur einen SHA-256-Hash des Schlüssels. Wenn LEFTBRAIN_SECRET gesetzt ist, speichert der Store zusätzlich eine Fernet-verschlüsselte Kopie jedes Schlüssels unter einem aus diesem Geheimnis abgeleiteten Schlüssel, sodass der angemeldete Eigentümer seinen eigenen Schlüssel erneut im Dashboard sehen und in die Dokumentationsbeispiele eingefügt bekommen kann. Ein Rotieren von LEFTBRAIN_SECRET lässt vorhandene Schlüssel weiter funktionieren, aber nicht mehr anzeigen; lassen Sie das Geheimnis ungesetzt, wird nur der Hash gespeichert.

Admin-CLI (beliebige DSN):

leftbrain-keys create --owner you@example.com --daily 50000 --rpm 300 --expires 90d --note "partner"   # default 365d; --expires never warns
leftbrain-keys list                                     # one JSON line per key, with expires_at / expired
leftbrain-keys disable lblz_xxxxxxxx
leftbrain-keys enable lblz_xxxxxxxx
leftbrain-keys revoke lblz_xxxxxxxx
leftbrain-keys set lblz_xxxxxxxx --daily 20000 --rpm 120 --expires 30d   # --expires counts from now; also revives an expired key
leftbrain-keys usage --days 7
leftbrain-keys stats

Kostenloses Hosting, das passt: Northflank-Sandbox (Always-on-Dienst + kostenloses Postgres + benutzerdefinierte Domain) – siehe docs/deploy-northflank.md für eine Schritt-für-Schritt-Anleitung inklusive DNS für eine Subdomain.

Beispiele für Änderungen

Entwicklung

git clone https://github.com/Lazy-Coder-03/leftbrain && cd leftbrain
python -m venv .venv && . .venv/bin/activate     # .venv\Scripts\activate on Windows
pip install -e ".[dev]"
pytest                          # unit tests
python scripts/smoke.py         # every tool, end to end
python scripts/mcp_client_check.py   # spawn each MCP server over stdio and call it
ruff check src tests

Layout: src/leftbrain/core/ enthält die reinen Funktionen (eine Datei pro Tool), contract.py den Umschlag, mcp_server.py den Stdio-Server, serve.py den HTTP-Server, external/ und files/ die optionalen Sets.

Releases werden durch das Pushen eines vX.Y.Z-Tags erstellt – siehe docs/releasing.md; was sich in jeder Version geändert hat, steht in CHANGELOG.md.

Roadmap

• TypeScript-Port (gleiche Tool-Namen und Vertrag) für Node-basierte Agenten

• OCR-Fallback für gescannte PDFs

• csv/xlsx-Parsing in files

Lizenz

MIT