Broker & Arena

Open source agent runtime for ferricula.

What the broker does

The broker (delos-broker.py) sits between ferricula and the LLM. It is the runtime that turns a language model into a memory-backed agent.

Tool-call loop — the broker sends tool definitions to the LLM, receives tool-call requests back, executes them against ferricula's HTTP API, and returns the results. This loop runs until the LLM produces a final text response.

Embedding — before writing a memory to ferricula, the broker embeds the text via shivvr to produce a 1536-dimension vector. The LLM never handles raw vectors.

Load governance — on each turn, the broker calls GET /tools to check the current load tier. Based on the tier, it filters which tools the LLM can see. At CRITICAL, the broker bypasses the small model entirely and escalates to a frontier model.

Idle curiosity — when the agent is quiet (no user input), the broker runs an idle loop. It generates a curiosity_query from recent memories, web-crawls it via GrubCrawler, and ingests the results back into ferricula. The agent learns on its own.

Audit trail — every tool call the LLM makes is logged to ferricula as a memory on the thinking channel. This gives you a complete record of what the agent did and why.

The tool surface

The broker exposes 14 tools to the LLM. Which tools are visible depends on the current load tier.

Load governance

Each turn, the broker calls GET /tools on ferricula. The response includes the current load tier, which determines the active tool surface.

At CRITICAL, the broker stops sending tool calls to the small local model. Instead, it escalates to a frontier model (Claude via Anthropic API) for the turn. This is ponder escalation — the system recognizes it's overwhelmed and brings in a more capable reasoner.

Loading a core into a new model

Because memories live in ferricula — not in the LLM — you can swap the model without losing anything. The persona (system prompt) shapes how the LLM speaks. The memories shape what it knows. These are independent layers.

Steps

1. Keep the ferricula container running (or keep the Docker volume mounted).

2. Change the BROKER_MODEL env var to any Ollama model, or modify the broker code to use a different LLM provider entirely.

3. Start the broker. The new model inherits the full identity automatically — all memories, keystones, graph edges, and emotional state persist.

4. On the first turn, the broker calls memory_recall and the existing memories surface. The new model picks up where the old one left off.

Example: two brokers, same core

# Broker A: local Gemma model
FERRICULA_URL=http://localhost:8765 \
BROKER_MODEL=gemma3:12b \
SHIVVR_URL=https://shivvr.nuts.services \
python delos-broker.py

# Broker B: Claude via Anthropic API (same ferricula)
FERRICULA_URL=http://localhost:8765 \
BROKER_MODEL=claude-sonnet-4-20250514 \
ANTHROPIC_API_KEY=sk-... \
python delos-broker.py

Both brokers read from and write to the same ferricula instance. Memories created by one are visible to the other. The agent's knowledge is continuous across model swaps.

Running the arena

The ferricula-arena repository contains the broker and a Python SDK for building your own integrations.

Clone and run

git clone https://github.com/DeepBlueDynamics/ferricula-arena.git
cd ferricula-arena
pip install -r requirements.txt

# Set environment
export FERRICULA_URL=http://localhost:8765
export SHIVVR_URL=https://shivvr.nuts.services
export BROKER_MODEL=gemma3:12b

python delos-broker.py

Python SDK

The SDK provides FerriculaClient and ShivvrClient for direct programmatic access.

from arena.clients import FerriculaClient, ShivvrClient
import asyncio

async def main():
    ferricula = FerriculaClient("http://localhost:8765")
    shivvr = ShivvrClient("https://shivvr.nuts.services")

    # Embed and store
    vec = await shivvr.embed("The best products make you feel something.")
    mid = await ferricula.remember("The best products make you feel something.", vec,
                                   channel="hearing", importance=0.8)

    # Recall
    hits = await ferricula.recall_text("what makes great design", shivvr, k=5)
    for h in hits:
        print(f"id={h.id} fidelity={h.fidelity:.3f}")

asyncio.run(main())

Key files