Metadata-Version: 2.4
Name: botnesia-core
Version: 0.1.0
Summary: Open-source agent runtime primitives extracted from the BotNesia platform (SDK core, runtime, state, memory, policy, providers).
Author: BotNesia
License: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: httpx>=0.27
Requires-Dist: asyncpg>=0.29
Provides-Extra: redis
Requires-Dist: redis>=5.0; extra == "redis"
Provides-Extra: numpy
Requires-Dist: numpy>=1.26; extra == "numpy"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Dynamic: license-file

# botnesia-core

![botnesia-core](assets/banner.svg)

**The open agent-runtime foundation behind BotNesia** — build durable,
multi-agent, MCP-native AI systems in Python.

[![CI](https://github.com/asroryandesfar-art/botnesia-core/actions/workflows/ci.yml/badge.svg)](https://github.com/asroryandesfar-art/botnesia-core/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/asroryandesfar-art/botnesia-core?sort=semver)](https://github.com/asroryandesfar-art/botnesia-core/releases)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
![Python](https://img.shields.io/badge/python-3.10%2B-blue)

**🌐 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

[![BotNesia product](assets/product-landing.png)](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

> **Note:** not on PyPI yet (planned for 0.1.x — see [Roadmap](#roadmap)). Install
> from the release wheel or from source today.

```bash
# from the v0.1.0 release wheel:
pip install https://github.com/asroryandesfar-art/botnesia-core/releases/download/v0.1.0/botnesia_core-0.1.0-py3-none-any.whl

# 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

![Architecture](assets/architecture.svg)

`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).
