cognitive-modules 0.3.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

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,91 @@ 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")
+    
+    overflow = manifest.get("overflow", {
+        "enabled": False,
+        "recoverable": True,
+        "max_items": 5,
+        "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 +279,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 +329,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 +360,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 +390,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)

cognitive/mcp_server.py

@@ -0,0 +1,245 @@
+"""
+Cognitive Modules MCP Server
+
+提供 MCP (Model Context Protocol) 接口，让 Claude Code、Cursor 等工具可以使用 Cognitive Modules。
+
+启动方式:
+    cogn mcp
+    
+或直接运行:
+    python -m cognitive.mcp_server
+"""
+
+from typing import Optional, Any
+import json
+import os
+
+try:
+    from mcp.server.fastmcp import FastMCP
+except ImportError:
+    raise ImportError(
+        "MCP dependencies not installed. "
+        "Install with: pip install cognitive-modules[mcp]"
+    )
+
+from .registry import list_modules, find_module
+from .loader import load_module
+from .runner import run_module as execute_module
+
+# ============================================================
+# MCP Server Setup
+# ============================================================
+
+mcp = FastMCP(
+    "Cognitive Modules",
+    description="可验证的结构化 AI 任务规范 - 提供代码审查、任务排序等模块",
+)
+
+
+# ============================================================
+# Tools
+# ============================================================
+
+@mcp.tool()
+def cognitive_run(
+    module: str,
+    args: str,
+    provider: Optional[str] = None,
+    model: Optional[str] = None,
+) -> dict[str, Any]:
+    """
+    运行 Cognitive Module，获取结构化的 AI 分析结果。
+    
+    Args:
+        module: 模块名称，如 "code-reviewer", "task-prioritizer"
+        args: 输入参数，如代码片段或任务列表
+        provider: LLM 提供商（可选），如 "openai", "anthropic"
+        model: 模型名称（可选），如 "gpt-4o", "claude-3-5-sonnet-20241022"
+    
+    Returns:
+        结构化结果，包含分析内容、confidence（置信度）和 rationale（推理过程）
+    
+    Example:
+        cognitive_run("code-reviewer", "def login(u,p): return db.query(f'SELECT * FROM users WHERE name={u}')")
+        
+        返回:
+        {
+            "ok": true,
+            "data": {
+                "issues": [{"type": "security", "severity": "critical", "description": "SQL 注入"}],
+                "confidence": 0.95,
+                "rationale": "检测到字符串拼接 SQL"
+            }
+        }
+    """
+    # 检查模块是否存在
+    module_path = find_module(module)
+    if not module_path:
+        return {"ok": False, "error": f"Module '{module}' not found"}
+    
+    # 设置 provider（如果指定）
+    original_provider = os.environ.get("LLM_PROVIDER")
+    original_model = os.environ.get("LLM_MODEL")
+    
+    try:
+        if provider:
+            os.environ["LLM_PROVIDER"] = provider
+        if model:
+            os.environ["LLM_MODEL"] = model
+        
+        # 执行模块
+        result = execute_module(module, args=args)
+        
+        return {"ok": True, "data": result, "module": module}
+    except Exception as e:
+        return {"ok": False, "error": str(e), "module": module}
+    finally:
+        # 恢复原始环境变量
+        if original_provider:
+            os.environ["LLM_PROVIDER"] = original_provider
+        elif "LLM_PROVIDER" in os.environ and provider:
+            del os.environ["LLM_PROVIDER"]
+        
+        if original_model:
+            os.environ["LLM_MODEL"] = original_model
+        elif "LLM_MODEL" in os.environ and model:
+            del os.environ["LLM_MODEL"]
+
+
+@mcp.tool()
+def cognitive_list() -> dict[str, Any]:
+    """
+    列出所有已安装的 Cognitive Modules。
+    
+    Returns:
+        模块列表，包含名称、位置和格式信息
+    
+    Example:
+        cognitive_list()
+        
+        返回:
+        {
+            "modules": [
+                {"name": "code-reviewer", "location": "builtin", "format": "v1"},
+                {"name": "task-prioritizer", "location": "builtin", "format": "v1"}
+            ],
+            "count": 2
+        }
+    """
+    modules = list_modules()
+    return {
+        "modules": [
+            {"name": m["name"], "location": m["location"], "format": m["format"]}
+            for m in modules
+        ],
+        "count": len(modules),
+    }
+
+
+@mcp.tool()
+def cognitive_info(module: str) -> dict[str, Any]:
+    """
+    获取 Cognitive Module 的详细信息。
+    
+    Args:
+        module: 模块名称
+    
+    Returns:
+        模块详情，包含名称、描述、输入输出格式等
+    
+    Example:
+        cognitive_info("code-reviewer")
+        
+        返回:
+        {
+            "name": "code-reviewer",
+            "version": "1.0.0",
+            "description": "代码安全和质量审查",
+            "responsibility": "分析代码并识别潜在问题"
+        }
+    """
+    module_path = find_module(module)
+    if not module_path:
+        return {"ok": False, "error": f"Module '{module}' not found"}
+    
+    try:
+        m = load_module(module)
+        meta = m.get("meta", {})
+        
+        return {
+            "ok": True,
+            "name": meta.get("name", module),
+            "version": meta.get("version"),
+            "description": meta.get("description") or meta.get("responsibility"),
+            "responsibility": meta.get("responsibility"),
+            "input_schema": m.get("input_schema"),
+            "output_schema": m.get("output_schema"),
+        }
+    except Exception as e:
+        return {"ok": False, "error": str(e)}
+
+
+# ============================================================
+# Resources
+# ============================================================
+
+@mcp.resource("cognitive://modules")
+def get_modules_resource() -> str:
+    """获取所有模块列表（资源形式）"""
+    modules = list_modules()
+    return json.dumps([m["name"] for m in modules], indent=2)
+
+
+@mcp.resource("cognitive://module/{name}")
+def get_module_resource(name: str) -> str:
+    """获取单个模块的 prompt 内容"""
+    module_path = find_module(name)
+    if not module_path:
+        return f"Module '{name}' not found"
+    
+    try:
+        m = load_module(name)
+        return m.get("prompt", "")
+    except Exception as e:
+        return f"Error: {e}"
+
+
+# ============================================================
+# Prompts
+# ============================================================
+
+@mcp.prompt()
+def code_review_prompt(code: str) -> str:
+    """生成代码审查提示"""
+    return f"""请使用 cognitive_run 工具审查以下代码：
+
+```
+{code}
+```
+
+调用: cognitive_run("code-reviewer", "{code[:100]}...")
+"""
+
+
+@mcp.prompt()
+def task_prioritize_prompt(tasks: str) -> str:
+    """生成任务排序提示"""
+    return f"""请使用 cognitive_run 工具对以下任务进行优先级排序：
+
+{tasks}
+
+调用: cognitive_run("task-prioritizer", "{tasks}")
+"""
+
+
+# ============================================================
+# 启动入口
+# ============================================================
+
+def serve():
+    """启动 MCP 服务器"""
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    serve()