claude-mpm 1.0.0__py3-none-any.whl → 2.0.0__py3-none-any.whl

claude_mpm/schemas/agent_schema.json

@@ -0,0 +1,328 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Claude MPM Agent Schema",
+  "description": "Schema definition for Claude MPM agent templates",
+  "type": "object",
+  "required": ["id", "version", "metadata", "capabilities", "instructions"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9_]*$",
+      "description": "Unique agent identifier (lowercase, alphanumeric with underscores)",
+      "examples": ["research", "engineer", "qa", "security"]
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Semantic version of the agent template",
+      "examples": ["1.0.0", "2.1.3"]
+    },
+    "metadata": {
+      "type": "object",
+      "required": ["name", "description", "category", "tags"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 3,
+          "maxLength": 50,
+          "description": "Human-readable agent name"
+        },
+        "description": {
+          "type": "string",
+          "minLength": 10,
+          "maxLength": 200,
+          "description": "Brief description of agent purpose"
+        },
+        "category": {
+          "type": "string",
+          "enum": ["engineering", "research", "quality", "operations", "specialized"],
+          "description": "Agent category for organization"
+        },
+        "tags": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*$"
+          },
+          "minItems": 1,
+          "maxItems": 10,
+          "uniqueItems": true,
+          "description": "Tags for agent discovery"
+        },
+        "author": {
+          "type": "string",
+          "description": "Agent template author"
+        },
+        "created_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Creation timestamp"
+        },
+        "updated_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Last update timestamp"
+        }
+      }
+    },
+    "capabilities": {
+      "type": "object",
+      "required": ["model", "tools", "resource_tier"],
+      "properties": {
+        "model": {
+          "type": "string",
+          "enum": [
+            "claude-3-haiku-20240307",
+            "claude-3-5-haiku-20241022",
+            "claude-3-sonnet-20240229",
+            "claude-3-5-sonnet-20241022",
+            "claude-3-opus-20240229",
+            "claude-3-5-sonnet-20240620",
+            "claude-sonnet-4-20250514",
+            "claude-4-sonnet-20250514",
+            "claude-opus-4-20250514",
+            "claude-4-opus-20250514"
+          ],
+          "description": "Claude model to use for this agent"
+        },
+        "tools": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "Read", "Write", "Edit", "MultiEdit",
+              "Grep", "Glob", "LS", "Bash",
+              "WebSearch", "WebFetch",
+              "NotebookRead", "NotebookEdit",
+              "TodoWrite", "ExitPlanMode",
+              "git", "docker", "kubectl", "terraform",
+              "aws", "gcloud", "azure"
+            ]
+          },
+          "uniqueItems": true,
+          "description": "Available tools for the agent"
+        },
+        "resource_tier": {
+          "type": "string",
+          "enum": ["intensive", "standard", "lightweight"],
+          "description": "Resource allocation tier"
+        },
+        "max_tokens": {
+          "type": "integer",
+          "minimum": 1000,
+          "maximum": 200000,
+          "default": 8192,
+          "description": "Maximum tokens for response"
+        },
+        "temperature": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "default": 0.7,
+          "description": "Model temperature setting"
+        },
+        "timeout": {
+          "type": "integer",
+          "minimum": 30,
+          "maximum": 3600,
+          "default": 300,
+          "description": "Operation timeout in seconds"
+        },
+        "memory_limit": {
+          "type": "integer",
+          "minimum": 512,
+          "maximum": 8192,
+          "description": "Memory limit in MB (for resource tier)"
+        },
+        "cpu_limit": {
+          "type": "integer",
+          "minimum": 10,
+          "maximum": 100,
+          "description": "CPU limit percentage (for resource tier)"
+        },
+        "network_access": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether agent needs network access"
+        },
+        "file_access": {
+          "type": "object",
+          "properties": {
+            "read_paths": {
+              "type": "array",
+              "items": {"type": "string"},
+              "description": "Allowed read paths"
+            },
+            "write_paths": {
+              "type": "array",
+              "items": {"type": "string"},
+              "description": "Allowed write paths"
+            }
+          }
+        }
+      }
+    },
+    "instructions": {
+      "type": "string",
+      "minLength": 100,
+      "maxLength": 8000,
+      "description": "Agent system instructions (8000 character limit)"
+    },
+    "knowledge": {
+      "type": "object",
+      "description": "Agent-specific knowledge and context",
+      "properties": {
+        "domain_expertise": {
+          "type": "array",
+          "items": {"type": "string"},
+          "description": "Areas of expertise"
+        },
+        "best_practices": {
+          "type": "array",
+          "items": {"type": "string"},
+          "description": "Best practices the agent follows"
+        },
+        "constraints": {
+          "type": "array",
+          "items": {"type": "string"},
+          "description": "Operating constraints"
+        },
+        "examples": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "scenario": {"type": "string"},
+              "approach": {"type": "string"}
+            }
+          },
+          "description": "Example scenarios and approaches"
+        }
+      }
+    },
+    "interactions": {
+      "type": "object",
+      "description": "Agent interaction patterns",
+      "properties": {
+        "input_format": {
+          "type": "object",
+          "properties": {
+            "required_fields": {
+              "type": "array",
+              "items": {"type": "string"}
+            },
+            "optional_fields": {
+              "type": "array",
+              "items": {"type": "string"}
+            }
+          }
+        },
+        "output_format": {
+          "type": "object",
+          "properties": {
+            "structure": {
+              "type": "string",
+              "enum": ["markdown", "json", "structured", "free-form"]
+            },
+            "includes": {
+              "type": "array",
+              "items": {"type": "string"}
+            }
+          }
+        },
+        "handoff_agents": {
+          "type": "array",
+          "items": {"type": "string"},
+          "description": "Agents this agent can hand off to"
+        },
+        "triggers": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "condition": {"type": "string"},
+              "action": {"type": "string"}
+            }
+          },
+          "description": "Conditions that trigger specific actions"
+        }
+      }
+    },
+    "testing": {
+      "type": "object",
+      "description": "Testing configuration for the agent",
+      "properties": {
+        "test_cases": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["input", "expected_behavior"],
+            "properties": {
+              "name": {"type": "string"},
+              "input": {"type": "string"},
+              "expected_behavior": {"type": "string"},
+              "validation_criteria": {
+                "type": "array",
+                "items": {"type": "string"}
+              }
+            }
+          }
+        },
+        "performance_benchmarks": {
+          "type": "object",
+          "properties": {
+            "response_time": {"type": "integer"},
+            "token_usage": {"type": "integer"},
+            "success_rate": {"type": "number"}
+          }
+        }
+      }
+    },
+    "hooks": {
+      "type": "object",
+      "description": "Hook configurations for extensibility",
+      "properties": {
+        "pre_execution": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "name": {"type": "string"},
+              "enabled": {"type": "boolean"}
+            }
+          }
+        },
+        "post_execution": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "name": {"type": "string"},
+              "enabled": {"type": "boolean"}
+            }
+          }
+        }
+      }
+    }
+  },
+  "additionalProperties": false,
+  "definitions": {
+    "resource_tier_limits": {
+      "intensive": {
+        "memory_limit": {"min": 4096, "max": 8192},
+        "cpu_limit": {"min": 60, "max": 100},
+        "timeout": {"min": 600, "max": 3600}
+      },
+      "standard": {
+        "memory_limit": {"min": 2048, "max": 4096},
+        "cpu_limit": {"min": 30, "max": 60},
+        "timeout": {"min": 300, "max": 1200}
+      },
+      "lightweight": {
+        "memory_limit": {"min": 512, "max": 2048},
+        "cpu_limit": {"min": 10, "max": 30},
+        "timeout": {"min": 30, "max": 600}
+      }
+    }
+  }
+}

claude_mpm/services/agent_management_service.py

@@ -40,15 +40,15 @@ class AgentManager:
         Initialize AgentManager.
         
         Args:
-            framework_dir: Path to framework agent-roles directory
+            framework_dir: Path to agents templates directory
             project_dir: Path to project-specific agents directory
         """
         # Use PathResolver for consistent path discovery
         if framework_dir is None:
             try:
-                framework_root = PathResolver.get_framework_root()
-                self.framework_dir = framework_root / "framework" / "agent-roles"
-            except FileNotFoundError:
+                # Use agents templates directory
+                self.framework_dir = Path(__file__).parent.parent / "agents" / "templates"
+            except Exception:
                 # Fallback to agents directory
                 self.framework_dir = PathResolver.get_agents_dir()
         else:

claude_mpm/services/agent_profile_loader.py

@@ -118,7 +118,7 @@ class AgentProfileLoader(BaseService):
         self.tier_paths = {
             ProfileTier.PROJECT: self.working_directory / 'agents',
             ProfileTier.USER: self.user_home / '.claude-pm' / 'agents',
-            ProfileTier.SYSTEM: self.framework_path / 'agent-roles' if self.framework_path else None
+            ProfileTier.SYSTEM: Path(__file__).parent.parent / 'agents' / 'templates'
         }
         
         # Remove None values

claude_mpm/services/agent_registry.py

@@ -155,7 +155,6 @@ class AgentRegistry:
         # System-level agents - multiple possible locations
         system_paths = [
             Path(__file__).parent.parent / 'agents' / 'templates',
-            Path(__file__).parent.parent / 'framework' / 'agent-roles',
             Path('/opt/claude-pm/agents'),
             Path('/usr/local/claude-pm/agents')
         ]

claude_mpm/services/base_agent_manager.py

@@ -64,10 +64,10 @@ class BaseAgentStructure:
 class BaseAgentManager:
     """Manages base_agent.md with structured updates and validation."""
     
-    def __init__(self, framework_dir: Optional[Path] = None):
+    def __init__(self, agents_dir: Optional[Path] = None):
         """Initialize BaseAgentManager."""
-        self.framework_dir = framework_dir or Path(__file__).parent.parent.parent / "framework" / "agent-roles"
-        self.base_agent_path = self.framework_dir / "base_agent.md"
+        self.agents_dir = agents_dir or Path(__file__).parent.parent / "agents"
+        self.base_agent_path = self.agents_dir / "BASE_AGENT_TEMPLATE.md"
         self.cache = SharedPromptCache.get_instance()
         
     def read_base_agent(self) -> Optional[BaseAgentStructure]:

claude_mpm/utils/error_handler.py

@@ -0,0 +1,247 @@
+"""
+Enhanced error handling utilities for claude-mpm.
+
+Inspired by awesome-claude-code's comprehensive error handling approach.
+"""
+
+import logging
+import sys
+from typing import Optional, Type, Callable, Any, Dict
+from functools import wraps
+import traceback
+from datetime import datetime
+
+logger = logging.getLogger(__name__)
+
+
+class MPMError(Exception):
+    """Base exception for claude-mpm errors."""
+    
+    def __init__(self, message: str, details: Optional[Dict[str, Any]] = None, 
+                 suggestions: Optional[List[str]] = None):
+        """Initialize MPM error with details and suggestions."""
+        super().__init__(message)
+        self.details = details or {}
+        self.suggestions = suggestions or []
+        self.timestamp = datetime.now()
+    
+    def get_user_friendly_message(self) -> str:
+        """Get a user-friendly error message."""
+        lines = [f"❌ Error: {str(self)}"]
+        
+        if self.details:
+            lines.append("\nDetails:")
+            for key, value in self.details.items():
+                lines.append(f"  {key}: {value}")
+        
+        if self.suggestions:
+            lines.append("\n💡 Suggestions:")
+            for suggestion in self.suggestions:
+                lines.append(f"  - {suggestion}")
+        
+        return '\n'.join(lines)
+
+
+class AgentLoadError(MPMError):
+    """Raised when agent loading fails."""
+    pass
+
+
+class ValidationError(MPMError):
+    """Raised when validation fails."""
+    pass
+
+
+class ExecutionError(MPMError):
+    """Raised when agent execution fails."""
+    pass
+
+
+class ConfigurationError(MPMError):
+    """Raised when configuration is invalid."""
+    pass
+
+
+def handle_errors(error_type: Type[Exception] = Exception, 
+                 fallback_value: Any = None,
+                 log_level: int = logging.ERROR) -> Callable:
+    """
+    Decorator for handling errors with detailed logging and user feedback.
+    
+    Args:
+        error_type: Type of exception to catch
+        fallback_value: Value to return on error
+        log_level: Logging level for errors
+    """
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            try:
+                return func(*args, **kwargs)
+            except error_type as e:
+                # Log the error with full traceback
+                logger.log(log_level, f"Error in {func.__name__}: {e}", exc_info=True)
+                
+                # Provide user-friendly feedback
+                if isinstance(e, MPMError):
+                    print(e.get_user_friendly_message(), file=sys.stderr)
+                else:
+                    print(f"❌ Error: {e}", file=sys.stderr)
+                
+                return fallback_value
+            except Exception as e:
+                # Catch unexpected errors
+                logger.critical(f"Unexpected error in {func.__name__}: {e}", exc_info=True)
+                print(f"❌ Unexpected error: {e}", file=sys.stderr)
+                print("💡 This might be a bug. Please report it.", file=sys.stderr)
+                return fallback_value
+        
+        return wrapper
+    return decorator
+
+
+class ErrorContext:
+    """Context manager for enhanced error reporting."""
+    
+    def __init__(self, operation: str, details: Optional[Dict[str, Any]] = None):
+        """Initialize error context."""
+        self.operation = operation
+        self.details = details or {}
+    
+    def __enter__(self):
+        """Enter the context."""
+        logger.debug(f"Starting operation: {self.operation}")
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Exit the context, handling any errors."""
+        if exc_type is None:
+            logger.debug(f"Completed operation: {self.operation}")
+            return
+        
+        # Log the error with context
+        logger.error(
+            f"Error during {self.operation}: {exc_val}",
+            extra={'operation': self.operation, 'details': self.details},
+            exc_info=True
+        )
+        
+        # Don't suppress the exception
+        return False
+
+
+def retry_on_error(max_attempts: int = 3, 
+                  delay: float = 1.0,
+                  backoff_factor: float = 2.0,
+                  exceptions: tuple = (Exception,)) -> Callable:
+    """
+    Decorator for retrying operations on error.
+    
+    Args:
+        max_attempts: Maximum number of attempts
+        delay: Initial delay between attempts
+        backoff_factor: Multiplier for delay after each failure
+        exceptions: Tuple of exceptions to retry on
+    """
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        async def async_wrapper(*args, **kwargs):
+            import asyncio
+            
+            last_exception = None
+            current_delay = delay
+            
+            for attempt in range(max_attempts):
+                try:
+                    return await func(*args, **kwargs)
+                except exceptions as e:
+                    last_exception = e
+                    if attempt < max_attempts - 1:
+                        logger.warning(
+                            f"Attempt {attempt + 1}/{max_attempts} failed for {func.__name__}: {e}"
+                        )
+                        await asyncio.sleep(current_delay)
+                        current_delay *= backoff_factor
+                    else:
+                        logger.error(
+                            f"All {max_attempts} attempts failed for {func.__name__}"
+                        )
+            
+            raise last_exception
+        
+        @wraps(func)
+        def sync_wrapper(*args, **kwargs):
+            import time
+            
+            last_exception = None
+            current_delay = delay
+            
+            for attempt in range(max_attempts):
+                try:
+                    return func(*args, **kwargs)
+                except exceptions as e:
+                    last_exception = e
+                    if attempt < max_attempts - 1:
+                        logger.warning(
+                            f"Attempt {attempt + 1}/{max_attempts} failed for {func.__name__}: {e}"
+                        )
+                        time.sleep(current_delay)
+                        current_delay *= backoff_factor
+                    else:
+                        logger.error(
+                            f"All {max_attempts} attempts failed for {func.__name__}"
+                        )
+            
+            raise last_exception
+        
+        # Return appropriate wrapper based on function type
+        import asyncio
+        if asyncio.iscoroutinefunction(func):
+            return async_wrapper
+        else:
+            return sync_wrapper
+    
+    return decorator
+
+
+def format_exception_chain(exc: Exception) -> str:
+    """Format an exception chain for display."""
+    lines = []
+    current = exc
+    level = 0
+    
+    while current is not None:
+        indent = "  " * level
+        lines.append(f"{indent}{'└─' if level > 0 else ''}{type(current).__name__}: {current}")
+        
+        if hasattr(current, '__cause__'):
+            current = current.__cause__
+            level += 1
+        else:
+            break
+    
+    return '\n'.join(lines)
+
+
+# Setup patterns from awesome-claude-code
+def suggest_setup_fix(error: Exception) -> List[str]:
+    """Suggest fixes for common setup errors."""
+    suggestions = []
+    error_msg = str(error).lower()
+    
+    if 'git' in error_msg and 'not found' in error_msg:
+        suggestions.append("Install git from https://git-scm.com/downloads")
+    
+    if 'python' in error_msg and 'module' in error_msg:
+        suggestions.append("Ensure you're in a virtual environment")
+        suggestions.append("Run: pip install -e .")
+    
+    if 'permission' in error_msg:
+        suggestions.append("Check file permissions")
+        suggestions.append("You may need to run with appropriate privileges")
+    
+    if 'config' in error_msg or 'configuration' in error_msg:
+        suggestions.append("Check your configuration files")
+        suggestions.append("Run: mpm validate-config")
+    
+    return suggestions

claude_mpm/validation/__init__.py

@@ -0,0 +1,5 @@
+"""Validation framework for claude-mpm."""
+
+from .agent_validator import AgentValidator, ValidationResult
+
+__all__ = ['AgentValidator', 'ValidationResult']