loom-agent 0.0.1__py3-none-any.whl → 0.0.2__py3-none-any.whl

loom/interfaces/event_producer.py

@@ -0,0 +1,172 @@
+"""
+Event Producer Protocol for Loom 2.0
+
+Defines the interface that all event-producing components must implement.
+This enables type-safe composition of streaming agents.
+"""
+
+from typing import Protocol, AsyncGenerator, runtime_checkable
+from loom.core.events import AgentEvent
+
+
+@runtime_checkable
+class EventProducer(Protocol):
+    """
+    Protocol for components that produce AgentEvent streams.
+
+    Any component that participates in the agent execution pipeline
+    and produces events should implement this protocol.
+
+    Example:
+        ```python
+        class MyCustomExecutor(EventProducer):
+            async def produce_events(self) -> AsyncGenerator[AgentEvent, None]:
+                yield AgentEvent.phase_start("custom_phase")
+                # ... do work
+                yield AgentEvent.phase_end("custom_phase")
+        ```
+    """
+
+    async def produce_events(self) -> AsyncGenerator[AgentEvent, None]:
+        """
+        Produce a stream of agent events.
+
+        Yields:
+            AgentEvent: Events representing execution progress
+
+        Example:
+            ```python
+            async for event in producer.produce_events():
+                if event.type == AgentEventType.LLM_DELTA:
+                    print(event.content, end="")
+            ```
+        """
+        ...
+
+
+@runtime_checkable
+class ToolExecutor(Protocol):
+    """
+    Protocol for tool execution components that produce events.
+
+    This is a specialized EventProducer for tool execution.
+    """
+
+    async def execute_tool(
+        self,
+        tool_name: str,
+        arguments: dict
+    ) -> AsyncGenerator[AgentEvent, None]:
+        """
+        Execute a tool and yield progress events.
+
+        Args:
+            tool_name: Name of the tool to execute
+            arguments: Tool arguments
+
+        Yields:
+            AgentEvent: Tool execution events (TOOL_EXECUTION_START,
+                        TOOL_PROGRESS, TOOL_RESULT, or TOOL_ERROR)
+        """
+        ...
+
+
+@runtime_checkable
+class LLMEventProducer(Protocol):
+    """
+    Protocol for LLM components that produce streaming events.
+
+    This enables streaming LLM calls with real-time token generation.
+    """
+
+    async def stream_with_events(
+        self,
+        messages: list,
+        tools: list = None
+    ) -> AsyncGenerator[AgentEvent, None]:
+        """
+        Stream LLM generation as AgentEvents.
+
+        Args:
+            messages: Conversation messages
+            tools: Optional tool definitions
+
+        Yields:
+            AgentEvent: LLM events (LLM_START, LLM_DELTA, LLM_COMPLETE,
+                        LLM_TOOL_CALLS)
+        """
+        ...
+
+
+# ===== Helper Functions =====
+
+async def merge_event_streams(
+    *producers: EventProducer
+) -> AsyncGenerator[AgentEvent, None]:
+    """
+    Merge multiple event streams into a single stream.
+
+    This is useful for parallel execution where multiple components
+    produce events concurrently.
+
+    Args:
+        *producers: EventProducer instances to merge
+
+    Yields:
+        AgentEvent: Events from all producers in arrival order
+
+    Example:
+        ```python
+        async for event in merge_event_streams(executor1, executor2):
+            print(event)
+        ```
+    """
+    import asyncio
+
+    # Create tasks for all producers
+    tasks = [
+        asyncio.create_task(_consume_producer(producer))
+        for producer in producers
+    ]
+
+    # Yield events as they arrive
+    pending = set(tasks)
+    while pending:
+        done, pending = await asyncio.wait(
+            pending,
+            return_when=asyncio.FIRST_COMPLETED
+        )
+
+        for task in done:
+            events = task.result()
+            for event in events:
+                yield event
+
+
+async def _consume_producer(producer: EventProducer) -> list:
+    """Helper to consume a producer into a list"""
+    events = []
+    async for event in producer.produce_events():
+        events.append(event)
+    return events
+
+
+async def collect_events(
+    producer: EventProducer
+) -> list:
+    """
+    Collect all events from a producer into a list.
+
+    Args:
+        producer: EventProducer to consume
+
+    Returns:
+        List of all events produced
+
+    Example:
+        ```python
+        events = await collect_events(my_executor)
+        print(f"Generated {len(events)} events")
+        ```
+    """
+    return await _consume_producer(producer)

loom/interfaces/tool.py

@@ -7,12 +7,32 @@ from pydantic import BaseModel
 
 
 class BaseTool(ABC):
-    """工具基础接口。"""
+    """
+    工具基础接口。
+
+    Attributes:
+        name: Tool name (unique identifier)
+        description: Tool description for LLM
+        args_schema: Pydantic model for argument validation
+        is_read_only: Whether tool only reads data (safe to parallelize) 🆕
+        category: Tool category (general/destructive/network) 🆕
+        requires_confirmation: Whether tool requires user confirmation 🆕
+    """
 
     name: str
     description: str
     args_schema: type[BaseModel]
 
+    # 🆕 Loom 2.0 - Orchestration attributes
+    is_read_only: bool = False
+    """Whether this tool only reads data (safe to parallelize with other read-only tools)."""
+
+    category: str = "general"
+    """Tool category: 'general', 'destructive', 'network'."""
+
+    requires_confirmation: bool = False
+    """Whether this tool requires explicit user confirmation before execution."""
+
     @abstractmethod
     async def run(self, **kwargs) -> Any:
         raise NotImplementedError
@@ -23,5 +43,6 @@ class BaseTool(ABC):
 
     @property
     def is_concurrency_safe(self) -> bool:
+        """Legacy attribute for backward compatibility."""
         return True
 

loom/security/__init__.py

@@ -0,0 +1,13 @@
+"""Security module for Loom 2.0"""
+
+from loom.security.models import RiskLevel, SecurityDecision, PathSecurityResult
+from loom.security.path_validator import PathSecurityValidator
+from loom.security.validator import SecurityValidator
+
+__all__ = [
+    "RiskLevel",
+    "SecurityDecision",
+    "PathSecurityResult",
+    "PathSecurityValidator",
+    "SecurityValidator",
+]

loom/security/models.py

@@ -0,0 +1,85 @@
+"""
+Security Models
+
+Data models for security validation results.
+"""
+
+from enum import Enum
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+
+class RiskLevel(str, Enum):
+    """Security risk levels for tool execution."""
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    CRITICAL = "critical"
+
+    def __lt__(self, other):
+        """Allow comparison of risk levels."""
+        order = {
+            RiskLevel.LOW: 0,
+            RiskLevel.MEDIUM: 1,
+            RiskLevel.HIGH: 2,
+            RiskLevel.CRITICAL: 3
+        }
+        return order[self] < order[other]
+
+    def __gt__(self, other):
+        order = {
+            RiskLevel.LOW: 0,
+            RiskLevel.MEDIUM: 1,
+            RiskLevel.HIGH: 2,
+            RiskLevel.CRITICAL: 3
+        }
+        return order[self] > order[other]
+
+
+@dataclass
+class SecurityDecision:
+    """
+    Result of security validation.
+
+    Attributes:
+        allow: Whether the operation is allowed
+        risk_level: Assessed risk level
+        reason: Human-readable reason for decision
+        failed_layers: List of security layers that failed
+        warnings: Non-blocking warnings
+    """
+    allow: bool
+    risk_level: RiskLevel
+    reason: str
+    failed_layers: List[str] = field(default_factory=list)
+    warnings: List[str] = field(default_factory=list)
+
+    @property
+    def is_safe(self) -> bool:
+        """Check if decision is safe to execute."""
+        return self.allow and self.risk_level in [RiskLevel.LOW, RiskLevel.MEDIUM]
+
+    def __repr__(self) -> str:
+        status = "ALLOWED" if self.allow else "BLOCKED"
+        return f"SecurityDecision({status}, risk={self.risk_level.value}, reason='{self.reason}')"
+
+
+@dataclass
+class PathSecurityResult:
+    """
+    Result of path security validation.
+
+    Attributes:
+        is_safe: Whether the path is safe to access
+        normalized_path: Resolved absolute path
+        warnings: Non-critical warnings
+        violations: Security violations found
+    """
+    is_safe: bool
+    normalized_path: str
+    warnings: List[str] = field(default_factory=list)
+    violations: List[str] = field(default_factory=list)
+
+    def __repr__(self) -> str:
+        status = "SAFE" if self.is_safe else "UNSAFE"
+        return f"PathSecurityResult({status}, violations={len(self.violations)})"

loom/security/path_validator.py

@@ -0,0 +1,128 @@
+"""
+Path Security Validator
+
+Validates file paths for security issues like path traversal and system path access.
+"""
+
+from pathlib import Path
+from typing import List, Optional
+from loom.security.models import PathSecurityResult
+
+
+# System paths that should never be accessed
+SYSTEM_PATHS = [
+    "/etc",
+    "/sys",
+    "/proc",
+    "/dev",
+    "/boot",
+    "/root",
+    "/var/log",
+    "/bin",
+    "/sbin",
+    "/usr/bin",
+    "/usr/sbin",
+]
+
+
+class PathSecurityValidator:
+    """
+    Validate file paths for security issues.
+
+    Checks for:
+    - Path traversal attacks (../)
+    - Absolute paths outside working directory
+    - System path access
+    - Invalid path constructions
+
+    Example:
+        ```python
+        validator = PathSecurityValidator(working_dir=Path("/Users/project"))
+
+        # Safe path
+        result = validator.validate_path("src/main.py")
+        assert result.is_safe
+
+        # Path traversal attempt
+        result = validator.validate_path("../../etc/passwd")
+        assert not result.is_safe
+        ```
+    """
+
+    def __init__(self, working_dir: Optional[Path] = None):
+        """
+        Initialize path validator.
+
+        Args:
+            working_dir: Working directory to enforce boundaries (defaults to cwd)
+        """
+        self.working_dir = (working_dir or Path.cwd()).resolve()
+
+    def validate_path(self, path: str) -> PathSecurityResult:
+        """
+        Validate a file path for security issues.
+
+        Args:
+            path: File path to validate
+
+        Returns:
+            PathSecurityResult with validation outcome
+        """
+        violations: List[str] = []
+        warnings: List[str] = []
+        normalized_path = path
+
+        # Check 1: Detect explicit path traversal
+        if ".." in path:
+            violations.append("Path traversal detected (..)")
+
+        # Check 2: Resolve and validate boundaries
+        try:
+            # Handle both relative and absolute paths
+            if Path(path).is_absolute():
+                resolved = Path(path).resolve()
+            else:
+                resolved = (self.working_dir / path).resolve()
+
+            normalized_path = str(resolved)
+
+            # Check if within working directory
+            try:
+                resolved.relative_to(self.working_dir)
+            except ValueError:
+                violations.append(
+                    f"Path outside working directory: {resolved} "
+                    f"(working dir: {self.working_dir})"
+                )
+
+            # Check 3: System path protection
+            for sys_path in SYSTEM_PATHS:
+                if str(resolved).startswith(sys_path):
+                    violations.append(
+                        f"System path access denied: {sys_path}"
+                    )
+                    break
+
+        except Exception as e:
+            violations.append(f"Path resolution failed: {e}")
+
+        is_safe = len(violations) == 0
+
+        return PathSecurityResult(
+            is_safe=is_safe,
+            normalized_path=normalized_path,
+            warnings=warnings,
+            violations=violations
+        )
+
+    def is_safe_path(self, path: str) -> bool:
+        """
+        Quick check if path is safe.
+
+        Args:
+            path: Path to check
+
+        Returns:
+            True if path is safe
+        """
+        return self.validate_path(path).is_safe