How aixp-labs/soulbot works
SoulBot is an AI-agent framework whose main workflow takes a user message through a CLI, web/API, or Telegram entry point, runs it in an agent and session context, routes blueprint-defined work to tools or an LLM, and returns a response, optionally as a stream. Its documented product branches include AISOP execution, AIAP/AISP capabilities, multi-agent workflows, scheduling, and observability. The README supplies several runtime relationships; unsampled implementation details are represented only where the tree supports a component, not as inferred call chains.
Main entry points: runner.py Runner · llm_agent.py Agent Tree · base_session_service.py Session Service · runtime.py AISOP Executor
Components 25
Entry and UI
- Web Dev UI
frontend/src/views/ChatView.vue - API Client
frontend/src/composables/useApi.ts - API Server
src/soulbot/server/api_server.py - CLI
src/soulbot/cli.py - Telegram Bot
src/soulbot/connect/telegram.py
Agent Runtime
- Runner
src/soulbot/runners/runner.py - Agent Tree
src/soulbot/agents/llm_agent.py - Interaction Events
src/soulbot/events/event.py - Event Bus
src/soulbot/bus/event_bus.py - LLM Adapter
src/soulbot/models/acp_llm.py - LLM Request
src/soulbot/models/llm_request.py
Agent Capabilities
- AISOP Executor
src/soulbot/aisop/runtime.py - AIAP Packages
src/soulbot/templates/basic/aiap/aiap_list.py - AISP Skills
src/soulbot/templates/basic/aisp/aisp_list.py - Tools
src/soulbot/tools/base_tool.py - Command System
src/soulbot/commands/executor.py
Conversation State
- Session Service
src/soulbot/sessions/base_session_service.py - SQLite Sessions
src/soulbot/sessions/database_session_service.py - Session State
src/soulbot/sessions/state.py - History Services
src/soulbot/history/sqlite_history_service.py
Operations
- Scheduling
src/soulbot/scheduler/schedule_service.py - Observability
src/soulbot/observability/metrics.py - Telegram Service
Other components
- User
- LLM CLI Process
Connections 27
- User → Web Dev UI: sends message
README.md - Web Dev UI → API Client: requests API
- API Client → API Server: calls
frontend/src/composables/useApi.ts - User → CLI: starts run
README.md - User → Telegram Bot: sends message
README.md - API Server → Runner: invokes
README.md - CLI → Runner: invokes
README.md - Telegram Bot → Runner: invokes
README.md - Runner → Agent Tree: runs agent
README.md - Runner → Session Service: uses sessions
README.md - Runner → Event Bus: publishes events
README.md - Agent Tree → LLM Request: builds request
src/soulbot/agents/llm_agent.py - Agent Tree → Tools: executes tools
src/soulbot/agents/llm_agent.py - Agent Tree → Command System: dispatches commands
src/soulbot/agents/llm_agent.py - Agent Tree → AISOP Executor: runs blueprint
README.md - AISOP Executor → AIAP Packages: loads packages
README.md - AISOP Executor → AISP Skills: runs skills
README.md - LLM Request → LLM Adapter: generates response
README.md - LLM Adapter → LLM CLI Process: uses ACP
README.md - Session Service → SQLite Sessions: persists sessions
src/soulbot/sessions/database_session_service.py - Session Service → Session State: applies state deltas
src/soulbot/sessions/base_session_service.py - Session Service → Interaction Events: stores events
src/soulbot/sessions/base_session_service.py - Runner → History Services: uses history
- Command System → Scheduling: schedules tasks
src/soulbot/scheduler/schedule_service.py - Scheduling → Runner: runs scheduled work
src/soulbot/scheduler/schedule_service.py - Event Bus → Telegram Service: streams updates
- Runner → Observability: records telemetry