claude-mpm 3.0.1__py3-none-any.whl → 3.1.0__py3-none-any.whl

claude_mpm/__init__.py

@@ -1,6 +1,15 @@
 """Claude MPM - Multi-Agent Project Manager."""
 
-from ._version import __version__
+from pathlib import Path
+
+# Get version from VERSION file - single source of truth
+version_file = Path(__file__).parent.parent.parent / "VERSION"
+if version_file.exists():
+    __version__ = version_file.read_text().strip()
+else:
+    # Default version if VERSION file is missing
+    __version__ = "0.0.0"
+
 __author__ = "Claude MPM Team"
 
 # Import main components

claude_mpm/agents/agent_loader.py

@@ -58,6 +58,7 @@ Usage Examples:
 import json
 import logging
 import os
+import time
 import yaml
 from pathlib import Path
 from typing import Optional, Dict, Any, Tuple, Union, List
@@ -625,7 +626,7 @@ def _get_model_config(agent_name: str, complexity_analysis: Optional[Dict[str, A
         model_config = {
             "selection_method": "dynamic_complexity_based",
             "complexity_score": complexity_score,
-            "complexity_level": complexity_analysis.get('complexity_level', ComplexityLevel.MEDIUM).value,
+            "complexity_level": complexity_analysis.get('complexity_level', ComplexityLevel.MEDIUM),
             "optimal_prompt_size": complexity_analysis.get('optimal_prompt_size', (700, 1000)),
             "default_model": default_model
         }

claude_mpm/cli.py

@@ -8,15 +8,25 @@ from typing import Optional
 
 try:
     # Try relative imports first (when used as package)
-    from ._version import __version__
     from .core.logger import get_logger, setup_logging
     from .constants import CLICommands, CLIPrefix, AgentCommands, LogLevel, CLIFlags
 except ImportError:
     # Fall back to absolute imports (when run directly)
-    from claude_mpm._version import __version__
     from core.logger import get_logger, setup_logging
     from constants import CLICommands, CLIPrefix, AgentCommands, LogLevel, CLIFlags
 
+# Get version from VERSION file - single source of truth
+version_file = Path(__file__).parent.parent.parent / "VERSION"
+if version_file.exists():
+    __version__ = version_file.read_text().strip()
+else:
+    # Try to import from package as fallback
+    try:
+        from . import __version__
+    except ImportError:
+        # Default version if all else fails
+        __version__ = "0.0.0"
+
 
 
 def _preprocess_args(argv: Optional[list] = None) -> list:

claude_mpm/schemas/agent_schema.json

@@ -5,30 +5,30 @@
   "description": "Schema definition for Claude MPM agent templates. This schema enforces the structure and validation rules for all agent configurations in the Claude MPM system.",
   "type": "object",
   "required": [
-    "schema_version",  // Required: Must match the schema version this agent was built for
-    "agent_id",        // Required: Unique identifier for the agent type
-    "agent_version",   // Required: Semantic version of this specific agent template
-    "agent_type",      // Required: Categorizes the agent's primary function
-    "metadata",        // Required: Human-readable information about the agent
-    "capabilities",    // Required: Technical specifications and resource requirements
-    "instructions"     // Required: System prompt that defines agent behavior
+    "schema_version",
+    "agent_id",
+    "agent_version",
+    "agent_type",
+    "metadata",
+    "capabilities",
+    "instructions"
   ],
   "properties": {
     "schema_version": {
       "type": "string",
-      "pattern": "^\\d+\\.\\d+\\.\\d+$",  // Enforces semantic versioning format (X.Y.Z)
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
       "description": "Schema version for the agent template format. This ensures compatibility between the agent template and the schema validator. Must be updated when breaking changes are made to the schema.",
       "examples": ["1.0.0", "1.2.0"]
     },
     "agent_id": {
       "type": "string",
-      "pattern": "^[a-z][a-z0-9_]*$",  // Must start with lowercase letter, followed by lowercase letters, numbers, or underscores
+      "pattern": "^[a-z][a-z0-9_]*$",
       "description": "Unique agent identifier used for agent discovery and loading. This ID must be unique across all agents in the system and follows snake_case naming convention.",
       "examples": ["research_agent", "engineer_agent", "qa_agent", "security_agent"]
     },
     "agent_version": {
       "type": "string",
-      "pattern": "^\\d+\\.\\d+\\.\\d+$",  // Enforces semantic versioning for agent templates
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
       "description": "Semantic version of the agent template itself (not the schema). Increment major for breaking changes, minor for new features, patch for bug fixes.",
       "examples": ["1.0.0", "2.1.3"]
     },
@@ -36,35 +36,35 @@
       "type": "string",
       "description": "Type of agent that determines its primary function and default capabilities. This categorization helps in agent discovery and capability matching.",
       "enum": [
-        "base",              // Generic agent with no specialization
-        "engineer",          // Code implementation and development
-        "qa",                // Quality assurance and testing
-        "documentation",     // Documentation creation and maintenance
-        "research",          // Code analysis and research
-        "security",          // Security analysis and vulnerability detection
-        "ops",               // Operations and infrastructure management
-        "data_engineer",     // Data pipeline and ETL development
-        "version_control"    // Git and version control operations
+        "base",
+        "engineer",
+        "qa",
+        "documentation",
+        "research",
+        "security",
+        "ops",
+        "data_engineer",
+        "version_control"
       ]
     },
     "metadata": {
       "type": "object",
       "required": [
-        "name",         // Human-readable name for UI display
-        "description",  // Brief explanation of agent's purpose
-        "tags"          // Searchable tags for agent discovery
+        "name",
+        "description",
+        "tags"
       ],
       "properties": {
         "name": {
           "type": "string",
-          "minLength": 3,      // Minimum 3 characters for meaningful names
-          "maxLength": 50,     // Maximum 50 characters to prevent UI overflow
+          "minLength": 3,
+          "maxLength": 50,
           "description": "Human-readable agent name displayed in UI and logs. Should be concise but descriptive."
         },
         "description": {
           "type": "string",
-          "minLength": 10,     // Minimum 10 characters to ensure meaningful descriptions
-          "maxLength": 200,    // Maximum 200 characters for conciseness
+          "minLength": 10,
+          "maxLength": 200,
           "description": "Brief description of agent purpose and capabilities. Used in agent selection and documentation."
         },
         "category": {
@@ -76,11 +76,11 @@
           "type": "array",
           "items": {
             "type": "string",
-            "pattern": "^[a-z][a-z0-9-]*$"  // Lowercase letters, numbers, and hyphens only
+            "pattern": "^[a-z][a-z0-9-]*$"
           },
-          "minItems": 1,        // At least one tag required for discovery
-          "maxItems": 10,       // Maximum 10 tags to prevent over-tagging
-          "uniqueItems": true,  // No duplicate tags allowed
+          "minItems": 1,
+          "maxItems": 10,
+          "uniqueItems": true,
           "description": "Tags for agent discovery and categorization. Used by the agent registry for searching and filtering."
         },
         "author": {
@@ -102,24 +102,21 @@
     "capabilities": {
       "type": "object",
       "required": [
-        "model",          // Claude model version to use
-        "tools",          // Array of allowed tools for the agent
-        "resource_tier"   // Resource allocation category
+        "model",
+        "tools",
+        "resource_tier"
       ],
       "properties": {
         "model": {
           "type": "string",
           "enum": [
-            // Haiku models - fastest, most cost-effective
             "claude-3-haiku-20240307",
             "claude-3-5-haiku-20241022",
-            // Sonnet models - balanced performance
             "claude-3-sonnet-20240229",
             "claude-3-5-sonnet-20241022",
             "claude-3-5-sonnet-20240620",
             "claude-sonnet-4-20250514",
             "claude-4-sonnet-20250514",
-            // Opus models - highest capability
             "claude-3-opus-20240229",
             "claude-opus-4-20250514",
             "claude-4-opus-20250514"
@@ -131,68 +128,61 @@
           "items": {
             "type": "string",
             "enum": [
-              // File operations
-              "Read",          // Read file contents
-              "Write",         // Write new files
-              "Edit",          // Edit existing files
-              "MultiEdit",     // Multiple edits in one operation
-              // Search and navigation
-              "Grep",          // Search file contents
-              "Glob",          // Find files by pattern
-              "LS",            // List directory contents
-              // System operations
-              "Bash",          // Execute shell commands
-              // Web operations
-              "WebSearch",     // Search the web
-              "WebFetch",      // Fetch web content
-              // Notebook operations
-              "NotebookRead",  // Read Jupyter notebooks
-              "NotebookEdit",  // Edit Jupyter notebooks
-              // Workflow operations
-              "TodoWrite",     // Manage task lists
-              "ExitPlanMode",  // Exit planning mode
-              // CLI tools (future expansion)
-              "git",           // Git operations
-              "docker",        // Docker commands
-              "kubectl",       // Kubernetes operations
-              "terraform",     // Infrastructure as code
-              "aws",           // AWS CLI
-              "gcloud",        // Google Cloud CLI
-              "azure"          // Azure CLI
+              "Read",
+              "Write",
+              "Edit",
+              "MultiEdit",
+              "Grep",
+              "Glob",
+              "LS",
+              "Bash",
+              "WebSearch",
+              "WebFetch",
+              "NotebookRead",
+              "NotebookEdit",
+              "TodoWrite",
+              "ExitPlanMode",
+              "git",
+              "docker",
+              "kubectl",
+              "terraform",
+              "aws",
+              "gcloud",
+              "azure"
             ]
           },
-          "uniqueItems": true,  // Each tool can only be listed once
+          "uniqueItems": true,
           "description": "Available tools for the agent. Tools determine what operations the agent can perform."
         },
         "resource_tier": {
           "type": "string",
           "enum": [
-            "basic",         // Default resources for simple tasks
-            "standard",      // Medium resources for typical operations
-            "intensive",     // High resources for complex tasks
-            "lightweight"    // Minimal resources for quick operations
+            "basic",
+            "standard",
+            "intensive",
+            "lightweight"
           ],
           "description": "Resource allocation tier that determines memory, CPU, and timeout limits. See definitions section for specific limits."
         },
         "max_tokens": {
           "type": "integer",
-          "minimum": 1000,      // Minimum for meaningful responses
-          "maximum": 200000,    // Maximum supported by Claude models
-          "default": 8192,      // Default suitable for most tasks
+          "minimum": 1000,
+          "maximum": 200000,
+          "default": 8192,
           "description": "Maximum tokens for response generation. Higher values allow longer responses but increase cost and latency."
         },
         "temperature": {
           "type": "number",
-          "minimum": 0,         // 0 = deterministic, focused
-          "maximum": 1,         // 1 = creative, varied
-          "default": 0.7,       // Balanced default
+          "minimum": 0,
+          "maximum": 1,
+          "default": 0.7,
           "description": "Model temperature setting controlling response randomness. Lower values for consistency, higher for creativity."
         },
         "timeout": {
           "type": "integer",
-          "minimum": 30,        // Minimum 30 seconds for basic operations
-          "maximum": 3600,      // Maximum 1 hour for long-running tasks
-          "default": 300,       // Default 5 minutes
+          "minimum": 30,
+          "maximum": 3600,
+          "default": 300,
           "description": "Operation timeout in seconds. Should align with resource_tier settings."
         },
         "memory_limit": {
@@ -241,8 +231,8 @@
     },
     "instructions": {
       "type": "string",
-      "minLength": 100,      // Minimum to ensure meaningful instructions
-      "maxLength": 8000,     // Maximum to fit within context limits
+      "minLength": 100,
+      "maxLength": 8000,
       "description": "Agent system instructions that define behavior, approach, and constraints. This becomes the agent's system prompt."
     },
     "knowledge": {
@@ -382,10 +372,8 @@
       }
     }
   },
-  "additionalProperties": false,  // Strict validation - no extra properties allowed
+  "additionalProperties": false,
   "definitions": {
-    // Resource tier definitions provide guidance for resource allocation
-    // These are not enforced by the schema but used by the runtime
     "resource_tier_limits": {
       "intensive": {
         "memory_limit": {"min": 4096, "max": 8192},

claude_mpm/schemas/agent_schema_documentation.md

@@ -0,0 +1,181 @@
+# Agent Schema Documentation
+
+This document preserves the inline documentation from the agent_schema.json file. The JSON Schema itself must remain comment-free for proper parsing.
+
+## Schema Version 1.2.0
+
+### Required Fields
+
+- **schema_version**: Must match the schema version this agent was built for
+- **agent_id**: Unique identifier for the agent type
+- **agent_version**: Semantic version of this specific agent template
+- **agent_type**: Categorizes the agent's primary function
+- **metadata**: Human-readable information about the agent
+- **capabilities**: Technical specifications and resource requirements
+- **instructions**: System prompt that defines agent behavior
+
+### Field Descriptions
+
+#### schema_version
+- **Pattern**: `^\d+\.\d+\.\d+$` (Enforces semantic versioning format X.Y.Z)
+- **Description**: Schema version for the agent template format. This ensures compatibility between the agent template and the schema validator. Must be updated when breaking changes are made to the schema.
+- **Examples**: "1.0.0", "1.2.0"
+
+#### agent_id
+- **Pattern**: `^[a-z][a-z0-9_]*$` (Must start with lowercase letter, followed by lowercase letters, numbers, or underscores)
+- **Description**: Unique agent identifier used for agent discovery and loading. This ID must be unique across all agents in the system and follows snake_case naming convention.
+- **Examples**: "research_agent", "engineer_agent", "qa_agent", "security_agent"
+
+#### agent_version
+- **Pattern**: `^\d+\.\d+\.\d+$` (Enforces semantic versioning for agent templates)
+- **Description**: Semantic version of the agent template itself (not the schema). Increment major for breaking changes, minor for new features, patch for bug fixes.
+- **Examples**: "1.0.0", "2.1.3"
+
+#### agent_type
+- **Description**: Type of agent that determines its primary function and default capabilities. This categorization helps in agent discovery and capability matching.
+- **Enum values**:
+  - `base`: Generic agent with no specialization
+  - `engineer`: Code implementation and development
+  - `qa`: Quality assurance and testing
+  - `documentation`: Documentation creation and maintenance
+  - `research`: Code analysis and research
+  - `security`: Security analysis and vulnerability detection
+  - `ops`: Operations and infrastructure management
+  - `data_engineer`: Data pipeline and ETL development
+  - `version_control`: Git and version control operations
+
+### Metadata Object
+
+#### Required metadata fields:
+- **name**: Human-readable name for UI display
+- **description**: Brief explanation of agent's purpose
+- **tags**: Searchable tags for agent discovery
+
+#### Metadata field constraints:
+- **name**: 
+  - minLength: 3 (Minimum 3 characters for meaningful names)
+  - maxLength: 50 (Maximum 50 characters to prevent UI overflow)
+- **description**:
+  - minLength: 10 (Minimum 10 characters to ensure meaningful descriptions)
+  - maxLength: 200 (Maximum 200 characters for conciseness)
+- **tags**:
+  - Pattern: `^[a-z][a-z0-9-]*$` (Lowercase letters, numbers, and hyphens only)
+  - minItems: 1 (At least one tag required for discovery)
+  - maxItems: 10 (Maximum 10 tags to prevent over-tagging)
+  - uniqueItems: true (No duplicate tags allowed)
+
+### Capabilities Object
+
+#### Required capabilities fields:
+- **model**: Claude model version to use
+- **tools**: Array of allowed tools for the agent
+- **resource_tier**: Resource allocation category
+
+#### Model Options
+Available Claude models grouped by performance tier:
+
+**Haiku models** (fastest, most cost-effective):
+- claude-3-haiku-20240307
+- claude-3-5-haiku-20241022
+
+**Sonnet models** (balanced performance):
+- claude-3-sonnet-20240229
+- claude-3-5-sonnet-20241022
+- claude-3-5-sonnet-20240620
+- claude-sonnet-4-20250514
+- claude-4-sonnet-20250514
+
+**Opus models** (highest capability):
+- claude-3-opus-20240229
+- claude-opus-4-20250514
+- claude-4-opus-20250514
+
+#### Available Tools
+Tools are grouped by functionality:
+
+**File operations**:
+- `Read`: Read file contents
+- `Write`: Write new files
+- `Edit`: Edit existing files
+- `MultiEdit`: Multiple edits in one operation
+
+**Search and navigation**:
+- `Grep`: Search file contents
+- `Glob`: Find files by pattern
+- `LS`: List directory contents
+
+**System operations**:
+- `Bash`: Execute shell commands
+
+**Web operations**:
+- `WebSearch`: Search the web
+- `WebFetch`: Fetch web content
+
+**Notebook operations**:
+- `NotebookRead`: Read Jupyter notebooks
+- `NotebookEdit`: Edit Jupyter notebooks
+
+**Workflow operations**:
+- `TodoWrite`: Manage task lists
+- `ExitPlanMode`: Exit planning mode
+
+**CLI tools** (future expansion):
+- `git`: Git operations
+- `docker`: Docker commands
+- `kubectl`: Kubernetes operations
+- `terraform`: Infrastructure as code
+- `aws`: AWS CLI
+- `gcloud`: Google Cloud CLI
+- `azure`: Azure CLI
+
+#### Resource Tiers
+Resource allocation tiers determine memory, CPU, and timeout limits:
+
+- **basic**: Default resources for simple tasks
+- **standard**: Medium resources for typical operations
+- **intensive**: High resources for complex tasks
+- **lightweight**: Minimal resources for quick operations
+
+#### Capability Constraints
+
+**max_tokens**:
+- minimum: 1000 (Minimum for meaningful responses)
+- maximum: 200000 (Maximum supported by Claude models)
+- default: 8192 (Default suitable for most tasks)
+
+**temperature**:
+- minimum: 0 (0 = deterministic, focused)
+- maximum: 1 (1 = creative, varied)
+- default: 0.7 (Balanced default)
+
+**timeout**:
+- minimum: 30 (Minimum 30 seconds for basic operations)
+- maximum: 3600 (Maximum 1 hour for long-running tasks)
+- default: 300 (Default 5 minutes)
+
+### Instructions Field
+- **minLength**: 100 (Minimum to ensure meaningful instructions)
+- **maxLength**: 8000 (Maximum to fit within context limits)
+- **Description**: Agent system instructions that define behavior, approach, and constraints. This becomes the agent's system prompt.
+
+### Additional Properties
+- **additionalProperties**: false (Strict validation - no extra properties allowed)
+
+## Resource Tier Definitions
+
+These definitions provide guidance for resource allocation (not enforced by schema but used by runtime):
+
+### Intensive Tier
+- memory_limit: 4096-8192 MB
+- cpu_limit: 60-100%
+- timeout: 600-3600 seconds
+
+### Standard Tier
+- memory_limit: 2048-4096 MB
+- cpu_limit: 30-60%
+- timeout: 300-1200 seconds
+
+### Lightweight Tier
+- memory_limit: 512-2048 MB
+- cpu_limit: 10-30%
+- timeout: 30-600 seconds