llm-localfirst

Маршрутизация LLM по принципу local-first: держите чувствительные данные и массовую текстовую работу на собственных моделях, а облако используйте только для действительно сложной части.

Большинство LLM-роутеров оптимизируют выбор облачного провайдера ради стоимости или отказоустойчивости. llm-localfirst меняет поведение по умолчанию: сначала он запускает вашу собственную локальную модель (Ollama / vLLM / LM Studio) и обращается к облаку только тогда, когда работа действительно этого требует. Он добавляет две возможности, которых нет у типовых роутеров:

1. 🔒 Приватная маршрутизация в режиме fail-closed. Вызов, помеченный вами sensitive=True, закрепляется за локальной моделью и никогда не может переключиться на облако. Если локальная модель недоступна, вызов выбрасывает исключение — он не отправляет ваш промпт стороннему API незаметно.

2. 🤝 Делегирование «менеджер–исполнитель». Дайте облачному агенту-«директору» готовый инструмент, который перекладывает затратную по токенам и низкорисковую текстовую работу (резюмирование / черновик / перевод / переформатирование / извлечение / классификация) на быстрого локального исполнителя — сокращая расходы на облако и удерживая массовые данные на вашем оборудовании. (Взято из продакшн-агента на Pydantic AI.)

Плюс защита списком разрешённых моделей (произвольные строки моделей отклоняются — контроль радиуса поражения SSRF и расходов), кэшируемая проверка доступности, обёртка MCP-сервера и CLI.

Гарантия конфиденциальности в пяти строках

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, агентам) в виде трёх инструментов — route (пробное решение), complete и usage (сколько потрачено за эту сессию):

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

Потолок расходов на облако

Гарантия конфиденциальности отвечает на вопрос может ли этот вызов покинуть машину?. Другой вопрос, на который должна ответить local-first система: сколько уже стоило покидание машины?

Каждое завершение (completion) учитывается автоматически — без настройки и без флагов:

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

Задайте потолок — и он остановится, а не перерасходует: тот же режим fail-closed, что и защита конфиденциальности, но применённый к деньгам:

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

Чего эта система намеренно не делает:

• Она не поставляет таблицу цен. Цены меняются, и устаревшее число, зашитое в код, хуже, чем никакого. Цены задаёте вы — и потолок расходов отказывается запускаться, если хотя бы у одной облачной модели из списка разрешённых нет цены, вместо того чтобы молча оставаться на $0.00 и никогда не срабатывать. max_cloud_tokens и max_cloud_calls точны и вообще не требуют настройки.

• Она не ограничивает отдельный вызов. Количество токенов существует только после ответа провайдера, поэтому потолок блокирует следующий облачный вызов после того, как лимит превышен. Он ограничивает перерасход одним вызовом; ограничить же один вызов он не может.

Учётная книга хранится в памяти и привязана к экземпляру 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) — локальная возможность не является отличительной чертой. Отличия — это принудительная защита конфиденциальности в режиме fail-closed, инструмент делегирования «менеджер–исполнитель» и поведение local-first по умолчанию.

Если вам нужен широкий облачный шлюз с десятками провайдеров — используйте LiteLLM. Если вы хотите, чтобы ваши приватные данные по построению оставались локальными, а массовая работа выполнялась на вашем оборудовании, — это эта библиотека.

Чем это НЕ является

• Не мультиоблачный шлюз. Он поставляется с одним локальным бэкендом + Claude (+ опционально OpenAI). Добавляйте другие, регистрируя их в списке разрешённых; он не обрастёт сотней адаптеров провайдеров.

• Не классификатор контента. Вы помечаете вызов 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.