cognitive-modules 0.4.0__py3-none-any.whl → 0.5.1__py3-none-any.whl

cognitive/__init__.py

@@ -9,4 +9,4 @@ Usage:
     cog doctor                   # Check environment setup
 """
 
-__version__ = "0.1.0"
+__version__ = "0.5.1"

cognitive/cli.py

@@ -1,20 +1,22 @@
 """
-Cognitive CLI - Main entry point for the cog command.
+Cognitive CLI - Main entry point for the cogn command.
 
 Commands:
-    cog list                      List installed modules
-    cog run <module> <input>      Run a module
-    cog validate <module>         Validate module structure
-    cog add <url> --module <name> Add module from GitHub (recommended)
-    cog update <module>           Update module to latest version
-    cog versions <url>            List available versions for a repo
-    cog install <source>          Install module from git/local/registry
-    cog remove <module>           Remove an installed module
-    cog uninstall <module>        Remove an installed module (alias)
-    cog init <name>               Create a new module from template
-    cog search <query>            Search the public registry
-    cog doctor                    Check environment setup
-    cog info <module>             Show module details
+    cogn list                      List installed modules
+    cogn run <module> <input>      Run a module
+    cogn validate <module>         Validate module structure
+    cogn add <url> --module <name> Add module from GitHub (recommended)
+    cogn update <module>           Update module to latest version
+    cogn versions <url>            List available versions for a repo
+    cogn install <source>          Install module from git/local/registry
+    cogn remove <module>           Remove an installed module
+    cogn uninstall <module>        Remove an installed module (alias)
+    cogn init <name>               Create a new module from template
+    cogn search <query>            Search the public registry
+    cogn doctor                    Check environment setup
+    cogn info <module>             Show module details
+    cogn serve                     Start HTTP API server
+    cogn mcp                       Start MCP server for Claude/Cursor
 """
 
 import json
@@ -47,6 +49,7 @@ from .runner import run_module
 from .subagent import run_with_subagents
 from .validator import validate_module
 from .templates import create_module
+from .migrate import migrate_module, migrate_all_modules
 from .providers import check_provider_status
 
 app = typer.Typer(
@@ -160,11 +163,19 @@ def run_cmd(
 @app.command("validate")
 def validate_cmd(
     module: str = typer.Argument(..., help="Module name or path"),
+    v22: bool = typer.Option(False, "--v22", help="Validate v2.2 format requirements"),
 ):
-    """Validate a cognitive module's structure and examples."""
-    rprint(f"[cyan]→[/cyan] Validating module: [bold]{module}[/bold]\n")
+    """
+    Validate a cognitive module's structure and examples.
+    
+    Examples:
+        cogn validate code-reviewer
+        cogn validate code-reviewer --v22   # Check v2.2 requirements
+    """
+    mode_str = " [dim](v2.2 strict)[/dim]" if v22 else ""
+    rprint(f"[cyan]→[/cyan] Validating module: [bold]{module}[/bold]{mode_str}\n")
     
-    is_valid, errors, warnings = validate_module(module)
+    is_valid, errors, warnings = validate_module(module, v22=v22)
     
     if warnings:
         rprint(f"[yellow]⚠ Warnings ({len(warnings)}):[/yellow]")
@@ -173,7 +184,10 @@ def validate_cmd(
         print()
     
     if is_valid:
-        rprint(f"[green]✓ Module '{module}' is valid[/green]")
+        if v22:
+            rprint(f"[green]✓ Module '{module}' is valid v2.2 format[/green]")
+        else:
+            rprint(f"[green]✓ Module '{module}' is valid[/green]")
     else:
         rprint(f"[red]✗ Validation failed ({len(errors)} errors):[/red]")
         for e in errors:
@@ -181,6 +195,83 @@ def validate_cmd(
         raise typer.Exit(1)
 
 
+@app.command("migrate")
+def migrate_cmd(
+    module: Optional[str] = typer.Argument(None, help="Module name or path (omit for --all)"),
+    all_modules: bool = typer.Option(False, "--all", "-a", help="Migrate all installed modules"),
+    dry_run: bool = typer.Option(False, "--dry-run", "-n", help="Show what would be done without making changes"),
+    no_backup: bool = typer.Option(False, "--no-backup", help="Skip creating backup before migration"),
+):
+    """
+    Migrate modules from v1/v2.1 to v2.2 format.
+    
+    Examples:
+        cogn migrate code-reviewer          # Migrate single module
+        cogn migrate code-reviewer --dry-run # Preview changes
+        cogn migrate --all                  # Migrate all modules
+    """
+    if not module and not all_modules:
+        rprint("[red]Error: Provide module name or use --all[/red]")
+        raise typer.Exit(1)
+    
+    if all_modules:
+        rprint(f"[cyan]→[/cyan] Migrating all modules to v2.2...")
+        if dry_run:
+            rprint("[dim](dry run - no changes will be made)[/dim]")
+        print()
+        
+        results = migrate_all_modules(dry_run=dry_run, backup=not no_backup)
+        
+        success_count = 0
+        for name, success, changes, warnings in results:
+            if success:
+                success_count += 1
+                rprint(f"[green]✓[/green] {name}")
+                for c in changes:
+                    rprint(f"    {c}")
+            else:
+                rprint(f"[red]✗[/red] {name}")
+                for w in warnings:
+                    rprint(f"    [yellow]{w}[/yellow]")
+        
+        print()
+        rprint(f"[green]Migrated: {success_count}/{len(results)}[/green]")
+        
+    else:
+        mode_str = " [dim](dry run)[/dim]" if dry_run else ""
+        rprint(f"[cyan]→[/cyan] Migrating module: [bold]{module}[/bold]{mode_str}\n")
+        
+        success, changes, warnings = migrate_module(
+            module,
+            dry_run=dry_run,
+            backup=not no_backup
+        )
+        
+        if changes:
+            rprint(f"[cyan]Changes:[/cyan]")
+            for c in changes:
+                rprint(f"  - {c}")
+            print()
+        
+        if warnings:
+            rprint(f"[yellow]⚠ Warnings:[/yellow]")
+            for w in warnings:
+                rprint(f"  - {w}")
+            print()
+        
+        if success:
+            if dry_run:
+                rprint(f"[green]✓ Migration preview complete[/green]")
+                rprint(f"  Run without --dry-run to apply changes")
+            else:
+                rprint(f"[green]✓ Module '{module}' migrated to v2.2[/green]")
+                rprint(f"\nValidate with:")
+                rprint(f"  [cyan]cogn validate {module} --v22[/cyan]")
+        else:
+            rprint(f"[red]✗ Migration failed[/red]")
+            raise typer.Exit(1)
+
+
 @app.command("install")
 def install_cmd(
     source: str = typer.Argument(..., help="Source: github:org/repo/path, registry:name, or local path"),
@@ -607,6 +698,70 @@ def info_cmd(
         rprint(f"\n  Update with: [cyan]cog update {meta.get('name', module)}[/cyan]")
 
 
+@app.command("serve")
+def serve_cmd(
+    host: str = typer.Option("0.0.0.0", "--host", "-h", help="Host to bind"),
+    port: int = typer.Option(8000, "--port", "-p", help="Port to bind"),
+):
+    """
+    Start HTTP API server for workflow integration.
+    
+    Example:
+        cogn serve --port 8000
+        
+    Then use:
+        curl -X POST http://localhost:8000/run \\
+          -H "Content-Type: application/json" \\
+          -d '{"module": "code-reviewer", "args": "your code"}'
+    """
+    try:
+        import uvicorn
+    except ImportError:
+        rprint("[red]Error:[/red] Server dependencies not installed.")
+        rprint("\nInstall with:")
+        rprint("  [cyan]pip install cognitive-modules[server][/cyan]")
+        raise typer.Exit(1)
+    
+    rprint(f"[green]Starting Cognitive API server...[/green]")
+    rprint(f"  Host: {host}")
+    rprint(f"  Port: {port}")
+    rprint(f"  Docs: http://{host if host != '0.0.0.0' else 'localhost'}:{port}/docs")
+    rprint()
+    
+    uvicorn.run("cognitive.server:app", host=host, port=port, reload=False)
+
+
+@app.command("mcp")
+def mcp_cmd():
+    """
+    Start MCP (Model Context Protocol) server.
+    
+    Enables Claude Code, Cursor, and other MCP-compatible tools to use Cognitive Modules.
+    
+    Example:
+        cogn mcp
+        
+    Configure in Claude Desktop (claude_desktop_config.json):
+        {
+          "mcpServers": {
+            "cognitive": {
+              "command": "cogn",
+              "args": ["mcp"]
+            }
+          }
+        }
+    """
+    try:
+        from .mcp_server import serve
+    except ImportError:
+        rprint("[red]Error:[/red] MCP dependencies not installed.")
+        rprint("\nInstall with:")
+        rprint("  [cyan]pip install cognitive-modules[mcp][/cyan]")
+        raise typer.Exit(1)
+    
+    serve()
+
+
 @app.callback(invoke_without_command=True)
 def main(
     ctx: typer.Context,

cognitive/loader.py

@@ -1,7 +1,13 @@
 """
 Module Loader - Load cognitive modules in all formats.
 
-Format v2 (recommended):
+Format v2.2 (latest):
+  - module.yaml (machine-readable manifest with tier, overflow, enums, compat)
+  - prompt.md (human-readable prompt)
+  - schema.json (meta + input + data + error)
+  - tests/ (golden tests)
+
+Format v2/v2.1 (supported):
   - module.yaml (machine-readable manifest)
   - prompt.md (human-readable prompt)
   - schema.json (input + output + error)
@@ -21,11 +27,24 @@ Format v0 (old, deprecated):
 
 import json
 from pathlib import Path
-from typing import Optional
+from typing import Optional, Literal
 
 import yaml
 
 
+# =============================================================================
+# Type Definitions (v2.2)
+# =============================================================================
+
+ModuleTier = Literal["exec", "decision", "exploration"]
+SchemaStrictness = Literal["high", "medium", "low"]
+EnumStrategy = Literal["strict", "extensible"]
+
+
+# =============================================================================
+# Format Detection
+# =============================================================================
+
 def detect_format(module_path: Path) -> str:
     """Detect module format: 'v2', 'v1', or 'v0'."""
     if (module_path / "module.yaml").exists():
@@ -38,6 +57,22 @@ def detect_format(module_path: Path) -> str:
         raise FileNotFoundError(f"No module.yaml, MODULE.md, or module.md found in {module_path}")
 
 
+def detect_v2_version(manifest: dict) -> str:
+    """Detect v2.x version from manifest content."""
+    # v2.2 indicators
+    if manifest.get("tier") or manifest.get("overflow") or manifest.get("enums"):
+        return "v2.2"
+    # v2.1 indicators
+    if manifest.get("policies") or manifest.get("failure"):
+        return "v2.1"
+    # Default v2.0
+    return "v2.0"
+
+
+# =============================================================================
+# Frontmatter Parsing
+# =============================================================================
+
 def parse_frontmatter(content: str) -> tuple[dict, str]:
     """Parse YAML frontmatter from markdown content."""
     if not content.startswith('---'):
@@ -52,12 +87,19 @@ def parse_frontmatter(content: str) -> tuple[dict, str]:
     return frontmatter, body
 
 
+# =============================================================================
+# v2.2 Loader
+# =============================================================================
+
 def load_v2_format(module_path: Path) -> dict:
-    """Load module in v2 format (module.yaml + prompt.md + schema.json)."""
+    """Load module in v2.x format (module.yaml + prompt.md + schema.json)."""
     # Load module.yaml
     with open(module_path / "module.yaml", 'r', encoding='utf-8') as f:
         manifest = yaml.safe_load(f)
     
+    # Detect version
+    version_str = detect_v2_version(manifest)
+    
     # Load prompt.md
     prompt_path = module_path / "prompt.md"
     if prompt_path.exists():
@@ -71,13 +113,28 @@ def load_v2_format(module_path: Path) -> dict:
     if schema_path.exists():
         with open(schema_path, 'r', encoding='utf-8') as f:
             schema = json.load(f)
+        
         input_schema = schema.get("input", {})
-        output_schema = schema.get("output", {})
+        
+        # Support both "data" (v2.2) and "output" (v2.1) aliases
+        compat = manifest.get("compat", {})
+        if compat.get("schema_output_alias") == "data" or "data" in schema:
+            data_schema = schema.get("data", schema.get("output", {}))
+            output_schema = data_schema  # Keep for backward compat
+        else:
+            output_schema = schema.get("output", {})
+            data_schema = output_schema
+        
         error_schema = schema.get("error", {})
+        meta_schema = schema.get("meta", {})
+        defs = schema.get("$defs", {})
     else:
         input_schema = {}
         output_schema = {}
+        data_schema = {}
         error_schema = {}
+        meta_schema = {}
+        defs = {}
     
     # Extract constraints (supports both old and new format)
     constraints_raw = manifest.get("constraints", {})
@@ -98,42 +155,102 @@ def load_v2_format(module_path: Path) -> dict:
         "behavior_equivalence_false_max_confidence": constraints_raw.get("behavior_equivalence_false_max_confidence", 0.7),
     }
     
-    # Extract policies (v2.1)
+    # Extract v2.1 fields
     policies = manifest.get("policies", {})
-    
-    # Extract tools policy
     tools = manifest.get("tools", {})
-    
-    # Extract output contract
     output_contract = manifest.get("output", {})
-    
-    # Extract failure contract
     failure_contract = manifest.get("failure", {})
-    
-    # Extract runtime requirements
     runtime_requirements = manifest.get("runtime_requirements", {})
     
+    # Extract v2.2 fields
+    tier: Optional[ModuleTier] = manifest.get("tier")
+    schema_strictness: SchemaStrictness = manifest.get("schema_strictness", "medium")
+    
+    # Determine default max_items based on strictness (SPEC-v2.2)
+    # high=0 (disabled), medium=5, low=20
+    strictness_max_items = {
+        "high": 0,
+        "medium": 5,
+        "low": 20
+    }
+    default_max_items = strictness_max_items.get(schema_strictness, 5)
+    default_enabled = schema_strictness != "high"
+    
+    overflow_raw = manifest.get("overflow", {})
+    overflow = {
+        "enabled": overflow_raw.get("enabled", default_enabled),
+        "recoverable": overflow_raw.get("recoverable", True),
+        "max_items": overflow_raw.get("max_items", default_max_items),
+        "require_suggested_mapping": overflow_raw.get("require_suggested_mapping", True)
+    }
+    
+    enums = manifest.get("enums", {
+        "strategy": "extensible" if tier in ("decision", "exploration") else "strict",
+        "unknown_tag": "custom"
+    })
+    
+    compat = manifest.get("compat", {
+        "accepts_v21_payload": True,
+        "runtime_auto_wrap": True,
+        "schema_output_alias": "data"
+    })
+    
+    io_config = manifest.get("io", {})
+    tests = manifest.get("tests", [])
+    
     return {
+        # Core identity
         "name": manifest.get("name", module_path.name),
         "version": manifest.get("version", "1.0.0"),
         "responsibility": manifest.get("responsibility", ""),
         "excludes": manifest.get("excludes", []),
+        
+        # Path and format info
         "path": module_path,
         "format": "v2",
+        "format_version": version_str,
+        
+        # Raw manifest
         "metadata": manifest,
+        
+        # Schemas
         "input_schema": input_schema,
-        "output_schema": output_schema,
+        "output_schema": output_schema,  # v2.1 compat
+        "data_schema": data_schema,       # v2.2
         "error_schema": error_schema,
+        "meta_schema": meta_schema,       # v2.2
+        "schema_defs": defs,
+        
+        # Constraints and policies
         "constraints": constraints,
         "policies": policies,
         "tools": tools,
+        
+        # Contracts
         "output_contract": output_contract,
         "failure_contract": failure_contract,
+        
+        # Runtime
         "runtime_requirements": runtime_requirements,
+        
+        # v2.2 specific
+        "tier": tier,
+        "schema_strictness": schema_strictness,
+        "overflow": overflow,
+        "enums": enums,
+        "compat": compat,
+        "io": io_config,
+        "tests": tests,
+        
+        # Prompt
         "prompt": prompt,
     }
 
 
+# =============================================================================
+# v1 Loader (Legacy)
+# =============================================================================
+
 def load_v1_format(module_path: Path) -> dict:
     """Load module in v1 format (MODULE.md + schema.json)."""
     # Load MODULE.md
@@ -173,14 +290,26 @@ def load_v1_format(module_path: Path) -> dict:
         "excludes": metadata.get("excludes", []),
         "path": module_path,
         "format": "v1",
+        "format_version": "v1.0",
         "metadata": metadata,
         "input_schema": input_schema,
         "output_schema": output_schema,
+        "data_schema": output_schema,  # Alias for v2.2 compat
         "constraints": constraints,
         "prompt": prompt,
+        # v2.2 defaults for v1 modules
+        "tier": None,
+        "schema_strictness": "medium",
+        "overflow": {"enabled": False},
+        "enums": {"strategy": "strict"},
+        "compat": {"accepts_v21_payload": True, "runtime_auto_wrap": True},
     }
 
 
+# =============================================================================
+# v0 Loader (Deprecated)
+# =============================================================================
+
 def load_v0_format(module_path: Path) -> dict:
     """Load module in v0 format (old 6-file format)."""
     # Load module.md
@@ -211,14 +340,26 @@ def load_v0_format(module_path: Path) -> dict:
         "excludes": [],
         "path": module_path,
         "format": "v0",
+        "format_version": "v0.0",
         "metadata": metadata,
         "input_schema": input_schema,
         "output_schema": output_schema,
+        "data_schema": output_schema,  # Alias
         "constraints": constraints,
         "prompt": prompt,
+        # v2.2 defaults
+        "tier": None,
+        "schema_strictness": "medium",
+        "overflow": {"enabled": False},
+        "enums": {"strategy": "strict"},
+        "compat": {"accepts_v21_payload": True, "runtime_auto_wrap": True},
     }
 
 
+# =============================================================================
+# Main Loader
+# =============================================================================
+
 def load_module(module_path: Path) -> dict:
     """Load a module, auto-detecting format."""
     fmt = detect_format(module_path)
@@ -230,6 +371,10 @@ def load_module(module_path: Path) -> dict:
         return load_v0_format(module_path)
 
 
+# =============================================================================
+# Module Discovery
+# =============================================================================
+
 def find_module(name: str, search_paths: list[Path]) -> Optional[dict]:
     """Find and load a module by name from search paths."""
     for base_path in search_paths:
@@ -256,3 +401,35 @@ def list_modules(search_paths: list[Path]) -> list[dict]:
                 except FileNotFoundError:
                     continue
     return modules
+
+
+# =============================================================================
+# Utility Functions
+# =============================================================================
+
+def get_module_tier(module: dict) -> Optional[ModuleTier]:
+    """Get module tier (exec, decision, exploration)."""
+    return module.get("tier")
+
+
+def get_schema_strictness(module: dict) -> SchemaStrictness:
+    """Get schema strictness level."""
+    return module.get("schema_strictness", "medium")
+
+
+def is_overflow_enabled(module: dict) -> bool:
+    """Check if overflow (extensions.insights) is enabled."""
+    overflow = module.get("overflow", {})
+    return overflow.get("enabled", False)
+
+
+def get_enum_strategy(module: dict) -> EnumStrategy:
+    """Get enum extension strategy."""
+    enums = module.get("enums", {})
+    return enums.get("strategy", "strict")
+
+
+def should_auto_wrap(module: dict) -> bool:
+    """Check if runtime should auto-wrap v2.1 to v2.2."""
+    compat = module.get("compat", {})
+    return compat.get("runtime_auto_wrap", True)