brain

A local, persona-agnostic assistant brain. Two tiers, both running entirely on small local models via Ollama — no cloud:

• Reflex tier — natural language → one structured action in ~30 ms (deterministic fast-paths + a tiny LLM router fallback). Commands, status queries, app/site launch.
• Deliberate tier — for hard or multi-step questions: a reasoner model picks a tool, fills its arguments, runs it, and loops (plan → act → observe → self-correct). The tools do the exact work, so a 3–4B model only has to route.

Bring your own persona — brain ships with a neutral default and lets you inject voice, identity, and a warm finalizer without touching the brain.

Why

Small local models guess at arithmetic, time, and facts. brain doesn't let them: it routes "if a train leaves at 2:40pm and the trip takes 95 minutes…" to a time_math tool that returns 4:15 PM exactly, instead of a confident wrong guess. On a checkable question set this moved capability 75% → 100% versus plain chat.

Install

git clone https://github.com/everyday-value-agent/brain && cd brain
pip install -e .                 # stdlib-only core
ollama pull qwen2.5:1.5b         # reflex router
ollama pull phi4-mini            # deliberate reasoner
ollama pull nomic-embed-text     # skill retrieval

Quickstart

python -m eva "what's my battery"             # reflex → a skill
DIANA_AGENT=1 python -m eva "how many minutes between 9:50am and 11:05am"
# → 75 minutes (1h 15m)

from eva import brain, agent

brain.interpret("set volume to 30")              # → Plan(system_skill, volume_set, {level:30})
agent.answer_once("convert 100 celsius to fahrenheit")   # → "100°C = 212.00°F."
agent.run_loop("convert 10 km to miles and what is 144 / 12")  # multi-step

Bring your own persona

from eva import brain
brain.set_system_prompt_provider(lambda: "You are Ada, a dry-witted ops assistant.")

Tools

eva/tools.py wraps the skill registry plus calculate, convert, define, get_time, weather, web_search, and deterministic time_math / time_diff. Add your own by appending a Tool(name, desc, params, fn) to the registry. Danger gating and a dry-run backstop are enforced once, in tools.run.

Configuration (env)

var	default	meaning
SOPHIE_ROUTER_MODEL	qwen2.5:1.5b	reflex router
SOPHIE_REASONER_MODEL	phi4-mini	deliberate reasoner
SOPHIE_MODEL	gemma2:2b	chat / optional finalizer
DIANA_AGENT	0	enable the deliberate tier
SOPHIE_REASONER_KEEP_ALIVE	2m	reasoner idle TTL (frees RAM)

The SOPHIE_ prefix is historical — the package was called sophie before the rename to eva. The variable names are kept so existing deployments don't break.

Benchmarks

python scripts/bench_reasoner.py phi4-mini nemotron-3-nano:4b   # pick a reasoner
DIANA_AGENT=1 python scripts/grade_capability.py               # chat vs tools

Tests

pip install -e ".[test]" && pytest -q

Where this comes from

brain is the persona-agnostic half of Diana, carved out automatically by scripts/carve-public.sh in that repo — so this is generated from a working assistant, not a demo written to look like one. The persona lives there; the reflex router, retrieval gate, skill registry and tool loop live here.

Part of Project EVA.

License

MIT