leftbrain

AI 에이전트를 위한 좌뇌(left brain). 언어 모델이 약한 모든 것에 대해 정확하고 결정적인 답변을 제공합니다 — 산술과 미적분, 날짜와 시간대, 단위 변환, 비례 스케일링, 세기(counting), 정렬, 검증, 무작위성, 해시 — 그리고 선택적으로 실시간 데이터(날씨, 환율)와 파일 도구(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. 결정적(Deterministic)만. 같은 입력, 같은 출력. 도구 안에 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로 제한됩니다.

계약(Contract)

모든 도구는 동일한 봉투(envelope)를 반환합니다:

{"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로 사용(호스팅)

하나의 프로세스가 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)

기본적으로 무상태(stateless)로 실행되므로 모든 로드 밸런서 뒤에서 수평 확장이 가능합니다. 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회/분

그리고 키 API는 다음과 같이 동작합니다:

• 셀프 서비스 가입: POST /keys/signup {"email": "dev@example.com"} → {"key": "lblz_…", "daily_quota": 1000, "rpm": 60}. IP당 하루 3회 가입, 이메일당 활성 키 3개로 제한됩니다. 익명 가입은 LEFTBRAIN_OPEN_SIGNUP=1이 아니면 비활성화됩니다. 웹 사이트가 있으면 사람들은 대신 /login에서 로그인합니다.

• 모든 요청은 계량됩니다: X-RateLimit-Remaining-Today, X-RateLimit-Limit-Day, X-RateLimit-Limit-Minute 헤더; 한도에 도달하면 Retry-After와 함께 429; 비활성화된 키는 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(쿠키 서명용, 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는 봉투(envelope)를, 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