loom-agent 0.3.3__py3-none-any.whl

loom/node/base.py

@@ -0,0 +1,121 @@
+"""
+Base Node Abstraction (Fractal System)
+"""
+
+import asyncio
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional
+from uuid import uuid4
+
+from loom.protocol.cloudevents import CloudEvent
+from loom.kernel.dispatcher import Dispatcher
+
+class Node(ABC):
+    """
+    Abstract Base Class for all Fractal Nodes (Agent, Tool, Crew).
+    Implements standard event subscription and request handling.
+    """
+    
+    def __init__(self, node_id: str, dispatcher: Dispatcher):
+        self.node_id = node_id
+        self.dispatcher = dispatcher
+        self.source_uri = f"/node/{node_id}" # Standard URI
+        
+        # Auto-subscribe to my requests
+        asyncio.create_task(self._subscribe_to_events())
+
+    async def _subscribe_to_events(self):
+        """Subscribe to 'node.request' targeting this node."""
+        topic = f"node.request/{self.source_uri.strip('/')}"
+        await self.dispatcher.bus.subscribe(topic, self._handle_request)
+
+    async def _handle_request(self, event: CloudEvent):
+        """
+        Standard request handler.
+        1. Calls node-specific process()
+        2. Dispatches response/result/error
+        """
+        try:
+            # 1. Process
+            result = await self.process(event)
+            
+            # 2. Respond
+            response_event = CloudEvent.create(
+                source=self.source_uri,
+                type="node.response",
+                data={
+                    "request_id": event.id,
+                    "result": result
+                },
+                traceparent=event.traceparent
+            )
+            # Response topic usually goes to whoever asked, or open bus
+            # In request-reply pattern, typically we might just publish it
+            # and the caller subscribes to node.response/originator
+            
+            # For now, just generic publish
+            await self.dispatcher.dispatch(response_event)
+            
+        except Exception as e:
+            error_event = CloudEvent.create(
+                source=self.source_uri,
+                type="node.error",
+                data={
+                    "request_id": event.id,
+                    "error": str(e)
+                },
+                traceparent=event.traceparent
+            )
+            await self.dispatcher.dispatch(error_event)
+
+    async def call(self, target_node: str, data: Dict[str, Any]) -> Any:
+        """
+        Call another node and wait for response.
+
+        FIXED: Now properly cleans up subscription using unsubscribe()
+        to prevent memory leaks from accumulated handlers.
+        """
+        request_id = str(uuid4())
+        request_event = CloudEvent.create(
+            source=self.source_uri,
+            type="node.request",
+            data=data,
+            subject=target_node,
+        )
+        request_event.id = request_id
+
+        # Subscribe to response
+        # Using Broadcast Reply pattern: listen to target's responses
+        response_future = asyncio.Future()
+
+        async def handle_response(event: CloudEvent):
+            if event.data and event.data.get("request_id") == request_id:
+                if not response_future.done():
+                    if event.type == "node.error":
+                         response_future.set_exception(Exception(event.data.get("error", "Unknown Error")))
+                    else:
+                         response_future.set_result(event.data.get("result"))
+
+        # Topic: node.response/{target_node}
+        # Note: clean URI
+        target_topic = f"node.response/{target_node.strip('/')}"
+
+        # We need access to bus directly or via dispatcher
+        # Dispatcher has .bus
+        await self.dispatcher.bus.subscribe(target_topic, handle_response)
+
+        try:
+            # Dispatch request
+            await self.dispatcher.dispatch(request_event)
+
+            # Wait for response
+            return await asyncio.wait_for(response_future, timeout=30.0)
+        finally:
+            # FIXED: Cleanup subscription to prevent memory leaks
+            await self.dispatcher.bus.unsubscribe(target_topic, handle_response)
+
+
+    @abstractmethod
+    async def process(self, event: CloudEvent) -> Any:
+        """Core logic."""
+        pass

loom/node/crew.py

@@ -0,0 +1,105 @@
+"""
+Crew Node (Orchestrator)
+"""
+
+from typing import Any, List, Literal
+
+from loom.protocol.cloudevents import CloudEvent
+from loom.protocol.interfaces import NodeProtocol
+from loom.node.base import Node
+from loom.kernel.dispatcher import Dispatcher
+from loom.protocol.memory_operations import ContextSanitizer
+from loom.builtin.memory.sanitizers import BubbleUpSanitizer
+
+class CrewNode(Node):
+    """
+    A Node that orchestrates other Nodes (recursive composition).
+
+    FIXED: Now accepts List[NodeProtocol] instead of List[AgentNode].
+    This enables TRUE fractal recursion:
+    - CrewNode can contain AgentNode
+    - CrewNode can contain other CrewNode (nested crews)
+    - CrewNode can contain RouterNode
+    - Any Node type that implements NodeProtocol
+
+    This adheres to "Protocol-First" and "Fractal Uniformity" principles.
+    """
+
+    def __init__(
+        self,
+        node_id: str,
+        dispatcher: Dispatcher,
+        agents: List[NodeProtocol],
+        pattern: Literal["sequential", "parallel"] = "sequential",
+        sanitizer: ContextSanitizer = None
+    ):
+        super().__init__(node_id, dispatcher)
+        self.agents = agents
+        self.pattern = pattern
+        self.sanitizer = sanitizer or BubbleUpSanitizer()
+        
+    async def process(self, event: CloudEvent) -> Any:
+        """
+        Execute the crew pattern.
+        """
+        task = event.data.get("task", "")
+        
+        if self.pattern == "sequential":
+            return await self._execute_sequential(task, event.traceparent)
+        
+        return {"error": "Unsupported pattern"}
+        
+    async def _execute_sequential(self, task: str, traceparent: str = None) -> Any:
+        """
+        Chain agents sequentially. A -> B -> C
+
+        FIXED: Now uses self.call() to ensure all calls go through event bus.
+        This ensures:
+        - Interceptor hooks are triggered
+        - Studio can capture events
+        - Distributed deployment is supported
+        - Fractal uniformity is maintained
+        """
+        current_input = task
+        chain_results = []
+
+        for agent in self.agents:
+            # Use self.call() to invoke through event bus
+            # This ensures proper event flow: request -> dispatch -> interceptors -> agent -> response
+            try:
+                result = await self.call(
+                    target_node=agent.source_uri,
+                    data={"task": current_input}
+                )
+            except Exception as e:
+                # Error already propagated through event bus
+                return {
+                    "error": f"Agent {agent.node_id} failed: {str(e)}",
+                    "trace": chain_results
+                }
+
+            # Extract response
+            # self.call() returns the result data from node.response event
+            if isinstance(result, dict):
+                response = result.get("response", str(result))
+            else:
+                response = str(result)
+
+            # Sanitization (Fractal Metabolism)
+            # Limit the bubble-up context to prevent context pollution in long chains
+            sanitized_response = await self.sanitizer.sanitize(str(response), target_token_limit=100)
+
+            chain_results.append({
+                "agent": agent.node_id,
+                "output": response, # Full output in trace
+                "sanitized": sanitized_response
+            })
+
+            # Pass to next agent
+            # Design choice: pass full output (agent's memory will metabolize if needed)
+            current_input = response
+
+        return {
+            "final_output": current_input,
+            "trace": chain_results
+        }

loom/node/router.py

@@ -0,0 +1,77 @@
+"""
+Router Node (Attention Mechanism)
+"""
+
+from typing import Any, List, Dict
+from loom.protocol.cloudevents import CloudEvent
+from loom.protocol.interfaces import NodeProtocol
+from loom.node.base import Node
+from loom.kernel.dispatcher import Dispatcher
+from loom.interfaces.llm import LLMProvider
+
+class AttentionRouter(Node):
+    """
+    Intelligent Router that routes tasks to the best suited Node based on description.
+
+    FIXED: Now accepts List[NodeProtocol] instead of List[AgentNode].
+    This enables fractal routing:
+    - Can route to AgentNode
+    - Can route to CrewNode (sub-teams)
+    - Can route to other RouterNode (nested routing)
+    - Any Node type that implements NodeProtocol
+
+    This adheres to "Protocol-First" and "Fractal Uniformity" principles.
+    """
+
+    def __init__(
+        self,
+        node_id: str,
+        dispatcher: Dispatcher,
+        agents: List[NodeProtocol],
+        provider: LLMProvider
+    ):
+        super().__init__(node_id, dispatcher)
+        self.agents = {agent.node_id: agent for agent in agents}
+        self.provider = provider
+        # Agent descriptions map
+        self.registry = {agent.node_id: agent.role for agent in agents}
+        
+    async def process(self, event: CloudEvent) -> Any:
+        task = event.data.get("task", "")
+        if not task:
+            return {"error": "No task provided"}
+            
+        # 1. Construct Prompt
+        options = "\n".join([f"- {aid}: {role}" for aid, role in self.registry.items()])
+        prompt = f"""
+        You are a routing system. Given the task, select the best agent ID to handle it.
+        Return ONLY the agent ID.
+        
+        Agents:
+        {options}
+        
+        Task: {task}
+        """
+        
+        # 2. LLM Select
+        # Simple chat call
+        response = await self.provider.chat([{"role": "user", "content": prompt}])
+        selected_id = response.content.strip()
+        
+        # Clean up potential extra chars/whitespace
+        # Iterate keys to find match if fuzzy
+        target_agent = None
+        for aid in self.agents:
+            if aid in selected_id:
+                target_agent = self.agents[aid]
+                break
+                
+        if not target_agent:
+             return {"error": f"Could not route task. Selected: {selected_id}"}
+             
+        # 3. Dispatch to Target
+        # Request-Reply: We wait for the agent and return its result.
+        # Use our Node.call mechanism!
+        
+        result = await self.call(target_agent.source_uri, {"task": task})
+        return {"result": result, "routed_to": target_agent.node_id}

loom/node/tool.py

@@ -0,0 +1,50 @@
+"""
+Tool Node (Fractal System)
+"""
+
+from typing import Any, Callable, Dict
+
+from loom.protocol.cloudevents import CloudEvent
+from loom.protocol.mcp import MCPToolDefinition
+from loom.node.base import Node
+from loom.kernel.dispatcher import Dispatcher
+
+class ToolNode(Node):
+    """
+    A Node that acts as an MCP Server for a single tool.
+    Reference Implementation.
+    """
+    
+    def __init__(
+        self,
+        node_id: str,
+        dispatcher: Dispatcher,
+        tool_def: MCPToolDefinition,
+        func: Callable[[Dict[str, Any]], Any]
+    ):
+        super().__init__(node_id, dispatcher)
+        self.tool_def = tool_def
+        self.func = func
+        
+    async def process(self, event: CloudEvent) -> Any:
+        """
+        Execute the tool.
+        Expects event.data to contain 'arguments'.
+        """
+        args = event.data.get("arguments", {})
+        
+        # In a real system, validate against self.tool_def.input_schema
+        
+        # Execute
+        try:
+            # Check if func is async
+            import inspect
+            if inspect.iscoroutinefunction(self.func):
+                result = await self.func(args)
+            else:
+                result = self.func(args)
+                
+            return {"result": result}
+        except Exception as e:
+            # Re-raise to trigger node.error in Base Node
+            raise RuntimeError(f"Tool execution failed: {e}")

loom/protocol/cloudevents.py

@@ -0,0 +1,73 @@
+"""
+CloudEvents v1.0 Implementation for Loom
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+from uuid import uuid4
+
+from pydantic import BaseModel, Field, ConfigDict
+
+class CloudEvent(BaseModel):
+    """
+    CloudEvents 1.0 Specification Implementation.
+    
+    Attributes:
+        specversion: The version of the CloudEvents specification which the event uses.
+        id: Identifies the event.
+        source: Identifies the context in which an event happened.
+        type: Describes the type of event related to the originating occurrence.
+        datacontenttype: Content type of data value.
+        dataschema: Identifies the schema that data adheres to.
+        subject: Describes the subject of the event in the context of the event producer (identified by source).
+        time: Timestamp of when the occurrence happened.
+        data: The event payload.
+        traceparent: W3C Trace Context (Extension)
+    """
+    
+    # Required Attributes
+    specversion: str = "1.0"
+    id: str = Field(default_factory=lambda: str(uuid4()))
+    source: str
+    type: str # e.g., "node.call", "agent.thought"
+    
+    # Optional Attributes
+    datacontenttype: Optional[str] = "application/json"
+    dataschema: Optional[str] = None
+    subject: Optional[str] = None
+    time: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    data: Optional[Any] = None
+    
+    # Extensions
+    traceparent: Optional[str] = None
+    extensions: Dict[str, Any] = Field(default_factory=dict)
+    
+    model_config = ConfigDict(
+        populate_by_name=True,
+        json_encoders={datetime: lambda v: v.isoformat()},
+        extra='allow'
+    )
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to standard CloudEvents dictionary structure."""
+        return self.model_dump(exclude_none=True, by_alias=True)
+    
+    @classmethod
+    def create(
+        cls, 
+        source: str, 
+        type: str, 
+        data: Optional[Any] = None, 
+        subject: Optional[str] = None,
+        traceparent: Optional[str] = None
+    ) -> "CloudEvent":
+        """Factory method to create a CloudEvent."""
+        return cls(
+            source=source,
+            type=type,
+            data=data,
+            subject=subject,
+            traceparent=traceparent
+        )

loom/protocol/interfaces.py

@@ -0,0 +1,164 @@
+"""
+Core Protocols for Loom Framework.
+Adhering to the "Protocol-First" design principle using typing.Protocol.
+"""
+
+from typing import Any, Dict, List, Optional, Protocol, runtime_checkable, AsyncIterator, Union
+
+from loom.protocol.cloudevents import CloudEvent
+
+# ----------------------------------------------------------------------
+# Node Protocol
+# ----------------------------------------------------------------------
+
+@runtime_checkable
+class NodeProtocol(Protocol):
+    """
+    Protocol for any Node in the Loom Fractal System.
+    """
+    node_id: str
+    source_uri: str
+    
+    async def process(self, event: CloudEvent) -> Any:
+        """
+        Process an incoming event and return a result.
+        """
+        ...
+
+    async def call(self, target_node: str, data: Dict[str, Any]) -> Any:
+        """
+        Send a request to another node and await the response.
+        """
+        ...
+
+# ----------------------------------------------------------------------
+# Memory Protocol
+# ----------------------------------------------------------------------
+
+@runtime_checkable
+class MemoryStrategy(Protocol):
+    """
+    Protocol for Memory interactions.
+    """
+    async def add(self, role: str, content: str, metadata: Optional[Dict[str, Any]] = None) -> None:
+        """Add a memory entry."""
+        ...
+
+    async def get_context(self, task: str = "") -> str:
+        """Get full context formatted for the LLM."""
+        ...
+
+    async def get_recent(self, limit: int = 10) -> List[Dict[str, Any]]:
+        """Get recent memory entries."""
+        ...
+
+    async def clear(self) -> None:
+        """Clear memory."""
+        ...
+
+
+@runtime_checkable
+class ReflectiveMemoryStrategy(MemoryStrategy, Protocol):
+    """
+    Extended Protocol for Memory with Reflection capabilities.
+
+    ADDED: Reflection methods for metabolic memory management.
+    Implementations that support reflection should implement this protocol.
+
+    This follows Protocol-First design - not all memories need reflection,
+    but those that do should implement these methods consistently.
+    """
+
+    def should_reflect(self, threshold: int = 20) -> bool:
+        """
+        Check if memory should be reflected/consolidated.
+
+        Args:
+            threshold: Number of entries that trigger reflection
+
+        Returns:
+            True if reflection should be performed
+        """
+        ...
+
+    def get_reflection_candidates(self, count: int = 10) -> List[Any]:
+        """
+        Get memory entries to be reflected/summarized.
+
+        Args:
+            count: Number of entries to retrieve for reflection
+
+        Returns:
+            List of memory entries (implementation-specific format)
+        """
+        ...
+
+    async def consolidate(self, summary: str, remove_count: int = 10) -> None:
+        """
+        Consolidate memories by replacing old entries with summary.
+
+        Args:
+            summary: The summarized/reflected knowledge
+            remove_count: Number of old entries to remove
+
+        This is the "metabolic" operation - converting detailed memories
+        into compact knowledge representations.
+        """
+        ...
+
+# ----------------------------------------------------------------------
+# LLM Protocol
+# ----------------------------------------------------------------------
+
+# We need the LLMResponse type, but we can't easily import it if it's in the interface file
+# without creating circular deps if that interface file imports this protocol file.
+# For now, we will use Any or assume the structure matches.
+# Ideally, data models should be in `loom.protocol.types` or similar, 
+# but we'll stick to `Any` or Dict for the strict Protocol definition to avoid tight coupling,
+# OR we rely on structural subtyping. 
+# But let's try to be precise if possible.
+
+@runtime_checkable
+class LLMProviderProtocol(Protocol):
+    """
+    Protocol for LLM Providers.
+    """
+    async def chat(
+        self, 
+        messages: List[Dict[str, Any]], 
+        tools: Optional[List[Dict[str, Any]]] = None
+    ) -> Any: # Returns LLMResponse compatible object
+        ...
+
+    async def stream_chat(
+        self,
+        messages: List[Dict[str, Any]],
+        tools: Optional[List[Dict[str, Any]]] = None
+    ) -> AsyncIterator[str]:
+        ...
+
+# ----------------------------------------------------------------------
+# Infra Protocols
+# ----------------------------------------------------------------------
+
+@runtime_checkable
+class TransportProtocol(Protocol):
+    """
+    Protocol for Event Transport (Pub/Sub).
+
+    FIXED: Added unsubscribe() to prevent memory leaks.
+    Handlers must be unsubscribed when no longer needed.
+    """
+    async def connect(self) -> None: ...
+    async def disconnect(self) -> None: ...
+    async def publish(self, topic: str, event: CloudEvent) -> None: ...
+    async def subscribe(self, topic: str, handler: Any) -> None: ...
+    async def unsubscribe(self, topic: str, handler: Any) -> None: ...
+
+@runtime_checkable
+class EventBusProtocol(Protocol):
+    """
+    Protocol for the Universal Event Bus.
+    """
+    async def publish(self, event: CloudEvent) -> None: ...
+    async def subscribe(self, topic: str, handler: Any) -> None: ...

loom/protocol/mcp.py

@@ -0,0 +1,97 @@
+"""
+Model Context Protocol (MCP) Implementation for Loom
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional
+from dataclasses import dataclass, field
+from pydantic import BaseModel, Field, ConfigDict
+
+# --- MCP Data Models ---
+
+class MCPToolDefinition(BaseModel):
+    """Definition of an MCP Tool."""
+    name: str
+    description: str
+    input_schema: Dict[str, Any] = Field(..., alias="inputSchema") 
+    
+    model_config = ConfigDict(populate_by_name=True)
+
+class MCPResource(BaseModel):
+    """Definition of an MCP Resource."""
+    uri: str
+    name: str
+    mime_type: str = Field(..., alias="mimeType")
+    description: Optional[str] = None
+    
+    model_config = ConfigDict(populate_by_name=True)
+
+class MCPPrompt(BaseModel):
+    """Definition of an MCP Prompt."""
+    name: str
+    description: str
+    arguments: List[Dict[str, Any]] = Field(default_factory=list)
+
+class MCPToolCall(BaseModel):
+    """A request to call a tool."""
+    name: str
+    arguments: Dict[str, Any]
+
+class MCPToolResult(BaseModel):
+    """Result of a tool call."""
+    content: List[Dict[str, Any]] # Text or Image content
+    is_error: bool = False
+
+# --- MCP Interfaces ---
+
+class MCPServer(ABC):
+    """
+    Abstract Interface for an MCP Server (provider of tools/resources).
+    """
+    
+    @abstractmethod
+    async def list_tools(self) -> List[MCPToolDefinition]:
+        """List available tools."""
+        pass
+
+    @abstractmethod
+    async def call_tool(self, name: str, arguments: Dict[str, Any]) -> MCPToolResult:
+        """Call a specific tool."""
+        pass
+
+    @abstractmethod
+    async def list_resources(self) -> List[MCPResource]:
+        """List available resources."""
+        pass
+        
+    @abstractmethod
+    async def read_resource(self, uri: str) -> str:
+        """Read a resource content."""
+        pass
+
+    @abstractmethod
+    async def list_prompts(self) -> List[MCPPrompt]:
+        """List available prompts."""
+        pass
+        
+    @abstractmethod
+    async def get_prompt(self, name: str, arguments: Dict[str, Any]) -> str:
+        """Get a prompt context."""
+        pass
+
+class MCPClient(ABC):
+    """
+    Abstract Interface for an MCP Client (consumer of tools/resources).
+    """
+    
+    @abstractmethod
+    async def discover_capabilities(self):
+        """Discover tools and resources from connected servers."""
+        pass
+    
+    @abstractmethod
+    async def call_tool(self, tool_name: str, arguments: Dict[str, Any]) -> Any:
+        """Execute a tool via the protocol."""
+        pass