llm-localfirst

ローカルファーストのLLMルーティング — 機密データと大量のテキスト処理は自前のモデルで行い、難しい部分だけクラウドに任せる。

ほとんどのLLMルーターは、コストやフェイルオーバーのためにどのクラウドプロバイダーを呼ぶかを最適化します。llm-localfirst はそのデフォルトを逆転させます。まず自分のローカルモデル（Ollama / vLLM / LM Studio）で実行し、本当に必要な場合にだけクラウドに手を伸ばします。一般的なルーターにはない2つの機能を追加します。

1. 🔒 フェイルクローズするプライバシールーティング。 sensitive=True と指定した呼び出しはローカルモデルに固定され、クラウドへのフォールバックは決して許可されません。ローカルモデルがダウンしている場合、呼び出しは例外を発生させ、プロンプトを第三者APIに静かに送信することはありません。

2. 🤝 マネージャー・ワーカー委譲。 クラウドの「ディレクター」エージェントに、トークン消費が大きくリスクの低いテキスト処理（要約 / 下書き / 翻訳 / 再フォーマット / 抽出 / 分類）を高速なローカルワーカーにオフロードするドロップインツールを提供します。クラウド費用を削減し、大量データを自社ハードウェアに保持します。（本番のPydantic AIエージェントから抽出）

さらに、モデル許可リストガード（任意のモデル文字列を拒否 — SSRF／コスト爆発半径の制御）、キャッシュ付き到達可能性プローブ、MCPサーバーラッパー、CLIも備えています。

プライバシー保証、5行で

from llm_localfirst import Router, LocalUnavailable

router = Router.from_env()
try:
    out = router.complete("Redact all PII from this record.",
                          source=customer_record, sensitive=True)
except LocalUnavailable:
    # Local model is down. We did NOT send the record to the cloud. You decide.
    ...

sensitive=True はこのデータがマシンの外に出てはならないことを意味します。ルーターは漏洩するくらいなら失敗を選びます。この非対称性 — 機密呼び出しはフェイルクローズ、通常の大量呼び出しはクラウドにフォールバック — こそがこの製品の本質です。

Related MCP server: OpenAI-Compatible MCP Gateway

インストール

pip install llm-localfirst              # the routing brain — zero provider SDKs
pip install "llm-localfirst[openai]"    # + talk to local Ollama/vLLM/LM Studio (and cloud OpenAI)
pip install "llm-localfirst[anthropic]" # + Claude (the default cloud fallback / reason model)
pip install "llm-localfirst[all]"       # everything (also: mcp, pydantic-ai)

決定パス（decide()）はプロバイダーSDKを一切インポートしないため、コアだけをインストールすればルーティングの確認 — そしてテストスイート全体の実行 — が可能です。

60秒クイックスタート（Ollama）

ollama pull qwen2.5:7b          # any OpenAI-compatible local server works
pip install "llm-localfirst[openai,anthropic]"
export ANTHROPIC_API_KEY=sk-ant-...   # only needed for the cloud fallback / reason path

from llm_localfirst import Router, Kind

router = Router.from_env()

# 1) Inspect routing WITHOUT spending a token.
print(router.decide(kind=Kind.BULK))     # -> local  (cheap + private)
print(router.decide(kind="reason"))      # -> cloud  (the hard part)
print(router.decide(sensitive=True))     # -> local  (pinned; never cloud)

# 2) Actually run it. Bulk work prefers local, and falls back to cloud only if local is down.
print(router.complete("Summarize this in one sentence.",
                      source=long_text, kind=Kind.BULK).text)

またはシェルから:

llm-localfirst doctor                      # show config, the allowlist, and local up/down
llm-localfirst route "summarize this" --kind bulk
llm-localfirst route "redact this" --sensitive    # exits non-zero if local is down (fail-closed)

ルーティングの決定方法

decide() はローカルモデルに到達可能かどうかをプローブし（キャッシュ付き）、以下のルールを順に適用します:

明示的な model は許可リスト上の名前である必要があり、任意の文字列（または紛れ込んだURL）は ModelNotAllowed を発生させます。この許可リストがSSRF／コストガードです — 呼び出し元がルーターを新しいエンドポイントや、設定されていない高価なモデルに向けることは決してできません。

マネージャー・ワーカー委譲（Pydantic AI）

クラウドのディレクターに計画とツール呼び出しを任せたまま、単純なテキスト処理をローカルワーカーにオフロードします:

from pydantic_ai import Agent
from llm_localfirst import Router
from llm_localfirst.integrations.pydantic_ai import attach_worker

router = Router.from_env()
director = Agent("anthropic:claude-haiku-4-5", system_prompt="...")

# Adds a `delegate_to_worker(task, source)` tool that routes to your LOCAL model.
# attach_worker REFUSES a non-local worker, so delegated source text can't leak.
attach_worker(director, router, worker_model="local",
              on_delegate=lambda task, result: ...)  # optional observability hook

ディレクターは要約、下書き、翻訳、再フォーマット、抽出に delegate_to_worker を呼び出します。これらはクラウドのトークンを消費する代わりにGPU上で実行されます。examples/manager_worker.py を参照してください。

MCPネイティブ

ルーターを任意のMCPクライアント（Claude Desktop、IDE、エージェント）に3つのツールとして公開します — route（ドライな決定）、complete、usage（このセッションの消費量）:

pip install "llm-localfirst[mcp]"
llm-localfirst mcp        # serves over stdio

クラウド費用の上限

プライバシー保証は*この呼び出しはマシンの外に出てもよいか？*という問いに答えます。ローカルファーストの構成が答えなければならないもう1つの問いは、*マシンの外に出たことで既にいくらかかっているか？*です。

すべての完了は自動的に計上されます — 設定もフラグも不要です:

router = Router.from_env()
router.complete("summarise this", source=long_document)

router.ledger.calls("cloud")            # 1
router.ledger.tokens("local")           # Usage(input_tokens=..., output_tokens=...)
router.ledger.snapshot()                # JSON-safe, for logs

上限を設定すれば、超過するのではなく停止します — プライバシーピンと同じフェイルクローズの姿勢を、お金に適用したものです:

from llm_localfirst import Budget, Router

router = Router(..., budget=Budget(max_cloud_tokens=200_000))
...
llm_localfirst.BudgetExceeded: cloud token budget spent: 203_400/200_000 tokens

ローカル呼び出しは決して制限されません。 ローカル実行の意味を損なうため、上限を設けることはありません — クラウド予算を使い切ったということはクラウドが閉じられたというだけで、大量処理は流れ続けます。

または、価格が必要なコストベースで:

export LF_PRICES='{"haiku": [0.8, 4.0], "sonnet": [3.0, 15.0], "opus": [15.0, 75.0]}'
export LF_MAX_CLOUD_COST=5.00

これが意図的に行わない2つのこと:

• 価格表は同梱しません。 価格は変動し、古いハードコードされた数値は数値がないより悪いものです。価格はユーザーが提供します — そしてコスト上限は、許可リスト上のクラウドモデルに価格がない場合、静かに $0.00 のまま発動しないのではなく、起動を拒否します。max_cloud_tokens と max_cloud_calls は正確で、設定は一切不要です。

• 単一の呼び出しを制限しません。 トークン数はプロバイダーが応答して初めて存在するため、上限は超過後の次のクラウド呼び出しをブロックします。超過を1呼び出しに抑えることはできますが、1呼び出し自体を制限することはできません。

台帳はメモリ上にあり、Router にスコープされます。これはプロセスのためのガードレールであり、課金ではありません — プロセスをまたいで支出を強制する必要がある場合は、ledger.snapshot() を独自のストアに永続化してください。

llm-localfirst complete "..." --usage    # tally on stderr, completion on stdout
llm-localfirst doctor                    # shows the budget and which models are priced

比較

llm-localfirst は汎用のマルチプロバイダーゲートウェイではありませんし、そうあろうともしていません。明確かつ公平に言うと: LiteLLM と Bifrost は既にローカルモデル（Ollama、vLLM）へのルーティングが可能です — ローカル対応は差別化要因ではありません。差別化要因は、フェイルクローズのプライバシーピン、マネージャー・ワーカー委譲ツール、そしてローカルファーストのデフォルト姿勢です。

多数のプロバイダーを持つ広範なクラウドゲートウェイが必要なら、LiteLLM を使用してください。プライベートデータを構造的にローカルに留め、大量処理を自社ハードウェアで実行したいなら、これがこのライブラリです。

これは何ではないか

• マルチクラウドゲートウェイではありません。 ローカルバックエンド1つ + Claude（+ オプションのOpenAI）を同梱します。追加するには許可リストに登録します。100のプロバイダーシムに成長することはありません。

• コンテンツ分類器ではありません。 ユーザーが呼び出しに sensitive=True（または kind）をタグ付けします。テキストがプライベートかどうかを推測するのではなく、宣言された内容を強制します。

• ロードバランシングやセマンティックキャッシュではありません。 これらはゲートウェイ機能です。これはプライバシー保証付きのルーティングポリシーです。

• コスト分析や課金ではありません。 費用上限はプロセス内のガードレールであり、ダッシュボードではありません: プロセスが終了するとカウントはリセットされ、プロバイダーが報告した内容を報告します。実際の数値については、プロバイダーの請求書を読んでください。

• プロンプトファイアウォールではありません。 呼び出しがどこで実行されるかを制御するもので、中身を制御するものではありません。

設定

すべての設定は環境変数（プレフィックス LF_）または .env ファイルから読み取られます。.env.example を参照してください。主なもの:

開発

uv venv && uv pip install -e '.[dev]'
ruff check . && pytest

ルーティングの核（ポリシー、レジストリ、ルーター、到達可能性）は100%オフラインでカバーされています — ネットワークもプロバイダーSDKも不要です。コントリビューション歓迎です。CONTRIBUTING.md を参照してください。

ライセンス

MIT © Shaxzodbek Qambaraliyev / Blaze。LICENSE を参照してください。