loom-agent 0.3.2__py3-none-any.whl

loom/memory/hierarchical.py

@@ -0,0 +1,94 @@
+"""
+Hierarchical Memory Implementation
+"""
+
+import time
+from typing import List, Dict, Any, Optional
+
+from loom.interfaces.memory import MemoryInterface, MemoryEntry
+
+class HierarchicalMemory(MemoryInterface):
+    """
+    A simplified 4-tier memory system.
+    
+    Tiers:
+    1. Ephemeral: Tool outputs (not implemented separate storage in this MVP, just tagged)
+    2. Working: Recent N items.
+    3. Session: Full conversation history.
+    4. Long-term: (Stub) Vector interactions.
+    """
+    
+    def __init__(self, session_limit: int = 100, working_limit: int = 5):
+        self.session_limit = session_limit
+        self.working_limit = working_limit
+        
+        self._session: List[MemoryEntry] = []
+        # working memory is a dynamic view or separate buffer? 
+        # In legacy design, it was promoted. Here, let's treat it as "Recent Window" logic for start.
+        
+    async def add(self, role: str, content: str, metadata: Optional[Dict[str, Any]] = None) -> None:
+        """Add to session memory."""
+        # print(f"[DEBUG Memory] Adding {role}: {content[:20]}...")
+        metadata = metadata or {}
+        tier = metadata.get("tier", "session")
+        
+        entry = MemoryEntry(
+            role=role,
+            content=content,
+            timestamp=time.time(),
+            metadata=metadata,
+            tier=tier
+        )
+        
+        self._session.append(entry)
+        
+        # Enforce limits
+        if len(self._session) > self.session_limit:
+            self._session.pop(0) # Simple FIFO
+            
+    async def get_context(self, task: str = "") -> str:
+        """
+        Construct a context string for the Agent.
+        
+        Format:
+        --- Long Term Memory ---
+        (Stub)
+        
+        --- Session History ---
+        User: ...
+        Assistant: ...
+        """
+        # Long term stub
+        long_term = ""
+        
+        # Working/Session view
+        # We perform a simple sliding window for now suitable for LLM Context Window
+        # or return full session if it fits.
+        
+        history_str = []
+        for entry in self._session:
+             history_str.append(f"{entry.role.capitalize()}: {entry.content}")
+             
+        return "\n".join(history_str)
+
+    async def get_recent(self, limit: int = 10) -> List[Dict[str, Any]]:
+        """Get recent raw messages for LLM API."""
+        messages = []
+        for entry in self._session[-limit:]:
+            msg = {"role": entry.role, "content": entry.content}
+
+            # Include tool_calls for assistant messages
+            if entry.role == "assistant" and "tool_calls" in entry.metadata:
+                msg["tool_calls"] = entry.metadata["tool_calls"]
+
+            # Include tool_call_id for tool messages
+            if entry.role == "tool" and "tool_call_id" in entry.metadata:
+                msg["tool_call_id"] = entry.metadata["tool_call_id"]
+                if "tool_name" in entry.metadata:
+                    msg["name"] = entry.metadata["tool_name"]
+
+            messages.append(msg)
+        return messages
+
+    async def clear(self) -> None:
+        self._session.clear()

loom/node/agent.py

@@ -0,0 +1,133 @@
+"""
+Agent Node (Fractal System)
+"""
+
+from typing import Any, Dict, List, Optional
+import uuid
+
+from loom.protocol.cloudevents import CloudEvent
+from loom.node.base import Node
+from loom.node.tool import ToolNode
+from loom.kernel.dispatcher import Dispatcher
+
+from loom.interfaces.llm import LLMProvider
+from loom.infra.llm import MockLLMProvider
+from loom.interfaces.memory import MemoryInterface
+from loom.memory.hierarchical import HierarchicalMemory
+
+class AgentNode(Node):
+    """
+    A Node that acts as an Intelligent Agent (MCP Client).
+    """
+    
+    def __init__(
+        self,
+        node_id: str,
+        dispatcher: Dispatcher,
+        role: str = "Assistant",
+        system_prompt: str = "You are a helpful assistant.",
+        tools: Optional[List[ToolNode]] = None,
+        provider: Optional[LLMProvider] = None,
+        memory: Optional[MemoryInterface] = None
+    ):
+        super().__init__(node_id, dispatcher)
+        self.role = role
+        self.system_prompt = system_prompt
+        self.known_tools = {t.tool_def.name: t for t in tools} if tools else {}
+        # Replaced internal list list with Memory Interface
+        self.memory = memory or HierarchicalMemory()
+        self.provider = provider or MockLLMProvider()
+
+    async def process(self, event: CloudEvent) -> Any:
+        """
+        Agent Loop with Memory:
+        1. Receive Task -> Add to Memory
+        2. Get Context from Memory
+        3. Think (LLM)
+        4. Tool Call -> Add Result to Memory
+        5. Final Response
+        """
+        return await self._execute_loop(event)
+
+    async def _execute_loop(self, event: CloudEvent) -> Any:
+        """
+        Execute the ReAct Loop.
+        """
+        task = event.data.get("task", "") or event.data.get("content", "")
+        max_iterations = event.data.get("max_iterations", 5)
+        
+        # 1. Perceive (Add to Memory)
+        await self.memory.add("user", task)
+        
+        iterations = 0
+        final_response = ""
+        
+        while iterations < max_iterations:
+            iterations += 1
+            
+            # 2. Recall (Get Context)
+            history = await self.memory.get_recent(limit=20)
+            messages = [{"role": "system", "content": self.system_prompt}] + history
+            
+            # 3. Think
+            mcp_tools = [t.tool_def.model_dump() for t in self.known_tools.values()]
+            response = await self.provider.chat(messages, tools=mcp_tools)
+            final_text = response.content
+            
+            # 4. Act (Tool Usage or Final Answer)
+            if response.tool_calls:
+                # Record the "thought" / call intent
+                # ALWAYS store assistant message with tool_calls (even if content is empty)
+                await self.memory.add("assistant", final_text or "", metadata={
+                    "tool_calls": response.tool_calls
+                })
+                
+                # Execute tools (Parallel support possible, here sequential)
+                for tc in response.tool_calls:
+                    tc_name = tc.get("name")
+                    tc_args = tc.get("arguments")
+                    
+                    # Emit thought event
+                    await self.dispatcher.dispatch(CloudEvent.create(
+                        source=self.source_uri,
+                        type="agent.thought",
+                        data={"thought": f"Calling {tc_name}", "tool_call": tc},
+                        traceparent=event.traceparent
+                    ))
+                    
+                    target_tool = self.known_tools.get(tc_name)
+                    
+                    if target_tool:
+                        tool_event = CloudEvent.create(
+                            source=self.source_uri,
+                            type="node.request",
+                            data={"arguments": tc_args},
+                            subject=target_tool.source_uri,
+                            traceparent=event.traceparent
+                        )
+                        
+                        tool_result_evt = await target_tool.process(tool_event)
+                        result_content = tool_result_evt.get("result")
+                        
+                        # Add Result to Memory (Observation)
+                        # We use 'tool' role.
+                        await self.memory.add("tool", str(result_content), metadata={"tool_name": tc_name, "tool_call_id": tc.get("id")})
+                    else:
+                        err_msg = f"Tool {tc_name} not found."
+                        await self.memory.add("system", err_msg)
+                
+                # Loop continues to reflect on tool results
+                continue
+            
+            else:
+                # Final Answer
+                await self.memory.add("assistant", final_text)
+                final_response = final_text
+                break
+        
+        if not final_response and iterations >= max_iterations:
+             final_response = "Error: Maximum iterations reached without final answer."
+             await self.memory.add("system", final_response)
+             
+        return {"response": final_response, "iterations": iterations}
+

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.
+        """
+        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:
+            # Cleanup subscription? 
+            # Current bus implementation doesn't support unsubscribe easily, 
+            # but in-memory transport might accumulate handlers.
+            # TODO: Add unsubscribe to Transport Protocol to prevent leaks.
+            pass
+
+
+    @abstractmethod
+    async def process(self, event: CloudEvent) -> Any:
+        """Core logic."""
+        pass

loom/node/crew.py

@@ -0,0 +1,103 @@
+"""
+Crew Node (Orchestrator)
+"""
+
+from typing import Any, List, Literal
+
+from loom.protocol.cloudevents import CloudEvent
+from loom.node.agent import AgentNode
+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).
+    """
+    
+    def __init__(
+        self,
+        node_id: str,
+        dispatcher: Dispatcher,
+        agents: List[AgentNode],
+        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
+        """
+        current_input = task
+        chain_results = []
+        
+        for agent in self.agents:
+            # 1. Create Event for Agent
+            event = CloudEvent.create(
+                source=self.source_uri,
+                type="node.request",
+                data={"task": current_input},
+                subject=agent.source_uri,
+                traceparent=traceparent
+            )
+            
+            # 2. Invoke (Directly for MVP sync flow, see AgentNode discussion)
+            try:
+                result = await agent.process(event)
+            except Exception as e:
+                # Robustness: Capture error but don't crash chain immediately?
+                # Or abort?
+                # For now, we abort but return error struct.
+                return {
+                    "error": f"Agent {agent.node_id} failed: {str(e)}",
+                    "trace": chain_results
+                }
+            
+            # 3. Process output
+            response = result.get("response", "")
+            
+            # Sanitization (Fractal Metabolism)
+            # Limit the bubble-up context to ~200 chars or reasonable token limit per agent to prevent pollution
+            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
+            })
+            
+            # 4. Pass to next
+            # We pass the full output to the immediate next strictly?
+            # Or do we pass the accumulated context? 
+            # In "Sequential", A's output is B's input.
+            # If A outputs 5000 tokens, B is overwhelmed.
+            # So passing sanitized response is better for long chains unless full data needed.
+            # But "task" usually implies specific instruction. 
+            # If sequential is "Refine this artifact", we need full artifact.
+            # If sequential is "Research -> Planner", we need summary.
+            
+            # Design choice: For generic Crew, we pass full output (trusting agent to handle it or memory to metabolize it).
+            # BUT the return value of THIS CrewNode to its parent should be sanitized or structured.
+            
+            current_input = response
+            
+        return {
+            "final_output": current_input,
+            "trace": chain_results
+        }

loom/node/router.py

@@ -0,0 +1,68 @@
+"""
+Router Node (Attention Mechanism)
+"""
+
+from typing import Any, List, Dict
+from loom.protocol.cloudevents import CloudEvent
+from loom.node.base import Node
+from loom.node.agent import AgentNode
+from loom.kernel.dispatcher import Dispatcher
+from loom.interfaces.llm import LLMProvider
+
+class AttentionRouter(Node):
+    """
+    Intelligent Router that routes tasks to the best suited Agent based on description.
+    """
+    
+    def __init__(
+        self,
+        node_id: str,
+        dispatcher: Dispatcher,
+        agents: List[AgentNode],
+        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
+        )