Skip to content

AIXP-Foundation/SoulBot

BranchesTags

Repository files navigation

SoulBot

AI Agent Framework with AISOP/AISIP Dual Protocol and AIAP Package System

Python 3.11+ License Tests

中文文档 | English

Axiom 0: Human Sovereignty and Wellbeing

SoulBot, AISOP, AISIP, and AIAP each independently adhere to the same foundational axiom:

Align: Human Sovereignty and Wellbeing

No process, rule, or optimization may override Axiom 0.

What is SoulBot?

SoulBot is a Python-based AI Agent framework that connects to LLMs through CLI subprocesses (ACP protocol) — no API keys required. It introduces a unique architecture where agent behavior is defined by AISOP blueprints (.aisop.json, Mermaid flowcharts) or AISIP blueprints (.aisip.json, JSON 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
  • Multi-Model Switching — Claude, Gemini, OpenCode (Kimi, etc.) — switch with one line in .env
  • AISOP/AISIP Dual Protocol — Agent behavior defined by .aisop.json (Mermaid flowcharts) or .aisip.json (JSON flowcharts) blueprints with auto protocol detection
  • AIAP Package System — Hot-pluggable capability packages (*_aiap) with dual-format entry points (AISOP/AISIP), extending agent functionality
  • 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

Install

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

Run

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

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

# Terminal interactive mode
soulbot run examples/simple/SoulBot_Agent

# Telegram Bot
soulbot telegram examples/simple/SoulBot_Agent

Create Your Own Agent

soulbot create my_agent

This generates:

my_agent/
├── agent.py          # Agent definition (dual protocol runtime)
├── main.aisop.json   # AISOP blueprint (Mermaid flowchart)
├── .env              # Configuration (model selection)
├── aisop_aiap/       # AISOP-format AIAP package directory
└── aisip_aiap/       # AISIP-format AIAP package directory

Edit .env to select your LLM backend, then run:

soulbot run my_agent

Architecture

AISOP/AISIP + AIAP

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
AISIP V1.0.0 AI Standard Interaction Procedure — AISOP's sister protocol that defines control flow through JSON flowcharts, sharing §0/§2/§5/§6 specs with AISOP, differing only in §4 flow format
AIAP Packages AI Application Packages — hot-pluggable capability modules (*_aiap/) with dual-format entry points (main.aisop.json or main.aisip.json)

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), AISIP uses JSON syntax (ideal for programmatic processing). This separation makes agent behavior reproducible and version-controllable.

User Message
    ↓
agent.py → _dynamic_instruction()
    ├── _SYSTEM_PROMPT (WHO — runtime identity)
    ├── main.aisop.json or main.aisip.json (WHAT — routing rules, auto-detected)
    └── [Available AIAP packages] (capabilities, scanned from aisop_aiap/ and aisip_aiap/)
    ↓
LLM follows flowchart:
    NLU[Match Intent] → Run[Load & Execute *_aiap/main.aisop.json or main.aisip.json]
    ↓
AIAP package's flow executes domain-specific logic
    ↓
Response returned to user

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/AISIP Engine →  .aisop.json (Mermaid) / .aisip.json (JSON) → 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           →  CLI subprocess JSON-RPC
     ├── ClaudeACPClient    (claude-acp/*)
     ├── GeminiACPClient    (gemini-acp/*)
     └── OpenCodeACPClient  (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)

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

Recommended Models for AISOP/AISIP

Models proven to run AISOP/AISIP flows flawlessly:

Model Notes
gemini-3-flash-preview Fast and precise, recommended for daily use
gemini-3.1-pro-preview Stronger reasoning, ideal for complex flows

Best runtime combination: SoulBot + Gemini CLI + gemini-3-flash-preview

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:8000

Features: Markdown rendering, SSE streaming, agent switching, session management, dark theme.

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

Telegram Bot

  1. Get a bot token from @BotFather
  2. Add TELEGRAM_BOT_TOKEN=your_token to .env
  3. Run: soulbot telegram examples/simple/SoulBot_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/AISIP payload: scheduled tasks carry complete AISOP/AISIP 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/               # Model layer (ACPLlm, ModelRegistry)
│   ├── acp/                  # ACP protocol (Claude/Gemini/OpenCode clients)
│   ├── 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
│   └── SoulBot_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-Foundation/SoulBot.git

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

See INSTALL.md for detailed installation and publishing guide.

Documentation

Document Description
GUIDE.md Comprehensive usage guide
INSTALL.md Installation, packaging, and publishing
docs/guide/01-function-call-guide.md Function Call developer guide
docs/guide/02-soulbot-cmd-guide.md SoulBot CMD developer guide

License

This project is licensed under the Apache License 2.0 — see the LICENSE file for details.

Copyright 2026 AIXP Foundation AIXP.dev | SoulBot.dev

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

About

SoulBot.dev

SoulBot.dev

Resources

Readme

License

Apache-2.0 license

Contributing

Contributing
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

No contributors

Languages