agentic-brain

What is agentic-brain?

agentic-brain is an open-source Python framework for building AI agents you can actually ship. It handles the parts that trip teams up in production: intelligent LLM routing with local-first fallbacks, GraphRAG-backed memory that degrades gracefully without Neo4j, durable workflows inspired by Temporal, and a screen-reader-friendly CLI built for people who rely on assistive technology. You get a working agent loop in five minutes. The same codebase scales to multi-agent swarms with vector search, Kafka event streams, and enterprise auth.

Why we built this

This project started because the available agent frameworks assumed a sighted developer sitting at a desk with a fast internet connection. That did not describe us.

Joseph Webber, the primary author, is a blind developer based in Adelaide, Australia. When every CLI spits out emoji-heavy, colour-coded output that screen readers mangle, and when every framework assumes you will visually inspect a dashboard, you end up either patching things yourself or going without. So we built from scratch with accessibility as a constraint, not a feature request.

The result is a framework that works just as well over SSH on a headless server, through a VoiceOver session on macOS, or offline with Ollama when the internet is out. It is maintained by ChatLemur Pty Ltd as a goodwill contribution to the community.

ChatLemur integration

agentic-brain is the open-source foundation. ChatLemur.com is the commercial product built on top of it.

The framework is the part that belongs to the community: routing, memory, GraphRAG, accessibility, the ab CLI, ADL, and the agent building system. ChatLemur adds proprietary intelligence on top — market data pipelines, the Lenny AI analyst, Discord integration, and the web platform. None of that is in this repository.

If you build something with agentic-brain, you are building on the same foundation ChatLemur runs on in production.

---

Triple moat

• Offline-first — works without internet using Ollama, local memory fallbacks, SQLite-backed workflow compatibility, and airlock-friendly CLI flows
• Accessibility-first — built for WCAG 2.1 AA, VoiceOver, screen-reader formatting, keyboard-first flows, and accessible web surfaces
• Free-first — Groq/Ollama cascade plus OpenRouter free and cheap paths before premium providers

Why developers choose agentic-brain

• Build production agents: Agent, AgentRunner, RAGAgent, MixtureOfAgents, UserProxyAgent
• Ship with guardrails: ethics and safety modules, quarantines, auth, audit hooks, and compliance helpers
• Route intelligently: LLMRouter, SmartRouter, worker orchestration, and fallback chains
• Stay local when needed: offline-first execution, local models, and memory fallbacks
• Go beyond vector search: GraphRAG, loader integrations, chunking, evaluation, and retrieval pipelines
• Support real products: FastAPI, WebSocket/SSE streaming, dashboard routes, agent routes, and WooCommerce hooks
• Target real hardware: MLX and Apple Silicon support, plus CUDA and ROCm acceleration paths
• Design for real users: personas, industry modes, VoiceOver coordination, and accessibility-focused surfaces
• Stream real events: Kafka and Redpanda loaders for operational pipelines

---

Quick start

1. Install

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install agentic-brain rich neo4j

Common install profiles:

Need	Install
Python API only	pip install agentic-brain
CLI runtime	pip install agentic-brain rich neo4j
FastAPI server	pip install "agentic-brain[api]"
Cloud LLM SDKs	pip install "agentic-brain[llm]"
GraphRAG helpers	pip install "agentic-brain[graphrag]"
JWT auth helpers	pip install "agentic-brain[auth]"
LDAP, SAML, MFA	pip install "agentic-brain[enterprise]"
Premium/local voice extras	pip install "agentic-brain[voice-kokoro]"
Everything	pip install "agentic-brain[all]"

Requirements:

• Python 3.11+
• Optional services depending on what you use: Ollama, Neo4j, Redis

2. Verify the install

ab version
ab --screen-reader explain "what does git rebase do"
ab airlock true

ab --screen-reader enables screen-reader-safe formatting: no emoji, clean section markers, optional voice announcements. Pass it to any command.

Contributors: one-command setup

python3 -m venv .venv
source .venv/bin/activate
make setup-dev

This installs development dependencies, pre-commit hooks, and code quality tools. See CONTRIBUTING.md for the full guide.

3. Create your first agent

# Scaffold from a production-ready template
ab agent create --template chatbot support-bot

# See what you have
ab agent list

# Smoke test locally
ab agent run support-bot --disable-llm

# Run scenarios
ab agent test support-bot

# Expose HTTP endpoints
ab agent serve support-bot

4. First local-first agent in Python

from agentic_brain import Agent

agent = Agent(name="assistant", audio_enabled=False)
response = agent.chat("Summarise why offline AI matters.")
print(response)

By default, Agent uses the router stack and falls back to in-memory storage if Neo4j is unavailable.

5. First tool-enabled agent loop

import asyncio

from agentic_brain.agents import AgentRunner, function_tool


@function_tool(description="Return a friendly deployment status")
def deploy_status(service: str) -> str:
    return f"{service} is healthy and ready to deploy."


async def main() -> None:
    runner = AgentRunner(name="ops-bot", tools=[deploy_status])
    result = await runner.run("Check the deployment status for the api service.")
    print(result.output)


asyncio.run(main())

---

ADL — Agentic Definition Language

Define your entire AI brain in one declarative file using the Agentic Definition Language (ADL), inspired by JHipster JDL.

Quick ADL commands

# Initialize a new brain.adl with templates
ab adl init

# Validate ADL syntax
ab adl validate brain.adl

# Generate config files, .env, and docker-compose from ADL
ab adl generate brain.adl

# Import JHipster JDL and convert to ADL
ab adl import jdl --input app.jdl --output brain.adl

Example brain.adl

application MyAssistant {
  name "My AI Assistant"
  version "1.0.0"
  license MIT
}

// Primary LLM with fallback
llm Primary {
  provider OpenAI
  model gpt-4o
  temperature 0.7
  maxTokens 4096
  fallback Local
}

// Local fallback LLM
llm Local {
  provider Ollama
  model "llama3.2:3b"
}

// RAG knowledge base
rag KnowledgeBase {
  vectorStore Neo4j
  embeddingModel "sentence-transformers/all-MiniLM-L6-v2"
  chunkSize 512
  loaders [PDF, Markdown, Code]
}

// Voice output
voice Assistant {
  provider macOS
  defaultVoice "Karen"
  rate 155
}

// REST API configuration
api REST {
  port 8000
  cors ["*"]
}

// Security settings
security {
  authentication JWT
  sso [Google, Microsoft]
  rateLimit strict
}

Why ADL?

• One file, everything: LLMs, RAG, voice, API, security, and more
• IDE-friendly: Syntax highlighting and validation
• Generator-backed: Auto-generates config, .env, and docker-compose.yml
• Team-ready: Version control friendly, easy code review
• JHipster compatible: Import existing .jdl files

See examples/brain.adl and examples/minimal.adl for templates, or run ab adl init to get started.

---

Agent building system

The ab CLI in V4 turns agent development into a tight build-run-test-serve loop:

ab agent create --template chatbot support-bot
ab agent run support-bot
ab agent list
ab agent test support-bot
ab agent serve support-bot

Command	What it does
ab agent create	Scaffold a new agent from a built-in or production-ready template
ab agent run	Execute an agent locally for fast iteration
ab agent list	Discover available agents in your workspace
ab agent test	Run scenario tests before deployment
ab agent serve	Wrap an agent in FastAPI and expose /health and /run

Production-ready templates

Start from templates designed for real products, not toy demos.

The CLI ships with scaffold templates such as call_center, chatbot, customer_support, sales_assistant, task_manager, and woocommerce.

Template	Best for	Why it matters
chatbot	Customer service	FAQ lookup, handoff patterns, accessible support flows
woocommerce	E-commerce	Store support, order workflows, webhook-friendly integrations
call_center	Voice/phone	Short voice-safe replies, transcript-aware flows, escalation and compliance logging

Template modules live in src/agentic_brain/templates/agents and are designed to be extended, tested, and shipped.

---

Feature map

LLM routing

• LLMRouter adds streaming, semantic caching, fallback chains, safety guards, and provider-aware routing with support for OpenRouter and LiteLLM integrations
• SmartRouter ships with multi-worker routing for intelligent provider selection and load distribution
• ProviderFallbackChain and CascadingFallbackChain implement free-first, cheap-first, and premium escalation strategies

Agent building

• High-level Agent for memory + router + audio in one object
• AgentRunner for multi-turn agent loops with tool execution and optional handoff support
• RAGAgent for retrieval-grounded agents
• Planner, ReActAgent, MixtureOfAgents, and UserProxyAgent for more structured orchestration
• ToolRegistry plus built-ins: search, calculator, code execution, web lookup

Memory, GraphRAG, and retrieval

• Neo4jMemory with automatic fallback to InMemoryStore
• Session management, summarisation, session stitching, and unified memory hooks
• RAGPipeline, GraphRAG, EnhancedGraphRAG, GlobalSearch, reranking, chunking, and evaluation helpers
• A broad loader catalog across documents, event streams, databases, enterprise systems, and structured data ingestion
• EasyModeRAG for progressive onboarding

Durability and workflow support

• agentic_brain.temporal is a Temporal-compatible layer for workflows, activities, clients, workers, and tests
• agentic_brain.context adds checkpoints, context-window estimation, offline recovery, and continue-as-new style handoffs
• The compatibility layer is designed to work without a separate Temporal server

API and delivery

• ab, ab-copilot, agentic-brain, and agentic CLI entry points
• FastAPI app with health, chat, streaming, sessions, setup, auth helpers, REST RAG endpoints, agent routes, dashboard routes, and WooCommerce webhooks
• /ws/chat plus agent SSE and WebSocket endpoints for real-time integrations

Security, auth, personas, and compliance

• JWT, API keys, sessions, OAuth2/OIDC, HTTP Basic, LDAP/Active Directory, SAML, Firebase, and refresh-token rotation helpers
• Role and authority decorators for FastAPI and service code
• Personas and industry modes for domain-specific behaviour
• Ethics guardrails, quarantine flows, and safety controls for production deployments
• Australian compliance modules for AML/CTF, ASIC, APRA, CDR, NPP, and Privacy Act requirements

---

CLI command reference

All commands are available as ab <command>. Run ab --help or ab <command> --help for full option details.

Core commands

Command	Description	Example
ab version	Print version (optionally compare with gh copilot)	ab version --verbose
ab status	System status and provider API key checklist	ab status
ab doctor	Full dependency and config health check	ab doctor
ab config	View or set configuration values	ab config default_model groq/llama-3.3-70b-versatile
ab auth	Store an API key for a provider	ab auth groq --key gsk_xxx
ab airlock	Enable/disable offline-only mode	ab airlock true
ab models	List available LLM models	ab models --local

AI commands

Command	Description	Example
ab explain	Explain code, commands, or concepts	ab explain "git rebase -i HEAD~3"
ab suggest	Get shell command or code suggestions	ab suggest --shell "compress all PDFs"
ab complete	Complete a code snippet	ab complete "def fibonacci(n):"
ab chat	Interactive multi-turn chat with slash commands	ab chat --session my-project
ab voice	Hands-free voice input and output	ab voice --continuous
ab swarm	Decompose a complex task across multiple agents	ab swarm "audit this codebase" --agents 5
ab consensus	Query multiple models and synthesise answers	ab consensus "REST vs GraphQL" --bots groq,ollama

Agent commands (ab agent)

Command	Description	Example
ab agent create	Scaffold a new agent from a template	ab agent create --template chatbot support-bot
ab agent list	List agents in your workspace	ab agent list
ab agent run	Run an agent locally	ab agent run support-bot
ab agent test	Run scenario tests for an agent	ab agent test support-bot
ab agent serve	Wrap an agent in a FastAPI server	ab agent serve support-bot

RAG commands

Command	Description	Example
ab index	Index documents for RAG	ab index ./docs --recursive
ab query	Query indexed documents	ab query "How does auth work?"
ab eval	Evaluate RAG results from a JSON file	ab eval ./results.json
ab health	Check RAG system health	ab health
ab wizard	Interactive RAG setup wizard	ab wizard

ADL commands (ab adl)

Command	Description	Example
ab adl init	Create a new brain.adl template	ab adl init
ab adl validate	Validate ADL syntax	ab adl validate
ab adl generate	Generate config/docker-compose from ADL	ab adl generate
ab adl serve	Start API server from ADL config	ab adl serve --reload
ab adl show	Display ADL config in readable form	ab adl show
ab adl import	Convert JHipster JDL to ADL	ab adl import jdl --input app.jdl
ab adl export	Export ADL to JSON/YAML/TOML	ab adl export --format yaml

Secrets commands (ab secrets)

Command	Description	Example
ab secrets set	Store a secret in macOS Keychain	ab secrets set OPENAI_API_KEY
ab secrets get	Retrieve a secret (masked by default)	ab secrets get OPENAI_API_KEY
ab secrets list	List stored secret names	ab secrets list
ab secrets delete	Delete a secret	ab secrets delete OPENAI_API_KEY
ab secrets import-env	Import secrets from a .env file	ab secrets import-env --file .env
ab secrets status	Show Keychain manager status	ab secrets status

Session commands (ab session)

Command	Description	Example
ab session status	Show current session context	ab session status
ab session list	List saved sessions	ab session list --limit 5
ab session save	Save current session manually	ab session save
ab session restore	Restore a previous session	ab session restore --id abc123
ab session new	Start a named session	ab session new --name my-project
ab session clear	Delete a session or all sessions	ab session clear --all

Misc

Command	Description	Example
ab compare	Feature comparison with GitHub Copilot CLI	ab compare
ab serve	Start the web API server	ab serve --port 3001
ab accessibility	Manage screen-reader / VoiceOver settings	ab accessibility enable

---

Roadmap

These are the near-term items we are actively working on or planning:

Item	Status	Notes
Hermes runtime	Design phase	Standalone runtime for durable agent execution; designed as a pluggable execution backend
Voice input	Experimental	pip install "agentic-brain[voice-input]" — needs a working microphone; improving stability
ChatLemur plugin	Pending	Public plugin interface so ChatLemur and third-party products can extend the framework cleanly
Full /chat HTTP endpoint	In progress	Currently returns an echo placeholder; porting the REPL logic to the FastAPI route
REST RAG endpoints	In progress	api/rest.py stubs need wiring to RAGPipeline
SmartRouter provider coverage	Partial	11 provider IDs registered; expanding worker heat tracking
FreqTrade commands	Not wired	Set FREQTRADE_API_URL to a running FreqTrade REST API to activate

If you want to help with any of these, open an issue and say so.

---

Architecture at a glance

┌───────────────────────┐
│ CLI / Python / FastAPI│
└──────────┬────────────┘
           │
┌──────────▼────────────┐
│ Agents layer          │
│ Agent, AgentRunner,   │
│ RAGAgent              │
└──────────┬────────────┘
           │
┌──────────▼────────────┐
│ Router layer          │
│ LLMRouter,            │
│ SmartRouter, workers  │
└──────────┬────────────┘
           │
┌──────────▼────────────┐
│ Memory + RAG layer    │
│ Neo4jMemory,          │
│ GraphRAG, loaders     │
└──────────┬────────────┘
           │
┌──────────▼────────────┐
│ Durability + infra    │
│ Checkpoints, Temporal │
│ Redis, SQLite, Neo4j  │
└───────────────────────┘

---

Offline, accessibility, and cost control

Offline-first

• ab airlock is the CLI-facing offline switch
• Ollama is the default local model path across the router stack
• Agent falls back to in-memory memory if Neo4j is unavailable
• Temporal compatibility and context recovery use local storage patterns

Accessibility-first

• agentic_brain.cli.accessibility detects VoiceOver/NVDA/JAWS/Orca, removes inaccessible formatting, and announces progress
• agentic_brain.voice.voiceover coordinates speech so the framework does not talk over VoiceOver
• The --screen-reader flag is available on every command
• The repo includes dedicated accessibility tests plus ARIA and focus expectations for web-facing components

Free-first

• LLMRouter fallback chains prefer Ollama and Groq before moving up the cost curve
• ProviderFallbackChain groups providers into free, cheap, and premium tiers
• SmartRouter tracks worker heat and supports free-friendly routing modes

---

Current scope and sharp edges

To keep this README accurate:

• The main /chat HTTP endpoint currently returns an echo placeholder response in api/routes.py
• The lightweight REST endpoints in api/rest.py are intentionally placeholder/demo implementations
• The core router exposes 11 provider IDs, but provider diagnostics and SmartRouter worker coverage are a smaller subset today
• Some advanced routers and integrations are optional or lazy-loaded so import cost stays manageable

---

Documentation

• Getting Started
• Agent Building
• Architecture
• API Reference
• Comparison Guide
• Accessibility Notes

---

Contributing

See CONTRIBUTING.md. Bug reports, feature requests, and pull requests are all welcome. Questions go in GitHub Issues.

Security

See SECURITY.md for the vulnerability disclosure policy. Please do not open public issues for security bugs — email joseph.webber@gmail.com instead.

License

MIT — Copyright 2026 Joseph Webber / ChatLemur Pty Ltd