Skip to content

AIXP-Labs/SoulBot

BranchesTags

Repository files navigation

SoulBot

AI Agent Framework with AISOP Protocol and AIAP Package System

Python 3.11+ License Tests

中文文档 | English

What is SoulBot?

SoulBot is a Python-based AI Agent framework that connects to LLMs through CLI subprocesses using the ACP protocol (via soulacp) — no API keys required. It introduces a unique architecture where agent behavior is defined by AISOP blueprints (.aisop.json, Mermaid flowcharts) and extended through AIAP packages (*_aiap), making AI agent behavior deterministic, reproducible, and version-controlled.

Key Features

  • No API Key Required — Connects to LLMs via Claude Code / Gemini CLI / OpenCode CLI subprocesses (powered by soulacp)
  • Multi-Model Switching — Claude, Gemini, OpenCode (Kimi, etc.) — switch with one line in .env
  • AISOP Protocol — Agent behavior defined by .aisop.json (Mermaid flowcharts) blueprints
  • AIAP Package System — Hot-pluggable capability packages (*_aiap) with AISOP entry points, extending agent functionality
  • AISP Skills — Single-file AI Skill packages (*_aisp/) carrying machine-enforced contract red lines (HARD_FAIL on violation) and human-approval gates — run natively on the same engine
  • Agent Composition — Single agent, multi-agent routing, Sequential / Parallel / Loop workflows
  • Tool System — Python functions auto-wrapped as LLM-callable tools
  • Multi-Channel — Terminal CLI, Web Dev UI, Telegram Bot
  • Streaming Output — SSE typewriter effect (Web + Telegram)

Quick Start

Prerequisites

  • Python 3.11+
  • At least one LLM CLI tool installed:
Tool Install Login
Claude Code npm install -g @anthropic-ai/claude-code claude login
Gemini CLI npm install -g @google/gemini-cli gemini login
OpenCode npm install -g opencode Free models, no login needed

💡 Recommended combination: SoulBot + Claude Code CLI + a flagship Claude model. This project is primarily developed and tested with this stack (validated models: Opus 4.8, Fable 5). New users: start here.

Install

git clone https://github.com/AIXP-Labs/SoulBot.git
cd SoulBot
pip install -e .

First-time setup

Before running, rename the example config to .env:

mv examples/simple/Soul_Agent/.env.example examples/simple/Soul_Agent/.env

Open the new .env and pick your LLM backend (Claude / Gemini / OpenCode).

Run

# Simple mode (one-click Web Dev UI)
python start.py

# Web Dev UI (open http://127.0.0.1:2026)
soulbot web --agents-dir examples/simple

# Terminal interactive mode
soulbot run examples/simple/Soul_Agent

# Telegram Bot
soulbot telegram examples/simple/Soul_Agent

Create Your Own Agent

soulbot create my_agent

This generates:

my_agent/
├── agent.py                        # Agent definition (dual-protocol registry consumer)
├── aiap/                           # AIAP packages (*_aiap/) + aiap_list.py registry generator
├── aisp/                           # AISP skills (*_aisp/) + aisp_list.py + _shared/
├── soulbot_execute_engine_aiap/    # AISOP execution engine (node/agent dispatch, red-line gates)
├── soulbot_intent_classifier_aiap/ # Intent classifier package
└── heartbeat.aisop.json            # Scheduled-task blueprint

Create a .env to select your LLM backend (looked up in 3 layers: agent dir → agents dir → SoulBot root), then run:

soulbot run my_agent

Architecture

AISOP + AIAP + AISP

SoulBot introduces three core concepts:

Concept Description
AISOP V1.0.0 AI Standard Operating Procedure — a JSON-based blueprint protocol that defines agent behavior through Mermaid flowcharts
AIAP Packages AI Application Packages — hot-pluggable capability modules (*_aiap/) with AISOP entry point (main.aisop.json)
AISP Skills AI Skill Protocol — single-file skills (*_aisp/aisp.aisop.json) carrying an aisp_contract with non-negotiable red lines and human gates

The key insight: flowcharts serve as deterministic execution paths (like circuit diagrams), while prompts provide context and constraints (like component specifications). AISOP uses Mermaid syntax (ideal for visualization). This separation makes agent behavior reproducible and version-controllable.

User Message
    ↓
agent.py → _dynamic_instruction()
    ├── _SYSTEM_PROMPT (WHO — runtime identity)
    ├── main.aisop.json (WHAT — routing rules)
    └── [Available packages] — AIAP programs + AISP skills
        (generated registries: aiap_list.json / aisp_list.json from aiap/ & aisp/)
    ↓
LLM follows flowchart:
    NLU[Match Intent] → Run[Load & Execute *_aiap/main.aisop.json
                            or *_aisp/aisp.aisop.json]
    ↓
Package's flow executes domain-specific logic
    ↓
Response returned to user

The engine is a protocol-agnostic AISOP executor: contract red lines bound via enforced_by are hard gates (violation → HARD_FAIL halt, surfaced to the human), and ambiguous multi-candidate routing stops and asks the user (Axiom 0) instead of silently picking.

Governance Domains

AIAP operates under a tripartite federated trust model:

  • aisop.dev (Seed Layer): Defines the unchangeable format structure.
  • aiap.dev (Authority Layer): Defines the evolving governance rules.
  • soulbot.dev (Executor Layer): The reference runtime engine that physically acts upon AISOP code.

System Architecture

Entry Points
├── CLI Terminal     →  soulbot run <agent_dir>
├── Web Dev UI       →  soulbot web --agents-dir <dir>
├── API Server       →  soulbot api-server --agents-dir <dir>
└── Telegram Bot     →  soulbot telegram <agent_dir>
         ↓
Runner
├── Agent Tree       →  LlmAgent / SequentialAgent / ParallelAgent / LoopAgent
├── AISOP Engine       →  .aisop.json (Mermaid) → AIAP routing
├── Tool Calls       →  FunctionTool / AgentTool / TransferToAgentTool
├── CMD System       →  Embedded commands (scheduling, etc.)
├── Sessions         →  InMemory / SQLite + State delta
├── EventBus         →  pub/sub + filtering + priority
└── Streaming        →  partial Events → SSE / Telegram typewriter
         ↓
Model Layer
├── ModelRegistry    →  regex matching → adapter selection
└── ACPLlm           →  soulacp library
     (soulacp wraps CLI subprocesses as JSON-RPC clients;
      supports claude-acp/* | gemini-acp/* | opencode-acp/*)

Agent Development

Minimal Agent

from soulbot.agents import LlmAgent

root_agent = LlmAgent(
    name="my_agent",
    model="claude-acp/sonnet",
    instruction="You are a helpful assistant.",
)

Agent with Tools

from soulbot.agents import LlmAgent

def get_weather(city: str) -> dict:
    """Get weather for a city."""
    return {"city": city, "temp": 25, "condition": "sunny"}

root_agent = LlmAgent(
    name="weather_agent",
    model="claude-acp/sonnet",
    instruction="You can check weather for any city.",
    tools=[get_weather],
)

Functions are auto-wrapped as LLM tools: function name becomes tool name, docstring becomes description, type hints become JSON Schema.

Multi-Agent Routing

from soulbot.agents import LlmAgent

billing = LlmAgent(name="billing", model="claude-acp/sonnet",
                    description="Handles billing questions",
                    instruction="You are a billing specialist.")

tech = LlmAgent(name="tech", model="claude-acp/sonnet",
                description="Handles technical issues",
                instruction="You are tech support.")

root_agent = LlmAgent(
    name="router",
    model="claude-acp/sonnet",
    instruction="Route user to the appropriate specialist.",
    sub_agents=[billing, tech],
)

Workflow Agents

from soulbot.agents import LlmAgent, SequentialAgent, ParallelAgent, LoopAgent

# Sequential: run agents in order
root_agent = SequentialAgent(name="pipeline", sub_agents=[analyzer, responder])

# Parallel: run agents concurrently
root_agent = ParallelAgent(name="parallel", sub_agents=[search, summarize])

# Loop: repeat until escalation
root_agent = LoopAgent(name="refiner", sub_agents=[draft, review], max_iterations=3)

AISP Skills & aisp_store

examples/simple/aisp_store/ ships six ready-made AISP skills (inventory — delivery ≠ install):

Skill What it shows
aisp_creator_evolution_aisp v1.1.0 Creates / evolves AISP skills from a chat request (also mounted in Soul_Agent/aisp/, routable out of the box)
webapp_testing_aisp v1.3.0 Research-driven evolution chain (v1.0 → v1.3), Playwright web testing
mcp_builder_aisp v2.0.0 MCP server builder — a live SemVer MAJOR (predicate-flip) case
yijing_aisp I-Ching divination — the first AISP skill ever run natively by the engine
random_draw_aisp Unbiased random pick (CSPRNG, offline) — created end-to-end by the creator skill
redline_breach_test_aisp Hard-gate probe: deliberately violates its own red line — a conforming runtime MUST halt at breach.step2. Clone and verify it yourself
  • Install a skill: copy its folder from aisp_store/ into Soul_Agent/aisp/ — the registry (aisp_list.json) regenerates automatically on the next turn (a missing cache self-heals).
  • Create new skills by chatting (e.g. 创建一个 AISP 技能:...) — if several creators cover the intent and none is named, the router stops and asks you (Axiom 0); products land in aisp_store/ by default.
  • Or use the Web UI: the #/store page browses/downloads/installs from GitHub (version-aware — Up to date / Update / Local-newer warning before overwrite); the agent settings page installs/uninstalls from the local store with one click.

Configuration

.env Reference

# LLM Backend (set one to true)
CLAUDE_CLI=true
GEMINI_CLI=false
OPENCODE_CLI=false

# Model names
CLAUDE_MODEL=claude-acp/sonnet
GEMINI_MODEL=gemini-acp/gemini-3-flash-preview
OPENCODE_MODEL=opencode-acp/opencode/gemini-3-flash-preview

# Behavior
WORKSPACE_DIR=aiap            # AIAP package directory
ENABLE_FALLBACK=false         # Auto-switch model on failure
AUTO_APPROVE_PERMISSIONS=true # Auto-approve CLI permissions
SHOW_THOUGHTS=false           # Show AI thinking process

# Telegram (optional)
TELEGRAM_BOT_TOKEN=

Model Name Formats

Format Description
claude-acp/sonnet Claude Sonnet
claude-acp/opus Claude Opus
gemini-acp/gemini-3-flash-preview Gemini Flash
opencode-acp/opencode/gemini-3-flash-preview OpenCode Gemini Flash
opencode-acp/anthropic/claude-sonnet-4-5 OpenCode → Claude

CLI Commands

Command Description
soulbot run <agent_path> Terminal interactive mode
soulbot web --agents-dir <dir> Web Dev UI + API Server
soulbot api-server --agents-dir <dir> API Server only (no UI)
soulbot telegram <agent_path> Telegram Bot
soulbot create <name> Scaffold a new agent project

python -m soulbot can be used instead of soulbot without installation.

Web Dev UI

soulbot web --agents-dir examples/simple
# Open http://127.0.0.1:2026

Features: Markdown rendering, SSE streaming, agent switching, session management, dark theme, Store page (browse / download / install AIAP programs and AISP skills from GitHub, version-aware: Up to date / Update x→y / Local-newer warning with safe overwrite), per-agent AISP skill management (settings page: one-click install/uninstall from the local store; registry self-heals on the agent's next turn).

API Endpoints

Route Method Description
/health GET Health check
/list-apps GET List all agents
/apps/{name} GET Agent details
/run POST Synchronous execution
/run_sse POST SSE streaming execution
/aiap-store/programs GET List AIAP programs from a GitHub store (with local_version)
/aisp-store/skills GET List AISP skills from a GitHub store (with local_version)
/aisp-store/download / install POST Download to local store / install to an agent (overwrite = version-aware update)
/agents/{name}/aisps GET Mounted AISP skills of an agent
/aisp-library GET Local aisp_store/ inventory

Telegram Bot

  1. Get a bot token from @BotFather
  2. Add TELEGRAM_BOT_TOKEN=your_token to .env
  3. Run: soulbot telegram examples/simple/Soul_Agent

Or run Web + Telegram together: soulbot web --agents-dir examples/simple

Bot commands: /start, /clear, /history

Features: streaming output, Markdown rendering, auto message splitting, multi-agent routing via InlineKeyboard.

Scheduling

AI-driven scheduling system — the AI embeds <!--SOULBOT_CMD:--> directives in responses to create scheduled tasks.

  • Three trigger types: Once / Interval / Cron
  • Cross-agent scheduling: Agent A creates tasks for Agent B
  • AISOP payload: scheduled tasks carry complete AISOP V1.0.0 blueprints
  • Persistent recovery: auto-restore active tasks after restart

Project Structure

SoulBot/
├── src/soulbot/              # Framework source
│   ├── agents/               # Agent system (LlmAgent, Sequential, Parallel, Loop)
│   ├── tools/                # Tool system (FunctionTool, AgentTool)
│   ├── models/               # ACPLlm + ModelRegistry (delegates to soulacp library)
│   ├── runners/              # Runner (drives agent execution)
│   ├── sessions/             # Session (InMemory / SQLite)
│   ├── server/               # Web/API Server (FastAPI + SSE)
│   ├── connect/              # Channel connectors (Telegram)
│   ├── commands/             # CMD system (embedded commands)
│   ├── scheduler/            # Task scheduling
│   ├── templates/            # Agent scaffolding templates
│   └── cli.py                # CLI entry point
├── examples/simple/          # Example agents
│   └── Soul_Agent/        # Main agent with AIAP packages
├── tests/                    # 1266 unit tests
├── docs/                     # Documentation
└── pyproject.toml            # Project configuration

Testing

# All unit tests
python -m pytest tests/ -q

# Specific module
python -m pytest tests/test_agents/ -q

# E2E tests (requires real CLI login)
python -m pytest tests/e2e/ -m live -q

Installation Options

# Development (editable)
pip install -e ".[dev]"

# With Telegram support
pip install -e ".[telegram]"

# With SQLite sessions
pip install -e ".[sqlite]"

# Everything
pip install -e ".[dev,telegram,sqlite]"

# From GitHub
pip install git+https://github.com/AIXP-Labs/SoulBot.git

# One-line run (uv)
uvx --from git+https://github.com/AIXP-Labs/SoulBot.git soulbot web --agents-dir .

See INSTALL.md for detailed installation and publishing guide.

Documentation

Document Description
GUIDE.md Comprehensive usage guide (Chinese)
INSTALL.md Installation, packaging, and publishing (Chinese)
SECURITY.md Security policy and vulnerability reporting (EN + CN)
CONTRIBUTING.md Contribution process
GOVERNANCE.md Project governance and decision-making
CODE_OF_CONDUCT.md Community code of conduct (Axiom 0 alignment)
CHANGELOG.md Release history including security fixes
docs/guide/01-function-call-guide.md Function Call developer guide
docs/guide/02-soulbot-cmd-guide.md SoulBot CMD developer guide

AIXP Labs aixp.dev

AIXP Labs develops and maintains the following core projects:

Project Description Website
HSAW Human Sovereignty and Wellbeing — Axiom 0 white paper (foundation) hsaw.dev
AIZP AI Zenith-Zero Protocol — runtime behavioral alignment aizp.dev
AILP AI List Protocol — agent discovery and capability advertising ailp.dev
AIVP AI Value Protocol — international commerce, crypto asset settlement aivp.dev
AIRP AI RMB Protocol — Mainland China commerce, RMB licensed settlement airp.dev
AIBP AI Bot Protocol — social communication and trust aibp.dev
AIAP AI Application Protocol — governance and compliance aiap.dev
AISP AI Skill Protocol — single-file skills with machine-enforced contract red lines aisp.dev
AISOP AI Standard Operating Protocol — flow program definition aisop.dev
SoulSkill AISP skill reference library & multi-CLI plugin distribution soulskill.dev
SoulAgent Drop-in AI agent invoked directly by any CLI / SDK / IDE soulagent.dev
SoulBot AI agent runtime & orchestration framework (scheduling, agent-spawn, inter-agent comms) (this project) soulbot.dev
SoulACP Adapter library — bridging CLI tools and LLM providers soulacp.dev

⚠️ Disclaimer

This software is experimental and provided for research and educational purposes only. Not intended for production use. Use at your own risk. The authors assume no liability for any damages arising from the use of this software. See LICENSE for full terms (Apache 2.0).

License

Apache License 2.0 - Copyright 2026 AIXP Labs AIXP.dev | SoulBot.dev

Align Axiom 0: Human Sovereignty and Wellbeing. Version: SoulBot V1.0.0. www.soulbot.dev

About

SoulBot — Python AI agent framework — agent behavior defined by AISOP blueprints (Mermaid/JSON) and extended via hot-pluggable AIAP packages, running on LLM CLIs (Claude/Gemini/OpenCode) with no API key.

SoulBot.dev

Topics

multi-model autonomous-agents telegrambot ai-agents no-api-key self-fractal no-code-ai remote-programming self-evolution personal-ai-assistant glass-box-ai aisop-protocol fractal-intelligence human-sovereignty-and-wellbeing creator-evolution-aiap cognitive-cycle-aiap aibp-bot-aiap hsaw aiap-protocol soulbot-execute-engine-aiap

Resources

Readme

License

Apache-2.0 license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity
Custom properties

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages