loom-agent 0.3.2__py3-none-any.whl

loom/config/tool.py

@@ -0,0 +1,63 @@
+"""
+Tool Configuration & Factory
+"""
+
+import importlib
+import os
+from typing import Dict, Any, Optional, Callable
+from pydantic import BaseModel, Field
+
+from loom.node.tool import ToolNode
+from loom.protocol.mcp import MCPToolDefinition
+from loom.kernel.dispatcher import Dispatcher
+
+class ToolConfig(BaseModel):
+    """
+    Configuration for a Tool.
+    """
+    name: str
+    description: str = ""
+    python_path: str = Field(..., description="Dot-path to the python function e.g. 'my_pkg.tools.search'")
+    parameters: Dict[str, Any] = Field(default_factory=dict, description="Input schema properties")
+    env_vars: Dict[str, str] = Field(default_factory=dict)
+
+class ToolFactory:
+    """
+    Factory to load valid ToolConfigs into ToolNodes.
+    """
+    
+    @staticmethod
+    def create_node(
+        config: ToolConfig, 
+        node_id: str, 
+        dispatcher: Dispatcher
+    ) -> ToolNode:
+        # 1. Load function
+        module_name, func_name = config.python_path.rsplit(".", 1)
+        try:
+            mod = importlib.import_module(module_name)
+            func = getattr(mod, func_name)
+        except (ImportError, AttributeError) as e:
+            raise ValueError(f"Could not load tool function {config.python_path}: {e}")
+
+        # 2. Apply Env Vars
+        for k, v in config.env_vars.items():
+            os.environ[k] = v
+            
+        # 3. Create Definition
+        tool_def = MCPToolDefinition(
+            name=config.name,
+            description=config.description,
+            inputSchema={
+                "type": "object", 
+                "properties": config.parameters
+            }
+        )
+        
+        # 4. Create Node
+        return ToolNode(
+            node_id=node_id,
+            dispatcher=dispatcher,
+            tool_def=tool_def,
+            func=func
+        )

loom/infra/llm.py

@@ -0,0 +1,43 @@
+"""
+Mock LLM Provider for Testing
+"""
+
+from typing import List, Dict, Any, AsyncIterator, Optional
+from loom.interfaces.llm import LLMProvider, LLMResponse
+
+class MockLLMProvider(LLMProvider):
+    """
+    A Mock Provider that returns canned responses.
+    Useful for unit testing and demos without API keys.
+    """
+    
+    async def chat(
+        self, 
+        messages: List[Dict[str, Any]], 
+        tools: Optional[List[Dict[str, Any]]] = None
+    ) -> LLMResponse:
+        last_msg = messages[-1]["content"].lower()
+        
+        # Simple keywords
+        if "search" in last_msg:
+            # Simulate Tool Call
+            query = last_msg.replace("search", "").strip() or "fractal"
+            return LLMResponse(
+                content="",
+                tool_calls=[{
+                    "name": "search",
+                    "arguments": {"query": query},
+                    "id": "call_mock_123"
+                }]
+            )
+            
+        return LLMResponse(content=f"Mock response to: {last_msg}")
+
+    async def stream_chat(
+        self,
+        messages: List[Dict[str, Any]],
+        tools: Optional[List[Dict[str, Any]]] = None
+    ) -> AsyncIterator[str]:
+        yield "Mock "
+        yield "stream "
+        yield "response."

loom/infra/logging.py

@@ -0,0 +1,42 @@
+"""
+Structured Logging Configuration.
+"""
+
+import logging
+import sys
+import structlog
+from typing import Any
+
+def configure_logging(log_level: str = "INFO", json_format: bool = False) -> None:
+    """
+    Configure standard logging and structlog.
+    """
+    level = getattr(logging, log_level.upper(), logging.INFO)
+    
+    # Configure processors
+    processors = [
+        structlog.contextvars.merge_contextvars,
+        structlog.processors.add_log_level,
+        structlog.processors.StackInfoRenderer(),
+        structlog.dev.set_exc_info,
+        structlog.processors.TimeStamper(fmt="iso"),
+    ]
+    
+    if json_format:
+        processors.append(structlog.processors.JSONRenderer())
+    else:
+        processors.append(structlog.dev.ConsoleRenderer(colors=True))
+        
+    structlog.configure(
+        processors=processors,
+        wrapper_class=structlog.make_filtering_bound_logger(level),
+        context_class=dict,
+        logger_factory=structlog.PrintLoggerFactory(),
+        cache_logger_on_first_use=True
+    )
+
+def get_logger(name: str) -> Any:
+    """
+    Get a structured logger.
+    """
+    return structlog.get_logger(name)

loom/infra/store.py

@@ -0,0 +1,39 @@
+"""
+In-Memory Event Store Implementation
+"""
+
+from typing import List, Any
+from loom.interfaces.store import EventStore
+from loom.protocol.cloudevents import CloudEvent
+
+class InMemoryEventStore(EventStore):
+    """
+    Simple in-memory list storage for events.
+    Useful for testing and local demos.
+    """
+    
+    def __init__(self):
+        self._storage: List[CloudEvent] = []
+
+    async def append(self, event: CloudEvent) -> None:
+        self._storage.append(event)
+
+    async def get_events(self, limit: int = 100, offset: int = 0, **filters) -> List[CloudEvent]:
+        """
+        Naive implementation of filtering.
+        """
+        filtered = self._storage
+        
+        # Apply filters
+        # e.g. get_events(source="/agent/a")
+        if filters:
+            filtered = [
+                e for e in filtered 
+                if all(getattr(e, k, None) == v for k, v in filters.items())
+            ]
+            
+        # Apply pagination
+        return filtered[offset : offset + limit]
+        
+    def clear(self):
+        self._storage.clear()

loom/infra/transport/memory.py

@@ -0,0 +1,85 @@
+
+import asyncio
+from typing import Dict, List, Set
+from collections import defaultdict
+import logging
+
+from loom.interfaces.transport import Transport, EventHandler
+from loom.protocol.cloudevents import CloudEvent
+
+logger = logging.getLogger(__name__)
+
+class InMemoryTransport(Transport):
+    """
+    In-memory transport implementation using asyncio.Queue/Event.
+    Default for local development.
+    """
+
+    def __init__(self):
+        self._connected = False
+        self._handlers: Dict[str, List[EventHandler]] = defaultdict(list)
+        # For wildcard support: "node.request/*" -> [handler1, handler2]
+        self._wildcard_handlers: Dict[str, List[EventHandler]] = defaultdict(list)
+
+    async def connect(self) -> None:
+        self._connected = True
+        logger.info("InMemoryTransport connected")
+
+    async def disconnect(self) -> None:
+        self._connected = False
+        self._handlers.clear()
+        self._wildcard_handlers.clear()
+        logger.info("InMemoryTransport disconnected")
+
+    async def publish(self, topic: str, event: CloudEvent) -> None:
+        if not self._connected:
+             logger.warning("InMemoryTransport not connected, dropping event")
+             return
+
+        # Direct dispatch to handlers
+        await self._dispatch(topic, event)
+
+    async def subscribe(self, topic: str, handler: EventHandler) -> None:
+        if "*" in topic:
+            self._wildcard_handlers[topic].append(handler)
+        else:
+            self._handlers[topic].append(handler)
+
+    async def _dispatch(self, topic: str, event: CloudEvent) -> None:
+        targets: Set[EventHandler] = set()
+
+        # 1. Exact match
+        if topic in self._handlers:
+            targets.update(self._handlers[topic])
+
+        # 2. Wildcard match (Simple prefix/suffix matching)
+        for pattern, handlers in self._wildcard_handlers.items():
+            if self._match(topic, pattern):
+                targets.update(handlers)
+
+        # 3. Execute handlers
+        for handler in targets:
+            try:
+                # Fire and forget / await
+                # Since Bus expects us to be async, we await.
+                # But handlers might be slow, so we should spawn tasks?
+                # For in-memory bus, typically we want some concurrency.
+                asyncio.create_task(self._safe_exec(handler, event))
+            except Exception as e:
+                 logger.error(f"Error dispatching to handler: {e}")
+
+    async def _safe_exec(self, handler: EventHandler, event: CloudEvent):
+        try:
+             await handler(event)
+        except Exception as e:
+             logger.error(f"Handler failed: {e}")
+
+    def _match(self, topic: str, pattern: str) -> bool:
+        # Simple glob matching
+        if pattern == "*":
+            return True
+        if pattern.endswith("*"):
+            return topic.startswith(pattern[:-1])
+        if pattern.startswith("*"):
+            return topic.endswith(pattern[1:])
+        return topic == pattern

loom/infra/transport/nats.py

@@ -0,0 +1,141 @@
+
+import asyncio
+import logging
+from typing import Dict, List, Optional
+try:
+    import nats
+    from nats.aio.client import Client as NATSClient
+    from nats.js import JetStreamContext
+except ImportError:
+    nats = None
+    NATSClient = None # type: ignore
+    JetStreamContext = None # type: ignore
+
+from loom.interfaces.transport import Transport, EventHandler
+from loom.protocol.cloudevents import CloudEvent
+
+logger = logging.getLogger(__name__)
+
+class NATSTransport(Transport):
+    """
+    NATS Transport Implementation.
+    Supports Core NATS and JetStream (optional).
+    Requires 'nats-py' package.
+    """
+
+    def __init__(
+        self,
+        servers: List[str] = ["nats://localhost:4222"],
+        use_jetstream: bool = False,
+        stream_name: str = "LOOM_EVENTS",
+    ):
+        if not nats:
+            raise ImportError("nats-py package is required for NATSTransport. Install with 'pip install nats-py'")
+
+        self.servers = servers
+        self.use_jetstream = use_jetstream
+        self.stream_name = stream_name
+        
+        self.nc: Optional[NATSClient] = None
+        self.js: Optional[JetStreamContext] = None
+        self._handlers: Dict[str, List[EventHandler]] = {}
+        self._subscriptions: List = [] 
+        self._connected = False
+
+    async def connect(self) -> None:
+        try:
+            self.nc = await nats.connect(servers=self.servers)
+            
+            if self.use_jetstream:
+                self.js = self.nc.jetstream()
+                # Create stream if not exists is best effort or explicit setup
+                # Here we assume stream might be managed externally or auto-created
+                try:
+                    await self.js.add_stream(name=self.stream_name, subjects=["loom.>"])
+                except Exception as e:
+                    logger.debug(f"Stream creation check: {e}")
+
+            self._connected = True
+            logger.info(f"NATSTransport connected to {self.servers}")
+        except Exception as e:
+            logger.error(f"NATS connection failed: {e}")
+            raise
+
+    async def disconnect(self) -> None:
+        self._connected = False
+        
+        for sub in self._subscriptions:
+             try:
+                 await sub.unsubscribe()
+             except Exception:
+                 pass
+        
+        if self.nc:
+            await self.nc.close()
+
+        logger.info("NATSTransport disconnected")
+
+    async def publish(self, topic: str, event: CloudEvent) -> None:
+        if not self._connected:
+             raise RuntimeError("NATSTransport not connected")
+
+        # NATS Subject: loom.{topic} (replace / with .)
+        subject = self._to_subject(topic)
+        payload = event.model_dump_json().encode()
+
+        if self.use_jetstream and self.js:
+            await self.js.publish(subject, payload)
+        else:
+            await self.nc.publish(subject, payload)
+
+    async def subscribe(self, topic: str, handler: EventHandler) -> None:
+        if not self._connected:
+             raise RuntimeError("NATSTransport not connected")
+
+        # Normalize subject for wildcard
+        subject = self._to_subject(topic)
+        
+        # NATS wildcards: * (one token), > (tail)
+        # Loom wildcards: * (usually suffix)
+        # If topic ends with *, replace with >
+        if subject.endswith(".*"):
+            subject = subject[:-2] + ".>"
+
+        if topic not in self._handlers:
+            self._handlers[topic] = []
+            
+            async def cb(msg):
+                try:
+                    data = msg.data.decode()
+                    event = CloudEvent.model_validate_json(data)
+                    # How to map back to specific handlers?
+                    # We invoke all handlers for this subscription
+                    handlers = self._handlers.get(topic, [])
+                    for h in handlers:
+                         asyncio.create_task(self._safe_exec(h, event))
+                except Exception as e:
+                    logger.error(f"Error handling NATS message: {e}")
+
+            if self.use_jetstream and self.js:
+                # Durable consumer? For now, ephemeral to match interface
+                sub = await self.js.subscribe(subject, cb=cb)
+            else:
+                sub = await self.nc.subscribe(subject, cb=cb)
+            
+            self._subscriptions.append(sub)
+
+        self._handlers[topic].append(handler)
+        logger.debug(f"Subscribed to {subject}")
+
+    async def _safe_exec(self, handler: EventHandler, event: CloudEvent):
+        try:
+             await handler(event)
+        except Exception as e:
+             logger.error(f"Handler failed: {e}")
+
+    def _to_subject(self, topic: str) -> str:
+        # Replace / with . 
+        # e.g. node.request/agent -> node.request.agent
+        # loom prefix
+        safe_topic = topic.replace("/", ".")
+        return f"loom.{safe_topic}"

loom/infra/transport/redis.py

@@ -0,0 +1,140 @@
+
+import asyncio
+import json
+import logging
+from typing import Dict, List, Optional
+try:
+    import redis.asyncio as aioredis
+except ImportError:
+    aioredis = None
+
+from loom.interfaces.transport import Transport, EventHandler
+from loom.protocol.cloudevents import CloudEvent
+
+logger = logging.getLogger(__name__)
+
+class RedisTransport(Transport):
+    """
+    Redis Pub/Sub Transport.
+    Requires 'redis' package.
+    """
+
+    def __init__(self, redis_url: str = "redis://localhost:6379"):
+        if not aioredis:
+            raise ImportError("redis package is required for RedisTransport. Install with 'pip install redis'")
+        
+        self.redis_url = redis_url
+        self.redis: Optional[aioredis.Redis] = None
+        self.pubsub: Optional[aioredis.client.PubSub] = None
+        self._handlers: Dict[str, List[EventHandler]] = {}
+        self._connected = False
+        self._listen_task: Optional[asyncio.Task] = None
+
+    async def connect(self) -> None:
+        try:
+            self.redis = aioredis.from_url(self.redis_url, decode_responses=True)
+            await self.redis.ping()
+            self.pubsub = self.redis.pubsub()
+            self._connected = True
+            
+            # Start listener loop
+            self._listen_task = asyncio.create_task(self._listener())
+            logger.info(f"RedisTransport connected to {self.redis_url}")
+        except Exception as e:
+            logger.error(f"Redis connection failed: {e}")
+            raise
+
+    async def disconnect(self) -> None:
+        self._connected = False
+        if self._listen_task:
+            self._listen_task.cancel()
+            try:
+                await self._listen_task
+            except asyncio.CancelledError:
+                pass
+        
+        if self.pubsub:
+            await self.pubsub.close()
+        
+        if self.redis:
+            await self.redis.close()
+        
+        logger.info("RedisTransport disconnected")
+
+    async def publish(self, topic: str, event: CloudEvent) -> None:
+        if not self._connected:
+            raise RuntimeError("RedisTransport not connected")
+        
+        # Redis channel convention: loom.{topic}
+        channel = self._to_channel(topic)
+        payload = event.model_dump_json()
+        await self.redis.publish(channel, payload)
+
+    async def subscribe(self, topic: str, handler: EventHandler) -> None:
+        if not self._connected:
+            raise RuntimeError("RedisTransport not connected")
+
+        # Map loom topic to redis channel pattern
+        channel = self._to_channel(topic)
+        
+        if topic not in self._handlers:
+            self._handlers[topic] = []
+            # Subscribe in Redis
+            await self.pubsub.psubscribe(channel)
+            
+        self._handlers[topic].append(handler)
+        logger.debug(f"Subscribed to {channel}")
+
+    async def _listener(self):
+        try:
+            async for message in self.pubsub.listen():
+                if message["type"] == "pmessage":
+                    channel = message["channel"]
+                    data = message["data"]
+                    await self._handle_message(channel, data)
+        except asyncio.CancelledError:
+            pass
+        except Exception as e:
+            logger.error(f"Redis listener error: {e}")
+
+    async def _handle_message(self, channel: str, data: str):
+        # Convert redis channel back to topic? 
+        # Since we use psubscribe, we matched.
+        # But we need to find which handlers to invoke.
+        # Actually pattern matching is done by Redis.
+        # But our internal registry matches by topic.
+        
+        # Simplification: We iterate our topic patterns to find match?
+        # Or we assume channel == _to_channel(topic)
+        # But wildcard * in topic maps to * in redis.
+        
+        try:
+            event = CloudEvent.model_validate_json(data)
+            
+            # Dispatch to all matching local handlers
+            # This is slightly inefficient if we have many patterns, but robust.
+            for topic, handlers in self._handlers.items():
+                if self._match(channel, self._to_channel(topic)):
+                    for handler in handlers:
+                        asyncio.create_task(self._safe_exec(handler, event))
+        except Exception as e:
+            logger.error(f"Failed to handle Redis message: {e}")
+
+    async def _safe_exec(self, handler: EventHandler, event: CloudEvent):
+        try:
+             await handler(event)
+        except Exception as e:
+             logger.error(f"Handler failed: {e}")
+
+    def _to_channel(self, topic: str) -> str:
+        # loom.topic.sub
+        # If topic has /, replace with . ?
+        # Standard: topic is dot separated usually? 
+        # Loom uses "node.request" etc.
+        # If topic has *, it is wildcard.
+        return f"loom.{topic}"
+
+    def _match(self, channel: str, pattern: str) -> bool:
+        # Redis-style glob matching implemented in Python for dispatch
+        import fnmatch
+        return fnmatch.fnmatch(channel, pattern)

loom/interfaces/llm.py

@@ -0,0 +1,44 @@
+"""
+LLM Provider Interface
+"""
+
+from abc import ABC, abstractmethod
+from typing import List, Dict, Any, AsyncIterator, Optional
+from pydantic import BaseModel
+
+class LLMResponse(BaseModel):
+    """
+    Standardized response from an LLM.
+    """
+    content: str
+    tool_calls: List[Dict[str, Any]] = []
+    token_usage: Optional[Dict[str, int]] = None
+    
+from loom.protocol.interfaces import LLMProviderProtocol
+
+class LLMProvider(LLMProviderProtocol, ABC):
+    """
+    Abstract Interface for LLM Backends (OpenAI, Anthropic, Local).
+    """
+
+    @abstractmethod
+    async def chat(
+        self, 
+        messages: List[Dict[str, Any]], 
+        tools: Optional[List[Dict[str, Any]]] = None
+    ) -> LLMResponse:
+        """
+        Generate a response for a given chat history.
+        """
+        pass
+
+    @abstractmethod
+    async def stream_chat(
+        self,
+        messages: List[Dict[str, Any]],
+        tools: Optional[List[Dict[str, Any]]] = None
+    ) -> AsyncIterator[str]:
+        """
+        Stream the response content.
+        """
+        pass

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