loom-agent 0.3.3__py3-none-any.whl

loom/interfaces/memory.py

@@ -0,0 +1,50 @@
+"""
+Memory Interface
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional
+from pydantic import BaseModel, Field
+
+class MemoryEntry(BaseModel):
+    """
+    A single unit of memory.
+    """
+    role: str
+    content: str
+    timestamp: float = Field(default_factory=lambda: __import__("time").time())
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+    tier: str = "session"  # ephemeral, working, session, longterm
+
+from loom.protocol.interfaces import MemoryStrategy
+
+class MemoryInterface(MemoryStrategy, ABC):
+    """
+    Abstract Base Class for Agent Memory.
+    """
+    
+    @abstractmethod
+    async def add(self, role: str, content: str, metadata: Optional[Dict[str, Any]] = None) -> None:
+        """Add a memory entry."""
+        pass
+
+    @abstractmethod
+    async def get_context(self, task: str = "") -> str:
+        """
+        Get full context formatted for the LLM.
+        May involve retrieval relevant to the 'task'.
+        """
+        pass
+        
+    @abstractmethod
+    async def get_recent(self, limit: int = 10) -> List[Dict[str, Any]]:
+        """
+        Get recent memory entries as a list of dicts (role/content).
+        Useful for Chat History.
+        """
+        pass
+
+    @abstractmethod
+    async def clear(self) -> None:
+        """Clear short-term memory."""
+        pass

loom/interfaces/store.py

@@ -0,0 +1,29 @@
+"""
+Event Store Interface
+"""
+
+from abc import ABC, abstractmethod
+from typing import List, Optional, Dict, Any
+
+from loom.protocol.cloudevents import CloudEvent
+
+class EventStore(ABC):
+    """
+    Abstract Interface for Event Persistence.
+    Decouples the Event Bus from the storage mechanism (Memory, Redis, SQL).
+    """
+
+    @abstractmethod
+    async def append(self, event: CloudEvent) -> None:
+        """
+        Persist a single event.
+        """
+        pass
+
+    @abstractmethod
+    async def get_events(self, limit: int = 100, offset: int = 0, **filters) -> List[CloudEvent]:
+        """
+        Retrieve events with optional filtering.
+        Filters can match on standard CloudEvent attributes (source, type, etc.)
+        """
+        pass

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,85 @@
+"""
+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)
+
+    async def unsubscribe(self, topic: str, handler: Callable[[CloudEvent], Awaitable[None]]):
+        """
+        Unregister a handler from a topic.
+
+        FIXED: Added to prevent memory leaks from accumulated handlers.
+        Delegates to transport layer.
+        """
+        await self.transport.unsubscribe(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"
+]
+