Content
# botnesia-core
**The open agent-runtime foundation behind BotNesia** — build durable,
multi-agent, MCP-native AI systems in Python.
[](https://github.com/asroryandesfar-art/botnesia-core/actions/workflows/ci.yml)
[](https://pypi.org/project/botnesia-core/)
[](https://github.com/asroryandesfar-art/botnesia-core/releases)
[](LICENSE)
**🌐 Live product:** [app.botnesia.uk](https://app.botnesia.uk) · **🎬 Demo:** [YouTube](https://youtu.be/aNIVa4Q-okI)
> `botnesia-core` is the Apache-2.0 engine extracted from the BotNesia platform.
> The commercial product (billing, marketplace, pricing, the AI-Workforce agents,
> multi-tenant management, SSO) stays in **BotNesia Cloud** — this repo is the
> reusable core you can build on.
## See it in production
[](https://app.botnesia.uk)
*The live BotNesia product ([app.botnesia.uk](https://app.botnesia.uk)) runs on
this engine — a Supervisor agent orchestrating CS, Sales, Marketing, Knowledge,
Finance and HR agents across WhatsApp, Instagram, Telegram and web chat.*
---
## The problem
Building real AI agents means re-solving the same hard parts every time:
durability (surviving restarts, retries), multi-agent routing, tool/plugin
integration, provider fallback and cost control, memory, and safe outbound
calls. Most open agent frameworks stop at "prompt in a loop" and leave the
production plumbing to you. `botnesia-core` ships that plumbing — the exact
engine that powers the BotNesia product — as a clean, business-free library.
## What is BotNesia?
BotNesia is an **AI Workforce platform**: it turns business conversations and
operations into work done by a team of cooperating AI agents. `botnesia-core`
open-sources the primitives that make that possible — the agent SDK, a durable
runtime, shared state & memory, a tool/MCP plugin layer, provider routing, RAG,
reasoning components, and a workflow engine.
> **Open core:** this library is the engine; the hosted **BotNesia Cloud** adds
> the commercial layer (billing, marketplace, the AI-Workforce agents, tenant
> management, SSO). Learn more at the BotNesia product site.
## Why it's different
- **Durable, not just a wrapper.** A Postgres-backed task runtime with
retry/DLQ — agents survive restarts, unlike prompt-in-a-loop demos.
- **MCP-native plugins.** Add tools by pointing at any MCP server via one env
var — no code changes.
- **Multi-agent by design.** A registry + orchestrator route work across agents
that each implement `run()`.
- **Provider-agnostic + cost-aware.** `SmartModelRouter` across DeepSeek/Gemini/
Groq/OpenRouter with task-class routing.
- **Batteries, not lock-in.** Shared state (in-proc or Redis), long-term memory,
policy engine, prompt registry, evaluation, RAG — all as independent modules.
- **Business-free & auditable.** Zero secrets, zero billing/pricing/tenant code.
## How it compares
| | prompt-loop scripts | typical agent frameworks | **botnesia-core** |
|---|:---:|:---:|:---:|
| Durable runtime (retry/DLQ, survives restarts) | ❌ | partial | ✅ |
| Multi-agent registry + orchestrator | ❌ | ✅ | ✅ |
| MCP-native plugins (add tools via env) | ❌ | varies | ✅ |
| Shared state (in-proc **or** Redis) | ❌ | ❌ | ✅ |
| Cost-aware provider routing | ❌ | ❌ | ✅ |
| SSRF-guarded tool fetch | ❌ | ❌ | ✅ |
| Extracted from a live production product | ❌ | rare | ✅ |
*Not a benchmark — a capability comparison of what ships in the box.*
## Install
```bash
pip install botnesia-core
# or from source:
git clone https://github.com/asroryandesfar-art/botnesia-core
cd botnesia-core && pip install -e ".[dev]"
```
Optional extras: `pip install "botnesia-core[redis]"` (distributed state).
## Quick Start (5 minutes)
<!-- Demo: replace with assets/demo.gif once recorded (see assets/README.md) -->
> 🎬 **Demo:** a 60–90s quickstart recording will live at `assets/demo.gif`.
```python
import asyncio
from base import BaseAgent
class GreeterAgent(BaseAgent):
name = "greeter"
skills = ["greet"]
async def run(self, context: dict) -> dict:
return {"output": f"Halo {context.get('name', 'dunia')}!"}
print(asyncio.run(GreeterAgent(api_key=None).run({"name": "Sari"})))
# {'output': 'Halo Sari!'}
```
Then explore the runnable examples:
```bash
python examples/01_list_builtin_tools.py # inspect the tool registry
python examples/02_mcp_plugin_config.py # add tools via MCP plugins
python examples/03_define_workflow.py # render a workflow step
```
## Example: an LLM-backed agent
```python
from base import BaseAgent
class SummarizerAgent(BaseAgent):
name = "summarizer"
async def run(self, context: dict) -> dict:
text = context["text"]
# BaseAgent provides multi-provider LLM plumbing (bring your own key):
summary = await self._call_llm(
system="Summarize the user's text in one sentence.",
user=text,
)
return {"summary": summary}
```
Route across many agents with the orchestrator (`multi_agent_orchestrator`),
and run them durably with `task_runtime`.
## Architecture
`botnesia-core` is a set of independent, importable modules. Your app (or
BotNesia Cloud) sits on top, registers its own agents/tools, and adds the
commercial layer. Full guide: [`docs/SDK_GUIDE.md`](docs/SDK_GUIDE.md).
## BotNesia × Casper — verifiable AI decisions
AI agents increasingly take actions that affect money and customers. BotNesia
turns *"trust the AI"* into *"verify the AI"* by anchoring a hash of each
important agent decision on-chain.
- **On-chain proof:** the BotNesia product anchors decision hashes to an
`ai_proof_registry` smart contract on **Casper Testnet** (`casper-test`) via a
`store_proof` entry point. Each anchored decision produces a Casper deploy that
anyone can independently verify on the block explorer.
- **Real, verifiable references:**
- Contract hash — `15009cd4a6489c904b699c0a1f292e7e5557e823e54c236539c9ce9973ee2323`
- [Contract package on testnet.cspr.live](https://testnet.cspr.live/contract-package/897c4bd670325c1f17ab1704633a470f55eeeb1ec2b357ef48e5d26ecb78a9f0)
- Sample confirmed deploy — [`fbb4b7e7…aa7b4e`](https://testnet.cspr.live/deploy/fbb4b7e766c0275980074d070d446d8e64703c2c2eb81be84637dfa531aa7b4e)
- **Why Casper:** predictable fees and upgradable contracts suit a
per-decision anchoring workload, and its explorer makes proofs easy to verify.
> Scope note: the Casper anchoring client and contract run inside the **BotNesia
> product** (not in this open runtime package). This section documents how the
> platform uses Casper; `botnesia-core` is the agent engine those decisions run on.
## Plugins
The plugin system is **MCP** + the tool registry. Point at any MCP server:
```python
import os, json, mcp_registry
os.environ["MCP_SERVERS"] = json.dumps({"github": {"url": "https://mcp.example.com/github"}})
registry = mcp_registry.configure_from_env() # tools appear as mcp__github__*
```
See [`docs/PLUGIN_GUIDE.md`](docs/PLUGIN_GUIDE.md).
## Workflows
Define multi-step automations (agent → action → notification) with
`workflow_engine`; templated fields (`{{agent_output}}`) and conditional nodes
are supported. See `examples/03_define_workflow.py`.
## Roadmap
- **0.1.x** — stabilize primitives, PyPI, CI, guides.
- **0.2.x** — entry-point plugin discovery, injectable provider/observability hooks.
- **→ 1.0** — API stability guarantee, reference deployments, plugin gallery.
Full roadmap: [`ROADMAP.md`](ROADMAP.md).
## FAQ
**Is this the whole BotNesia product?**
No. It's the open engine. Billing, marketplace, pricing, the AI-Workforce
agents, tenant management and SSO stay in the commercial BotNesia Cloud.
**Do I need a database or Redis?**
No for the SDK basics. `task_runtime` uses Postgres for durable jobs, and
`platform_state` can use Redis for distributed state — both optional. The
default state backend is in-process.
**Which LLM providers are supported?**
DeepSeek, Gemini, Groq and OpenRouter via `SmartModelRouter`. Bring your own
API key; routing is cost-aware by task class.
**How do I add a tool or integration?**
Point at an MCP server via the `MCP_SERVERS` env var (no code), or register a
custom tool. See [`docs/PLUGIN_GUIDE.md`](docs/PLUGIN_GUIDE.md).
**Is it production-ready?**
The primitives are extracted from a production system and covered by tests.
APIs may still adjust before 1.0 (see `CHANGELOG.md` / `SUPPORTED_VERSIONS.md`).
**What Python versions?**
3.10+ (CI runs 3.10–3.12).
## Contributing & Community
Issues and PRs welcome — see [`CONTRIBUTING.md`](CONTRIBUTING.md),
[`GOVERNANCE.md`](GOVERNANCE.md), and [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md).
Security: [`SECURITY.md`](SECURITY.md).
## License
[Apache-2.0](LICENSE) © BotNesia. See [`NOTICE`](NOTICE).
