leftbrain

あなたのAIエージェントのための左脳。 言語モデルが苦手とするすべてのものに対して、正確で決定的な答えを提供します — 算術と微積分、日付とタイムゾーン、単位変換、比例スケーリング、カウント、ソート、検証、ランダム性、ハッシュ — さらにオプションのライブデータ（天気、為替レート）とファイルツール（PDFテキスト、画像→base64）も備えています。

プレーンな Pythonライブラリ として、または MCPサーバー（stdioまたはHTTPS）として、Claude Code、Claude Desktop、Cursor、Windsurf、Zed、その他のMCPクライアントと一緒に使用できます。

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

なぜ

モデルは右脳的です：流暢で直感的ですが、9.11 < 9.9、strawberry のrの数、今日が何日か、締め切りまでに残っている営業日数、03/04/2025が3月か4月かについて間違えます。これらのすべてには正確な答えがあります。leftbrainは、モデルが推測する代わりにその答えを与える、小さくてよく説明されたツールセットです。

設計ルール：

1. 決定的のみ。 同じ入力には同じ出力。ツール内のLLMはありません。

2. 推測する代わりに曖昧さを拒否。 IST、03/04/2025、ton、oz、KB — それぞれが暗黙の仮定ではなく具体的な選択肢を返します。

3. すべての解釈を表面化。 各レスポンスには assumptions[]（「ロケールINに従ってDD/MMとして読む」）と warnings[]（「日が月末にクランプされました」）が含まれます。

4. 正確と小数を同時に。 sqrt(2)/2 および 0.7071…、7/4 および 1.75。モデルが再丸めしないようにします。

5. 少数のツール、多数のモード。 13のコアツール、それぞれに mode パラメータがあり、毎ターンのツールリストを安価に保ちます。

6. 説明は いつ を言い、何 を言わない。 通常の失敗はモデルがツールを呼び出さないことです。

Related MCP server: Euclid

ツール

コア（leftbrain、オフライン、純関数）

外部（leftbrain-external、ネットワーク、キー不要の公開API）

ファイル（leftbrain-files、オプトイン）

ファイルを自分で開けないカスタムエージェントループ用（Claude Codeなどのホスト型エージェントはすでに開けます）。pdf_text、pdf_info、image_info、image_to_base64（バイト予算に合わせてリサイズ/圧縮、すぐ使えるAnthropicおよびOpenAI画像ブロックを返す）、base64_to_file、file_info、read_text、list_dir。アクセスは LEFTBRAIN_FILE_ROOTS に制限されています。

契約

すべてのツールは同じエンベロープを返します：

{"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 が null になることはありません。needs が存在する場合は、オプションを選んで再度呼び出してください。

インストール

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以上。APIキーは不要です。

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 はツール名を関数にマップします。OpenAIの関数呼び出し、LangChain、または独自のループに配線したい場合に使用できます — MCPは不要です。

MCPサーバーとして使用（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" }
  }
}

インストール不要："command": "uvx", "args": ["--from", "leftbrain[all]", "leftbrain"]。

HTTPS経由で使用（ホスト型）

1つのプロセスが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)

デフォルトでステートレスに動作するため、任意のロードバランサーの背後で水平スケールします。TLSは前面のプラットフォームで終端されます：

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

• Railway / Render / Fly.io: リポジトリを指定します。Dockerfile と $PORT は自動的に認識され、HTTPSが提供されます。

• セルフホスト: Caddyまたはnginxを前面に配置（reverse_proxy localhost:8080）、またはCloudflare Tunnelを使用します。

次に、クライアントを公開URLに接続します：

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

ヘルスチェック：GET /healthz。サービス説明：GET /。

ユーザーごとのAPIキー（公開無料ティア）

他の人が独自のキー、クォータ、レート制限でデプロイメントを使用できるようにするには、静的キーの代わりに（または併用して）キーストアを有効にします：

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

ストアは SQLite（パス、ボリューム付きの単一インスタンス用）または Postgres（LEFTBRAIN_KEYS_URL=postgres://…、pip install "leftbrain[postgres]"）を話します。永続ディスクのないプラットフォーム向けです。DSNは LEFTBRAIN_KEYS_URL、次に DATABASE_URL、次に LEFTBRAIN_KEYS_DB から読み取られます — そのためNorthflank/Render/Railwayが注入する DATABASE_URL が自動的に認識されます。

ストアが設定されると、leftbrain-serve はウェブサイトも提供します：

• / — ランディングページ（ブラウザ）またはJSONサービス説明（Accept: application/json）

• /login — GitHub OAuth。キーはアカウントの確認済みプライマリメールに属します

• /dashboard — 有効期間30/90/365日（または警告付きで無期限）のアクティブキーを最大3つ作成、今日の使用量と各キーの有効期限を表示、キーを再度表示、失効

• /docs — Windows PowerShell / macOS / Linuxタブ付きクイックスタート、MCPクライアント設定

• POST /demo/{numbers|convert|datetime|text} — キー不要のデモ、IPあたり30 req/min

キーAPIは次のように動作します：

• セルフサービスサインアップ: POST /keys/signup {"email": "dev@example.com"} → {"key": "lblz_…", "daily_quota": 1000, "rpm": 60}。IPあたり1日3回のサインアップとメールあたり3つのアクティブキーに制限されます。匿名サインアップは LEFTBRAIN_OPEN_SIGNUP=1 でない限り オフ です。ウェブサイトがある場合は、代わりに /login でサインインします。

• すべてのリクエスト はメータリングされます：X-RateLimit-Remaining-Today、X-RateLimit-Limit-Day、X-RateLimit-Limit-Minute ヘッダー。制限に達すると 429 と Retry-After。無効なキーには 403、キーの有効期間が終了すると 403 {"error": "expired", "message": "key expired on 2026-11-25; create a new one at /dashboard"}。期限切れキーは3アクティブ上限にカウントされません。

• 呼び出し側の自己チェック: GET /keys/me をキーとともに → 所有者、クォータ、今日の使用量、expires_at。

環境: GITHUB_CLIENT_ID、GITHUB_CLIENT_SECRET、LEFTBRAIN_SECRET(Cookie署名用、32文字以上のランダム文字列)、LEFTBRAIN_BASE_URL(例: https://leftbrain.idlesync.in、OAuthコールバックに使用)、および LEFTBRAIN_TRUSTED_PROXY_HOPS(デフォルト 1)— プロセスの前段で X-Forwarded-For に追記するプロキシの数。これにより、IP単位の制限は、呼び出し元が指定した最左のエントリではなく、あなたのプロキシが書き込んだエントリをキーとして判定されます。リバースプロキシが1つ(Northflank、Render、Fly、nginx)の場合は 1。さらに Cloudflare を前段に追加すると 2 になります。0 はプロキシが存在せず、転送ヘッダーを信頼しないことを意味します。

デフォルト値は LEFTBRAIN_DEFAULT_DAILY_QUOTA(1000)、LEFTBRAIN_DEFAULT_RPM(60)、LEFTBRAIN_SIGNUPS_PER_IP_PER_DAY(3)から取得されます。認証は常にキーの SHA-256 のみを比較します。LEFTBRAIN_SECRET が設定されている場合、ストアは各キーの Fernet 暗号化コピーも、そのシークレットから導出されたキーの下に保持するため、サインインした所有者はダッシュボードで自分のキーを再度表示し、ドキュメントの例に自動入力することができます。LEFTBRAIN_SECRET をローテーションすると、既存のキーは引き続き機能しますが、再表示はできなくなります。シークレットを未設定のままにすると、ハッシュのみが保存されます。

管理CLI(任意の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

ぴったりの無料ホスティング: Northflank のサンドボックス(常時稼働サービス + 無料 Postgres + カスタムドメイン)— サブドメインの DNS を含むステップバイステップは docs/deploy-northflank.md を参照してください。

変更される内容の例

開発

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

構成: src/leftbrain/core/ には純粋関数(ツールごとに1ファイル)、contract.py にはエンベロープ、mcp_server.py には stdio サーバー、serve.py には HTTP サーバー、external/ と files/ にはオプションのセットが格納されます。

リリースは vX.Y.Z タグをプッシュして作成されます — docs/releasing.md を参照してください。各バージョンの変更内容は CHANGELOG.md に記載されています。

ロードマップ

• Nodeベースのエージェント向け TypeScript ポート(同じツール名とコントラクト)

• スキャンされた PDF の OCR フォールバック

• files での csv/xlsx 解析

ライセンス

MIT