soorma-core 0.7.7

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

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 three agent types for building distributed AI systems:

• Tool - Synchronous, stateless operations (< 1 second)
• Worker - Asynchronous, stateful tasks with delegation
• Planner - Strategic reasoning and goal decomposition (Stage 4)

Platform Services:

• context.registry - Service discovery
• context.memory - Distributed state (Semantic, Episodic, Working memory)
• context.bus - Event choreography
• context.tracker - Observability

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

Comparison

Feature	Tool	Worker
Execution	Synchronous	Asynchronous
State	Stateless	Stateful (TaskContext)
Completion	Auto	Manual (task.complete())
Delegation	❌ No	✅ Yes
Memory I/O	❌ No	✅ Yes
Latency	< 100ms	Seconds to minutes
Example	Calculator	Order processing

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. 02-events-simple - Event pub/sub
3. 03-events-structured - LLM-based event selection
4. 04-memory-working - Workflow state
5. 05-memory-semantic - RAG patterns
6. 06-memory-episodic - Multi-agent chatbot

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.