soorma-core 0.3.0__py3-none-any.whl

soorma/__init__.py

@@ -0,0 +1,138 @@
+"""
+Soorma Core - The Open Source Foundation for AI Agents.
+
+The DisCo (Distributed Cognition) SDK for building production-grade AI agents.
+
+Core Concepts:
+- Agent: Base class for all autonomous agents
+- Planner: Strategic reasoning engine that breaks goals into tasks
+- Worker: Domain-specific cognitive node that executes tasks
+- Tool: Atomic, stateless capability micro-service
+
+Platform Context (available in all handlers):
+- context.registry: Service discovery & capabilities
+- context.memory: Distributed state management
+- context.bus: Event choreography (pub/sub)
+- context.tracker: Observability & state machines
+
+Usage:
+    from soorma import Worker, PlatformContext
+
+    worker = Worker(
+        name="research-worker",
+        description="Searches and analyzes research papers",
+        capabilities=["paper_search", "citation_analysis"],
+    )
+
+    @worker.on_task("search_papers")
+    async def search_papers(task, context: PlatformContext):
+        # Access shared memory
+        prefs = await context.memory.retrieve(f"user:{task.session_id}:preferences")
+        
+        # Perform the task
+        results = await search_papers(task.data["query"], prefs)
+        
+        # Store results for other workers
+        await context.memory.store(f"results:{task.task_id}", results)
+        
+        return {"papers": results}
+
+    worker.run()
+"""
+
+__version__ = "0.3.0"
+
+# Core imports
+from .events import EventClient
+from .context import (
+    PlatformContext,
+    RegistryClient,
+    MemoryClient,
+    BusClient,
+    TrackerClient,
+)
+from .agents import Agent, Planner, Worker, Tool
+from .agents.planner import Goal, Plan, Task
+from .agents.worker import TaskContext
+from .agents.tool import ToolRequest, ToolResponse
+
+# Public API
+__all__ = [
+    # Version
+    "__version__",
+    # Core classes
+    "Agent",
+    "Planner",
+    "Worker", 
+    "Tool",
+    # Context
+    "PlatformContext",
+    "RegistryClient",
+    "MemoryClient",
+    "BusClient",
+    "TrackerClient",
+    # Events
+    "EventClient",
+    # Data classes
+    "Goal",
+    "Plan",
+    "Task",
+    "TaskContext",
+    "ToolRequest",
+    "ToolResponse",
+    # Functions
+    "hello",
+    "event_handler",
+]
+
+
+def hello():
+    """
+    Welcome to Soorma.
+    
+    Displays version info and links to documentation.
+    """
+    print(f"Soorma Core v{__version__}")
+    print("=" * 50)
+    print("The DisCo (Distributed Cognition) SDK")
+    print("")
+    print("Domain Services (The Trinity):")
+    print("  • Planner: Strategic reasoning engine")
+    print("  • Worker:  Domain-specific cognitive node")
+    print("  • Tool:    Atomic, stateless capability")
+    print("")
+    print("Platform Context:")
+    print("  • context.registry - Service discovery")
+    print("  • context.memory   - Distributed state")
+    print("  • context.bus      - Event choreography")
+    print("  • context.tracker  - Observability")
+    print("")
+    print("Quick Start:")
+    print("  soorma init my-agent    # Create new agent")
+    print("  soorma dev              # Start local stack")
+    print("  soorma deploy           # Deploy to cloud")
+    print("")
+    print("Docs: https://soorma.ai")
+
+
+def event_handler(event_type: str):
+    """
+    Decorator to register an event handler.
+    
+    This is a legacy/convenience decorator. For new code, use:
+    - @agent.on_event("event.type") for generic agents
+    - @planner.on_goal("goal.type") for planners
+    - @worker.on_task("task_name") for workers
+    - @tool.on_invoke("operation") for tools
+    
+    Usage:
+        @event_handler("example.request")
+        async def handle_example(event, context):
+            ...
+    """
+    from typing import Callable
+    
+    def decorator(func: Callable) -> Callable:
+        func._soorma_event_type = event_type
+        return func
+    return decorator

soorma/agents/__init__.py

@@ -0,0 +1,17 @@
+"""
+Soorma Agents Module.
+
+This module provides the base Agent class and the DisCo "Trinity":
+- Planner: Strategic reasoning engine that breaks goals into tasks
+- Worker: Domain-specific cognitive node that executes tasks
+- Tool: Atomic, stateless capability for specific operations
+
+All three extend the base Agent class but provide specialized interfaces
+for their respective roles in the DisCo architecture.
+"""
+from .base import Agent
+from .planner import Planner
+from .worker import Worker
+from .tool import Tool
+
+__all__ = ["Agent", "Planner", "Worker", "Tool"]

soorma/agents/base.py

@@ -0,0 +1,523 @@
+"""
+Base Agent class for all Soorma agents.
+
+The Agent class provides the foundation for all agent types in the DisCo architecture.
+It handles:
+- Platform context initialization (registry, memory, bus, tracker)
+- Event subscription and publishing
+- Agent lifecycle (startup, shutdown)
+- Registry registration
+
+Usage:
+    from soorma.agents import Agent
+
+    agent = Agent(
+        name="my-agent",
+        description="My custom agent",
+        capabilities=["data_analysis"],
+    )
+
+    @agent.on_startup
+    async def startup():
+        print("Agent starting...")
+
+    @agent.on_event("data.requested")
+    async def handle_data_request(event, context):
+        result = process_data(event["data"])
+        await context.bus.publish("data.completed", result)
+
+    agent.run()
+"""
+import asyncio
+import logging
+import os
+import signal
+from abc import ABC
+from dataclasses import dataclass, field
+from typing import Any, Awaitable, Callable, Dict, List, Optional
+from uuid import uuid4
+
+from ..context import PlatformContext
+from ..events import EventClient
+
+logger = logging.getLogger(__name__)
+
+# Type aliases
+EventHandler = Callable[[Dict[str, Any], PlatformContext], Awaitable[None]]
+LifecycleHandler = Callable[[], Awaitable[None]]
+
+
+@dataclass
+class AgentConfig:
+    """Configuration for an agent."""
+    # Core identity
+    agent_id: str
+    name: str
+    description: str
+    version: str
+    agent_type: str  # "agent", "planner", "worker", "tool"
+    
+    # Capabilities and events
+    capabilities: List[Any] = field(default_factory=list)  # List[str] or List[AgentCapability]
+    events_consumed: List[str] = field(default_factory=list)
+    events_produced: List[str] = field(default_factory=list)
+    
+    # Runtime settings
+    heartbeat_interval: float = 30.0  # seconds
+    auto_register: bool = True
+    
+    # Platform URLs (from env or defaults)
+    registry_url: str = field(
+        default_factory=lambda: os.getenv("SOORMA_REGISTRY_URL", "http://localhost:8081")
+    )
+    event_service_url: str = field(
+        default_factory=lambda: os.getenv("SOORMA_EVENT_SERVICE_URL", "http://localhost:8082")
+    )
+    memory_url: str = field(
+        default_factory=lambda: os.getenv("SOORMA_MEMORY_URL", "http://localhost:8083")
+    )
+    tracker_url: str = field(
+        default_factory=lambda: os.getenv("SOORMA_TRACKER_URL", "http://localhost:8084")
+    )
+
+
+class Agent(ABC):
+    """
+    Base class for all Soorma agents.
+    
+    An Agent is an autonomous unit in the DisCo architecture that:
+    - Registers with the Soorma Registry on startup
+    - Subscribes to events it can handle
+    - Processes events using registered handlers
+    - Publishes result events
+    
+    The base Agent class is framework-agnostic - you can use it directly
+    or through the specialized Planner, Worker, and Tool classes.
+    
+    Attributes:
+        name: Human-readable name of the agent
+        description: What this agent does
+        version: Semantic version string
+        capabilities: List of capabilities this agent provides
+        config: Full agent configuration
+        context: Platform context (registry, memory, bus, tracker)
+    
+    Usage:
+        agent = Agent(
+            name="data-processor",
+            description="Processes incoming data requests",
+            capabilities=["data_processing", "csv_parsing"],
+        )
+        
+        @agent.on_event("data.requested")
+        async def handle_request(event, context):
+            # Process the event
+            result = await process(event["data"])
+            # Publish result
+            await context.bus.publish("data.completed", {"result": result})
+        
+        agent.run()
+    """
+    
+    def __init__(
+        self,
+        name: str,
+        description: str = "",
+        version: str = "0.1.0",
+        agent_type: str = "agent",
+        capabilities: Optional[List[str]] = None,
+        events_consumed: Optional[List[str]] = None,
+        events_produced: Optional[List[str]] = None,
+        agent_id: Optional[str] = None,
+        auto_register: bool = True,
+    ):
+        """
+        Initialize the agent.
+        
+        Args:
+            name: Human-readable name
+            description: What this agent does
+            version: Semantic version (default: "0.1.0")
+            agent_type: Type of agent ("agent", "planner", "worker", "tool")
+            capabilities: List of capabilities provided
+            events_consumed: Event types this agent subscribes to
+            events_produced: Event types this agent publishes
+            agent_id: Unique ID (auto-generated if not provided)
+            auto_register: Whether to register with Registry on startup
+        """
+        self.config = AgentConfig(
+            agent_id=agent_id or f"{name}-{str(uuid4())[:8]}",
+            name=name,
+            description=description,
+            version=version,
+            agent_type=agent_type,
+            capabilities=capabilities or [],
+            events_consumed=events_consumed or [],
+            events_produced=events_produced or [],
+            auto_register=auto_register,
+        )
+        
+        # Convenience accessors
+        self.name = name
+        self.description = description
+        self.version = version
+        self.capabilities = self.config.capabilities
+        
+        # Platform context (initialized on run)
+        self._context: Optional[PlatformContext] = None
+        
+        # Lifecycle handlers
+        self._startup_handlers: List[LifecycleHandler] = []
+        self._shutdown_handlers: List[LifecycleHandler] = []
+        
+        # Event handlers: event_type -> handler
+        self._event_handlers: Dict[str, List[EventHandler]] = {}
+        
+        # Runtime state
+        self._running = False
+        self._heartbeat_task: Optional[asyncio.Task] = None
+    
+    @property
+    def agent_id(self) -> str:
+        """Get the unique agent ID."""
+        return self.config.agent_id
+    
+    @property
+    def context(self) -> PlatformContext:
+        """
+        Get the platform context.
+        
+        Raises:
+            RuntimeError: If accessed before agent.run() is called
+        """
+        if self._context is None:
+            raise RuntimeError("Platform context not initialized. Call agent.run() first.")
+        return self._context
+    
+    # =========================================================================
+    # Decorators for registering handlers
+    # =========================================================================
+    
+    def on_startup(self, func: LifecycleHandler) -> LifecycleHandler:
+        """
+        Decorator to register a startup handler.
+        
+        Startup handlers are called after platform services connect
+        but before the agent starts processing events.
+        
+        Usage:
+            @agent.on_startup
+            async def startup():
+                print("Agent starting...")
+        """
+        self._startup_handlers.append(func)
+        return func
+    
+    def on_shutdown(self, func: LifecycleHandler) -> LifecycleHandler:
+        """
+        Decorator to register a shutdown handler.
+        
+        Shutdown handlers are called when the agent is stopping,
+        before disconnecting from platform services.
+        
+        Usage:
+            @agent.on_shutdown
+            async def shutdown():
+                print("Agent shutting down...")
+        """
+        self._shutdown_handlers.append(func)
+        return func
+    
+    def on_event(self, event_type: str) -> Callable[[EventHandler], EventHandler]:
+        """
+        Decorator to register an event handler.
+        
+        Handlers receive the event payload and the platform context.
+        Multiple handlers can be registered for the same event type.
+        
+        Usage:
+            @agent.on_event("data.requested")
+            async def handle_request(event, context):
+                result = await process(event["data"])
+                await context.bus.publish("data.completed", result)
+        
+        Args:
+            event_type: The event type to handle
+        
+        Returns:
+            Decorator function
+        """
+        def decorator(func: EventHandler) -> EventHandler:
+            if event_type not in self._event_handlers:
+                self._event_handlers[event_type] = []
+            self._event_handlers[event_type].append(func)
+            
+            # Track in consumed events
+            if event_type not in self.config.events_consumed:
+                self.config.events_consumed.append(event_type)
+            
+            logger.debug(f"Registered handler for event: {event_type}")
+            return func
+        return decorator
+    
+    # =========================================================================
+    # Event Publishing (convenience methods)
+    # =========================================================================
+    
+    async def emit(
+        self,
+        event_type: str,
+        data: Dict[str, Any],
+        topic: Optional[str] = None,
+        correlation_id: Optional[str] = None,
+    ) -> str:
+        """
+        Emit an event to the event bus.
+        
+        This is a convenience method that delegates to context.bus.publish().
+        
+        Args:
+            event_type: Event type (e.g., "order.created")
+            data: Event payload
+            topic: Target topic (auto-inferred if not provided)
+            correlation_id: Optional correlation ID
+        
+        Returns:
+            The event ID
+        """
+        return await self.context.bus.publish(
+            event_type=event_type,
+            data=data,
+            topic=topic,
+            correlation_id=correlation_id,
+        )
+    
+    # =========================================================================
+    # Agent Lifecycle
+    # =========================================================================
+    
+    async def _initialize_context(self) -> None:
+        """Initialize the platform context."""
+        logger.info(f"Initializing platform context for {self.name}")
+        
+        # Create EventClient for bus
+        event_client = EventClient(
+            event_service_url=self.config.event_service_url,
+            agent_id=self.agent_id,
+            source=self.name,
+        )
+        
+        # Register our event handlers with the EventClient
+        for event_type, handlers in self._event_handlers.items():
+            for handler in handlers:
+                @event_client.on_event(event_type)
+                async def wrapped_handler(event: Dict[str, Any], h=handler) -> None:
+                    await h(event, self._context)
+        
+        # Create context with configured clients
+        from ..context import RegistryClient, MemoryClient, BusClient, TrackerClient
+        
+        self._context = PlatformContext(
+            registry=RegistryClient(base_url=self.config.registry_url),
+            memory=MemoryClient(base_url=self.config.memory_url),
+            bus=BusClient(event_client=event_client),
+            tracker=TrackerClient(base_url=self.config.tracker_url),
+        )
+    
+    async def _register_with_registry(self) -> bool:
+        """Register the agent with the Registry service."""
+        if not self.config.auto_register:
+            return True
+        
+        logger.info(f"Registering {self.name} with Registry")
+        
+        success = await self.context.registry.register(
+            agent_id=self.agent_id,
+            name=self.name,
+            agent_type=self.config.agent_type,
+            capabilities=self.config.capabilities,
+            events_consumed=self.config.events_consumed,
+            events_produced=self.config.events_produced,
+            metadata={
+                "version": self.version,
+                "description": self.description,
+            },
+        )
+        
+        if success:
+            logger.info(f"✓ Registered {self.name} ({self.agent_id})")
+        else:
+            logger.warning(f"⚠ Failed to register with Registry (continuing in offline mode)")
+        
+        return success
+    
+    async def _deregister_from_registry(self) -> None:
+        """Deregister from the Registry service."""
+        if not self.config.auto_register:
+            return
+        
+        logger.info(f"Deregistering {self.name} from Registry")
+        await self.context.registry.deregister(self.agent_id)
+    
+    async def _start_heartbeat(self) -> None:
+        """Start the heartbeat task."""
+        async def heartbeat_loop():
+            while self._running:
+                try:
+                    await asyncio.sleep(self.config.heartbeat_interval)
+                    if self._running:
+                        await self.context.registry.heartbeat(self.agent_id)
+                except asyncio.CancelledError:
+                    break
+                except Exception as e:
+                    logger.debug(f"Heartbeat failed: {e}")
+        
+        self._heartbeat_task = asyncio.create_task(heartbeat_loop())
+    
+    async def _stop_heartbeat(self) -> None:
+        """Stop the heartbeat task."""
+        if self._heartbeat_task:
+            self._heartbeat_task.cancel()
+            try:
+                await self._heartbeat_task
+            except asyncio.CancelledError:
+                pass
+            self._heartbeat_task = None
+    
+    async def _subscribe_to_events(self) -> None:
+        """Subscribe to event topics."""
+        if not self.config.events_consumed:
+            logger.info("No events to subscribe to")
+            return
+        
+        # Derive topics from event types
+        topics = self._derive_topics(self.config.events_consumed)
+        
+        logger.info(f"Subscribing to topics: {topics}")
+        await self.context.bus.subscribe(topics)
+    
+    def _derive_topics(self, event_types: List[str]) -> List[str]:
+        """Derive topic patterns from event types."""
+        topics = set()
+        for event_type in event_types:
+            # Support wildcards in event types
+            if "*" in event_type:
+                topics.add(event_type)
+            elif event_type.endswith(".requested") or event_type.endswith(".request"):
+                topics.add("action-requests")
+            elif event_type.endswith(".completed") or event_type.endswith(".result"):
+                topics.add("action-results")
+            elif event_type.startswith("billing."):
+                topics.add("billing")
+            elif event_type.startswith("notification."):
+                topics.add("notifications")
+            else:
+                topics.add("business-facts")
+        return list(topics)
+    
+    async def start(self) -> None:
+        """
+        Start the agent.
+        
+        This method:
+        1. Initializes the platform context
+        2. Registers with the Registry
+        3. Calls startup handlers
+        4. Subscribes to events
+        5. Starts the heartbeat
+        
+        For blocking execution, use agent.run() instead.
+        """
+        if self._running:
+            logger.warning("Agent already running")
+            return
+        
+        logger.info(f"🚀 Starting {self.name} v{self.version}")
+        
+        # Initialize platform context
+        await self._initialize_context()
+        
+        # Register with Registry
+        await self._register_with_registry()
+        
+        # Call startup handlers
+        for handler in self._startup_handlers:
+            await handler()
+        
+        # Subscribe to events
+        await self._subscribe_to_events()
+        
+        # Start heartbeat
+        await self._start_heartbeat()
+        
+        self._running = True
+        logger.info(f"✓ {self.name} is running")
+    
+    async def stop(self) -> None:
+        """
+        Stop the agent gracefully.
+        
+        This method:
+        1. Stops the heartbeat
+        2. Calls shutdown handlers
+        3. Deregisters from Registry
+        4. Closes platform connections
+        """
+        if not self._running:
+            return
+        
+        logger.info(f"🛑 Stopping {self.name}")
+        self._running = False
+        
+        # Stop heartbeat
+        await self._stop_heartbeat()
+        
+        # Call shutdown handlers
+        for handler in self._shutdown_handlers:
+            try:
+                await handler()
+            except Exception as e:
+                logger.error(f"Shutdown handler error: {e}")
+        
+        # Deregister
+        await self._deregister_from_registry()
+        
+        # Close context
+        if self._context:
+            await self._context.close()
+            self._context = None
+        
+        logger.info(f"👋 {self.name} stopped")
+    
+    def run(self) -> None:
+        """
+        Start the agent and run until interrupted.
+        
+        This is the main entry point for running an agent.
+        It handles signal handlers for graceful shutdown.
+        
+        Usage:
+            if __name__ == "__main__":
+                agent.run()
+        """
+        async def _run():
+            # Setup signal handlers
+            loop = asyncio.get_event_loop()
+            stop_event = asyncio.Event()
+            
+            def signal_handler():
+                stop_event.set()
+            
+            for sig in (signal.SIGINT, signal.SIGTERM):
+                loop.add_signal_handler(sig, signal_handler)
+            
+            try:
+                await self.start()
+                await stop_event.wait()
+            finally:
+                await self.stop()
+        
+        try:
+            asyncio.run(_run())
+        except KeyboardInterrupt:
+            pass