crackerjack 0.31.10__py3-none-any.whl → 0.31.13__py3-none-any.whl

crackerjack/intelligence/agent_orchestrator.py

@@ -1,9 +1,3 @@
-"""Multi-Agent Execution Orchestrator.
-
-Coordinates execution of multiple agents with smart routing, fallback strategies,
-and result aggregation.
-"""
-
 import asyncio
 import logging
 import typing as t
@@ -22,26 +16,20 @@ from .agent_selector import AgentScore, AgentSelector, TaskDescription
 
 
 class ExecutionStrategy(Enum):
-    """Strategy for multi-agent execution."""
-
-    SINGLE_BEST = "single_best"  # Use only the highest-scored agent
-    PARALLEL = "parallel"  # Run multiple agents in parallel
-    SEQUENTIAL = "sequential"  # Run agents one by one until success
-    CONSENSUS = "consensus"  # Run multiple agents and compare results
+    SINGLE_BEST = "single_best"
+    PARALLEL = "parallel"
+    SEQUENTIAL = "sequential"
+    CONSENSUS = "consensus"
 
 
 class ExecutionMode(Enum):
-    """Mode of execution."""
-
-    AUTONOMOUS = "autonomous"  # Full automation
-    GUIDED = "guided"  # With human oversight
-    ADVISORY = "advisory"  # Recommendations only
+    AUTONOMOUS = "autonomous"
+    GUIDED = "guided"
+    ADVISORY = "advisory"
 
 
 @dataclass
 class ExecutionRequest:
-    """Request for agent execution."""
-
     task: TaskDescription
     strategy: ExecutionStrategy = ExecutionStrategy.SINGLE_BEST
     mode: ExecutionMode = ExecutionMode.AUTONOMOUS
@@ -53,11 +41,9 @@ class ExecutionRequest:
 
 @dataclass
 class ExecutionResult:
-    """Result of agent execution."""
-
     success: bool
-    primary_result: t.Any | None  # Main result from best agent
-    all_results: list[tuple[RegisteredAgent, t.Any]]  # All agent results
+    primary_result: t.Any | None
+    all_results: list[tuple[RegisteredAgent, t.Any]]
     execution_time: float
     agents_used: list[str]
     strategy_used: ExecutionStrategy
@@ -66,8 +52,6 @@ class ExecutionResult:
 
 
 class AgentOrchestrator:
-    """Multi-agent execution orchestrator."""
-
     def __init__(
         self,
         registry: AgentRegistry | None = None,
@@ -79,7 +63,6 @@ class AgentOrchestrator:
         self._execution_stats: dict[str, int] = {}
 
     async def execute(self, request: ExecutionRequest) -> ExecutionResult:
-        """Execute a request using the intelligent agent system."""
         start_time = asyncio.get_event_loop().time()
 
         try:
@@ -88,7 +71,6 @@ class AgentOrchestrator:
                 f"(strategy: {request.strategy.value})"
             )
 
-            # Get agent candidates
             candidates = await self.selector.select_agents(
                 request.task, max_candidates=request.max_agents
             )
@@ -100,7 +82,6 @@ class AgentOrchestrator:
                     request.strategy,
                 )
 
-            # Execute based on strategy
             if request.strategy == ExecutionStrategy.SINGLE_BEST:
                 result = await self._execute_single_best(request, candidates)
             elif request.strategy == ExecutionStrategy.PARALLEL:
@@ -115,14 +96,13 @@ class AgentOrchestrator:
             execution_time = asyncio.get_event_loop().time() - start_time
             result.execution_time = execution_time
 
-            # Update stats
             for agent_name in result.agents_used:
                 self._execution_stats[agent_name] = (
                     self._execution_stats.get(agent_name, 0) + 1
                 )
 
             self.logger.info(
-                f"Execution completed in {execution_time:.2f}s: "
+                f"Execution completed in {execution_time: .2f}s: "
                 f"{'success' if result.success else 'failure'} "
                 f"using {len(result.agents_used)} agents"
             )
@@ -142,7 +122,6 @@ class AgentOrchestrator:
         request: ExecutionRequest,
         candidates: list[AgentScore],
     ) -> ExecutionResult:
-        """Execute using the single best agent."""
         best_candidate = candidates[0]
 
         try:
@@ -152,14 +131,13 @@ class AgentOrchestrator:
                 success=True,
                 primary_result=result,
                 all_results=[(best_candidate.agent, result)],
-                execution_time=0.0,  # Will be set by caller
+                execution_time=0.0,
                 agents_used=[best_candidate.agent.metadata.name],
                 strategy_used=ExecutionStrategy.SINGLE_BEST,
                 recommendations=self._generate_recommendations(best_candidate),
             )
 
         except Exception as e:
-            # Fallback to next best agent if available
             if len(candidates) > 1 and request.fallback_to_system:
                 self.logger.warning(
                     f"Primary agent {best_candidate.agent.metadata.name} failed: {e}. "
@@ -172,7 +150,7 @@ class AgentOrchestrator:
                     mode=request.mode,
                     max_agents=len(candidates) - 1,
                     timeout_seconds=request.timeout_seconds,
-                    fallback_to_system=False,  # Prevent infinite recursion
+                    fallback_to_system=False,
                     context=request.context,
                 )
 
@@ -193,7 +171,6 @@ class AgentOrchestrator:
         request: ExecutionRequest,
         candidates: list[AgentScore],
     ) -> ExecutionResult:
-        """Execute multiple agents in parallel."""
         tasks = []
         agents_to_execute = candidates[: request.max_agents]
 
@@ -203,7 +180,6 @@ class AgentOrchestrator:
             )
             tasks.append((candidate.agent, task))
 
-        # Wait for all tasks to complete
         results = []
         successful_results = []
 
@@ -218,12 +194,10 @@ class AgentOrchestrator:
             except Exception as e:
                 results.append((agent, e))
 
-        # Choose best successful result
         primary_result = None
         agents_used = []
 
         if successful_results:
-            # Use result from highest-priority agent
             successful_results.sort(key=lambda x: x[0].metadata.priority, reverse=True)
             primary_result = successful_results[0][1]
             agents_used = [agent.metadata.name for agent, _ in successful_results]
@@ -243,7 +217,6 @@ class AgentOrchestrator:
         request: ExecutionRequest,
         candidates: list[AgentScore],
     ) -> ExecutionResult:
-        """Execute agents sequentially until one succeeds."""
         results = []
 
         for candidate in candidates[: request.max_agents]:
@@ -255,7 +228,6 @@ class AgentOrchestrator:
 
                 results.append((candidate.agent, result))
 
-                # Success - return immediately
                 return ExecutionResult(
                     success=True,
                     primary_result=result,
@@ -273,7 +245,6 @@ class AgentOrchestrator:
                 )
                 continue
 
-        # All agents failed
         return ExecutionResult(
             success=False,
             primary_result=None,
@@ -289,13 +260,11 @@ class AgentOrchestrator:
         request: ExecutionRequest,
         candidates: list[AgentScore],
     ) -> ExecutionResult:
-        """Execute multiple agents and build consensus from results."""
-        # First run parallel execution
         parallel_request = ExecutionRequest(
             task=request.task,
             strategy=ExecutionStrategy.PARALLEL,
             mode=request.mode,
-            max_agents=min(request.max_agents, 3),  # Limit for consensus
+            max_agents=min(request.max_agents, 3),
             timeout_seconds=request.timeout_seconds,
             fallback_to_system=False,
             context=request.context,
@@ -306,7 +275,6 @@ class AgentOrchestrator:
         if not parallel_result.success:
             return parallel_result
 
-        # Analyze results for consensus
         successful_results = [
             (agent, result)
             for agent, result in parallel_result.all_results
@@ -314,10 +282,8 @@ class AgentOrchestrator:
         ]
 
         if len(successful_results) < 2:
-            # Not enough results for consensus - return best result
             return parallel_result
 
-        # Build consensus (simplified - could be much more sophisticated)
         consensus_result = self._build_consensus(successful_results)
 
         return ExecutionResult(
@@ -333,15 +299,11 @@ class AgentOrchestrator:
     async def _execute_agent(
         self, agent: RegisteredAgent, request: ExecutionRequest
     ) -> t.Any:
-        """Execute a specific agent."""
         if agent.agent is not None:
-            # Crackerjack agent
             return await self._execute_crackerjack_agent(agent, request)
         elif agent.agent_path is not None:
-            # User agent
             return await self._execute_user_agent(agent, request)
         elif agent.subagent_type is not None:
-            # System agent
             return await self._execute_system_agent(agent, request)
         else:
             raise ValueError(f"Invalid agent configuration: {agent.metadata.name}")
@@ -349,7 +311,6 @@ class AgentOrchestrator:
     async def _execute_agent_safe(
         self, agent: RegisteredAgent, request: ExecutionRequest
     ) -> t.Any:
-        """Execute an agent with exception handling."""
         try:
             return await self._execute_agent(agent, request)
         except Exception as e:
@@ -360,20 +321,17 @@ class AgentOrchestrator:
         agent: RegisteredAgent,
         request: ExecutionRequest,
     ) -> t.Any:
-        """Execute a built-in crackerjack agent."""
         if not agent.agent:
             raise ValueError("No crackerjack agent instance available")
 
-        # Convert task to Issue for crackerjack agents
         issue = Issue(
             id="orchestrated_task",
             type=self._map_task_to_issue_type(request.task),
             severity=self._map_task_priority_to_severity(request.task),
             message=request.task.description,
-            file_path=None,  # Could be extracted from task if needed
+            file_path=None,
         )
 
-        # Execute agent
         result = await agent.agent.analyze_and_fix(issue)
         return result
 
@@ -382,11 +340,8 @@ class AgentOrchestrator:
         agent: RegisteredAgent,
         request: ExecutionRequest,
     ) -> t.Any:
-        """Execute a user agent via Task tool."""
-        # Import Task tool dynamically to avoid circular imports
         from crackerjack.mcp.tools.core_tools import create_task_with_subagent
 
-        # Use Task tool to execute user agent
         result = await create_task_with_subagent(
             description=f"Execute task using {agent.metadata.name}",
             prompt=request.task.description,
@@ -400,14 +355,11 @@ class AgentOrchestrator:
         agent: RegisteredAgent,
         request: ExecutionRequest,
     ) -> t.Any:
-        """Execute a system agent via Task tool."""
         if not agent.subagent_type:
             raise ValueError("No subagent type specified for system agent")
 
-        # Import Task tool dynamically
         from crackerjack.mcp.tools.core_tools import create_task_with_subagent
 
-        # Use Task tool to execute system agent
         result = await create_task_with_subagent(
             description=f"Execute task using {agent.metadata.name}",
             prompt=request.task.description,
@@ -417,11 +369,8 @@ class AgentOrchestrator:
         return result
 
     def _map_task_to_issue_type(self, task: TaskDescription):
-        """Map task context to Issue type for crackerjack agents."""
-        # Import IssueType here to avoid circular imports
         from crackerjack.agents.base import IssueType
 
-        # Simple mapping - could be more sophisticated
         context_map = {
             "code_quality": IssueType.FORMATTING,
             "refactoring": IssueType.COMPLEXITY,
@@ -434,7 +383,6 @@ class AgentOrchestrator:
         if task.context and task.context.value in context_map:
             return context_map[task.context.value]
 
-        # Analyze task description for hints
         desc_lower = task.description.lower()
         if "test" in desc_lower:
             return IssueType.TEST_FAILURE
@@ -445,10 +393,9 @@ class AgentOrchestrator:
         elif "format" in desc_lower:
             return IssueType.FORMATTING
 
-        return IssueType.FORMATTING  # Default
+        return IssueType.FORMATTING
 
     def _map_task_priority_to_severity(self, task: TaskDescription):
-        """Map task priority to Issue severity."""
         from crackerjack.agents.base import Priority
 
         if task.priority >= 80:
@@ -459,14 +406,10 @@ class AgentOrchestrator:
         return Priority.LOW
 
     def _build_consensus(self, results: list[tuple[RegisteredAgent, t.Any]]) -> t.Any:
-        """Build consensus from multiple agent results."""
-        # Simplified consensus - could be much more sophisticated
-        # For now, just return the result from the highest-priority agent
         results.sort(key=lambda x: x[0].metadata.priority, reverse=True)
         return results[0][1]
 
     def _generate_recommendations(self, candidate: AgentScore) -> list[str]:
-        """Generate recommendations based on agent selection."""
         recommendations = []
 
         if candidate.final_score > 0.8:
@@ -491,7 +434,6 @@ class AgentOrchestrator:
         start_time: float,
         strategy: ExecutionStrategy,
     ) -> ExecutionResult:
-        """Create an error result."""
         execution_time = asyncio.get_event_loop().time() - start_time
 
         return ExecutionResult(
@@ -505,7 +447,6 @@ class AgentOrchestrator:
         )
 
     def get_execution_stats(self) -> dict[str, t.Any]:
-        """Get execution statistics."""
         from operator import itemgetter
 
         return {
@@ -519,10 +460,8 @@ class AgentOrchestrator:
         }
 
     async def analyze_task_routing(self, task: TaskDescription) -> dict[str, t.Any]:
-        """Analyze how a task would be routed through the system."""
         analysis = await self.selector.analyze_task_complexity(task)
 
-        # Add orchestration recommendations
         if analysis["complexity_level"] == "high":
             analysis["recommended_strategy"] = ExecutionStrategy.CONSENSUS
         elif analysis["candidate_count"] > 3:
@@ -535,12 +474,10 @@ class AgentOrchestrator:
         return analysis
 
 
-# Global orchestrator instance
 _orchestrator_instance: AgentOrchestrator | None = None
 
 
 async def get_agent_orchestrator() -> AgentOrchestrator:
-    """Get or create the global agent orchestrator."""
     global _orchestrator_instance
 
     if _orchestrator_instance is None:

crackerjack/intelligence/agent_registry.py

@@ -1,9 +1,3 @@
-"""Intelligent Agent Registry System.
-
-Unifies access to crackerjack agents, user agents, and system agents with smart
-prioritization and capability mapping.
-"""
-
 import logging
 import typing as t
 from dataclasses import dataclass
@@ -14,16 +8,12 @@ from crackerjack.agents.base import SubAgent, agent_registry
 
 
 class AgentSource(Enum):
-    """Source of an agent."""
-
     CRACKERJACK = "crackerjack"
     USER = "user"
     SYSTEM = "system"
 
 
 class AgentCapability(Enum):
-    """Agent capability categories."""
-
     ARCHITECTURE = "architecture"
     REFACTORING = "refactoring"
     TESTING = "testing"
@@ -38,13 +28,11 @@ class AgentCapability(Enum):
 
 @dataclass
 class AgentMetadata:
-    """Metadata about an agent."""
-
     name: str
     source: AgentSource
     capabilities: set[AgentCapability]
-    priority: int  # Higher is better
-    confidence_factor: float  # Multiplier for confidence scores
+    priority: int
+    confidence_factor: float
     description: str
     model: str | None = None
     tags: list[str] | None = None
@@ -52,17 +40,13 @@ class AgentMetadata:
 
 @dataclass
 class RegisteredAgent:
-    """A registered agent with metadata and access."""
-
     metadata: AgentMetadata
-    agent: SubAgent | None = None  # None for user/system agents
-    agent_path: Path | None = None  # Path to user agent file
-    subagent_type: str | None = None  # For system agents
+    agent: SubAgent | None = None
+    agent_path: Path | None = None
+    subagent_type: str | None = None
 
 
 class AgentRegistry:
-    """Registry of all available agents across all systems."""
-
     def __init__(self) -> None:
         self.logger = logging.getLogger(__name__)
         self._agents: dict[str, RegisteredAgent] = {}
@@ -70,15 +54,12 @@ class AgentRegistry:
         self._user_agent_cache: dict[str, dict[str, t.Any]] = {}
 
     async def initialize(self) -> None:
-        """Initialize the registry with all available agents."""
         self.logger.info("Initializing Intelligent Agent Registry")
 
-        # Load agents in priority order
         await self._register_crackerjack_agents()
         await self._register_user_agents()
         await self._register_system_agents()
 
-        # Build capability mapping
         self._build_capability_map()
 
         self.logger.info(
@@ -89,13 +70,10 @@ class AgentRegistry:
         )
 
     async def _register_crackerjack_agents(self) -> None:
-        """Register built-in crackerjack agents."""
         self.logger.debug("Registering crackerjack agents")
 
-        # Get all registered crackerjack agents
         from crackerjack.agents.base import AgentContext
 
-        # Create a dummy context to get agents
         context = AgentContext(
             project_path=Path.cwd(),
         )
@@ -109,7 +87,7 @@ class AgentRegistry:
                 name=agent.name,
                 source=AgentSource.CRACKERJACK,
                 capabilities=capabilities,
-                priority=100,  # Highest priority
+                priority=100,
                 confidence_factor=1.0,
                 description=f"Built-in crackerjack {agent.__class__.__name__}",
             )
@@ -123,7 +101,6 @@ class AgentRegistry:
             self.logger.debug(f"Registered crackerjack agent: {agent.name}")
 
     async def _register_user_agents(self) -> None:
-        """Register user agents from ~/.claude/agents/."""
         self.logger.debug("Registering user agents")
 
         user_agents_dir = Path.home() / ".claude" / "agents"
@@ -141,7 +118,7 @@ class AgentRegistry:
                         name=agent_data["name"],
                         source=AgentSource.USER,
                         capabilities=capabilities,
-                        priority=80,  # Second priority
+                        priority=80,
                         confidence_factor=0.9,
                         description=agent_data.get("description", "User agent"),
                         model=agent_data.get("model"),
@@ -161,10 +138,8 @@ class AgentRegistry:
                 self.logger.warning(f"Failed to parse user agent {agent_file}: {e}")
 
     async def _register_system_agents(self) -> None:
-        """Register built-in system agents from Task tool."""
         self.logger.debug("Registering system agents")
 
-        # Known system agents from Task tool
         system_agents = [
             (
                 "general-purpose",
@@ -186,7 +161,7 @@ class AgentRegistry:
                 name=agent_name,
                 source=AgentSource.SYSTEM,
                 capabilities=capabilities,
-                priority=60,  # Lowest priority
+                priority=60,
                 confidence_factor=0.7,
                 description=description,
             )
@@ -200,7 +175,6 @@ class AgentRegistry:
             self.logger.debug(f"Registered system agent: {agent_name}")
 
     async def _parse_user_agent_file(self, agent_file: Path) -> dict[str, t.Any] | None:
-        """Parse a user agent markdown file."""
         try:
             content = agent_file.read_text(encoding="utf-8")
             return self._extract_agent_data_from_content(content)
@@ -209,8 +183,7 @@ class AgentRegistry:
             return None
 
     def _extract_agent_data_from_content(self, content: str) -> dict[str, t.Any] | None:
-        """Extract agent data from file content."""
-        if not content.startswith("---\n"):
+        if not content.startswith("- --\n"):
             return None
 
         lines = content.split("\n")
@@ -222,30 +195,26 @@ class AgentRegistry:
         return self._build_agent_data(lines, yaml_end)
 
     def _find_yaml_end_marker(self, lines: list[str]) -> int:
-        """Find the end marker for YAML frontmatter."""
         for i, line in enumerate(lines[1:], 1):
-            if line == "---":
+            if line == "- --":
                 return i
         return -1
 
     def _build_agent_data(self, lines: list[str], yaml_end: int) -> dict[str, t.Any]:
-        """Build agent data from parsed lines."""
         yaml_lines = lines[1:yaml_end]
         agent_data = {}
 
         for line in yaml_lines:
-            if ":" in line:
-                key, value = line.split(":", 1)
+            if ": " in line:
+                key, value = line.split(": ", 1)
                 agent_data[key.strip()] = value.strip()
 
         agent_data["content"] = "\n".join(lines[yaml_end + 1 :])
         return agent_data
 
     def _infer_capabilities_from_agent(self, agent: SubAgent) -> set[AgentCapability]:
-        """Infer capabilities from a crackerjack agent."""
         capabilities = set()
 
-        # Map agent class names to capabilities
         class_name = agent.__class__.__name__.lower()
 
         if "architect" in class_name:
@@ -269,7 +238,6 @@ class AgentRegistry:
         if "dry" in class_name:
             capabilities.add(AgentCapability.REFACTORING)
 
-        # Fallback to general code analysis
         if not capabilities:
             capabilities.add(AgentCapability.CODE_ANALYSIS)
 
@@ -278,7 +246,6 @@ class AgentRegistry:
     def _infer_capabilities_from_user_agent(
         self, agent_data: dict[str, t.Any]
     ) -> set[AgentCapability]:
-        """Infer capabilities from user agent metadata."""
         capabilities = set()
 
         name = agent_data.get("name", "").lower()
@@ -287,7 +254,6 @@ class AgentRegistry:
 
         text = f"{name} {description} {content}"
 
-        # Keyword mapping
         keyword_map = {
             AgentCapability.ARCHITECTURE: [
                 "architect",
@@ -320,7 +286,6 @@ class AgentRegistry:
             if any(keyword in text for keyword in keywords):
                 capabilities.add(capability)
 
-        # Fallback
         if not capabilities:
             capabilities.add(AgentCapability.CODE_ANALYSIS)
 
@@ -329,7 +294,6 @@ class AgentRegistry:
     def _infer_capabilities_from_system_agent(
         self, name: str, description: str
     ) -> set[AgentCapability]:
-        """Infer capabilities from system agent."""
         capabilities = set()
 
         text = f"{name} {description}".lower()
@@ -341,14 +305,12 @@ class AgentRegistry:
         if "output" in text or "style" in text:
             capabilities.add(AgentCapability.FORMATTING)
 
-        # Fallback
         if not capabilities:
             capabilities.add(AgentCapability.CODE_ANALYSIS)
 
         return capabilities
 
     def _build_capability_map(self) -> None:
-        """Build mapping from capabilities to agent names."""
         self._capability_map.clear()
 
         for agent_name, registered_agent in self._agents.items():
@@ -357,7 +319,6 @@ class AgentRegistry:
                     self._capability_map[capability] = []
                 self._capability_map[capability].append(agent_name)
 
-        # Sort by priority within each capability
         for agent_names in self._capability_map.values():
             agent_names.sort(
                 key=lambda name: self._agents[name].metadata.priority, reverse=True
@@ -366,36 +327,30 @@ class AgentRegistry:
     def get_agents_by_capability(
         self, capability: AgentCapability
     ) -> list[RegisteredAgent]:
-        """Get agents that have a specific capability, sorted by priority."""
         agent_names = self._capability_map.get(capability, [])
         return [self._agents[name] for name in agent_names]
 
     def get_agent_by_name(self, name: str) -> RegisteredAgent | None:
-        """Get a specific agent by name."""
         return self._agents.get(name)
 
     def list_all_agents(self) -> list[RegisteredAgent]:
-        """List all registered agents, sorted by priority."""
         agents = list(self._agents.values())
         agents.sort(key=lambda a: a.metadata.priority, reverse=True)
         return agents
 
     def get_agent_stats(self) -> dict[str, t.Any]:
-        """Get statistics about registered agents."""
         stats: dict[str, t.Any] = {
             "total_agents": len(self._agents),
             "by_source": {},
             "by_capability": {},
         }
 
-        # Count by source
         for source in AgentSource:
             count = len(
                 [a for a in self._agents.values() if a.metadata.source == source]
             )
             stats["by_source"][source.value] = count
 
-        # Count by capability
         for capability in AgentCapability:
             count = len(self._capability_map.get(capability, []))
             stats["by_capability"][capability.value] = count
@@ -403,12 +358,10 @@ class AgentRegistry:
         return stats
 
 
-# Global registry instance
 agent_registry_instance = AgentRegistry()
 
 
 async def get_agent_registry() -> AgentRegistry:
-    """Get the initialized agent registry."""
     if not agent_registry_instance._agents:
         await agent_registry_instance.initialize()
     return agent_registry_instance