loom-agent 0.3.3__py3-none-any.whl

loom/kernel/interceptors/hitl.py

@@ -0,0 +1,51 @@
+"""
+Human-in-the-Loop Interceptor
+"""
+
+import asyncio
+from typing import List, Optional, Any
+from loom.kernel.base_interceptor import Interceptor
+from loom.protocol.cloudevents import CloudEvent
+
+class HITLInterceptor(Interceptor):
+    """
+    Pauses execution for Human Approval on sensitive events.
+    """
+    
+    def __init__(self, patterns: List[str]):
+        """
+        Args:
+            patterns: List of substring matches for Event Type or Subject.
+                      e.g. ["tool.execute/delete_file", "payment"]
+        """
+        self.patterns = patterns
+
+    async def pre_invoke(self, event: CloudEvent) -> Optional[CloudEvent]:
+        # Check simple pattern match
+        identifier = f"{event.type}/{event.subject or ''}"
+        
+        should_pause = any(p in identifier for p in self.patterns)
+        
+        if should_pause:
+            print(f"\n[HITL] ⚠️  STOP! Event requires approval: {identifier}")
+            print(f"       Data: {str(event.data)[:200]}")
+            
+            # This blocks the Dispatcher! 
+            # In a real async web app, this would suspend and wait for an API call (Webhook/Signal).
+            # For this CLI SDK, we use blocking input (in a separate thread if needed, or just sync).
+            # Since standard input() is blocking, it pauses the loop. 
+            # In purely async heavily concurrent apps, use a non-blocking wrapper.
+            # Here: simplistic CLI approach.
+            
+            approval = await asyncio.to_thread(input, "       Approve? (y/N): ")
+            
+            if approval.lower().strip() != "y":
+                print("       ❌ Denied.")
+                return None # Drop event
+            
+            print("       ✅ Approved.")
+            
+        return event
+
+    async def post_invoke(self, event: CloudEvent) -> None:
+        pass

loom/kernel/interceptors/studio.py

@@ -0,0 +1,129 @@
+
+import asyncio
+import json
+import os
+import time
+from typing import Optional, List, Dict, Any
+import logging
+
+try:
+    import websockets
+    from websockets.client import WebSocketClientProtocol
+except ImportError:
+    websockets = None
+    WebSocketClientProtocol = Any
+
+from loom.kernel.base_interceptor import Interceptor
+from loom.protocol.cloudevents import CloudEvent
+
+logger = logging.getLogger(__name__)
+
+class StudioInterceptor(Interceptor):
+    """
+    Studio Interceptor: Captures all events and forwards them to Studio Server.
+
+    Features:
+    - Async non-blocking: Uses asyncio.create_task to avoid blocking main flow.
+    - Optional: Controlled by LOOM_STUDIO_ENABLED environment variable.
+    - Batching: Buffers events and sends in batches to reduce network overhead.
+    """
+
+    def __init__(self, studio_url: str = "ws://localhost:8765", enabled: bool = False):
+        self.studio_url = studio_url
+        self.ws: Optional[WebSocketClientProtocol] = None
+        self.event_buffer: List[CloudEvent] = []
+        self.buffer_size = 10
+        # Priority: Argument > Env Var
+        self.enabled = enabled or os.getenv("LOOM_STUDIO_ENABLED", "false").lower() == "true"
+        self._loop = None
+        
+        if self.enabled and not websockets:
+            logger.warning("LOOM_STUDIO_ENABLED is true but websockets is not installed. Disabling Studio.")
+            self.enabled = False
+
+        if self.enabled:
+             asyncio.create_task(self._ensure_connection())
+
+    async def _ensure_connection(self):
+        """Ensure WebSocket connection is established"""
+        if not self.enabled:
+            return
+
+        if self.ws:
+            try:
+                # Basic check if open
+                if self.ws.state == 1: # Open
+                     return
+            except Exception:
+                pass
+            self.ws = None
+
+        try:
+            # Append /ws/ingest to the base URL if not present
+            url = self.studio_url
+            if not url.endswith("/ws/ingest"):
+                url = f"{url.rstrip('/')}/ws/ingest"
+            
+            # Simple debounce/lock could go here but for now just log
+            print(f"DEBUG: Connecting to {url}") 
+            self.ws = await websockets.connect(url)
+            logger.info(f"Connected to Loom Studio at {url}")
+            print(f"DEBUG: Connected successfully")
+        except Exception as e:
+            # Silent fail to not disrupt agent operation, but log it
+            logger.debug(f"Failed to connect to Studio: {e}") 
+            print(f"DEBUG: Failed to connect: {e}")
+            self.ws = None
+
+    async def pre_invoke(self, event: CloudEvent) -> Optional[CloudEvent]:
+        """Capture event (pre-phase) - 不发送事件，只在 post_invoke 发送以避免重复"""
+        # 不在 pre 阶段发送事件，只在 post 阶段发送完整的事件
+        return event
+
+    async def post_invoke(self, event: CloudEvent) -> None:
+        """Capture event (post-phase) - 只在此阶段发送事件，避免重复"""
+        if self.enabled:
+            enriched_event_data = event.model_dump(mode='json')
+            if "extensions" not in enriched_event_data:
+                enriched_event_data["extensions"] = {}
+                
+            # 标记为 post 阶段（虽然现在只在 post 发送，但保留标记以便将来扩展）
+            enriched_event_data["extensions"]["studio_phase"] = "post"
+            enriched_event_data["extensions"]["studio_timestamp"] = time.time()
+
+            asyncio.create_task(self._send_event_data(enriched_event_data))
+
+    async def _send_event_data(self, event_data: Dict[str, Any]):
+        """Buffer and send event data"""
+        try:
+            self.event_buffer.append(event_data)
+
+            if len(self.event_buffer) >= self.buffer_size:
+                await self._flush_buffer()
+        except Exception as e:
+            logger.error(f"Error in StudioInterceptor: {e}")
+
+    async def _flush_buffer(self):
+        """Flush buffered events to server"""
+        if not self.event_buffer:
+            return
+            
+        # Snapshot and clear immediately to avoid duplicates/race
+        current_batch = list(self.event_buffer)
+        self.event_buffer = []
+
+        await self._ensure_connection()
+
+        if self.ws:
+            try:
+                batch = {
+                    "type": "event_batch",
+                    "events": current_batch
+                }
+                await self.ws.send(json.dumps(batch))
+            except Exception as e:
+                logger.debug(f"Failed to send batch to Studio: {e}")
+                print(f"DEBUG: Failed to send batch: {e}")
+                # Re-queue? For now drop to avoid complexity
+        else:
+             print(f"DEBUG: No connection, dropping batch of {len(current_batch)}")

loom/kernel/interceptors/timeout.py

@@ -0,0 +1,27 @@
+"""
+Standard Kernel Interceptors.
+"""
+
+from typing import Optional
+from loom.protocol.cloudevents import CloudEvent
+from loom.kernel.base_interceptor import Interceptor
+
+class TimeoutInterceptor(Interceptor):
+    """
+    Enforces a timeout on event processing by injecting a deadline constraint.
+    The Dispatcher or Transport is responsible for respecting this constraint.
+    """
+    def __init__(self, default_timeout_sec: float = 30.0):
+        self.default_timeout_sec = default_timeout_sec
+        
+    async def pre_invoke(self, event: CloudEvent) -> Optional[CloudEvent]:
+        # If timeout not already set in extensions, inject it
+        extensions = event.extensions or {}
+        if "timeout" not in extensions:
+            extensions["timeout"] = self.default_timeout_sec
+            event.extensions = extensions
+            
+        return event
+
+    async def post_invoke(self, event: CloudEvent) -> None:
+        pass

loom/kernel/state.py

@@ -0,0 +1,71 @@
+"""
+State Management (Kernel)
+"""
+
+from typing import Any, Dict, List, Optional
+import copy
+
+from loom.protocol.cloudevents import CloudEvent
+from loom.protocol.patch import StatePatch, apply_patch as apply_dict_patch
+
+class StateStore:
+    """
+    Manages the application state tree.
+    Updates state by applying 'state.patch' events.
+    """
+    
+    def __init__(self):
+        self._root: Dict[str, Any] = {}
+        
+    def apply_event(self, event: CloudEvent) -> None:
+        """
+        Update state if event contains patches.
+        Expected event.type = "state.patch"
+        Expected event.data = {"patches": [...]}
+        """
+        if event.type != "state.patch":
+            return
+            
+        patches_data = event.data.get("patches", [])
+        if not patches_data:
+            return
+            
+        for p_data in patches_data:
+            try:
+                patch = StatePatch(**p_data)
+                # Apply strictly to root
+                apply_dict_patch(self._root, patch)
+            except Exception as e:
+                # In a real system, we might want to dead-letter queue this
+                print(f"Failed to apply patch: {e}")
+
+    def get_snapshot(self, path: str = "/") -> Any:
+        """
+        Get a deep copy of the state at a specific path.
+        """
+        if path == "/":
+            return copy.deepcopy(self._root)
+            
+        tokens = [t for t in path.split('/') if t]
+        current = self._root
+        
+        for token in tokens:
+            if isinstance(current, dict):
+                current = current.get(token)
+            elif isinstance(current, list):
+                try:
+                    idx = int(token)
+                    if 0 <= idx < len(current):
+                        current = current[idx]
+                    else:
+                        current = None
+                except ValueError:
+                    current = None
+            
+            if current is None:
+                return None
+                
+        return copy.deepcopy(current)
+
+    def clear(self):
+        self._root = {}

loom/memory/hierarchical.py

@@ -0,0 +1,124 @@
+"""
+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()
+
+    def should_reflect(self, threshold: int = 20) -> bool:
+        """Check if memory needs reflection (session memory exceeds threshold)."""
+        return len(self._session) > threshold
+
+    def get_reflection_candidates(self, count: int = 10) -> List[MemoryEntry]:
+        """Get the oldest 'count' records for summarization."""
+        return self._session[:count]
+
+    async def consolidate(self, summary: str, remove_count: int) -> None:
+        """
+        Consolidate memory:
+        1. Remove the oldest 'remove_count' entries.
+        2. Insert a 'Summary' entry at the beginning (or logically older).
+        """
+        # Remove old entries
+        del self._session[:remove_count]
+        
+        # Create summary entry
+        summary_entry = MemoryEntry(
+            role="system",
+            content=f"[Memory Reflection] Summary of previous conversation:\n{summary}",
+            timestamp=time.time(),
+            metadata={"type": "reflection_summary"},
+            tier="long-term"
+        )
+        
+        # Insert at start
+        self._session.insert(0, summary_entry)
+

loom/node/agent.py

@@ -0,0 +1,252 @@
+"""
+Agent Node (Fractal System)
+"""
+
+from typing import Any, Dict, List, Optional
+from dataclasses import dataclass, field
+import uuid
+
+from loom.protocol.cloudevents import CloudEvent
+from loom.protocol.interfaces import ReflectiveMemoryStrategy
+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
+
+
+@dataclass
+class ReflectionConfig:
+    """
+    Configuration for Memory Reflection (Human Factors Engineering).
+
+    Framework DETECTS when reflection is needed.
+    Developer CONFIGURES how reflection should behave.
+    System EXECUTES the reflection according to config.
+    """
+    threshold: int = 20
+    """Number of entries before reflection is triggered"""
+
+    candidate_count: int = 10
+    """Number of memory entries to include in reflection"""
+
+    remove_count: int = 10
+    """Number of entries to remove after consolidation"""
+
+    prompt_template: str = "Summarize the following conversation segment into a concise knowledge entry:\n\n{history}"
+    """Template for the reflection prompt. {history} will be replaced with actual history."""
+
+    enabled: bool = True
+    """Whether reflection is enabled"""
+
+
+class AgentNode(Node):
+    """
+    A Node that acts as an Intelligent Agent (MCP Client).
+
+    FIXED: Now accepts ReflectionConfig for configurable memory reflection,
+    following Human Factors Engineering principle (developer controls strategy).
+    """
+
+    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,
+        enable_auto_reflection: bool = False,
+        reflection_config: Optional[ReflectionConfig] = 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()
+        self.enable_auto_reflection = enable_auto_reflection
+        # FIXED: Configurable reflection parameters (Human Factors Engineering)
+        self.reflection_config = reflection_config or ReflectionConfig()
+
+    async def _perform_reflection(self) -> None:
+        """
+        Check and perform metabolic memory reflection.
+
+        FIXED: Now uses developer-configured parameters instead of hardcoded values.
+        Framework DETECTS, Developer CONFIGURES, System EXECUTES.
+
+        FIXED: Uses Protocol check instead of isinstance for better abstraction.
+        """
+        # 0. Check if reflection is enabled
+        if not self.reflection_config.enabled:
+            return
+
+        # 1. Check if memory supports reflection (Protocol-First)
+        if not isinstance(self.memory, ReflectiveMemoryStrategy):
+            # Memory doesn't support reflection, skip silently
+            return
+
+        # 2. Check if memory needs reflection (Framework DETECTS)
+        if not self.memory.should_reflect(threshold=self.reflection_config.threshold):
+            return
+
+        # 3. Get candidates (Developer CONFIGURED count)
+        candidates = self.memory.get_reflection_candidates(
+            count=self.reflection_config.candidate_count
+        )
+
+        # 4. Summarize with LLM (Developer CONFIGURED prompt)
+        history_text = "\n".join([f"{e.role}: {e.content}" for e in candidates])
+        prompt = self.reflection_config.prompt_template.format(history=history_text)
+
+        try:
+            # We use a separate call (not affecting main context)
+            response = await self.provider.chat([{"role": "user", "content": prompt}])
+            summary = response.content
+
+            # 5. Consolidate (Developer CONFIGURED remove_count)
+            await self.memory.consolidate(
+                summary,
+                remove_count=self.reflection_config.remove_count
+            )
+
+            # 6. Emit Event
+            await self.dispatcher.dispatch(CloudEvent.create(
+                source=self.source_uri,
+                type="agent.reflection",
+                data={"summary": summary},
+            ))
+        except Exception as e:
+            # Reflection shouldn't crash the agent
+            # FIXED: Should emit event instead of just print
+            error_event = CloudEvent.create(
+                source=self.source_uri,
+                type="agent.reflection.failed",
+                data={"error": str(e)}
+            )
+            await self.dispatcher.dispatch(error_event)
+
+    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
+        """
+        # Hook: Auto Reflection
+        if self.enable_auto_reflection:
+             await self._perform_reflection()
+             
+        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()]
+            
+            # Check for Adaptive Control Overrides (from Interceptors)
+            llm_config = event.extensions.get("llm_config_override")
+            
+            response = await self.provider.chat(messages, tools=mcp_tools, config=llm_config)
+            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:
+                        # FIXED: Use self.call() to invoke through event bus
+                        # This ensures:
+                        # - Tool calls are visible in Studio
+                        # - Interceptors can control tool execution
+                        # - Supports distributed tool nodes
+                        # - Maintains fractal uniformity
+                        try:
+                            tool_result = await self.call(
+                                target_node=target_tool.source_uri,
+                                data={"arguments": tc_args}
+                            )
+
+                            # Extract result content
+                            if isinstance(tool_result, dict):
+                                result_content = tool_result.get("result", str(tool_result))
+                            else:
+                                result_content = str(tool_result)
+
+                            # Add Result to Memory (Observation)
+                            await self.memory.add("tool", str(result_content), metadata={
+                                "tool_name": tc_name,
+                                "tool_call_id": tc.get("id")
+                            })
+                        except Exception as e:
+                            # Tool call failed through event bus
+                            err_msg = f"Tool {tc_name} failed: {str(e)}"
+                            await self.memory.add("system", err_msg)
+                    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)
+             
+        # Hook: Check reflection after new memories added
+        if self.enable_auto_reflection:
+             await self._perform_reflection()
+
+        return {"response": final_response, "iterations": iterations}
+