soorma-core 0.8.0

The Open Source Foundation for AI Agents. Powered by the DisCo (Distributed Cognition) architecture.

Soorma Core SDK

The Open Source Foundation for AI Agents.

Soorma is an agentic infrastructure platform based on the DisCo (Distributed Cognition) architecture. It provides a standardized Control Plane (Registry, Event Bus, Memory Service) for building production-grade multi-agent systems.

🚧 Status: Day 0 (Pre-Alpha)

We're in active pre-launch refactoring to solidify architecture and APIs before v1.0. The SDK and infrastructure are functional for building multi-agent systems.

Learn more: soorma.ai

What's New in v0.8.0

• 🤖 ChoreographyPlanner - LLM-based autonomous orchestration (50+ model providers via LiteLLM)
• 📊 PlanContext - State machine for multi-step workflows with pause/resume
• 📈 TrackerClient - Event-driven observability and progress tracking
• 🎯 Pattern Selection Framework - Choose the right pattern for your use case
• 🔐 BYO Model Credentials - Developer-controlled LLM providers (OpenAI, Azure, Anthropic, Ollama)

Install with LLM support: pip install soorma-core[ai]

Installation

During Pre-Launch: We recommend installing from local source to stay synchronized with breaking changes:

# Clone the repository
git clone https://github.com/soorma-ai/soorma-core.git
cd soorma-core

# Install from source
pip install -e sdk/python

After v1.0 Release: Standard PyPI installation will be recommended: pip install soorma-core

Requirements: Python 3.11+

Quick Start

Note: Infrastructure runs locally via Docker. Clone the repo to get started.

# 1. Clone the repository
git clone https://github.com/soorma-ai/soorma-core.git
cd soorma-core

# 2. Start local infrastructure
soorma dev --build

# 3. Run the Hello World example
cd examples/01-hello-world
python worker.py

# 4. In another terminal, send a request
python client.py Alice

Next steps: See the Examples Guide for a complete learning path.

Core Concepts

Soorma provides four agent patterns for building distributed AI systems:

• Tool - Synchronous, stateless operations (< 1 second)
• Worker - Asynchronous, stateful tasks with delegation
• Planner - Multi-step workflows with manual state machine control
• ChoreographyPlanner - Autonomous LLM-based orchestration

Platform Services:

• context.registry - Service discovery & capability lookup
• context.memory - Distributed state (Semantic, Episodic, Working, Plan context)
• context.bus - Event choreography (pub/sub)
• context.tracker - Observability & progress tracking

Learn more: See the comprehensive documentation for architecture details, patterns, and API references.

Agent Models

Tool Model (Synchronous)

Tools handle fast, stateless operations that return immediate results:

from soorma import Tool
from soorma.agents.tool import InvocationContext

tool = Tool(name="calculator")

@tool.on_invoke("calculate.add")
async def add_numbers(request: InvocationContext, context):
    numbers = request.data["numbers"]
    return {"sum": sum(numbers)}  # Auto-published to caller

Characteristics:

• ⚡ Stateless: No persistence between calls
• 🚀 Fast: Returns immediately (< 1 second)
• 🔄 Auto-complete: SDK publishes response automatically
• 📊 Use cases: Calculations, lookups, validations

Example: 01-hello-tool

Worker Model (Asynchronous with Delegation)

Workers handle multi-step, stateful tasks with delegation:

from soorma import Worker
from soorma.task_context import TaskContext, ResultContext

worker = Worker(name="order-processor")

@worker.on_task("order.process.requested")
async def process_order(task: TaskContext, context):
    # Save state
    task.state["order_id"] = task.data["order_id"]
    await task.save()
    
    # Delegate to sub-workers
    await task.delegate_parallel([
        DelegationSpec("inventory.reserve.requested", {...}, "inventory.reserved"),
        DelegationSpec("payment.process.requested", {...}, "payment.processed"),
    ])

@worker.on_result("inventory.reserved")
@worker.on_result("payment.processed")
async def handle_result(result: ResultContext, context):
    task = await result.restore_task()
    task.update_sub_task_result(result.correlation_id, result.data)
    
    # Complete when all results arrived
    if task.aggregate_parallel_results(task.state["group_id"]):
        await task.complete({"status": "completed"})

Characteristics:

• 💾 Stateful: TaskContext persists across delegations
• 🔄 Asynchronous: Manual completion with task.complete()
• 🎯 Delegation: Sequential or parallel sub-tasks
• ⚙️ Use cases: Workflows, long-running operations, coordination

Delegation Patterns:

• Sequential: task.delegate() - One sub-task at a time
• Parallel: task.delegate_parallel() - Fan-out with aggregation
• Multi-level: Workers can delegate to Workers (arbitrary depth)

Example: 08-worker-basic

Planner Model (Multi-Step Workflows)

Planners orchestrate multi-step workflows using state machines:

from soorma import Planner
from soorma.workflow import StateConfig, StateTransition, StateAction

planner = Planner(name="approval-workflow")

# Define state machine
states = [
    StateConfig(
        name="pending_review",
        transitions=[StateTransition(event="review.approved", next_state="pending_execution")],
        actions=[StateAction(event="review.requested", data={...})]
    ),
    # ... more states
]

@planner.on_goal("approval.workflow.requested")
async def start_workflow(goal, context):
    plan = await PlanContext.create_from_goal(goal, states, context)
    await plan.execute_next(context)  # Execute first state's actions

@planner.on_transition()
async def handle_transition(event, context, plan, next_state):
    await plan.execute_next(context)  # Execute next state's actions

Characteristics:

• 🎯 Manual control: Developer defines all state transitions
• 💾 Stateful: PlanContext persists across events
• 🔄 Re-entrant: Pause/resume for human-in-the-loop workflows
• 📊 Use cases: Approval workflows, multi-stage pipelines

Example: 09-planner-basic

ChoreographyPlanner Model (Autonomous Orchestration)

ChoreographyPlanner uses LLMs to autonomously decide next actions:

from soorma.agents.planner import ChoreographyPlanner

planner = ChoreographyPlanner(
    name="research-planner",
    model="gpt-4",  # or azure/gpt-4, anthropic/claude-3, ollama/llama3, etc.
    api_key=os.getenv("OPENAI_API_KEY"),  # BYO credentials
    system_instructions="You are a research assistant...",
    max_actions=10  # Circuit breaker
)

@planner.on_goal("research.requested")
async def handle_research(goal, context):
    plan = await planner.reason_and_execute(
        goal=goal.data["query"],
        context=context,
        custom_context={"domain": "AI research"}  # Business logic injection
    )

Characteristics:

• 🤖 Autonomous: LLM decides which events to publish and when to complete
• 🌐 Event discovery: Queries Registry for available capabilities
• ✅ Validation: Prevents LLM hallucinations via event schema checks
• 💰 Cost-aware: Configurable planning strategies (balanced|conservative|aggressive)
• 🔐 BYO credentials: Developer controls LLM provider and API keys
• 📊 Use cases: Research workflows, adaptive planning, dynamic orchestration

Installation: pip install soorma-core[ai] (includes LiteLLM for 50+ model providers)

Example: 10-choreography-basic

Pattern Comparison

Feature	Tool	Worker	Planner	ChoreographyPlanner
Execution	Synchronous	Asynchronous	Multi-step	Multi-step
State	Stateless	TaskContext	PlanContext	PlanContext
Completion	Auto	Manual	Manual	Auto (LLM decides)
Delegation	❌ No	✅ Yes	✅ Yes	✅ Yes
Control	Full	High	Full	Autonomous
LLM Required	❌ No	❌ No	❌ No	✅ Yes
Latency	< 100ms	Seconds	Varies	1-10s per decision
Cost	Free	Free	Free	LLM API costs
Example	Calculator	Order processing	Approval workflow	Research assistant

Choosing a pattern: See the Pattern Selection Guide for decision criteria and flowcharts.

CLI Reference

Command	Description
soorma init <name>	Create a new agent project
soorma dev	Start local infrastructure
soorma dev --build	Build and start (first time)
soorma dev --status	Show infrastructure status
soorma dev --logs	View infrastructure logs
soorma dev --stop	Stop infrastructure
soorma dev --stop --clean	Stop and remove all data
soorma version	Show SDK version

The soorma dev command runs infrastructure (Registry, NATS, Event Service, Memory Service) in Docker while your agent code runs natively on the host for fast iteration and debugging.

Documentation & Resources

📚 Complete Documentation: github.com/soorma-ai/soorma-core

Key Guides:

• Examples Guide - Progressive learning path from hello-world to advanced patterns
• Developer Guide - Development workflows and testing
• Agent Patterns - Tool, Worker, Planner models and DisCo pattern
• Event System - Event-driven architecture, topics, messaging
• Memory System - CoALA framework and memory types
• Discovery - Registry and capability discovery

🎓 Learning Path:

1. 01-hello-world - Basic Worker pattern
2. 01-hello-tool - Stateless Tool pattern
3. 02-events-simple - Event pub/sub
4. 03-events-structured - LLM-based event selection
5. 04-memory-working - Workflow state
6. 05-memory-semantic - RAG patterns
7. 06-memory-episodic - Multi-agent chatbot
8. 08-worker-basic - Task delegation (parallel)
9. 09-planner-basic - State machine workflows
10. 10-choreography-basic - Autonomous LLM planning

Contributing & Support

• Repository: github.com/soorma-ai/soorma-core
• Issues: Report bugs or request features
• Discussions: Ask questions
• Changelog: Release notes

License

MIT License - see LICENSE for details.