claude-mpm 3.1.2__py3-none-any.whl → 3.1.3__py3-none-any.whl

claude_mpm/models/__init__.py

@@ -1,24 +1,106 @@
 """
-Agent models package.
+Claude MPM Models Package
+=========================
 
-WHY: This package centralizes all data models used for agent management,
-providing a single source of truth for data structures across the system.
+Centralized data models for the Claude MPM system.
+
+WHY: This package centralizes all data models to:
+- Prevent circular imports
+- Reduce code duplication
+- Ensure consistent data structures
+- Make models easily discoverable
+
+DESIGN DECISION: Models are organized by domain:
+- agent_definition: Core agent behavior models
+- lifecycle: Agent lifecycle management models
+- modification: Change tracking models
+- persistence: Storage operation models
+- registry: Discovery and management models
+- common: Shared constants and enums
 """
 
+# Agent definition models
 from .agent_definition import (
-    AgentDefinition,
-    AgentMetadata,
     AgentType,
     AgentSection,
+    AgentPermissions,
     AgentWorkflow,
-    AgentPermissions
+    AgentMetadata,
+    AgentDefinition
+)
+
+# Lifecycle models
+from .lifecycle import (
+    LifecycleOperation,
+    LifecycleState,
+    AgentLifecycleRecord,
+    LifecycleOperationResult
+)
+
+# Modification models
+from .modification import (
+    ModificationType,
+    ModificationTier,
+    AgentModification,
+    ModificationHistory
+)
+
+# Persistence models
+from .persistence import (
+    PersistenceStrategy,
+    PersistenceOperation,
+    PersistenceRecord
+)
+
+# Registry models
+from .registry import (
+    AgentTier,
+    AgentRegistryMetadata
+)
+
+# Common constants
+from .common import (
+    AGENT_FILE_EXTENSIONS,
+    AGENT_IGNORE_PATTERNS,
+    CORE_AGENT_TYPES,
+    SPECIALIZED_AGENT_TYPES,
+    ALL_AGENT_TYPES
 )
 
 __all__ = [
-    'AgentDefinition',
-    'AgentMetadata',
+    # Agent definition
     'AgentType',
     'AgentSection',
+    'AgentPermissions',
     'AgentWorkflow',
-    'AgentPermissions'
+    'AgentMetadata',
+    'AgentDefinition',
+    
+    # Lifecycle
+    'LifecycleOperation',
+    'LifecycleState',
+    'AgentLifecycleRecord',
+    'LifecycleOperationResult',
+    
+    # Modification
+    'ModificationType',
+    'ModificationTier',
+    'AgentModification',
+    'ModificationHistory',
+    
+    # Persistence
+    'PersistenceStrategy',
+    'PersistenceOperation',
+    'PersistenceRecord',
+    
+    # Registry
+    'AgentTier',
+    'AgentRegistryMetadata',
+    
+    # Common
+    'AGENT_FILE_EXTENSIONS',
+    'AGENT_IGNORE_PATTERNS',
+    'CORE_AGENT_TYPES',
+    'SPECIALIZED_AGENT_TYPES',
+    'ALL_AGENT_TYPES'
 ]

claude_mpm/models/common.py

@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+"""
+Common Models
+=============
+
+Shared enums and models used across multiple services.
+
+WHY: This module contains enums and models that are used by multiple
+services but don't belong to any specific domain.
+
+DESIGN DECISION: Creating a common module prevents:
+- Circular imports between specific model modules
+- Duplication of shared enums
+- Inconsistencies in shared constants
+"""
+
+from enum import Enum
+
+
+# Note: We're not creating a unified TierType enum here because:
+# 1. ModificationTier uses PROJECT/USER/SYSTEM for modification tracking
+# 2. AgentTier uses USER/SYSTEM for registry discovery
+# 3. AgentType in agent_definition.py is for agent classification (CORE/PROJECT/CUSTOM/etc)
+# These serve different purposes and should remain separate.
+
+# Common constants that might be shared across services
+AGENT_FILE_EXTENSIONS = {'.md', '.json', '.yaml', '.yml'}
+AGENT_IGNORE_PATTERNS = {'__pycache__', '.git', 'node_modules', '.pytest_cache'}
+
+# Core agent types used for classification
+CORE_AGENT_TYPES = {
+    'engineer', 'architect', 'qa', 'security', 'documentation',
+    'ops', 'data', 'research', 'version_control'
+}
+
+SPECIALIZED_AGENT_TYPES = {
+    'pm_orchestrator', 'frontend', 'backend', 'devops', 'ml',
+    'database', 'api', 'mobile', 'cloud', 'testing'
+}
+
+ALL_AGENT_TYPES = CORE_AGENT_TYPES | SPECIALIZED_AGENT_TYPES

claude_mpm/models/lifecycle.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""
+Lifecycle Models
+================
+
+Data models for agent lifecycle management.
+
+WHY: These models are extracted from agent_lifecycle_manager.py to centralize
+data definitions and reduce duplication across services.
+
+DESIGN DECISION: Keeping lifecycle-specific models separate allows:
+- Clear separation of concerns
+- Easy reuse across different services
+- Independent evolution of data structures
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Dict, List, Optional, Any
+
+from claude_mpm.models.modification import ModificationTier
+
+
+class LifecycleOperation(Enum):
+    """Agent lifecycle operations."""
+    CREATE = "create"
+    UPDATE = "update"
+    DELETE = "delete"
+    RESTORE = "restore"
+    MIGRATE = "migrate"
+    REPLICATE = "replicate"
+    VALIDATE = "validate"
+
+
+class LifecycleState(Enum):
+    """Agent lifecycle states."""
+    ACTIVE = "active"
+    MODIFIED = "modified"
+    DELETED = "deleted"
+    CONFLICTED = "conflicted"
+    MIGRATING = "migrating"
+    VALIDATING = "validating"
+
+
+@dataclass
+class AgentLifecycleRecord:
+    """Complete lifecycle record for an agent.
+    
+    WHY: This model tracks the complete history and state of an agent
+    throughout its lifecycle, enabling audit trails and state management.
+    """
+    
+    agent_name: str
+    current_state: LifecycleState
+    tier: ModificationTier
+    file_path: str
+    created_at: float
+    last_modified: float
+    version: str
+    modifications: List[str] = field(default_factory=list)  # Modification IDs
+    persistence_operations: List[str] = field(default_factory=list)  # Operation IDs
+    backup_paths: List[str] = field(default_factory=list)
+    validation_status: str = "valid"
+    validation_errors: List[str] = field(default_factory=list)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    
+    @property
+    def age_days(self) -> float:
+        """Get age in days."""
+        import time
+        return (time.time() - self.created_at) / (24 * 3600)
+    
+    @property
+    def last_modified_datetime(self) -> datetime:
+        """Get last modified as datetime."""
+        return datetime.fromtimestamp(self.last_modified)
+
+
+@dataclass
+class LifecycleOperationResult:
+    """Result of a lifecycle operation.
+    
+    WHY: Provides a consistent structure for operation results,
+    making it easier to track success/failure and gather metrics.
+    """
+    
+    operation: LifecycleOperation
+    agent_name: str
+    success: bool
+    duration_ms: float
+    error_message: Optional[str] = None
+    modification_id: Optional[str] = None
+    persistence_id: Optional[str] = None
+    cache_invalidated: bool = False
+    registry_updated: bool = False
+    metadata: Dict[str, Any] = field(default_factory=dict)

claude_mpm/models/modification.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python3
+"""
+Modification Models
+===================
+
+Data models for agent modification tracking.
+
+WHY: These models are extracted from agent_modification_tracker.py to centralize
+data definitions and enable reuse across services.
+
+DESIGN DECISION: Modification tracking models are kept separate because:
+- They represent a distinct domain (change tracking)
+- Multiple services need to work with modifications
+- The structure can evolve independently of other models
+"""
+
+from dataclasses import dataclass, field, asdict
+from datetime import datetime
+from enum import Enum
+from typing import Dict, List, Optional, Any
+import time
+
+
+class ModificationType(Enum):
+    """Types of agent modifications."""
+    CREATE = "create"
+    MODIFY = "modify"
+    DELETE = "delete"
+    MOVE = "move"
+    RESTORE = "restore"
+
+
+class ModificationTier(Enum):
+    """Agent hierarchy tiers for modification tracking.
+    
+    WHY: This enum is used across multiple services to ensure
+    consistent tier classification throughout the system.
+    """
+    PROJECT = "project"
+    USER = "user"
+    SYSTEM = "system"
+
+
+@dataclass
+class AgentModification:
+    """Agent modification record with comprehensive metadata.
+    
+    WHY: This model captures all relevant information about a single
+    modification event, enabling detailed audit trails and rollback capabilities.
+    """
+    
+    modification_id: str
+    agent_name: str
+    modification_type: ModificationType
+    tier: ModificationTier
+    file_path: str
+    timestamp: float
+    user_id: Optional[str] = None
+    modification_details: Dict[str, Any] = field(default_factory=dict)
+    file_hash_before: Optional[str] = None
+    file_hash_after: Optional[str] = None
+    file_size_before: Optional[int] = None
+    file_size_after: Optional[int] = None
+    backup_path: Optional[str] = None
+    validation_status: str = "pending"
+    validation_errors: List[str] = field(default_factory=list)
+    related_modifications: List[str] = field(default_factory=list)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    
+    @property
+    def modification_datetime(self) -> datetime:
+        """Get modification timestamp as datetime."""
+        return datetime.fromtimestamp(self.timestamp)
+    
+    @property
+    def age_seconds(self) -> float:
+        """Get age of modification in seconds."""
+        return time.time() - self.timestamp
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for serialization."""
+        data = asdict(self)
+        data['modification_type'] = self.modification_type.value
+        data['tier'] = self.tier.value
+        return data
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> 'AgentModification':
+        """Create from dictionary."""
+        data['modification_type'] = ModificationType(data['modification_type'])
+        data['tier'] = ModificationTier(data['tier'])
+        return cls(**data)
+
+
+@dataclass
+class ModificationHistory:
+    """Complete modification history for an agent.
+    
+    WHY: Aggregates all modifications for a single agent, providing
+    a complete change history for analysis and rollback.
+    """
+    
+    agent_name: str
+    modifications: List[AgentModification] = field(default_factory=list)
+    current_version: Optional[str] = None
+    total_modifications: int = 0
+    first_seen: Optional[float] = None
+    last_modified: Optional[float] = None
+    
+    def add_modification(self, modification: AgentModification) -> None:
+        """Add a modification to history."""
+        self.modifications.append(modification)
+        self.total_modifications += 1
+        self.last_modified = modification.timestamp
+        
+        if self.first_seen is None:
+            self.first_seen = modification.timestamp
+    
+    def get_recent_modifications(self, hours: int = 24) -> List[AgentModification]:
+        """Get modifications within specified hours."""
+        cutoff = time.time() - (hours * 3600)
+        return [mod for mod in self.modifications if mod.timestamp >= cutoff]
+    
+    def get_modifications_by_type(self, mod_type: ModificationType) -> List[AgentModification]:
+        """Get modifications by type."""
+        return [mod for mod in self.modifications if mod.modification_type == mod_type]

claude_mpm/models/persistence.py

@@ -0,0 +1,57 @@
+#!/usr/bin/env python3
+"""
+Persistence Models
+==================
+
+Data models for agent persistence operations.
+
+WHY: These models are extracted from agent_persistence_service.py to centralize
+data definitions and maintain consistency across services.
+
+DESIGN DECISION: Persistence models are minimal because actual persistence
+is now handled by AgentManager, but we maintain these for API compatibility.
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional, Any, Dict
+
+
+class PersistenceStrategy(Enum):
+    """Agent persistence strategies.
+    
+    WHY: Different strategies allow flexibility in how agents are persisted
+    based on their tier and use case.
+    """
+    USER_OVERRIDE = "user_override"
+    PROJECT_SPECIFIC = "project_specific"
+    SYSTEM_DEFAULT = "system_default"
+
+
+class PersistenceOperation(Enum):
+    """Persistence operation types."""
+    CREATE = "create"
+    UPDATE = "update"
+    DELETE = "delete"
+    BACKUP = "backup"
+    RESTORE = "restore"
+
+
+@dataclass
+class PersistenceRecord:
+    """Record of a persistence operation.
+    
+    WHY: Tracks persistence operations for audit trails and debugging,
+    even though actual persistence is delegated to AgentManager.
+    """
+    operation_id: str
+    operation_type: PersistenceOperation
+    agent_name: str
+    source_tier: Any  # Can be ModificationTier or string
+    target_tier: Optional[Any] = None
+    strategy: Optional[PersistenceStrategy] = None
+    success: bool = True
+    timestamp: float = 0.0
+    file_path: Optional[str] = None
+    error_message: Optional[str] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)

claude_mpm/models/registry.py

@@ -0,0 +1,91 @@
+#!/usr/bin/env python3
+"""
+Registry Models
+===============
+
+Data models for agent registry and discovery.
+
+WHY: These models are extracted from agent_registry.py to centralize
+data definitions and avoid duplication with agent_definition.py models.
+
+DESIGN DECISION: Registry models are kept separate from agent definitions
+because they serve different purposes:
+- Registry models are for discovery and management
+- Agent definitions are for execution and behavior
+"""
+
+from dataclasses import dataclass, field, asdict
+from enum import Enum
+from typing import Dict, List, Any, Optional
+import time
+
+
+class AgentTier(Enum):
+    """Agent hierarchy tiers for registry.
+    
+    WHY: Different from ModificationTier because registry uses a
+    simpler two-tier system (user/system) for discovery.
+    """
+    USER = "user"
+    SYSTEM = "system"
+
+
+@dataclass
+class AgentRegistryMetadata:
+    """Registry-specific metadata for discovered agents.
+    
+    WHY: This is different from AgentMetadata in agent_definition.py because:
+    - Registry needs discovery-specific information (path, checksum, etc.)
+    - Agent definitions need behavior-specific information
+    - Keeping them separate avoids coupling discovery to execution
+    
+    NOTE: This replaces the AgentMetadata class in agent_registry.py to avoid
+    conflicts with the one in agent_definition.py
+    """
+    name: str
+    path: str
+    tier: AgentTier
+    agent_type: str  # Using string instead of AgentType enum to avoid conflicts
+    description: str = ""
+    version: str = "0.0.0"
+    dependencies: List[str] = field(default_factory=list)
+    capabilities: List[str] = field(default_factory=list)
+    created_at: float = field(default_factory=time.time)
+    last_modified: float = field(default_factory=time.time)
+    file_size: int = 0
+    checksum: str = ""
+    is_valid: bool = True
+    validation_errors: List[str] = field(default_factory=list)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    
+    # Compatibility properties for existing code
+    @property
+    def type(self) -> str:
+        """Compatibility property for existing code expecting 'type' attribute."""
+        return self.agent_type
+    
+    @property
+    def validated(self) -> bool:
+        """Compatibility property for existing code expecting 'validated' attribute."""
+        return self.is_valid
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for serialization."""
+        data = asdict(self)
+        data['tier'] = self.tier.value
+        # Include compatibility fields
+        data['type'] = self.agent_type
+        data['validated'] = self.is_valid
+        return data
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> 'AgentRegistryMetadata':
+        """Create from dictionary."""
+        # Handle compatibility fields
+        if 'type' in data and 'agent_type' not in data:
+            data['agent_type'] = data['type']
+        if 'validated' in data and 'is_valid' not in data:
+            data['is_valid'] = data['validated']
+        
+        data['tier'] = AgentTier(data['tier'])
+        return cls(**data)

claude_mpm/security/__init__.py

@@ -0,0 +1,8 @@
+"""Security module for claude-mpm.
+
+Provides security validation and enforcement for agent operations.
+"""
+
+from .bash_validator import BashSecurityValidator, create_validator
+
+__all__ = ['BashSecurityValidator', 'create_validator']