claude-mpm 3.9.9__py3-none-any.whl → 4.0.3__py3-none-any.whl

claude_mpm/services/agents/deployment/validation/template_validator.py

@@ -0,0 +1,299 @@
+"""Template validator for agent templates."""
+
+import json
+from pathlib import Path
+from typing import Any, Dict, List
+
+from claude_mpm.core.logger import get_logger
+
+from .validation_result import ValidationResult, ValidationSeverity
+
+
+class TemplateValidator:
+    """Validator for agent template files.
+
+    This validator checks agent template JSON files for:
+    - Valid JSON syntax
+    - Required fields according to agent schema
+    - Field value validation
+    - Schema compliance
+    """
+
+    def __init__(self):
+        """Initialize the template validator."""
+        self.logger = get_logger(__name__)
+
+        # Required fields according to agent schema
+        self.required_fields = {
+            "schema_version": str,
+            "agent_id": str,
+            "agent_version": str,
+            "agent_type": str,
+            "metadata": dict,
+            "capabilities": dict,
+            "instructions": dict,
+        }
+
+        # Required metadata fields
+        self.required_metadata_fields = {
+            "name": str,
+            "description": str,
+            "category": str,
+            "tags": list,
+        }
+
+        # Required capabilities fields
+        self.required_capabilities_fields = {
+            "model": str,
+            "tools": list,
+        }
+
+        # Required instructions fields
+        self.required_instructions_fields = {
+            "system_prompt": str,
+        }
+
+    def validate_template_file(self, template_file: Path) -> ValidationResult:
+        """Validate a template file.
+
+        Args:
+            template_file: Path to template file
+
+        Returns:
+            ValidationResult with validation outcome
+        """
+        result = ValidationResult(is_valid=True)
+
+        # Check if file exists
+        if not template_file.exists():
+            result.add_error(f"Template file does not exist: {template_file}")
+            return result
+
+        # Check if it's a file
+        if not template_file.is_file():
+            result.add_error(f"Template path is not a file: {template_file}")
+            return result
+
+        try:
+            # Read and parse JSON
+            content = template_file.read_text(encoding="utf-8")
+            template_data = json.loads(content)
+
+            # Validate structure
+            self._validate_template_structure(template_data, result)
+
+            # Validate metadata
+            if "metadata" in template_data:
+                self._validate_metadata(template_data["metadata"], result)
+
+            # Validate capabilities
+            if "capabilities" in template_data:
+                self._validate_capabilities(template_data["capabilities"], result)
+
+            # Validate instructions
+            if "instructions" in template_data:
+                self._validate_instructions(template_data["instructions"], result)
+
+            # Validate agent ID format
+            if "agent_id" in template_data:
+                self._validate_agent_id(template_data["agent_id"], result)
+
+            # Add metadata
+            result.metadata["template_file"] = str(template_file)
+            result.metadata["agent_id"] = template_data.get("agent_id", "unknown")
+
+        except json.JSONDecodeError as e:
+            result.add_error(
+                f"Invalid JSON syntax: {e}", line_number=getattr(e, "lineno", None)
+            )
+        except UnicodeDecodeError as e:
+            result.add_error(f"File encoding error: {e}")
+        except Exception as e:
+            result.add_error(f"Unexpected error reading template: {e}")
+
+        return result
+
+    def _validate_template_structure(
+        self, template_data: Dict[str, Any], result: ValidationResult
+    ) -> None:
+        """Validate the basic template structure.
+
+        Args:
+            template_data: Template data dictionary
+            result: ValidationResult to update
+        """
+        # Check required fields
+        for field, expected_type in self.required_fields.items():
+            if field not in template_data:
+                result.add_error(f"Missing required field: {field}")
+            else:
+                value = template_data[field]
+                if not isinstance(value, expected_type):
+                    result.add_error(
+                        f"Field '{field}' should be {expected_type.__name__}, got {type(value).__name__}",
+                        field_name=field,
+                    )
+
+        # Check schema version
+        if "schema_version" in template_data:
+            schema_version = template_data["schema_version"]
+            if not schema_version.startswith("1."):
+                result.add_warning(
+                    f"Schema version '{schema_version}' may not be supported",
+                    field_name="schema_version",
+                    suggestion="Use schema version 1.x.x",
+                )
+
+    def _validate_metadata(
+        self, metadata: Dict[str, Any], result: ValidationResult
+    ) -> None:
+        """Validate metadata section.
+
+        Args:
+            metadata: Metadata dictionary
+            result: ValidationResult to update
+        """
+        for field, expected_type in self.required_metadata_fields.items():
+            if field not in metadata:
+                result.add_error(
+                    f"Missing required metadata field: {field}",
+                    field_name=f"metadata.{field}",
+                )
+            else:
+                value = metadata[field]
+                if not isinstance(value, expected_type):
+                    result.add_error(
+                        f"Metadata field '{field}' should be {expected_type.__name__}, got {type(value).__name__}",
+                        field_name=f"metadata.{field}",
+                    )
+
+        # Validate specific fields
+        if "name" in metadata:
+            name = metadata["name"]
+            if not name or not name.strip():
+                result.add_error(
+                    "Agent name cannot be empty", field_name="metadata.name"
+                )
+
+        if "description" in metadata:
+            description = metadata["description"]
+            if not description or not description.strip():
+                result.add_error(
+                    "Agent description cannot be empty",
+                    field_name="metadata.description",
+                )
+            elif len(description) < 10:
+                result.add_warning(
+                    "Agent description is very short",
+                    field_name="metadata.description",
+                    suggestion="Provide a more detailed description",
+                )
+
+        if "tags" in metadata:
+            tags = metadata["tags"]
+            if not isinstance(tags, list):
+                result.add_error("Tags should be a list", field_name="metadata.tags")
+            elif len(tags) == 0:
+                result.add_warning("No tags specified", field_name="metadata.tags")
+
+    def _validate_capabilities(
+        self, capabilities: Dict[str, Any], result: ValidationResult
+    ) -> None:
+        """Validate capabilities section.
+
+        Args:
+            capabilities: Capabilities dictionary
+            result: ValidationResult to update
+        """
+        for field, expected_type in self.required_capabilities_fields.items():
+            if field not in capabilities:
+                result.add_error(
+                    f"Missing required capabilities field: {field}",
+                    field_name=f"capabilities.{field}",
+                )
+            else:
+                value = capabilities[field]
+                if not isinstance(value, expected_type):
+                    result.add_error(
+                        f"Capabilities field '{field}' should be {expected_type.__name__}, got {type(value).__name__}",
+                        field_name=f"capabilities.{field}",
+                    )
+
+        # Validate model
+        if "model" in capabilities:
+            model = capabilities["model"]
+            valid_models = ["sonnet", "haiku", "opus"]
+            if model not in valid_models:
+                result.add_warning(
+                    f"Unknown model '{model}'",
+                    field_name="capabilities.model",
+                    suggestion=f"Use one of: {', '.join(valid_models)}",
+                )
+
+        # Validate tools
+        if "tools" in capabilities:
+            tools = capabilities["tools"]
+            if not isinstance(tools, list):
+                result.add_error(
+                    "Tools should be a list", field_name="capabilities.tools"
+                )
+            elif len(tools) == 0:
+                result.add_warning(
+                    "No tools specified", field_name="capabilities.tools"
+                )
+
+    def _validate_instructions(
+        self, instructions: Dict[str, Any], result: ValidationResult
+    ) -> None:
+        """Validate instructions section.
+
+        Args:
+            instructions: Instructions dictionary
+            result: ValidationResult to update
+        """
+        for field, expected_type in self.required_instructions_fields.items():
+            if field not in instructions:
+                result.add_error(
+                    f"Missing required instructions field: {field}",
+                    field_name=f"instructions.{field}",
+                )
+            else:
+                value = instructions[field]
+                if not isinstance(value, expected_type):
+                    result.add_error(
+                        f"Instructions field '{field}' should be {expected_type.__name__}, got {type(value).__name__}",
+                        field_name=f"instructions.{field}",
+                    )
+
+        # Validate system prompt
+        if "system_prompt" in instructions:
+            system_prompt = instructions["system_prompt"]
+            if not system_prompt or not system_prompt.strip():
+                result.add_error(
+                    "System prompt cannot be empty",
+                    field_name="instructions.system_prompt",
+                )
+            elif len(system_prompt) < 20:
+                result.add_warning(
+                    "System prompt is very short",
+                    field_name="instructions.system_prompt",
+                    suggestion="Provide more detailed instructions",
+                )
+
+    def _validate_agent_id(self, agent_id: str, result: ValidationResult) -> None:
+        """Validate agent ID format.
+
+        Args:
+            agent_id: Agent ID to validate
+            result: ValidationResult to update
+        """
+        import re
+
+        # Agent ID should be lowercase with hyphens
+        pattern = r"^[a-z][a-z0-9]*(-[a-z0-9]+)*$"
+        if not re.match(pattern, agent_id):
+            result.add_error(
+                f"Invalid agent ID format: '{agent_id}'",
+                field_name="agent_id",
+                suggestion="Use lowercase letters, numbers, and hyphens only (e.g., 'my-agent')",
+            )

claude_mpm/services/agents/deployment/validation/validation_result.py

@@ -0,0 +1,226 @@
+"""Validation result classes for deployment validation."""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+
+class ValidationSeverity(Enum):
+    """Severity levels for validation issues."""
+
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"
+    CRITICAL = "critical"
+
+
+@dataclass
+class ValidationIssue:
+    """A single validation issue."""
+
+    severity: ValidationSeverity
+    message: str
+    field_name: Optional[str] = None
+    line_number: Optional[int] = None
+    suggestion: Optional[str] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def __str__(self) -> str:
+        """String representation of the issue."""
+        parts = [f"[{self.severity.value.upper()}]"]
+
+        if self.field_name:
+            parts.append(f"Field '{self.field_name}':")
+
+        parts.append(self.message)
+
+        if self.line_number:
+            parts.append(f"(line {self.line_number})")
+
+        return " ".join(parts)
+
+
+@dataclass
+class ValidationResult:
+    """Result of a validation operation."""
+
+    is_valid: bool
+    issues: List[ValidationIssue] = field(default_factory=list)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def errors(self) -> List[ValidationIssue]:
+        """Get all error-level issues."""
+        return [
+            issue
+            for issue in self.issues
+            if issue.severity in [ValidationSeverity.ERROR, ValidationSeverity.CRITICAL]
+        ]
+
+    @property
+    def warnings(self) -> List[ValidationIssue]:
+        """Get all warning-level issues."""
+        return [
+            issue
+            for issue in self.issues
+            if issue.severity == ValidationSeverity.WARNING
+        ]
+
+    @property
+    def infos(self) -> List[ValidationIssue]:
+        """Get all info-level issues."""
+        return [
+            issue for issue in self.issues if issue.severity == ValidationSeverity.INFO
+        ]
+
+    @property
+    def has_errors(self) -> bool:
+        """Check if there are any errors."""
+        return len(self.errors) > 0
+
+    @property
+    def has_warnings(self) -> bool:
+        """Check if there are any warnings."""
+        return len(self.warnings) > 0
+
+    @property
+    def error_count(self) -> int:
+        """Get the number of errors."""
+        return len(self.errors)
+
+    @property
+    def warning_count(self) -> int:
+        """Get the number of warnings."""
+        return len(self.warnings)
+
+    def add_error(
+        self,
+        message: str,
+        field_name: Optional[str] = None,
+        line_number: Optional[int] = None,
+        suggestion: Optional[str] = None,
+    ) -> None:
+        """Add an error to the validation result.
+
+        Args:
+            message: Error message
+            field_name: Optional field name
+            line_number: Optional line number
+            suggestion: Optional suggestion for fixing
+        """
+        self.issues.append(
+            ValidationIssue(
+                severity=ValidationSeverity.ERROR,
+                message=message,
+                field_name=field_name,
+                line_number=line_number,
+                suggestion=suggestion,
+            )
+        )
+        self.is_valid = False
+
+    def add_warning(
+        self,
+        message: str,
+        field_name: Optional[str] = None,
+        line_number: Optional[int] = None,
+        suggestion: Optional[str] = None,
+    ) -> None:
+        """Add a warning to the validation result.
+
+        Args:
+            message: Warning message
+            field_name: Optional field name
+            line_number: Optional line number
+            suggestion: Optional suggestion for improvement
+        """
+        self.issues.append(
+            ValidationIssue(
+                severity=ValidationSeverity.WARNING,
+                message=message,
+                field_name=field_name,
+                line_number=line_number,
+                suggestion=suggestion,
+            )
+        )
+
+    def add_info(
+        self,
+        message: str,
+        field_name: Optional[str] = None,
+        line_number: Optional[int] = None,
+    ) -> None:
+        """Add an info message to the validation result.
+
+        Args:
+            message: Info message
+            field_name: Optional field name
+            line_number: Optional line number
+        """
+        self.issues.append(
+            ValidationIssue(
+                severity=ValidationSeverity.INFO,
+                message=message,
+                field_name=field_name,
+                line_number=line_number,
+            )
+        )
+
+    def merge(self, other: "ValidationResult") -> "ValidationResult":
+        """Merge another validation result into this one.
+
+        Args:
+            other: Another validation result to merge
+
+        Returns:
+            New ValidationResult with merged issues
+        """
+        merged = ValidationResult(
+            is_valid=self.is_valid and other.is_valid,
+            issues=self.issues + other.issues,
+            metadata={**self.metadata, **other.metadata},
+        )
+        return merged
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert validation result to dictionary.
+
+        Returns:
+            Dictionary representation of the result
+        """
+        return {
+            "is_valid": self.is_valid,
+            "error_count": self.error_count,
+            "warning_count": self.warning_count,
+            "issues": [
+                {
+                    "severity": issue.severity.value,
+                    "message": issue.message,
+                    "field": issue.field_name,
+                    "line_number": issue.line_number,
+                    "suggestion": issue.suggestion,
+                    "metadata": issue.metadata,
+                }
+                for issue in self.issues
+            ],
+            "metadata": self.metadata,
+        }
+
+    def __str__(self) -> str:
+        """String representation of the validation result."""
+        if self.is_valid:
+            status = "VALID"
+        else:
+            status = "INVALID"
+
+        summary = f"Validation {status}"
+
+        if self.error_count > 0:
+            summary += f" ({self.error_count} errors"
+            if self.warning_count > 0:
+                summary += f", {self.warning_count} warnings"
+            summary += ")"
+        elif self.warning_count > 0:
+            summary += f" ({self.warning_count} warnings)"
+
+        return summary

claude_mpm/services/agents/loading/__init__.py

@@ -1,11 +1,11 @@
 """Agent loading and profile management services."""
 
-from .framework_agent_loader import FrameworkAgentLoader
 from .agent_profile_loader import AgentProfileLoader
 from .base_agent_manager import BaseAgentManager
+from .framework_agent_loader import FrameworkAgentLoader
 
 __all__ = [
     "FrameworkAgentLoader",
     "AgentProfileLoader",
     "BaseAgentManager",
-]
+]