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

loom/__init__.py

@@ -25,6 +25,33 @@ from .callbacks.observability import ObservabilityCallback, MetricsAggregator
 from .llm.model_health import ModelHealthChecker, HealthStatus
 from .llm.model_pool_advanced import ModelPoolLLM, ModelConfig, FallbackChain
 
+# Loom 0.0.3 - Unified Coordination & Performance
+from .core.agent_executor import AgentExecutor, TaskHandler
+from .core.unified_coordination import (
+    UnifiedExecutionContext,
+    IntelligentCoordinator,
+    CoordinationConfig
+)
+from .core.events import (
+    AgentEvent,
+    AgentEventType,
+    EventCollector,
+    EventFilter,
+    EventProcessor,
+    ToolCall,
+    ToolResult
+)
+from .core.turn_state import TurnState
+from .core.execution_context import ExecutionContext
+from .core.context_assembly import (
+    ContextAssembler,
+    ComponentPriority,
+    ContextComponent
+)
+
+# Loom 0.0.3 Developer API
+from .api.v0_0_3 import LoomAgent, loom_agent, unified_executor
+
 try:
     from importlib.metadata import version as _pkg_version
 
@@ -73,5 +100,29 @@ __all__ = [
     "ModelPoolLLM",
     "ModelConfig",
     "FallbackChain",
+    # Loom 0.0.3 exports - Core
+    "AgentExecutor",
+    "TaskHandler",
+    "UnifiedExecutionContext",
+    "IntelligentCoordinator",
+    "CoordinationConfig",
+    # Loom 0.0.3 exports - Events
+    "AgentEvent",
+    "AgentEventType",
+    "EventCollector",
+    "EventFilter",
+    "EventProcessor",
+    "ToolCall",
+    "ToolResult",
+    # Loom 0.0.3 exports - Context & State
+    "TurnState",
+    "ExecutionContext",
+    "ContextAssembler",
+    "ComponentPriority",
+    "ContextComponent",
+    # Loom 0.0.3 Developer API
+    "LoomAgent",
+    "loom_agent",
+    "unified_executor",
     "__version__",
 ]

loom/api/v0_0_3.py

@@ -0,0 +1,299 @@
+"""Loom 0.0.3 开发者 API - 简化统一协调使用
+
+提供开发者友好的 API 接口，让开发者能够轻松使用 Loom 0.0.3 的核心能力。
+"""
+
+import asyncio
+import time
+from typing import List, Optional, Dict, Any, AsyncGenerator, Union
+from ..core.agent_executor import AgentExecutor
+from ..core.unified_coordination import (
+    UnifiedExecutionContext,
+    IntelligentCoordinator,
+    CoordinationConfig
+)
+from ..core.events import AgentEvent, AgentEventType
+from ..core.turn_state import TurnState
+from ..core.execution_context import ExecutionContext
+from ..core.types import Message
+from ..interfaces.llm import BaseLLM
+from ..interfaces.tool import BaseTool
+
+
+class LoomAgent:
+    """Loom 0.0.3 统一协调 Agent
+    
+    提供简化的 API 接口，让开发者能够轻松使用统一协调机制。
+    """
+    
+    def __init__(
+        self,
+        llm: BaseLLM,
+        tools: Optional[Dict[str, BaseTool]] = None,
+        config: Optional[CoordinationConfig] = None,
+        execution_id: Optional[str] = None,
+        max_iterations: int = 50,
+        system_instructions: Optional[str] = None,
+        **kwargs
+    ):
+        """初始化 Loom 0.0.3 Agent
+        
+        Args:
+            llm: 语言模型实例
+            tools: 工具字典
+            config: 统一协调配置
+            execution_id: 执行 ID
+            max_iterations: 最大迭代次数
+            system_instructions: 系统指令
+            **kwargs: 其他参数
+        """
+        self.config = config or CoordinationConfig()
+        self.unified_context = UnifiedExecutionContext(
+            execution_id=execution_id or f"loom_agent_{int(time.time())}",
+            config=self.config
+        )
+        
+        self.executor = AgentExecutor(
+            llm=llm,
+            tools=tools or {},
+            unified_context=self.unified_context,
+            enable_unified_coordination=True,
+            max_iterations=max_iterations,
+            system_instructions=system_instructions,
+            **kwargs
+        )
+    
+    async def run(self, input_text: str, correlation_id: Optional[str] = None) -> str:
+        """运行 Agent 并返回最终结果
+        
+        Args:
+            input_text: 用户输入
+            correlation_id: 关联 ID
+            
+        Returns:
+            最终响应文本
+        """
+        turn_state = TurnState.initial(max_iterations=self.executor.max_iterations)
+        context = ExecutionContext.create(
+            correlation_id=correlation_id or f"run_{int(time.time())}"
+        )
+        messages = [Message(role="user", content=input_text)]
+        
+        final_content = ""
+        async for event in self.executor.tt(messages, turn_state, context):
+            if event.type == AgentEventType.AGENT_FINISH:
+                final_content = event.content or ""
+                break
+            elif event.type == AgentEventType.ERROR:
+                raise event.error
+        
+        return final_content
+    
+    async def stream(self, input_text: str, correlation_id: Optional[str] = None) -> AsyncGenerator[AgentEvent, None]:
+        """流式执行 Agent
+        
+        Args:
+            input_text: 用户输入
+            correlation_id: 关联 ID
+            
+        Yields:
+            AgentEvent: 执行事件
+        """
+        turn_state = TurnState.initial(max_iterations=self.executor.max_iterations)
+        context = ExecutionContext.create(
+            correlation_id=correlation_id or f"stream_{int(time.time())}"
+        )
+        messages = [Message(role="user", content=input_text)]
+        
+        async for event in self.executor.tt(messages, turn_state, context):
+            yield event
+    
+    async def execute_with_events(self, input_text: str, correlation_id: Optional[str] = None) -> List[AgentEvent]:
+        """执行并返回所有事件
+        
+        Args:
+            input_text: 用户输入
+            correlation_id: 关联 ID
+            
+        Returns:
+            事件列表
+        """
+        events = []
+        async for event in self.stream(input_text, correlation_id):
+            events.append(event)
+        return events
+    
+    async def run_with_progress(self, input_text: str, progress_callback=None) -> str:
+        """带进度回调的执行
+        
+        Args:
+            input_text: 用户输入
+            progress_callback: 进度回调函数
+            
+        Returns:
+            最终响应文本
+        """
+        final_content = ""
+        
+        async for event in self.stream(input_text):
+            if progress_callback:
+                await progress_callback(event)
+            
+            if event.type == AgentEventType.AGENT_FINISH:
+                final_content = event.content or ""
+                break
+            elif event.type == AgentEventType.ERROR:
+                raise event.error
+        
+        return final_content
+    
+    def get_coordinator(self) -> IntelligentCoordinator:
+        """获取智能协调器实例"""
+        return self.executor.coordinator
+    
+    def get_unified_context(self) -> UnifiedExecutionContext:
+        """获取统一执行上下文"""
+        return self.unified_context
+
+
+def create_loom_agent(
+    llm: BaseLLM,
+    tools: Optional[Dict[str, BaseTool]] = None,
+    config: Optional[CoordinationConfig] = None,
+    **kwargs
+) -> LoomAgent:
+    """创建 Loom 0.0.3 Agent
+    
+    Args:
+        llm: 语言模型实例
+        tools: 工具字典
+        config: 统一协调配置
+        **kwargs: 其他参数
+        
+    Returns:
+        LoomAgent 实例
+    """
+    return LoomAgent(llm=llm, tools=tools, config=config, **kwargs)
+
+
+def create_unified_executor(
+    llm: BaseLLM,
+    tools: Optional[Dict[str, BaseTool]] = None,
+    config: Optional[CoordinationConfig] = None,
+    execution_id: Optional[str] = None,
+    **kwargs
+) -> AgentExecutor:
+    """创建使用统一协调机制的 AgentExecutor
+    
+    Args:
+        llm: 语言模型实例
+        tools: 工具字典
+        config: 统一协调配置
+        execution_id: 执行 ID
+        **kwargs: 其他参数
+        
+    Returns:
+        AgentExecutor 实例
+    """
+    if config is None:
+        config = CoordinationConfig()
+    
+    unified_context = UnifiedExecutionContext(
+        execution_id=execution_id or f"executor_{int(time.time())}",
+        config=config
+    )
+    
+    return AgentExecutor(
+        llm=llm,
+        tools=tools or {},
+        unified_context=unified_context,
+        enable_unified_coordination=True,
+        **kwargs
+    )
+
+
+# 便捷函数
+def loom_agent(
+    llm: BaseLLM,
+    tools: Optional[Dict[str, BaseTool]] = None,
+    config: Optional[CoordinationConfig] = None,
+    **kwargs
+) -> LoomAgent:
+    """创建 Loom 0.0.3 统一协调 Agent
+    
+    这是最推荐的创建方式，提供简化的 API 和完整的功能。
+    
+    Args:
+        llm: 语言模型实例
+        tools: 工具字典
+        config: 统一协调配置
+        **kwargs: 其他参数
+        
+    Returns:
+        LoomAgent 实例
+        
+    Example:
+        ```python
+        import loom
+        from loom.builtin.llms import MockLLM
+        
+        agent = loom.loom_agent(
+            llm=MockLLM(),
+            tools={"calculator": CalculatorTool()}
+        )
+        
+        result = await agent.run("计算 2+2")
+        print(result)
+        ```
+    """
+    return create_loom_agent(llm=llm, tools=tools, config=config, **kwargs)
+
+
+def unified_executor(
+    llm: BaseLLM,
+    tools: Optional[Dict[str, BaseTool]] = None,
+    config: Optional[CoordinationConfig] = None,
+    **kwargs
+) -> AgentExecutor:
+    """创建统一协调 AgentExecutor
+    
+    适用于需要直接控制执行流程的高级用户。
+    
+    Args:
+        llm: 语言模型实例
+        tools: 工具字典
+        config: 统一协调配置
+        **kwargs: 其他参数
+        
+    Returns:
+        AgentExecutor 实例
+        
+    Example:
+        ```python
+        import loom
+        from loom.builtin.llms import MockLLM
+        
+        executor = loom.unified_executor(
+            llm=MockLLM(),
+            tools={"calculator": CalculatorTool()}
+        )
+        
+        turn_state = loom.TurnState.initial(max_iterations=10)
+        context = loom.ExecutionContext.create()
+        messages = [loom.Message(role="user", content="Hello")]
+        
+        async for event in executor.tt(messages, turn_state, context):
+            print(f"Event: {event.type} - {event.content}")
+        ```
+    """
+    return create_unified_executor(llm=llm, tools=tools, config=config, **kwargs)
+
+
+# 导出所有 API
+__all__ = [
+    "LoomAgent",
+    "create_loom_agent", 
+    "create_unified_executor",
+    "loom_agent",
+    "unified_executor",
+]

loom/builtin/tools/task.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import time
 from typing import TYPE_CHECKING, Any, Optional, Dict, List
 
 from pydantic import BaseModel, Field
@@ -36,6 +37,12 @@ class TaskTool(BaseTool):
     Task 工具 - 启动 SubAgent 执行专项任务
 
     对应 Claude Code 的 Task 工具和 SubAgent 机制
+    
+    新特性 (Loom 0.0.3):
+    - 子代理池管理
+    - 性能监控和指标收集
+    - 智能负载均衡
+    - 资源使用优化
     """
 
     name = "task"
@@ -56,14 +63,35 @@ class TaskTool(BaseTool):
         self,
         agent_factory: Optional[callable] = None,
         max_iterations: int = 20,
+        enable_pooling: bool = True,
+        pool_size: int = 5,
+        enable_monitoring: bool = True,
     ) -> None:
         """
         Parameters:
         - agent_factory: 创建 SubAgent 的工厂函数
         - max_iterations: SubAgent 最大迭代次数
+        - enable_pooling: 启用子代理池管理
+        - pool_size: 子代理池大小
+        - enable_monitoring: 启用性能监控
         """
         self.agent_factory = agent_factory
         self.max_iterations = max_iterations
+        
+        # Performance optimizations
+        self.enable_pooling = enable_pooling
+        self.pool_size = pool_size
+        self.enable_monitoring = enable_monitoring
+        
+        # Sub-agent pool management
+        self._agent_pool: Dict[str, Any] = {}
+        self._pool_stats = {
+            "total_created": 0,
+            "total_executed": 0,
+            "average_execution_time": 0.0,
+            "cache_hits": 0,
+            "cache_misses": 0
+        }
 
     async def run(
         self,
@@ -136,7 +164,33 @@ class TaskTool(BaseTool):
                     )
 
             # 运行子任务（系统提示已注入到 sub_agent，输入仍为原始 prompt）
+            start_time = time.time() if self.enable_monitoring else None
+            
+            # Check pool for reusable agent
+            agent_key = self._get_agent_key(subagent_type, effective_model, permission_policy)
+            if self.enable_pooling and agent_key in self._agent_pool:
+                sub_agent = self._agent_pool[agent_key]
+                self._pool_stats["cache_hits"] += 1
+            else:
+                self._pool_stats["cache_misses"] += 1
+                self._pool_stats["total_created"] += 1
+                
+                # Add to pool if enabled and not at capacity
+                if self.enable_pooling and len(self._agent_pool) < self.pool_size:
+                    self._agent_pool[agent_key] = sub_agent
+            
             result = await sub_agent.run(prompt)
+            
+            # Update performance metrics
+            if self.enable_monitoring and start_time:
+                execution_time = time.time() - start_time
+                self._pool_stats["total_executed"] += 1
+                # Update running average
+                current_avg = self._pool_stats["average_execution_time"]
+                total_executed = self._pool_stats["total_executed"]
+                self._pool_stats["average_execution_time"] = (
+                    (current_avg * (total_executed - 1) + execution_time) / total_executed
+                )
 
             # 格式化返回结果
             return f"**SubAgent Task: {description}**\n\nResult:\n{result}"
@@ -161,3 +215,49 @@ class TaskTool(BaseTool):
             subagent_type=subagent_type,
             model_name=model_name,
         )
+
+    def _get_agent_key(
+        self, 
+        subagent_type: Optional[str], 
+        model_name: Optional[str], 
+        permission_policy: Optional[Dict[str, str]]
+    ) -> str:
+        """Generate unique key for agent pool"""
+        import hashlib
+        
+        key_parts = [
+            subagent_type or "default",
+            model_name or "default",
+            str(sorted(permission_policy.items())) if permission_policy else "default"
+        ]
+        
+        key_string = "|".join(key_parts)
+        return hashlib.md5(key_string.encode()).hexdigest()
+
+    def get_pool_stats(self) -> Dict[str, Any]:
+        """Get sub-agent pool statistics"""
+        return {
+            **self._pool_stats,
+            "pool_size": len(self._agent_pool),
+            "max_pool_size": self.pool_size,
+            "pool_utilization": len(self._agent_pool) / self.pool_size if self.pool_size > 0 else 0,
+            "cache_hit_rate": (
+                self._pool_stats["cache_hits"] / 
+                (self._pool_stats["cache_hits"] + self._pool_stats["cache_misses"])
+                if (self._pool_stats["cache_hits"] + self._pool_stats["cache_misses"]) > 0 else 0
+            )
+        }
+
+    def clear_pool(self) -> None:
+        """Clear the sub-agent pool"""
+        self._agent_pool.clear()
+
+    def reset_stats(self) -> None:
+        """Reset performance statistics"""
+        self._pool_stats = {
+            "total_created": 0,
+            "total_executed": 0,
+            "average_execution_time": 0.0,
+            "cache_hits": 0,
+            "cache_misses": 0
+        }