loom-agent 0.3.2__py3-none-any.whl

loom/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.3.0"

loom/adapters/converters.py

@@ -0,0 +1,77 @@
+"""
+Tool Converters (M4)
+"""
+
+import inspect
+import json
+from typing import Any, Callable, Dict, get_type_hints, Type
+
+from loom.protocol.mcp import MCPToolDefinition
+
+class FunctionToMCP:
+    """
+    Converts Python functions to MCP Tool Definitions.
+    """
+    
+    @staticmethod
+    def convert(func: Callable[..., Any], name: str = None) -> MCPToolDefinition:
+        """
+        Introspects a python function and returns an MCP Tool Definition.
+        """
+        func_name = name or func.__name__
+        doc = inspect.getdoc(func) or "No description provided."
+        
+        # Parse arguments
+        sig = inspect.signature(func)
+        type_hints = get_type_hints(func)
+        
+        properties = {}
+        required = []
+        
+        for param_name, param in sig.parameters.items():
+            if param_name == "self" or param_name == "cls":
+                continue
+                
+            # Get type
+            py_type = type_hints.get(param_name, Any)
+            json_type = FunctionToMCP._map_type(py_type)
+            
+            prop_def = {"type": json_type}
+            
+            # TODO: Description from docstring parsing? (Google-style/NumPy-style)
+            # For now, just basic type.
+            
+            properties[param_name] = prop_def
+            
+            if param.default == inspect.Parameter.empty:
+                required.append(param_name)
+                
+        input_schema = {
+            "type": "object",
+            "properties": properties,
+            "required": required
+        }
+        
+        return MCPToolDefinition(
+            name=func_name,
+            description=doc,
+            input_schema=input_schema
+        )
+
+    @staticmethod
+    def _map_type(py_type: Type) -> str:
+        """Map Python type to JSON Schema type."""
+        if py_type == str:
+            return "string"
+        elif py_type == int:
+            return "integer"
+        elif py_type == float:
+            return "number"
+        elif py_type == bool:
+            return "boolean"
+        elif py_type == list or getattr(py_type, "__origin__", None) == list:
+            return "array"
+        elif py_type == dict or getattr(py_type, "__origin__", None) == dict:
+            return "object"
+        else:
+            return "string" # Default fallback

loom/adapters/registry.py

@@ -0,0 +1,43 @@
+"""
+Tool Registry (M4)
+"""
+
+from typing import Dict, Any, Callable, List, Optional
+from loom.protocol.mcp import MCPToolDefinition
+from loom.adapters.converters import FunctionToMCP
+# ToolNode is in loom.node.tool, but avoid circular import if possible.
+# Ideally Registry produces definitions + execution callables. 
+# Factory creates Nodes.
+
+class ToolRegistry:
+    """
+    Central repository for tools available to Agents.
+    """
+    
+    def __init__(self):
+        self._tools: Dict[str, Callable] = {}
+        self._definitions: Dict[str, MCPToolDefinition] = {}
+
+    def register_function(self, func: Callable, name: str = None) -> MCPToolDefinition:
+        """Register a python function as a tool."""
+        # Clean name
+        tool_name = name or func.__name__
+        
+        # Convert to MCP
+        definition = FunctionToMCP.convert(func, name=tool_name)
+        
+        # Store
+        self._tools[tool_name] = func
+        self._definitions[tool_name] = definition
+        
+        return definition
+        
+    def get_definition(self, name: str) -> Optional[MCPToolDefinition]:
+        return self._definitions.get(name)
+        
+    def get_callable(self, name: str) -> Optional[Callable]:
+        return self._tools.get(name)
+
+    @property
+    def definitions(self) -> List[MCPToolDefinition]:
+        return list(self._definitions.values())

loom/api/factory.py

@@ -0,0 +1,77 @@
+"""
+Loom SDK: Factory Helpers
+"""
+
+from typing import List, Optional, Callable, Dict, Any
+
+from loom.api.main import LoomApp
+from loom.node.agent import AgentNode
+from loom.node.tool import ToolNode
+from loom.node.crew import CrewNode
+from loom.protocol.mcp import MCPToolDefinition
+from loom.interfaces.llm import LLMProvider
+
+from loom.interfaces.memory import MemoryInterface
+
+def Agent(
+    app: LoomApp,
+    name: str,
+    role: str = "Assistant",
+    tools: Optional[List[ToolNode]] = None,
+    provider: Optional[LLMProvider] = None,
+    memory: Optional[MemoryInterface] = None
+) -> AgentNode:
+    """Helper to create an AgentNode."""
+    return AgentNode(
+        node_id=name,
+        dispatcher=app.dispatcher,
+        role=role,
+        tools=tools,
+        provider=provider,
+        memory=memory
+    )
+
+from loom.adapters.converters import FunctionToMCP
+
+def Tool(
+    app: LoomApp,
+    name: str,
+    func: Callable[..., Any],
+    description: Optional[str] = None,
+    parameters: Optional[Dict[str, Any]] = None
+) -> ToolNode:
+    """
+    Helper to create a ToolNode.
+    Auto-generates schema from function signature if parameters not provided.
+    """
+    
+    # Auto-generate definition/schema if not provided
+    auto_def = FunctionToMCP.convert(func, name=name)
+    
+    final_desc = description or auto_def.description
+    final_input_schema = parameters or auto_def.input_schema
+    
+    tool_def = MCPToolDefinition(
+        name=name,
+        description=final_desc,
+        input_schema=final_input_schema
+    )
+    
+    return ToolNode(
+        node_id=name,
+        dispatcher=app.dispatcher,
+        tool_def=tool_def,
+        func=func
+    )
+
+def Crew(
+    app: LoomApp,
+    name: str,
+    agents: List[AgentNode]
+) -> CrewNode:
+    """Helper to create a CrewNode."""
+    return CrewNode(
+        node_id=name,
+        dispatcher=app.dispatcher,
+        agents=agents
+    )

loom/api/main.py

@@ -0,0 +1,201 @@
+"""
+Loom SDK: Main Application
+"""
+
+import asyncio
+from typing import Callable, Any, Optional, Dict
+from uuid import uuid4
+
+from loom.kernel.bus import UniversalEventBus
+from loom.kernel.state import StateStore
+from loom.kernel.dispatcher import Dispatcher
+from loom.kernel.interceptors import TracingInterceptor
+from loom.kernel.interceptors.budget import BudgetInterceptor
+from loom.kernel.interceptors.depth import DepthInterceptor
+from loom.kernel.interceptors.hitl import HITLInterceptor
+from loom.kernel.interceptors.studio import StudioInterceptor
+from loom.protocol.cloudevents import CloudEvent
+from loom.interfaces.store import EventStore
+from loom.node.base import Node
+
+from loom.interfaces.transport import Transport
+
+class LoomApp:
+    """
+    The High-Level Application Object.
+    
+    Usage:
+        app = LoomApp(control_config={"budget": 5000})
+        app.add_node(agent)
+        app.run("Do something", target="agent_1")
+    """
+    
+    def __init__(self, 
+                 store: Optional[EventStore] = None, 
+                 transport: Optional[Transport] = None,
+                 control_config: Optional[Dict[str, Any]] = None):
+        
+        control_config = control_config or {}
+
+        if "transport" in control_config and isinstance(control_config["transport"], dict):
+             # Config dict provided, maybe future extensibility
+             pass
+        
+        # Transport Selection
+        # 1. Transport object passed directly
+        self.transport = transport
+        
+        if not self.transport:
+            # Config from control_config or Env
+            transport_cfg = {}
+            if "transport" in control_config and isinstance(control_config["transport"], dict):
+                transport_cfg = control_config["transport"]
+            
+            import os
+            # Priority: Config > Env > Default
+            transport_type = transport_cfg.get("type") or os.getenv("LOOM_TRANSPORT", "memory").lower()
+            
+            if transport_type == "redis":
+                from loom.infra.transport.redis import RedisTransport
+                redis_url = transport_cfg.get("redis_url") or os.getenv("REDIS_URL", "redis://localhost:6379")
+                self.transport = RedisTransport(redis_url=redis_url)
+            elif transport_type == "nats":
+                from loom.infra.transport.nats import NATSTransport
+                nats_servers_cfg = transport_cfg.get("nats_servers")
+                if nats_servers_cfg:
+                     nats_servers = nats_servers_cfg if isinstance(nats_servers_cfg, list) else [nats_servers_cfg]
+                else:
+                     nats_servers = os.getenv("NATS_SERVERS", "nats://localhost:4222").split(",")
+                self.transport = NATSTransport(servers=nats_servers)
+            else:
+                from loom.infra.transport.memory import InMemoryTransport
+                self.transport = InMemoryTransport()
+                
+        self.bus = UniversalEventBus(store=store, transport=self.transport)
+        self.state_store = StateStore()
+        self.dispatcher = Dispatcher(self.bus)
+        
+        # Default Interceptors
+        self.dispatcher.add_interceptor(TracingInterceptor())
+        
+        # Configured Controls
+        control_config = control_config or {}
+        
+        if "budget" in control_config:
+            cfg = control_config["budget"]
+            max_tokens = cfg["max_tokens"] if isinstance(cfg, dict) else cfg
+            self.dispatcher.add_interceptor(BudgetInterceptor(max_tokens=max_tokens))
+            
+        if "depth" in control_config:
+            cfg = control_config["depth"]
+            max_depth = cfg["max_depth"] if isinstance(cfg, dict) else cfg
+            self.dispatcher.add_interceptor(DepthInterceptor(max_depth=max_depth))
+            
+        if "hitl" in control_config:
+            # hitl expects a list of patterns
+            patterns = control_config["hitl"]
+            patterns = control_config["hitl"]
+            if isinstance(patterns, list):
+                self.dispatcher.add_interceptor(HITLInterceptor(patterns=patterns))
+
+        # Studio Support
+        # Check env var or control_config
+        studio_enabled = False
+        studio_url = "ws://localhost:8765"
+        
+        if "studio" in control_config:
+             studio_cfg = control_config["studio"]
+             if isinstance(studio_cfg, dict):
+                 studio_enabled = studio_cfg.get("enabled", False)
+                 studio_url = studio_cfg.get("url", studio_url)
+             elif isinstance(studio_cfg, bool):
+                 studio_enabled = studio_cfg
+        else:
+             import os
+             if os.getenv("LOOM_STUDIO_ENABLED", "false").lower() == "true":
+                 studio_enabled = True
+                 studio_url = os.getenv("LOOM_STUDIO_URL", studio_url)
+                 
+        if studio_enabled:
+            self.dispatcher.add_interceptor(StudioInterceptor(studio_url=studio_url, enabled=True))
+        
+        self._started = False
+        
+    async def start(self):
+        """Initialize async components."""
+        if self._started:
+            return
+        
+        await self.bus.connect()
+        await self.bus.subscribe("state.patch/*", self.state_store.apply_event)
+        self._started = True
+
+    def add_node(self, node: Node):
+        """Register a node with the app."""
+        # Nodes auto-subscribe in their __init__ using the dispatcher.
+        # We assume the node has already been initialized with THIS app's dispatcher.
+        # Or we can provide a helper here if Node wasn't initialized?
+        # Better: The Factory helper uses app.dispatcher.
+        pass
+
+    async def run(self, task: str, target: str) -> Any:
+        """
+        Run a single task targeting a specific node and return the result.
+        """
+        await self.start()
+        
+        request_id = str(uuid4())
+        event = CloudEvent.create(
+            source="/user/sdk",
+            type="node.request",
+            data={"task": task},
+            subject=target
+        )
+        event.id = request_id
+        
+        # Subscribe to response
+        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"))
+
+        target_topic = f"node.response/{target.strip('/')}"
+        
+        # We need to subscribe to the response
+        await self.bus.subscribe(target_topic, handle_response)
+        
+        try:
+            await self.dispatcher.dispatch(event)
+            
+            # Use timeout from event if set (injected by interceptor)
+            timeout = 30.0
+            if event.extensions and "timeout" in event.extensions:
+                try:
+                    timeout = float(event.extensions["timeout"])
+                except (ValueError, TypeError):
+                    pass
+            
+            return await asyncio.wait_for(response_future, timeout=timeout)
+        except asyncio.TimeoutError:
+            raise TimeoutError(f"Task targeting {target} timed out after {timeout}s")
+
+    def on(self, event_type: str, handler: Callable[[CloudEvent], Any]):
+        """
+        Add an observability hook.
+        """
+        async def _wrapper(event: CloudEvent):
+            if event_type == "*" or event.type == event_type:
+                res = handler(event)
+                if asyncio.iscoroutine(res):
+                    await res
+        
+        # We subscribe to the bus
+        # This requires an async context to call 'await bus.subscribe'.
+        # We can schedule it.
+        asyncio.create_task(self.bus.subscribe(f"{event_type}/*" if event_type != "*" else "*", _wrapper))
+

loom/builtin/__init__.py

@@ -0,0 +1,3 @@
+"""
+Built-in standard implementations for Loom components.
+"""

loom/builtin/memory/__init__.py

@@ -0,0 +1,3 @@
+"""
+Built-in memory implementations (Metabolic Memory components).
+"""

loom/builtin/memory/metabolic.py

@@ -0,0 +1,96 @@
+"""
+Metabolic Memory Core Implementation.
+"""
+
+import asyncio
+from typing import Any, Dict, List, Optional
+from loom.interfaces.memory import MemoryInterface, MemoryEntry
+from loom.protocol.memory_operations import MemoryValidator, ProjectStateObject, ContextSanitizer
+from loom.builtin.memory.validators import HeuristicValueAssessor
+from loom.builtin.memory.pso import SimplePSO
+from loom.builtin.memory.sanitizers import CompressiveSanitizer
+
+class MetabolicMemory(MemoryInterface):
+    """
+    Advanced Memory System that 'metabolizes' information.
+    1. Perceives (Validates importances)
+    2. Maintains State (PSO)
+    3. Consolidates (Compresses/Sanitizes)
+    """
+    
+    def __init__(
+        self, 
+        validator: Optional[MemoryValidator] = None,
+        pso: Optional[ProjectStateObject] = None,
+        sanitizer: Optional[ContextSanitizer] = None
+    ):
+        self.validator = validator or HeuristicValueAssessor()
+        self.pso = pso or SimplePSO()
+        self.sanitizer = sanitizer or CompressiveSanitizer()
+        
+        self.short_term: List[MemoryEntry] = []
+        self.limit = 10 # Short term limit before consolidation triggers
+        
+    async def add(self, role: str, content: str, metadata: Optional[Dict[str, Any]] = None) -> None:
+        """
+        Add entry with metabolic processing.
+        """
+        # 1. Perception / Validation
+        importance = await self.validator.validate(content)
+        
+        # 2. Add to Short Term
+        entry = MemoryEntry(
+            role=role, 
+            content=content, 
+            metadata={**(metadata or {}), "importance": importance, "tier": "ephemeral"}
+        )
+        self.short_term.append(entry)
+        
+        # 3. Trigger Metabolism (Consolidation) if limit reached
+        if len(self.short_term) > self.limit:
+            await self.consolidate()
+
+    async def get_context(self, task: str = "") -> str:
+        """
+        Construct context from PSO + Short Term.
+        """
+        pso_context = self.pso.to_markdown()
+        
+        # Get high importance short term or just recent
+        recent_context = "\n".join([f"{e.role}: {e.content}" for e in self.short_term])
+        
+        return f"{pso_context}\n\n### Recent Activity\n{recent_context}"
+        
+    async def get_recent(self, limit: int = 10) -> List[Dict[str, Any]]:
+        return [e.model_dump() for e in self.short_term[-limit:]]
+        
+    async def clear(self) -> None:
+        self.short_term = []
+        # PSO persists? Or clears? Usually PSO persists for the project lifetime.
+        # But for 'clear memory' command, maybe we reset session.
+        pass
+
+    async def consolidate(self) -> None:
+        """
+        Metabolic Cycle:
+        1. Update PSO with recent events.
+        2. Compress short_term -> long_term (not impl here) or just drop low value.
+        3. Keep only high value in short_term?
+        """
+        # 1. Update PSO
+        # Convert entries to dicts for PSO
+        events = [e.model_dump() for e in self.short_term]
+        await self.pso.update(events)
+        
+        # 2. Prune Short Term
+        # Keep only last N/2, or keep high score?
+        # Simple FIFO for now, but in real metabolic, we'd keep high importance ones active longer.
+        # Let's keep last 5.
+        
+        # If we wanted to "Santize" / Compress:
+        # text_block = ...
+        # compressed = await self.sanitizer.sanitize(text_block)
+        # We might move compressed summary to a 'middle term' tier.
+        
+        keep_count = self.limit // 2
+        self.short_term = self.short_term[-keep_count:]

loom/builtin/memory/pso.py

@@ -0,0 +1,41 @@
+"""
+Project State Object (PSO) Implementation.
+"""
+
+from typing import Any, Dict, List
+from loom.protocol.memory_operations import ProjectStateObject
+
+class SimplePSO(ProjectStateObject):
+    def __init__(self):
+        self.state: Dict[str, Any] = {
+            "goals": [],
+            "completed_tasks": [],
+            "current_context": "",
+            "variables": {}
+        }
+        
+    async def update(self, events: List[Dict[str, Any]]) -> None:
+        """
+        Update state based on heuristic interpretation of events.
+        """
+        for event in events:
+            role = event.get("role")
+            content = event.get("content", "")
+            
+            if role == "user" and ("task" in content.lower() or "goal" in content.lower()):
+                self.state["goals"].append(content)
+            elif role == "tool" and "result" in str(content).lower():
+                self.state["completed_tasks"].append(str(content)[:100])
+                
+    async def snapshot(self) -> Dict[str, Any]:
+        return self.state.copy()
+
+    def to_markdown(self) -> str:
+        md = "## Project State\n"
+        md += "### Goals\n"
+        for g in self.state["goals"]:
+            md += f"- [ ] {g}\n"
+        md += "\n### Completed\n"
+        for t in self.state["completed_tasks"]:
+            md += f"- [x] {t}\n"
+        return md

loom/builtin/memory/sanitizers.py

@@ -0,0 +1,39 @@
+"""
+Context Sanitizers Implementation.
+"""
+
+from loom.protocol.memory_operations import ContextSanitizer
+
+class BubbleUpSanitizer(ContextSanitizer):
+    """
+    Sanitizes child context for parent consumption.
+    Extracts high-level signals.
+    """
+    async def sanitize(self, context: str, target_token_limit: int) -> str:
+        # 1. Identify "Goal"
+        # 2. Identify "Result"
+        # 3. Identify "Blockers"
+        
+        # Simple string processing for prototype
+        lines = context.split('\n')
+        important_lines = [line for line in lines if "Result:" in line or "Error:" in line or "Goal:" in line]
+        
+        result = "\n".join(important_lines)
+        if len(result) > target_token_limit * 4: # rough char approx
+             return result[:target_token_limit * 4] + "..."
+        return result
+
+class CompressiveSanitizer(ContextSanitizer):
+    """
+    Compresses older conversation turns.
+    """
+    async def sanitize(self, context: str, target_token_limit: int) -> str:
+        # In a real impl, calls LLM to summarize.
+        # Here we just truncate the middle.
+        
+        if len(context) < target_token_limit * 4:
+            return context
+            
+        head = context[:(target_token_limit * 2)]
+        tail = context[-(target_token_limit * 2):]
+        return f"{head}\n... [Compressed {len(context) - len(head) - len(tail)} chars] ...\n{tail}"

loom/builtin/memory/validators.py

@@ -0,0 +1,55 @@
+"""
+Memory Validators Implementation.
+"""
+
+from typing import Any
+from loom.protocol.memory_operations import MemoryValidator
+
+# Assumed LLM interface access - in real implementation, this would be injected
+# For now we'll accept an LLMProvider in init
+
+class HeuristicValueAssessor(MemoryValidator):
+    def __init__(self, key_terms: list[str] = None):
+        self.key_terms = key_terms or ["goal", "error", "result", "important", "decision"]
+
+    async def validate(self, content: Any) -> float:
+        """
+        Simple heuristic: active if contains key terms or is short and punchy.
+        """
+        text = str(content).lower()
+        score = 0.0
+        
+        # Length bias: too short might be noise, too long might be noise
+        if 10 < len(text) < 500:
+            score += 0.3
+            
+        # Term bias
+        for term in self.key_terms:
+            if term in text:
+                score += 0.2
+        
+        return min(1.0, score)
+
+class LLMValueAssessor(MemoryValidator):
+    def __init__(self, llm_provider: Any): # using Any to avoid circ dep for now
+        self.llm = llm_provider
+        
+    async def validate(self, content: Any) -> float:
+        """
+        Ask LLM to score the importance.
+        """
+        prompt = f"""
+        Rate the importance of the following memory entry for a long-term project on a scale of 0.0 to 1.0.
+        Return ONLY the number.
+        
+        Entry:
+        {content}
+        """
+        try:
+            # Assumed simple LLM call not needing message structure for simplicity in this prototype
+            # But in reality, we'd use the proper Chat interface
+            # response = await self.llm.chat([{"role": "user", "content": prompt}])
+            # For now, let's mock/assume simple wrapper or return a high default
+            return 0.8 # Placeholder for actual LLM call
+        except:
+            return 0.5