leftbrain

El hemisferio izquierdo para tu agente de IA. Respuestas exactas y deterministas para todo aquello en lo que los modelos de lenguaje fallan — aritmética y cálculo, fechas y zonas horarias, conversión de unidades, escalado proporcional, conteo, ordenación, validación, aleatoriedad, hashes — además de datos en vivo opcionales (clima, tipos de cambio) y herramientas de archivos (texto PDF, imagen → base64).

Úsalo como una biblioteca de Python simple, o como un servidor MCP (stdio o HTTPS) con Claude Code, Claude Desktop, Cursor, Windsurf, Zed, o cualquier cliente MCP.

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

Por qué

Los modelos son de hemisferio derecho: fluidos, intuitivos, y se equivocan en 9.11 < 9.9, el número de erres en strawberry, qué día es, cuántos días hábiles quedan antes de una fecha límite, y si 03/04/2025 es marzo o abril. Cada uno de esos tiene una respuesta exacta. leftbrain es un pequeño conjunto de herramientas bien descritas que le da al modelo esa respuesta en lugar de dejar que adivine.

Reglas de diseño:

1. Solo determinista. Misma entrada, misma salida. Sin LLM dentro de la herramienta.

2. Rechaza la ambigüedad en lugar de adivinar. IST, 03/04/2025, ton, oz, KB — cada uno devuelve las opciones concretas en lugar de una suposición silenciosa.

3. Muestra cada interpretación. Cada respuesta incluye assumptions[] ("leído como DD/MM según locale IN") y warnings[] ("día ajustado al final del mes").

4. Exacto y decimal, juntos. sqrt(2)/2 y 0.7071…, 7/4 y 1.75, para que el modelo nunca vuelva a redondear.

5. Pocas herramientas, muchos modos. 13 herramientas principales, cada una con un parámetro mode, para que la lista de herramientas siga siendo económica en cada turno.

6. Las descripciones dicen cuándo, no qué. El fallo habitual es que el modelo no llama a la herramienta.

Related MCP server: Euclid

Herramientas

Núcleo (leftbrain, sin conexión, funciones puras)

Externas (leftbrain-external, red, APIs públicas sin clave)

Archivos (leftbrain-files, opcional)

Para bucles de agente personalizados que no pueden abrir archivos por sí mismos (los agentes alojados como Claude Code ya pueden). pdf_text, pdf_info, image_info, image_to_base64 (redimensionar/comprimir a un presupuesto de bytes; devuelve bloques de imagen listos para Anthropic y OpenAI), base64_to_file, file_info, read_text, list_dir. El acceso se limita a LEFTBRAIN_FILE_ROOTS.

El contrato

Cada herramienta devuelve el mismo sobre:

{"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 nunca es null. Cuando needs está presente, elige una opción y vuelve a llamar.

Instalación

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+. Cero claves API.

Uso desde 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 mapea nombres de herramientas a funciones si quieres conectarlas a OpenAI function-calling, LangChain, o tu propio bucle — no se requiere MCP.

Uso como servidor 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" }
  }
}

Sin instalación: "command": "uvx", "args": ["--from", "leftbrain[all]", "leftbrain"].

Uso a través de HTTPS (alojado)

Un solo proceso sirve todos los conjuntos de herramientas con 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)

Se ejecuta sin estado por defecto, por lo que escala horizontalmente detrás de cualquier balanceador de carga. TLS lo termina la plataforma que tiene delante:

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

• Railway / Render / Fly.io: apunta al repositorio; el Dockerfile y $PORT se recogen automáticamente, HTTPS está incluido.

• Autoalojado: pon Caddy o nginx delante (reverse_proxy localhost:8080), o un túnel de Cloudflare.

Luego conecta un cliente a la URL pública:

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

Salud: GET /healthz. Descripción del servicio: GET /.

Claves API por usuario (nivel gratuito público)

Para permitir que otras personas usen tu despliegue con sus propias claves, cuotas y límites de tasa, activa el almacén de claves en lugar de (o junto a) la clave estática:

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

El almacén habla SQLite (una ruta, para una instancia con un volumen) o Postgres (LEFTBRAIN_KEYS_URL=postgres://…, pip install "leftbrain[postgres]") para plataformas sin disco persistente. El DSN se lee de LEFTBRAIN_KEYS_URL, luego DATABASE_URL, luego LEFTBRAIN_KEYS_DB — así que el DATABASE_URL inyectado por Northflank/Render/Railway se recoge automáticamente.

Con un almacén configurado, leftbrain-serve también incluye un sitio web:

• / — página de aterrizaje (navegadores) o la descripción del servicio JSON (Accept: application/json)

• /login — OAuth de GitHub; las claves pertenecen al correo principal verificado de la cuenta

• /dashboard — crea hasta 3 claves activas con una vida de 30 / 90 / 365 días (o nunca, con una advertencia), ve el uso de hoy y cuándo expira cada clave, muestra una clave de nuevo, revoca

• /docs — inicio rápido con pestañas de Windows PowerShell / macOS / Linux, configuración de cliente MCP

• POST /demo/{numbers|convert|datetime|text} — demo sin clave, 30 req/min por IP

y la API de claves se comporta así:

• Registro autoservicio: POST /keys/signup {"email": "dev@example.com"} → {"key": "lblz_…", "daily_quota": 1000, "rpm": 60}. Limitado a 3 registros por IP al día y 3 claves activas por correo. El registro anónimo está desactivado a menos que LEFTBRAIN_OPEN_SIGNUP=1; con el sitio web, la gente inicia sesión en /login en su lugar.

• Cada solicitud se mide: cabeceras X-RateLimit-Remaining-Today, X-RateLimit-Limit-Day, X-RateLimit-Limit-Minute; 429 con Retry-After cuando se alcanza un límite; 403 para una clave deshabilitada, y 403 {"error": "expired", "message": "key expired on 2026-11-25; create a new one at /dashboard"} cuando la vida de una clave termina. Las claves expiradas dejan de contar para el límite de 3 activas.

• Autocomprobación del llamador: GET /keys/me con la clave → propietario, cuota, usado hoy, expires_at.

Entorno: GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, LEFTBRAIN_SECRET (firma de cookies, 32+ caracteres aleatorios), LEFTBRAIN_BASE_URL (p. ej. https://leftbrain.idlesync.in, usado para el callback de OAuth) y LEFTBRAIN_TRUSTED_PROXY_HOPS (por defecto 1): cuántos proxies añaden a X-Forwarded-For delante del proceso, de modo que los límites por IP se basan en la entrada que escribió tu proxy en lugar de la más a la izquierda proporcionada por el llamante. Un proxy inverso (Northflank, Render, Fly, nginx) es 1; añade Cloudflare delante y pasa a ser 2; 0 significa que nada lo proxya y no se cree ninguna cabecera de reenvío.

Los valores por defecto provienen de LEFTBRAIN_DEFAULT_DAILY_QUOTA (1000), LEFTBRAIN_DEFAULT_RPM (60), LEFTBRAIN_SIGNUPS_PER_IP_PER_DAY (3). La autenticación solo compara un SHA-256 de la clave. Cuando LEFTBRAIN_SECRET está definido, el almacén también guarda una copia cifrada con Fernet de cada clave, bajo una clave derivada de ese secreto, de modo que el propietario con sesión iniciada pueda volver a ver su propia clave en el panel y que se rellene en los ejemplos de la documentación. Rotar LEFTBRAIN_SECRET deja las claves existentes funcionando pero ya no se pueden revelar; deja el secreto sin definir y solo se almacena el hash.

CLI de administración (cualquier 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

Alojamiento gratuito que encaja: el sandbox de Northflank (servicio siempre activo + Postgres gratuito + dominio personalizado) — consulta docs/deploy-northflank.md para una guía paso a paso, incluido el DNS para un subdominio.

Ejemplos de lo que cambia

Desarrollo

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

Distribución: src/leftbrain/core/ contiene las funciones puras (un archivo por herramienta), contract.py el sobre, mcp_server.py el servidor stdio, serve.py el servidor HTTP, external/ y files/ los conjuntos opcionales.

Las versiones se publican empujando una etiqueta vX.Y.Z — consulta docs/releasing.md; lo que cambió en cada una está en CHANGELOG.md.

Hoja de ruta

• Puerto a TypeScript (mismos nombres de herramientas y contrato) para agentes basados en Node

• Respaldo OCR para PDFs escaneados

• Análisis de csv/xlsx en files

Licencia

MIT