loom-agent 0.3.2__py3-none-any.whl

loom/interfaces/transport.py

@@ -0,0 +1,35 @@
+"""
+Transport Interface (Connectivity Layer)
+"""
+
+from abc import ABC, abstractmethod
+from typing import Callable, Awaitable
+from loom.protocol.cloudevents import CloudEvent
+
+EventHandler = Callable[[CloudEvent], Awaitable[None]]
+
+class Transport(ABC):
+    """
+    Abstract Base Class for Event Transport.
+    Responsible for delivering events between components (local or remote).
+    """
+
+    @abstractmethod
+    async def connect(self) -> None:
+        """Establish connection to the transport layer."""
+        pass
+
+    @abstractmethod
+    async def disconnect(self) -> None:
+        """Close connection."""
+        pass
+
+    @abstractmethod
+    async def publish(self, topic: str, event: CloudEvent) -> None:
+        """Publish an event to a specific topic."""
+        pass
+
+    @abstractmethod
+    async def subscribe(self, topic: str, handler: EventHandler) -> None:
+        """Subscribe to a topic."""
+        pass

loom/kernel/base_interceptor.py

@@ -0,0 +1,97 @@
+"""
+Middleware Interceptors (Kernel)
+"""
+
+from abc import ABC, abstractmethod
+from typing import Optional, Set
+import uuid
+
+from loom.protocol.cloudevents import CloudEvent
+
+class Interceptor(ABC):
+    """
+    Abstract Base Class for Interceptors.
+    Allows AOP-style cross-cutting concerns (Auth, Logging, Budget).
+    """
+
+    @abstractmethod
+    async def pre_invoke(self, event: CloudEvent) -> Optional[CloudEvent]:
+        """
+        Called before the event is dispatched to a handler.
+        Return the event (modified or not) to proceed.
+        Return None to halt execution (block/filter).
+        """
+        pass
+
+    @abstractmethod
+    async def post_invoke(self, event: CloudEvent) -> None:
+        """
+        Called after the event has been processed.
+        """
+        pass
+
+class BudgetInterceptor(Interceptor):
+    """
+    Simulated Token Budget Interceptor.
+    """
+    def __init__(self, max_tokens: int = 100000):
+        self.max_tokens = max_tokens
+        self.used_tokens = 0
+        
+    async def pre_invoke(self, event: CloudEvent) -> Optional[CloudEvent]:
+        # Check if event carries token cost estimation
+        # This is a simplification.
+        if "token_usage" in event.data:
+            cost = event.data["token_usage"].get("estimated", 0)
+            if self.used_tokens + cost > self.max_tokens:
+                print(f"⚠️ Budget exceeded: {self.used_tokens}/{self.max_tokens}")
+                return None
+        return event
+
+    async def post_invoke(self, event: CloudEvent) -> None:
+        if "token_usage" in event.data:
+            actual = event.data["token_usage"].get("actual", 0)
+            self.used_tokens += actual
+
+class TracingInterceptor(Interceptor):
+    """
+    Injects Distributed Tracing Context (W3C Trace Parent).
+    """
+    async def pre_invoke(self, event: CloudEvent) -> Optional[CloudEvent]:
+        if not event.traceparent:
+            # Generate new trace
+            trace_id = uuid.uuid4().hex
+            span_id = uuid.uuid4().hex[:16]
+            event.traceparent = f"00-{trace_id}-{span_id}-01"
+        return event
+
+    async def post_invoke(self, event: CloudEvent) -> None:
+        pass
+
+class AuthInterceptor(Interceptor):
+    """
+    Basic Source Verification.
+    """
+    def __init__(self, allowed_prefixes: Set[str]):
+        self.allowed_prefixes = allowed_prefixes
+        
+    async def pre_invoke(self, event: CloudEvent) -> Optional[CloudEvent]:
+        if not event.source:
+             return None
+             
+        # Check simplified prefix
+        # e.g. source="/agent/foo", prefix="agent"
+        # source="agent", prefix="agent"
+        parts = event.source.strip("/").split("/")
+        if not parts:
+            return None
+            
+        prefix = parts[0]
+        if prefix not in self.allowed_prefixes:
+            print(f"🚫 Unauthorized source: {event.source}")
+            return None
+            
+        return event
+
+    async def post_invoke(self, event: CloudEvent) -> None:
+        pass

loom/kernel/bus.py

@@ -0,0 +1,76 @@
+"""
+Universal Event Bus (Kernel)
+"""
+
+import asyncio
+from typing import Dict, List, Callable, Awaitable, Optional, Any
+
+from loom.protocol.cloudevents import CloudEvent
+from loom.interfaces.store import EventStore
+from loom.infra.store import InMemoryEventStore
+from loom.interfaces.transport import Transport, EventHandler
+from loom.infra.transport.memory import InMemoryTransport
+
+class UniversalEventBus:
+    """
+    Universal Event Bus based on Event Sourcing.
+    Delegates routing to a Transport layer.
+    """
+    
+    def __init__(self, store: EventStore = None, transport: Transport = None):
+        self.store = store or InMemoryEventStore()
+        self.transport = transport or InMemoryTransport()
+        
+    async def connect(self):
+        """Connect the underlying transport."""
+        await self.transport.connect()
+        
+    async def disconnect(self):
+        """Disconnect the underlying transport."""
+        await self.transport.disconnect()
+
+    async def publish(self, event: CloudEvent) -> None:
+        """
+        Publish an event to the bus.
+        1. Persist to store.
+        2. Route to subscribers via Transport.
+        """
+        # 1. Persist
+        await self.store.append(event)
+        
+        # 2. Route via Transport
+        topic = self._get_topic(event)
+        
+        # Ensure connected
+        # (Optimistically connect. In prod, connect() called at startup app.start())
+        await self.transport.connect()
+        
+        await self.transport.publish(topic, event)
+
+    async def subscribe(self, topic: str, handler: Callable[[CloudEvent], Awaitable[None]]):
+        """Register a handler for a topic."""
+        # optimistic connect
+        await self.transport.connect()
+        await self.transport.subscribe(topic, handler)
+
+    def _get_topic(self, event: CloudEvent) -> str:
+        """Construct topic string from event."""
+        # Special routing for requests: use subject (target) if present
+        if event.subject and (event.type == "node.request" or event.type == "node.call"):
+            safe_subject = event.subject.strip("/")
+            return f"{event.type}/{safe_subject}"
+            
+        # Default: route by source (Origin)
+        safe_source = event.source.strip("/")
+        return f"{event.type}/{safe_source}"
+
+    async def get_events(self) -> List[CloudEvent]:
+        """Return all events in the store."""
+        return await self.store.get_events(limit=1000)
+
+    async def clear(self):
+        """Clear state (for testing)."""
+        if hasattr(self.store, "clear"):
+            self.store.clear()
+        
+        await self.transport.disconnect()

loom/kernel/dispatcher.py

@@ -0,0 +1,58 @@
+"""
+Event Dispatcher (Kernel)
+"""
+
+from typing import List, Any
+
+from loom.protocol.cloudevents import CloudEvent
+from loom.kernel.bus import UniversalEventBus
+from loom.kernel.base_interceptor import Interceptor
+
+class Dispatcher:
+    """
+    Central dispatch mechanism.
+    1. Runs Interceptor Chain (Pre-invoke).
+    2. Publishes to Bus.
+    3. Runs Interceptor Chain (Post-invoke).
+    """
+    
+    def __init__(self, bus: UniversalEventBus):
+        self.bus = bus
+        self.interceptors: List[Interceptor] = []
+        
+    def add_interceptor(self, interceptor: Interceptor) -> None:
+        """Add an interceptor to the chain."""
+        self.interceptors.append(interceptor)
+        
+    async def dispatch(self, event: CloudEvent) -> None:
+        """
+        Dispatch an event through the system.
+        """
+        # 1. Pre-invoke Interceptors
+        current_event = event
+        for interceptor in self.interceptors:
+            current_event = await interceptor.pre_invoke(current_event)
+            if current_event is None:
+                # Blocked by interceptor
+                return
+
+        # 2. Publish to Bus (Routing & Persistence)
+        import asyncio
+        timeout = 30.0 # Default fallback
+        if current_event.extensions and "timeout" in current_event.extensions:
+            try:
+                timeout = float(current_event.extensions["timeout"])
+            except:
+                pass
+                
+        try:
+             await asyncio.wait_for(self.bus.publish(current_event), timeout=timeout)
+        except asyncio.TimeoutError:
+             print(f"timeout dispatching event {current_event.id}")
+             # We might want to raise or handle graceful failure
+             # Raising allows the caller (e.g. app.run) to catch it
+             raise
+        
+        # 3. Post-invoke Interceptors (in reverse order)
+        for interceptor in reversed(self.interceptors):
+            await interceptor.post_invoke(current_event)

loom/kernel/interceptors/__init__.py

@@ -0,0 +1,14 @@
+from .timeout import TimeoutInterceptor
+from .budget import BudgetInterceptor
+from .depth import DepthInterceptor
+from .hitl import HITLInterceptor
+from loom.kernel.base_interceptor import TracingInterceptor
+
+__all__ = [
+    "TimeoutInterceptor",
+    "BudgetInterceptor",
+    "DepthInterceptor",
+    "HITLInterceptor",
+    "TracingInterceptor"
+]
+

loom/kernel/interceptors/budget.py

@@ -0,0 +1,60 @@
+"""
+Budget Interceptor
+"""
+
+from typing import Dict, Any, Optional
+from loom.kernel.base_interceptor import Interceptor
+from loom.protocol.cloudevents import CloudEvent
+
+class BudgetExceededError(Exception):
+    pass
+
+class BudgetInterceptor(Interceptor):
+    """
+    Controls resource usage (tokens/cost) per agent/node.
+    """
+    
+    def __init__(self, max_tokens: int = 100000):
+        self.max_tokens = max_tokens
+        # Usage tracking: {node_id: tokens_used}
+        self._usage: Dict[str, int] = {} 
+
+    async def pre_invoke(self, event: CloudEvent) -> Optional[CloudEvent]:
+        # Check if this is a request that consumes budget?
+        # Typically we check the SOURCE (Who is asking).
+        # If Agent A asks Tool B, Agent A is spending budget?
+        # Or if Agent A sends "node.response", it used tokens to generate it.
+        
+        # Policy: Check usage of the SOURCE node.
+        # If usage > max, block.
+        
+        node_id = event.source.split("/")[-1]
+        current_usage = self._usage.get(node_id, 0)
+        
+        if current_usage >= self.max_tokens:
+            raise BudgetExceededError(
+                f"Node {node_id} exceeded token budget: {current_usage}/{self.max_tokens}"
+            )
+            
+        return event
+
+    async def post_invoke(self, event: CloudEvent) -> None:
+        # Update usage based on event type or result
+        # For LLM-based agents, we usually get usage in the "agent.thought" or "node.response".
+        # In this demo system, we don't have real token counts from MockLLM.
+        # We'll heuristic: 1 char = 1 token for demo.
+        
+        node_id = event.source.split("/")[-1]
+        
+        tokens = 0
+        if event.data and isinstance(event.data, dict):
+            # If explicit usage field exists
+            if "usage" in event.data:
+                 tokens = event.data["usage"].get("total_tokens", 0)
+            else:
+                 # Heuristic
+                 content = str(event.data.get("thought", "") or event.data.get("result", "") or "")
+                 tokens = len(content) // 4 # Approx
+        
+        if tokens > 0:
+            self._usage[node_id] = self._usage.get(node_id, 0) + tokens

loom/kernel/interceptors/depth.py

@@ -0,0 +1,45 @@
+"""
+Depth Interceptor
+"""
+
+from typing import Optional, Any
+from loom.kernel.base_interceptor import Interceptor
+from loom.protocol.cloudevents import CloudEvent
+
+class RecursionLimitExceededError(Exception):
+    pass
+
+class DepthInterceptor(Interceptor):
+    """
+    Prevents infinite fractal recursion.
+    """
+    
+    def __init__(self, max_depth: int = 5):
+        self.max_depth = max_depth
+
+    async def pre_invoke(self, event: CloudEvent) -> Optional[CloudEvent]:
+        # We need to know the current depth.
+        # CloudEvents 1.0 doesn't have a standard depth field.
+        # We assume it is propagated in extension attribute `depth` or inside `tracestate`.
+        
+        # If it's a new request from User, depth is 0.
+        # If it's a sub-request, parent should have incremented it.
+        
+        # But Interceptor is on the Sender side (Dispatcher)? 
+        # Yes, Dispatcher is shared or per-node.
+        # If Dispatcher is centralized (LoomApp), it intercepts ALL events.
+        
+        # We check `event.extensions`.
+        current_depth = int(getattr(event, "depth", 0) or 0)
+        
+        if current_depth > self.max_depth:
+             raise RecursionLimitExceededError(f"Max recursion depth {self.max_depth} exceeded.")
+        
+        # When an Agent receives an event and sends a NEW event (Tool Call), 
+        # the Agent is responsible for correct propagation (depth+1).
+        # This interceptor essentially Gates it.
+        
+        return event
+
+    async def post_invoke(self, event: CloudEvent) -> None:
+        pass

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,137 @@
+
+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)"""
+        if self.enabled:
+            enriched_event_data = event.model_dump(mode='json')
+            if "extensions" not in enriched_event_data:
+                enriched_event_data["extensions"] = {}
+                
+            enriched_event_data["extensions"]["studio_phase"] = "pre"
+            enriched_event_data["extensions"]["studio_timestamp"] = time.time()
+
+            asyncio.create_task(self._send_event_data(enriched_event_data))
+
+        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"] = {}
+                
+            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 = {}