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, количества букв «r» в strawberry, какой сегодня день, сколько рабочих дней осталось до дедлайна и является ли 03/04/2025 мартом или апрелем. На каждый из этих вопросов есть точный ответ. leftbrain — это небольшой, хорошо описанный набор инструментов, который даёт модели этот ответ, а не позволяет ей гадать.

Правила дизайна:

1. Только детерминированность. Одинаковый вход — одинаковый выход. Никаких LLM внутри инструментов.

2. Отказ от двусмысленности вместо угадывания. IST, 03/04/2025, ton, oz, KB — каждый возвращает конкретные варианты, а не молчаливое предположение.

3. Показывать все интерпретации. Каждый ответ содержит assumptions[] («прочитано как ДД/ММ согласно локали IN») и 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 function-calling, 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 (хостинг)

Один процесс обслуживает все наборы инструментов через 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 предоставляется.

• Self-hosted: поставьте 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 /.

Per-user API keys (public free tier)

Чтобы позволить другим людям использовать ваше развёртывание с их собственными ключами, квотами и лимитами скорости, включите хранилище ключей вместо (или вместе со) статическим ключом:

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 — так что внедрённый DATABASE_URL от Northflank/Render/Railway подхватывается автоматически.

С настроенным хранилищем leftbrain-serve также обзаводится веб-сайтом:

• / — целевая страница (браузеры) или JSON-описание сервиса (Accept: application/json)

• /login — GitHub OAuth; ключи принадлежат подтверждённому основному email аккаунта

• /dashboard — создавайте до 3 активных ключей со сроком жизни 30 / 90 / 365 дней (или бессрочно, с предупреждением), смотрите сегодняшнее использование и когда истекает каждый ключ, показывайте ключ снова, отзывайте

• /docs — краткое руководство с вкладками Windows PowerShell / macOS / Linux, настройка MCP-клиента

• POST /demo/{numbers|convert|datetime|text} — демо без ключа, 30 запросов/мин на IP

и API ключей ведёт себя так:

• Самостоятельная регистрация: POST /keys/signup {"email": "dev@example.com"} → {"key": "lblz_…", "daily_quota": 1000, "rpm": 60}. Ограничение: 3 регистрации на IP в день и 3 активных ключа на email. Анонимная регистрация выключена, если не 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 привязывались к записи, которую добавил ваш прокси, а не к самой левой записи, подставленной вызывающей стороной. Один обратный прокси (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/ находятся чистые функции (по одному файлу на инструмент), в contract.py — конверт, в mcp_server.py — stdio-сервер, в serve.py — HTTP-сервер, в external/ и files/ — опциональные наборы.

Релизы выпускаются отправкой тега vX.Y.Z — см. docs/releasing.md; что изменилось в каждом из них, описано в CHANGELOG.md.

Дорожная карта

• Порт на TypeScript (те же имена инструментов и контракт) для агентов на Node

• OCR-запасной вариант для сканированных PDF

• Разбор csv/xlsx в files

Лицензия

MIT