loom-agent 0.0.1__py3-none-any.whl

loom/core/structured_logger.py

@@ -0,0 +1,279 @@
+"""US7: Structured Logging with Correlation IDs
+
+Provides JSON-formatted structured logging for production observability.
+
+Features:
+- Correlation ID tracking across requests
+- JSON format for log aggregation tools (Datadog, CloudWatch, etc.)
+- Context propagation
+- Performance metrics
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from typing import Any, Dict, Optional
+from datetime import datetime
+from contextvars import ContextVar
+
+
+# Context variable for correlation ID
+_correlation_id: ContextVar[Optional[str]] = ContextVar('correlation_id', default=None)
+
+
+class StructuredLogger:
+    """Structured logger with correlation ID support.
+
+    Example:
+        logger = StructuredLogger("my_agent")
+
+        # Set correlation ID for request
+        logger.set_correlation_id("req-123")
+
+        # All logs include correlation_id
+        logger.info("Processing request", user_id="user_456")
+        # Output: {"timestamp": "...", "level": "INFO", "message": "Processing request",
+        #          "correlation_id": "req-123", "user_id": "user_456"}
+    """
+
+    def __init__(
+        self,
+        name: str,
+        level: int = logging.INFO,
+        include_timestamp: bool = True,
+        include_location: bool = True,
+    ):
+        """Initialize structured logger.
+
+        Args:
+            name: Logger name (usually module or component name)
+            level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+            include_timestamp: Include ISO timestamp in logs
+            include_location: Include file location in logs
+        """
+        self.name = name
+        self.level = level
+        self.include_timestamp = include_timestamp
+        self.include_location = include_location
+        self._logger = logging.getLogger(name)
+        self._logger.setLevel(level)
+
+    def set_correlation_id(self, correlation_id: str) -> None:
+        """Set correlation ID for current context.
+
+        Args:
+            correlation_id: Unique identifier for request/conversation
+        """
+        _correlation_id.set(correlation_id)
+
+    def get_correlation_id(self) -> Optional[str]:
+        """Get current correlation ID."""
+        return _correlation_id.get()
+
+    def clear_correlation_id(self) -> None:
+        """Clear correlation ID from context."""
+        _correlation_id.set(None)
+
+    def _format_log(
+        self,
+        level: str,
+        message: str,
+        extra: Dict[str, Any],
+        exc_info: Optional[Exception] = None,
+    ) -> Dict[str, Any]:
+        """Format log entry as JSON-serializable dict.
+
+        Args:
+            level: Log level string
+            message: Log message
+            extra: Additional context fields
+            exc_info: Exception info if available
+
+        Returns:
+            JSON-serializable dict
+        """
+        log_entry = {
+            "level": level,
+            "message": message,
+            "logger": self.name,
+        }
+
+        # Add timestamp
+        if self.include_timestamp:
+            log_entry["timestamp"] = datetime.utcnow().isoformat() + "Z"
+
+        # Add correlation ID if available
+        correlation_id = self.get_correlation_id()
+        if correlation_id:
+            log_entry["correlation_id"] = correlation_id
+
+        # Add extra fields
+        if extra:
+            log_entry.update(extra)
+
+        # Add exception info
+        if exc_info:
+            log_entry["exception"] = {
+                "type": type(exc_info).__name__,
+                "message": str(exc_info),
+            }
+
+        return log_entry
+
+    def _log(
+        self,
+        level: int,
+        level_name: str,
+        message: str,
+        exc_info: Optional[Exception] = None,
+        **kwargs: Any,
+    ) -> None:
+        """Internal logging method.
+
+        Args:
+            level: Logging level constant
+            level_name: Level name string
+            message: Log message
+            exc_info: Exception if available
+            **kwargs: Additional context fields
+        """
+        if self._logger.isEnabledFor(level):
+            log_entry = self._format_log(level_name, message, kwargs, exc_info)
+
+            # Output as JSON
+            json_log = json.dumps(log_entry, default=str)
+
+            # Use standard logger
+            self._logger.log(level, json_log)
+
+    def debug(self, message: str, **kwargs: Any) -> None:
+        """Log debug message."""
+        self._log(logging.DEBUG, "DEBUG", message, **kwargs)
+
+    def info(self, message: str, **kwargs: Any) -> None:
+        """Log info message."""
+        self._log(logging.INFO, "INFO", message, **kwargs)
+
+    def warning(self, message: str, **kwargs: Any) -> None:
+        """Log warning message."""
+        self._log(logging.WARNING, "WARNING", message, **kwargs)
+
+    def error(self, message: str, exc_info: Optional[Exception] = None, **kwargs: Any) -> None:
+        """Log error message."""
+        self._log(logging.ERROR, "ERROR", message, exc_info=exc_info, **kwargs)
+
+    def critical(self, message: str, exc_info: Optional[Exception] = None, **kwargs: Any) -> None:
+        """Log critical message."""
+        self._log(logging.CRITICAL, "CRITICAL", message, exc_info=exc_info, **kwargs)
+
+    def log_performance(
+        self,
+        operation: str,
+        duration_ms: float,
+        success: bool = True,
+        **kwargs: Any,
+    ) -> None:
+        """Log performance metrics.
+
+        Args:
+            operation: Operation name
+            duration_ms: Duration in milliseconds
+            success: Whether operation succeeded
+            **kwargs: Additional metrics
+        """
+        self.info(
+            "Performance metric",
+            operation=operation,
+            duration_ms=duration_ms,
+            success=success,
+            **kwargs,
+        )
+
+
+class PerformanceTimer:
+    """Context manager for timing operations.
+
+    Example:
+        logger = StructuredLogger("my_agent")
+
+        with PerformanceTimer(logger, "llm_call") as timer:
+            result = await llm.generate(prompt)
+
+        # Automatically logs: {"operation": "llm_call", "duration_ms": 234.5, ...}
+    """
+
+    def __init__(
+        self,
+        logger: StructuredLogger,
+        operation: str,
+        log_level: str = "info",
+        **extra_context: Any,
+    ):
+        """Initialize performance timer.
+
+        Args:
+            logger: StructuredLogger instance
+            operation: Operation name
+            log_level: Log level for performance metric
+            **extra_context: Additional context to include
+        """
+        self.logger = logger
+        self.operation = operation
+        self.log_level = log_level
+        self.extra_context = extra_context
+        self.start_time: Optional[float] = None
+        self.end_time: Optional[float] = None
+
+    def __enter__(self):
+        """Start timer."""
+        self.start_time = time.time()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Stop timer and log performance."""
+        self.end_time = time.time()
+
+        if self.start_time is not None:
+            duration_ms = (self.end_time - self.start_time) * 1000
+            success = exc_type is None
+
+            self.logger.log_performance(
+                self.operation,
+                duration_ms,
+                success=success,
+                **self.extra_context,
+            )
+
+        return False  # Don't suppress exceptions
+
+
+# Global logger instance
+_default_logger = StructuredLogger("loom")
+
+
+def get_logger(name: str = "loom") -> StructuredLogger:
+    """Get or create a structured logger.
+
+    Args:
+        name: Logger name
+
+    Returns:
+        StructuredLogger instance
+    """
+    return StructuredLogger(name)
+
+
+def set_correlation_id(correlation_id: str) -> None:
+    """Set correlation ID for current context (convenience function).
+
+    Args:
+        correlation_id: Unique identifier
+    """
+    _correlation_id.set(correlation_id)
+
+
+def get_correlation_id() -> Optional[str]:
+    """Get current correlation ID (convenience function)."""
+    return _correlation_id.get()

loom/core/subagent_pool.py

@@ -0,0 +1,232 @@
+"""SubAgentPool: I2A isolated sub-agent architecture (US3)
+
+Spawns isolated sub-agents with independent tool permissions, message histories,
+and fault boundaries. Enables concurrent execution via Python 3.11 TaskGroups.
+
+Features:
+- Fault isolation (1 sub-agent failure doesn't affect others)
+- Tool whitelist enforcement (independent permissions)
+- Separate message histories (no cross-contamination)
+- Execution depth limits (max 3 levels, prevent infinite recursion)
+- Timeout and max_iterations enforcement
+- Concurrent sub-agent execution via asyncio.TaskGroup
+
+Architecture:
+- Each sub-agent is a fully isolated Agent instance
+- SubAgentPool manages lifecycle and resource limits
+- Uses cancel_token (US1) for timeout enforcement
+- Compatible with CompressionManager (US2)
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Dict, List, Optional
+from uuid import uuid4
+
+from loom.components.agent import Agent
+from loom.core.types import Message
+from loom.interfaces.llm import BaseLLM
+from loom.interfaces.memory import BaseMemory
+from loom.interfaces.tool import BaseTool
+
+
+class MaxDepthError(Exception):
+    """Raised when sub-agent execution depth exceeds maximum."""
+    pass
+
+
+class SubAgentPool:
+    """Manages isolated sub-agent spawning and execution.
+
+    Example:
+        pool = SubAgentPool(max_depth=3)
+
+        # Spawn sub-agent with tool whitelist
+        result = await pool.spawn(
+            llm=llm,
+            prompt="Analyze dependencies",
+            tool_whitelist=["read_file", "glob"],  # Only these tools
+            timeout_seconds=60,
+        )
+    """
+
+    def __init__(
+        self,
+        max_depth: int = 3,
+        default_timeout: float = 300.0,  # 5 minutes
+        default_max_iterations: int = 50,
+    ):
+        """Initialize SubAgentPool.
+
+        Args:
+            max_depth: Maximum execution depth (prevent infinite recursion)
+            default_timeout: Default timeout in seconds for sub-agents
+            default_max_iterations: Default max iterations for sub-agents
+        """
+        self.max_depth = max_depth
+        self.default_timeout = default_timeout
+        self.default_max_iterations = default_max_iterations
+        self._active_subagents: Dict[str, Agent] = {}
+
+    async def spawn(
+        self,
+        llm: BaseLLM,
+        prompt: str,
+        tools: Optional[List[BaseTool]] = None,
+        tool_whitelist: Optional[List[str]] = None,
+        memory: Optional[BaseMemory] = None,
+        execution_depth: int = 1,
+        timeout_seconds: Optional[float] = None,
+        max_iterations: Optional[int] = None,
+        system_instructions: Optional[str] = None,
+    ) -> str:
+        """Spawn an isolated sub-agent and execute task.
+
+        Args:
+            llm: LLM instance for sub-agent
+            prompt: Task prompt for sub-agent
+            tools: Available tools (will be filtered by whitelist)
+            tool_whitelist: List of allowed tool names (None = all tools)
+            memory: Memory instance (if None, sub-agent gets fresh memory)
+            execution_depth: Current execution depth (for depth limit)
+            timeout_seconds: Timeout in seconds (None = default)
+            max_iterations: Max iterations (None = default)
+            system_instructions: System instructions for sub-agent
+
+        Returns:
+            Final response from sub-agent
+
+        Raises:
+            MaxDepthError: If execution_depth > max_depth
+            asyncio.TimeoutError: If sub-agent exceeds timeout
+        """
+        # Check depth limit
+        if execution_depth > self.max_depth:
+            raise MaxDepthError(
+                f"Execution depth {execution_depth} exceeds maximum {self.max_depth}"
+            )
+
+        # Filter tools by whitelist
+        filtered_tools = self._apply_tool_whitelist(tools, tool_whitelist)
+
+        # Create isolated sub-agent (compression always enabled in v4.0.0)
+        subagent_id = str(uuid4())
+        subagent = Agent(
+            llm=llm,
+            tools=filtered_tools,
+            memory=memory,  # Separate memory instance
+            max_iterations=max_iterations or self.default_max_iterations,
+            system_instructions=system_instructions,
+        )
+
+        # Register active sub-agent
+        self._active_subagents[subagent_id] = subagent
+
+        try:
+            # Create cancel token for timeout enforcement
+            cancel_token = asyncio.Event()
+            timeout = timeout_seconds or self.default_timeout
+
+            # Execute sub-agent with timeout
+            task = asyncio.create_task(
+                subagent.run(prompt, cancel_token=cancel_token, correlation_id=subagent_id)
+            )
+
+            # Wait with timeout
+            result = await asyncio.wait_for(task, timeout=timeout)
+
+            return result
+
+        except asyncio.TimeoutError:
+            # Cancel sub-agent on timeout
+            cancel_token.set()
+            raise
+
+        finally:
+            # Cleanup: Remove from active pool
+            self._active_subagents.pop(subagent_id, None)
+
+    def _apply_tool_whitelist(
+        self,
+        tools: Optional[List[BaseTool]],
+        whitelist: Optional[List[str]],
+    ) -> Optional[List[BaseTool]]:
+        """Filter tools by whitelist.
+
+        Args:
+            tools: All available tools
+            whitelist: List of allowed tool names (None = all tools)
+
+        Returns:
+            Filtered list of tools
+        """
+        if tools is None or whitelist is None:
+            return tools
+
+        # Filter tools to only whitelisted ones
+        filtered = [tool for tool in tools if tool.name in whitelist]
+
+        return filtered if filtered else None
+
+    async def spawn_many(
+        self,
+        llm: BaseLLM,
+        prompts: List[str],
+        tools: Optional[List[BaseTool]] = None,
+        tool_whitelist: Optional[List[str]] = None,
+        timeout_seconds: Optional[float] = None,
+        return_exceptions: bool = True,
+    ) -> List[str]:
+        """Spawn multiple sub-agents concurrently.
+
+        Args:
+            llm: LLM instance (shared across sub-agents)
+            prompts: List of task prompts
+            tools: Available tools
+            tool_whitelist: Tool whitelist (applied to all sub-agents)
+            timeout_seconds: Timeout per sub-agent
+            return_exceptions: If True, return exceptions instead of raising
+
+        Returns:
+            List of results (or exceptions if return_exceptions=True)
+
+        Example:
+            prompts = ["Analyze file1.py", "Analyze file2.py", "Analyze file3.py"]
+            results = await pool.spawn_many(llm, prompts, tools=tools)
+        """
+        tasks = [
+            self.spawn(
+                llm=llm,
+                prompt=prompt,
+                tools=tools,
+                tool_whitelist=tool_whitelist,
+                timeout_seconds=timeout_seconds,
+            )
+            for prompt in prompts
+        ]
+
+        results = await asyncio.gather(*tasks, return_exceptions=return_exceptions)
+
+        return results
+
+    def get_active_count(self) -> int:
+        """Get number of currently active sub-agents."""
+        return len(self._active_subagents)
+
+    async def cancel_all(self) -> None:
+        """Cancel all active sub-agents.
+
+        Note: This is a best-effort cancellation. Sub-agents may not
+        respond immediately to cancellation signals.
+        """
+        for subagent_id, subagent in list(self._active_subagents.items()):
+            # Set cancel token (if sub-agent supports steering)
+            if hasattr(subagent.executor, "steering_control"):
+                subagent.executor.steering_control.abort()
+
+        # Wait a moment for cancellations to propagate
+        await asyncio.sleep(0.1)
+
+        # Clear active pool
+        self._active_subagents.clear()

loom/core/system_prompt.py

@@ -0,0 +1,141 @@
+"""系统提示生成模块 - 对齐 Claude Code 的动态系统提示构建机制"""
+
+from typing import Dict, List, Optional
+
+from loom.interfaces.tool import BaseTool
+
+
+class SystemPromptBuilder:
+    """动态生成系统提示，包含工具目录、风格指引与边界提醒"""
+
+    def __init__(
+        self,
+        base_instructions: Optional[str] = None,
+        style_guide: Optional[str] = None,
+        boundary_reminders: Optional[List[str]] = None,
+    ) -> None:
+        self.base_instructions = base_instructions or self._default_instructions()
+        self.style_guide = style_guide or self._default_style_guide()
+        self.boundary_reminders = boundary_reminders or self._default_boundary_reminders()
+
+    def build(
+        self,
+        tools: Dict[str, BaseTool],
+        context: Optional[Dict] = None,
+    ) -> str:
+        """构建完整的系统提示"""
+        sections = [
+            self.base_instructions,
+            self._build_tool_catalog(tools),
+            self.style_guide,
+            self._build_boundary_section(),
+        ]
+
+        if context:
+            sections.insert(1, self._build_context_section(context))
+
+        return "\n\n".join(filter(None, sections))
+
+    def _build_tool_catalog(self, tools: Dict[str, BaseTool]) -> str:
+        """生成工具目录"""
+        if not tools:
+            return ""
+
+        catalog_lines = ["## Available Tools", ""]
+        for tool in tools.values():
+            catalog_lines.append(f"### {tool.name}")
+            catalog_lines.append(f"**Description**: {getattr(tool, 'description', 'No description')}")
+
+            # 提取参数 schema
+            if hasattr(tool, "args_schema"):
+                try:
+                    schema = tool.args_schema.model_json_schema()
+                    properties = schema.get("properties", {})
+                    required = schema.get("required", [])
+
+                    if properties:
+                        catalog_lines.append("**Parameters**:")
+                        for param_name, param_info in properties.items():
+                            is_required = " (required)" if param_name in required else ""
+                            param_type = param_info.get("type", "any")
+                            param_desc = param_info.get("description", "")
+                            catalog_lines.append(f"- `{param_name}` ({param_type}){is_required}: {param_desc}")
+                except Exception:
+                    pass
+
+            # 并发安全性标记
+            if hasattr(tool, "is_concurrency_safe"):
+                safe = "✓" if tool.is_concurrency_safe else "✗"
+                catalog_lines.append(f"**Concurrency Safe**: {safe}")
+
+            catalog_lines.append("")
+
+        return "\n".join(catalog_lines)
+
+    def _build_context_section(self, context: Dict) -> str:
+        """构建上下文信息段"""
+        lines = ["## Context Information", ""]
+        for key, value in context.items():
+            lines.append(f"**{key}**: {value}")
+        return "\n".join(lines)
+
+    def _build_boundary_section(self) -> str:
+        """构建边界提醒段"""
+        if not self.boundary_reminders:
+            return ""
+        lines = ["## Important Reminders", ""]
+        for reminder in self.boundary_reminders:
+            lines.append(f"- {reminder}")
+        return "\n".join(lines)
+
+    @staticmethod
+    def _default_instructions() -> str:
+        return """You are an intelligent AI agent powered by the Loom framework.
+
+Your capabilities:
+- Analyze user requests and break them down into actionable steps
+- Use available tools to gather information and perform actions
+- Think step-by-step through complex problems
+- Provide clear, concise, and accurate responses
+
+When using tools:
+1. Carefully read the tool descriptions and parameters
+2. Provide all required parameters with correct types
+3. Handle tool results appropriately
+4. If a tool fails, try alternative approaches or inform the user
+
+Your responses should be:
+- Clear and well-structured
+- Accurate and factual
+- Helpful and actionable
+- Honest about limitations"""
+
+    @staticmethod
+    def _default_style_guide() -> str:
+        return """## Response Style
+
+- Use markdown formatting for better readability
+- Break down complex explanations into bullet points or numbered lists
+- When executing multiple steps, show your reasoning process
+- If uncertain, acknowledge the uncertainty
+- Cite tool results when making claims based on them"""
+
+    @staticmethod
+    def _default_boundary_reminders() -> List[str]:
+        return [
+            "Always validate tool parameters before calling",
+            "Respect tool execution timeouts and handle failures gracefully",
+            "Do not make assumptions about tool results without verification",
+            "If a task requires multiple steps, break it down clearly",
+            "Stop and ask for clarification if the user's intent is ambiguous",
+        ]
+
+
+def build_system_prompt(
+    tools: Dict[str, BaseTool],
+    custom_instructions: Optional[str] = None,
+    context: Optional[Dict] = None,
+) -> str:
+    """便捷函数：快速构建系统提示"""
+    builder = SystemPromptBuilder(base_instructions=custom_instructions)
+    return builder.build(tools, context)