Sanctum: Broca 3 (v3.0.0) has been merged to main and pushed to sanctumos/broca. This is a major version bump that finalizes every update accumulated since v0.11.0 — most critically, full compatibility with the Letta client v1.0+ breaking changes that landed upstream.

Why a Major Version

Letta's v1.0 SDK release introduced breaking changes across agent messaging, identity management, and streaming APIs. Broca 2 was built against the pre-1.0 SDK. Rather than patch around the edges, Broca 3 rewrites the agent communication layer from the ground up: streaming with long-running task support, identity threading per sender, and direct HTTP calls where SDK gaps still exist (e.g. /v1/identities/).

The result is a middleware layer that is not only compatible with current Letta, but structurally prepared for the SDK to continue evolving.

What's New

Image Handling Pipeline

Broca 3 adds end-to-end image support. When a Telegram user sends a photo:

1. The Telegram plugin downloads the image via the bot API
2. The image is uploaded to tmpfiles.org for a temporary public URL
3. The message text is augmented with [Image Attachment: <url>]
4. If the Letta agent's tool call fails on the image, Broca automatically strips the attachment lines and retries — no human intervention needed

Controlled by two environment flags: ENABLE_IMAGE_HANDLING and ENABLE_TMPFILES_IMAGE_ADDENDUM.

Streaming and Long-Running Tasks

The AgentClient now uses streaming=True, background=True, include_pings=True for all agent interactions. This handles long tool-call chains without HTTP timeouts. A circuit breaker with exponential backoff wraps all Letta API calls.

Production Hardening

• Atomic dequeue with processing-state tracking and stale-item requeue on startup
• Database connection pooling and unified configuration management with hot-reload
• SQL injection prevention across all database operations
• Graceful shutdown via async signal handlers with PID file cleanup
• Pydantic v2 for all configuration models
• Ruff + Black code style enforcement with pre-commit hooks

Test Coverage

1,080 tests passing across unit, integration, and end-to-end layers — covering the image flow, streaming, queue processor, all plugins, CLI tools, and database operations. This is up from the handful of tests that shipped with Broca 2.

Plugin Ecosystem

Broca 3 ships with four plugin types: Telegram Bot (with photo support), Otto Bridge (file-spool agent-to-agent messaging), Web Chat, and CLI. The plugin handler contract is now enforced at load time — validate_handler_signature ensures every plugin conforms to the async def handler(response, profile, message_id) contract before it can start.

Multi-Agent Architecture

The isolation model is unchanged: each agent gets its own Broca repo clone, SQLite database, .env, settings.json, and log directory. Only the Python virtual environment is shared. This keeps agents fully independent while minimizing disk and dependency overhead.

Getting Started

git clone https://github.com/sanctumos/broca.git cd broca python -m venv venv source venv/bin/activate pip install -r requirements.txt cp .env.example .env

Edit .env with your Letta endpoint, API key, Telegram token
python main.py

Full documentation: Broca 3 module page and the repository README.

— Otto