cognitive-modules 0.1.1__tar.gz → 0.3.0__tar.gz

{cognitive_modules-0.1.1/src/cognitive_modules.egg-info → cognitive_modules-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cognitive-modules
-Version: 0.1.1
+Version: 0.3.0
 Summary: Structured LLM task runner with schema validation, confidence scoring, and subagent orchestration
 Author: ziel-io
 License: MIT
@@ -151,6 +151,7 @@ cog doctor
 | 模块 | 功能 | 示例 |
 |------|------|------|
 | `code-reviewer` | 代码审查 | `cog run code-reviewer --args "你的代码"` |
+| `code-simplifier` | 代码简化 | `cog run code-simplifier --args "复杂代码"` |
 | `task-prioritizer` | 任务优先级排序 | `cog run task-prioritizer --args "任务1,任务2"` |
 | `api-designer` | REST API 设计 | `cog run api-designer --args "订单系统"` |
 | `ui-spec-generator` | UI 规范生成 | `cog run ui-spec-generator --args "电商首页"` |
@@ -241,6 +242,134 @@ export LLM_PROVIDER=ollama
 cog doctor
 ```
 
+## 创建新模块（完整流程）
+
+以 `code-simplifier` 为例：
+
+### Step 1: 创建目录结构
+
+```bash
+mkdir -p cognitive/modules/code-simplifier
+```
+
+### Step 2: 编写 MODULE.md
+
+```bash
+cat > cognitive/modules/code-simplifier/MODULE.md << 'EOF'
+---
+name: code-simplifier
+version: 1.0.0
+responsibility: Simplify complex code while preserving functionality
+
+excludes:
+  - Changing the code's behavior
+  - Adding new features
+  - Removing functionality
+
+constraints:
+  no_network: true
+  no_side_effects: true
+  require_confidence: true
+  require_rationale: true
+---
+
+# Code Simplifier Module
+
+You are an expert at refactoring and simplifying code.
+
+## Input
+
+Code to simplify: $ARGUMENTS
+
+## Simplification Strategies
+
+1. **Remove redundancy** - Eliminate duplicate code
+2. **Improve naming** - Use clear, descriptive names
+3. **Reduce nesting** - Flatten deep conditionals
+4. **Simplify logic** - Use built-in functions
+
+## Output Requirements
+
+Return JSON containing:
+- `simplified_code`: The simplified version
+- `changes`: List of changes made
+- `summary`: Brief description
+- `rationale`: Explanation of decisions
+- `confidence`: Confidence score [0-1]
+EOF
+```
+
+### Step 3: 编写 schema.json
+
+```bash
+cat > cognitive/modules/code-simplifier/schema.json << 'EOF'
+{
+  "$schema": "https://ziel-io.github.io/cognitive-modules/schema/v1.json",
+  "input": {
+    "type": "object",
+    "properties": {
+      "code": { "type": "string" },
+      "language": { "type": "string" },
+      "$ARGUMENTS": { "type": "string" }
+    }
+  },
+  "output": {
+    "type": "object",
+    "required": ["simplified_code", "changes", "summary", "rationale", "confidence"],
+    "properties": {
+      "simplified_code": { "type": "string" },
+      "changes": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "type": { "type": "string" },
+            "description": { "type": "string" }
+          }
+        }
+      },
+      "summary": { "type": "string" },
+      "rationale": { "type": "string" },
+      "confidence": { "type": "number", "minimum": 0, "maximum": 1 }
+    }
+  }
+}
+EOF
+```
+
+### Step 4: 验证模块
+
+```bash
+cog validate code-simplifier
+cog list  # 确认模块出现在列表中
+```
+
+### Step 5: 测试运行
+
+```bash
+cog run code-simplifier --args "def calc(x): if x > 0: if x < 10: return x * 2 else: return x else: return 0" --pretty
+```
+
+### Step 6: 添加示例（可选）
+
+```bash
+mkdir -p cognitive/modules/code-simplifier/examples
+# 添加 input.json 和 output.json 作为测试用例
+```
+
+### 模块设计要点
+
+| 要素 | 必须 | 说明 |
+|------|------|------|
+| `name` | ✅ | 唯一标识符，kebab-case |
+| `version` | ✅ | 语义化版本 |
+| `responsibility` | ✅ | 一句话描述职责 |
+| `excludes` | ✅ | 明确列出不做的事 |
+| `$ARGUMENTS` | ✅ | 支持命令行参数 |
+| `confidence` | ✅ | 输出必须包含 0-1 置信度 |
+| `rationale` | ✅ | 输出必须包含推理过程 |
+| `schema.json` | ✅ | 定义输入输出契约 |
+
 ## 开发
 
 ```bash
@@ -254,7 +383,7 @@ pip install -e ".[dev]"
 # 运行测试
 pytest tests/ -v
 
-# 创建新模块
+# 创建新模块（使用模板）
 cog init my-module -d "模块描述"
 cog validate my-module
 ```

{cognitive_modules-0.1.1 → cognitive_modules-0.3.0}/README.md

@@ -99,6 +99,7 @@ cog doctor
 | 模块 | 功能 | 示例 |
 |------|------|------|
 | `code-reviewer` | 代码审查 | `cog run code-reviewer --args "你的代码"` |
+| `code-simplifier` | 代码简化 | `cog run code-simplifier --args "复杂代码"` |
 | `task-prioritizer` | 任务优先级排序 | `cog run task-prioritizer --args "任务1,任务2"` |
 | `api-designer` | REST API 设计 | `cog run api-designer --args "订单系统"` |
 | `ui-spec-generator` | UI 规范生成 | `cog run ui-spec-generator --args "电商首页"` |
@@ -189,6 +190,134 @@ export LLM_PROVIDER=ollama
 cog doctor
 ```
 
+## 创建新模块（完整流程）
+
+以 `code-simplifier` 为例：
+
+### Step 1: 创建目录结构
+
+```bash
+mkdir -p cognitive/modules/code-simplifier
+```
+
+### Step 2: 编写 MODULE.md
+
+```bash
+cat > cognitive/modules/code-simplifier/MODULE.md << 'EOF'
+---
+name: code-simplifier
+version: 1.0.0
+responsibility: Simplify complex code while preserving functionality
+
+excludes:
+  - Changing the code's behavior
+  - Adding new features
+  - Removing functionality
+
+constraints:
+  no_network: true
+  no_side_effects: true
+  require_confidence: true
+  require_rationale: true
+---
+
+# Code Simplifier Module
+
+You are an expert at refactoring and simplifying code.
+
+## Input
+
+Code to simplify: $ARGUMENTS
+
+## Simplification Strategies
+
+1. **Remove redundancy** - Eliminate duplicate code
+2. **Improve naming** - Use clear, descriptive names
+3. **Reduce nesting** - Flatten deep conditionals
+4. **Simplify logic** - Use built-in functions
+
+## Output Requirements
+
+Return JSON containing:
+- `simplified_code`: The simplified version
+- `changes`: List of changes made
+- `summary`: Brief description
+- `rationale`: Explanation of decisions
+- `confidence`: Confidence score [0-1]
+EOF
+```
+
+### Step 3: 编写 schema.json
+
+```bash
+cat > cognitive/modules/code-simplifier/schema.json << 'EOF'
+{
+  "$schema": "https://ziel-io.github.io/cognitive-modules/schema/v1.json",
+  "input": {
+    "type": "object",
+    "properties": {
+      "code": { "type": "string" },
+      "language": { "type": "string" },
+      "$ARGUMENTS": { "type": "string" }
+    }
+  },
+  "output": {
+    "type": "object",
+    "required": ["simplified_code", "changes", "summary", "rationale", "confidence"],
+    "properties": {
+      "simplified_code": { "type": "string" },
+      "changes": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "type": { "type": "string" },
+            "description": { "type": "string" }
+          }
+        }
+      },
+      "summary": { "type": "string" },
+      "rationale": { "type": "string" },
+      "confidence": { "type": "number", "minimum": 0, "maximum": 1 }
+    }
+  }
+}
+EOF
+```
+
+### Step 4: 验证模块
+
+```bash
+cog validate code-simplifier
+cog list  # 确认模块出现在列表中
+```
+
+### Step 5: 测试运行
+
+```bash
+cog run code-simplifier --args "def calc(x): if x > 0: if x < 10: return x * 2 else: return x else: return 0" --pretty
+```
+
+### Step 6: 添加示例（可选）
+
+```bash
+mkdir -p cognitive/modules/code-simplifier/examples
+# 添加 input.json 和 output.json 作为测试用例
+```
+
+### 模块设计要点
+
+| 要素 | 必须 | 说明 |
+|------|------|------|
+| `name` | ✅ | 唯一标识符，kebab-case |
+| `version` | ✅ | 语义化版本 |
+| `responsibility` | ✅ | 一句话描述职责 |
+| `excludes` | ✅ | 明确列出不做的事 |
+| `$ARGUMENTS` | ✅ | 支持命令行参数 |
+| `confidence` | ✅ | 输出必须包含 0-1 置信度 |
+| `rationale` | ✅ | 输出必须包含推理过程 |
+| `schema.json` | ✅ | 定义输入输出契约 |
+
 ## 开发
 
 ```bash
@@ -202,7 +331,7 @@ pip install -e ".[dev]"
 # 运行测试
 pytest tests/ -v
 
-# 创建新模块
+# 创建新模块（使用模板）
 cog init my-module -d "模块描述"
 cog validate my-module
 ```

{cognitive_modules-0.1.1 → cognitive_modules-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cognitive-modules"
-version = "0.1.1"
+version = "0.3.0"
 description = "Structured LLM task runner with schema validation, confidence scoring, and subagent orchestration"
 readme = "README.md"
 license = {text = "MIT"}

cognitive_modules-0.3.0/src/cognitive/loader.py

@@ -0,0 +1,258 @@
+"""
+Module Loader - Load cognitive modules in all formats.
+
+Format v2 (recommended):
+  - module.yaml (machine-readable manifest)
+  - prompt.md (human-readable prompt)
+  - schema.json (input + output + error)
+  - tests/ (golden tests)
+
+Format v1 (legacy, still supported):
+  - MODULE.md (YAML frontmatter + prompt)
+  - schema.json (input + output)
+
+Format v0 (old, deprecated):
+  - module.md (YAML frontmatter)
+  - input.schema.json
+  - output.schema.json
+  - constraints.yaml
+  - prompt.txt
+"""
+
+import json
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+
+def detect_format(module_path: Path) -> str:
+    """Detect module format: 'v2', 'v1', or 'v0'."""
+    if (module_path / "module.yaml").exists():
+        return "v2"
+    elif (module_path / "MODULE.md").exists():
+        return "v1"
+    elif (module_path / "module.md").exists():
+        return "v0"
+    else:
+        raise FileNotFoundError(f"No module.yaml, MODULE.md, or module.md found in {module_path}")
+
+
+def parse_frontmatter(content: str) -> tuple[dict, str]:
+    """Parse YAML frontmatter from markdown content."""
+    if not content.startswith('---'):
+        return {}, content
+    
+    parts = content.split('---', 2)
+    if len(parts) < 3:
+        return {}, content
+    
+    frontmatter = yaml.safe_load(parts[1]) or {}
+    body = parts[2].strip()
+    return frontmatter, body
+
+
+def load_v2_format(module_path: Path) -> dict:
+    """Load module in v2 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)
+    
+    # Load prompt.md
+    prompt_path = module_path / "prompt.md"
+    if prompt_path.exists():
+        with open(prompt_path, 'r', encoding='utf-8') as f:
+            prompt = f.read()
+    else:
+        prompt = ""
+    
+    # Load schema.json
+    schema_path = module_path / "schema.json"
+    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", {})
+        error_schema = schema.get("error", {})
+    else:
+        input_schema = {}
+        output_schema = {}
+        error_schema = {}
+    
+    # Extract constraints (supports both old and new format)
+    constraints_raw = manifest.get("constraints", {})
+    policies_raw = manifest.get("policies", {})
+    
+    constraints = {
+        "operational": {
+            "no_external_network": constraints_raw.get("no_network", True) or policies_raw.get("network") == "deny",
+            "no_side_effects": constraints_raw.get("no_side_effects", True) or policies_raw.get("side_effects") == "deny",
+            "no_file_write": constraints_raw.get("no_file_write", True) or policies_raw.get("filesystem_write") == "deny",
+            "no_inventing_data": constraints_raw.get("no_inventing_data", True),
+        },
+        "output_quality": {
+            "require_confidence": manifest.get("output", {}).get("require_confidence", True),
+            "require_rationale": manifest.get("output", {}).get("require_rationale", True),
+            "require_behavior_equivalence": manifest.get("output", {}).get("require_behavior_equivalence", False),
+        },
+        "behavior_equivalence_false_max_confidence": constraints_raw.get("behavior_equivalence_false_max_confidence", 0.7),
+    }
+    
+    # Extract policies (v2.1)
+    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", {})
+    
+    return {
+        "name": manifest.get("name", module_path.name),
+        "version": manifest.get("version", "1.0.0"),
+        "responsibility": manifest.get("responsibility", ""),
+        "excludes": manifest.get("excludes", []),
+        "path": module_path,
+        "format": "v2",
+        "metadata": manifest,
+        "input_schema": input_schema,
+        "output_schema": output_schema,
+        "error_schema": error_schema,
+        "constraints": constraints,
+        "policies": policies,
+        "tools": tools,
+        "output_contract": output_contract,
+        "failure_contract": failure_contract,
+        "runtime_requirements": runtime_requirements,
+        "prompt": prompt,
+    }
+
+
+def load_v1_format(module_path: Path) -> dict:
+    """Load module in v1 format (MODULE.md + schema.json)."""
+    # Load MODULE.md
+    with open(module_path / "MODULE.md", 'r', encoding='utf-8') as f:
+        content = f.read()
+    
+    metadata, prompt = parse_frontmatter(content)
+    
+    # Extract constraints from metadata
+    constraints = {
+        "operational": {
+            "no_external_network": metadata.get("constraints", {}).get("no_network", True),
+            "no_side_effects": metadata.get("constraints", {}).get("no_side_effects", True),
+            "no_inventing_data": metadata.get("constraints", {}).get("no_inventing_data", True),
+        },
+        "output_quality": {
+            "require_confidence": metadata.get("constraints", {}).get("require_confidence", True),
+            "require_rationale": metadata.get("constraints", {}).get("require_rationale", True),
+        }
+    }
+    
+    # Load schema.json
+    schema_path = module_path / "schema.json"
+    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", {})
+    else:
+        input_schema = {}
+        output_schema = {}
+    
+    return {
+        "name": metadata.get("name", module_path.name),
+        "version": metadata.get("version", "1.0.0"),
+        "responsibility": metadata.get("responsibility", ""),
+        "excludes": metadata.get("excludes", []),
+        "path": module_path,
+        "format": "v1",
+        "metadata": metadata,
+        "input_schema": input_schema,
+        "output_schema": output_schema,
+        "constraints": constraints,
+        "prompt": prompt,
+    }
+
+
+def load_v0_format(module_path: Path) -> dict:
+    """Load module in v0 format (old 6-file format)."""
+    # Load module.md
+    with open(module_path / "module.md", 'r', encoding='utf-8') as f:
+        content = f.read()
+    
+    metadata, _ = parse_frontmatter(content)
+    
+    # Load schemas
+    with open(module_path / "input.schema.json", 'r', encoding='utf-8') as f:
+        input_schema = json.load(f)
+    
+    with open(module_path / "output.schema.json", 'r', encoding='utf-8') as f:
+        output_schema = json.load(f)
+    
+    # Load constraints
+    with open(module_path / "constraints.yaml", 'r', encoding='utf-8') as f:
+        constraints = yaml.safe_load(f)
+    
+    # Load prompt
+    with open(module_path / "prompt.txt", 'r', encoding='utf-8') as f:
+        prompt = f.read()
+    
+    return {
+        "name": metadata.get("name", module_path.name),
+        "version": metadata.get("version", "1.0.0"),
+        "responsibility": metadata.get("responsibility", ""),
+        "excludes": [],
+        "path": module_path,
+        "format": "v0",
+        "metadata": metadata,
+        "input_schema": input_schema,
+        "output_schema": output_schema,
+        "constraints": constraints,
+        "prompt": prompt,
+    }
+
+
+def load_module(module_path: Path) -> dict:
+    """Load a module, auto-detecting format."""
+    fmt = detect_format(module_path)
+    if fmt == "v2":
+        return load_v2_format(module_path)
+    elif fmt == "v1":
+        return load_v1_format(module_path)
+    else:
+        return load_v0_format(module_path)
+
+
+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:
+        module_path = base_path / name
+        if module_path.exists():
+            try:
+                return load_module(module_path)
+            except FileNotFoundError:
+                continue
+    return None
+
+
+def list_modules(search_paths: list[Path]) -> list[dict]:
+    """List all modules in search paths."""
+    modules = []
+    for base_path in search_paths:
+        if not base_path.exists():
+            continue
+        for module_dir in base_path.iterdir():
+            if module_dir.is_dir():
+                try:
+                    module = load_module(module_dir)
+                    modules.append(module)
+                except FileNotFoundError:
+                    continue
+    return modules

cognitive_modules-0.3.0/src/cognitive/runner.py

@@ -0,0 +1,276 @@
+"""
+Module Runner - Execute cognitive modules with validation.
+Supports v2 envelope format and legacy formats.
+"""
+
+import json
+from pathlib import Path
+from typing import Optional, TypedDict, Union
+
+import jsonschema
+import yaml
+
+from .registry import find_module
+from .loader import load_module
+from .providers import call_llm
+
+
+class EnvelopeError(TypedDict):
+    code: str
+    message: str
+
+
+class EnvelopeSuccess(TypedDict):
+    ok: bool  # True
+    data: dict
+
+
+class EnvelopeFailure(TypedDict):
+    ok: bool  # False
+    error: EnvelopeError
+    partial_data: Optional[dict]
+
+
+EnvelopeResponse = Union[EnvelopeSuccess, EnvelopeFailure]
+
+
+def validate_data(data: dict, schema: dict, label: str = "Data") -> list[str]:
+    """Validate data against schema. Returns list of errors."""
+    errors = []
+    if not schema:
+        return errors
+    try:
+        jsonschema.validate(instance=data, schema=schema)
+    except jsonschema.ValidationError as e:
+        errors.append(f"{label} validation error: {e.message} at {list(e.absolute_path)}")
+    except jsonschema.SchemaError as e:
+        errors.append(f"Schema error: {e.message}")
+    return errors
+
+
+def substitute_arguments(text: str, input_data: dict) -> str:
+    """Substitute $ARGUMENTS and $N placeholders in text."""
+    # Get arguments
+    args_value = input_data.get("$ARGUMENTS", input_data.get("query", input_data.get("code", "")))
+    
+    # Replace $ARGUMENTS
+    text = text.replace("$ARGUMENTS", str(args_value))
+    
+    # Replace $ARGUMENTS[N] and $N for indexed access
+    if isinstance(args_value, str):
+        args_list = args_value.split()
+        for i, arg in enumerate(args_list):
+            text = text.replace(f"$ARGUMENTS[{i}]", arg)
+            text = text.replace(f"${i}", arg)
+    
+    return text
+
+
+def build_prompt(module: dict, input_data: dict, use_envelope: bool = False) -> str:
+    """Build the complete prompt for the LLM."""
+    # Substitute $ARGUMENTS in prompt
+    prompt = substitute_arguments(module["prompt"], input_data)
+    
+    parts = [
+        prompt,
+        "\n\n## Constraints\n",
+        yaml.dump(module["constraints"], default_flow_style=False),
+        "\n\n## Input\n",
+        "```json\n",
+        json.dumps(input_data, indent=2, ensure_ascii=False),
+        "\n```\n",
+    ]
+    
+    if use_envelope:
+        parts.extend([
+            "\n## Response Format (Envelope)\n",
+            "You MUST wrap your response in the envelope format:\n",
+            "- Success: { \"ok\": true, \"data\": { ...your output... } }\n",
+            "- Error: { \"ok\": false, \"error\": { \"code\": \"ERROR_CODE\", \"message\": \"...\" } }\n",
+            "Return ONLY valid JSON.\n",
+        ])
+    else:
+        parts.extend([
+            "\n## Instructions\n",
+            "Analyze the input and generate output matching the required schema.",
+            "Return ONLY valid JSON. Do not include any text before or after the JSON.",
+        ])
+    
+    return "".join(parts)
+
+
+def parse_llm_response(response: str) -> dict:
+    """Parse LLM response, handling potential markdown code blocks."""
+    text = response.strip()
+    
+    # Remove markdown code blocks if present
+    if text.startswith("```"):
+        lines = text.split("\n")
+        start = 1
+        end = len(lines) - 1
+        for i, line in enumerate(lines[1:], 1):
+            if line.strip() == "```":
+                end = i
+                break
+        text = "\n".join(lines[start:end])
+    
+    return json.loads(text)
+
+
+def is_envelope_response(data: dict) -> bool:
+    """Check if response is in envelope format."""
+    return isinstance(data.get("ok"), bool)
+
+
+def parse_envelope_response(data: dict) -> EnvelopeResponse:
+    """Parse and normalize envelope response."""
+    if data.get("ok") is True:
+        return {
+            "ok": True,
+            "data": data.get("data", {})
+        }
+    else:
+        return {
+            "ok": False,
+            "error": data.get("error", {"code": "UNKNOWN", "message": "Unknown error"}),
+            "partial_data": data.get("partial_data")
+        }
+
+
+def convert_to_envelope(data: dict, is_error: bool = False) -> EnvelopeResponse:
+    """Convert legacy format to envelope format."""
+    if is_error or "error" in data:
+        error = data.get("error", {})
+        return {
+            "ok": False,
+            "error": {
+                "code": error.get("code", "UNKNOWN"),
+                "message": error.get("message", str(error))
+            },
+            "partial_data": None
+        }
+    else:
+        return {
+            "ok": True,
+            "data": data
+        }
+
+
+def run_module(
+    name_or_path: str,
+    input_data: dict,
+    validate_input: bool = True,
+    validate_output: bool = True,
+    model: Optional[str] = None,
+    use_envelope: Optional[bool] = None,
+) -> EnvelopeResponse:
+    """
+    Run a cognitive module with the given input.
+    Returns envelope format response.
+    
+    Args:
+        name_or_path: Module name or path to module directory
+        input_data: Input data dictionary
+        validate_input: Whether to validate input against schema
+        validate_output: Whether to validate output against schema
+        model: Optional model override
+        use_envelope: Force envelope format (auto-detect if None)
+    
+    Returns:
+        EnvelopeResponse with ok=True/False and data/error
+    """
+    # Find module path
+    path = Path(name_or_path)
+    if path.exists() and path.is_dir():
+        module_path = path
+    else:
+        module_path = find_module(name_or_path)
+        if not module_path:
+            return {
+                "ok": False,
+                "error": {"code": "MODULE_NOT_FOUND", "message": f"Module not found: {name_or_path}"},
+                "partial_data": None
+            }
+    
+    # Load module (auto-detects format)
+    module = load_module(module_path)
+    
+    # Determine if we should use envelope format
+    should_use_envelope = use_envelope
+    if should_use_envelope is None:
+        # Auto-detect: use envelope for v2 format or if output.envelope is True
+        output_contract = module.get("output_contract", {})
+        should_use_envelope = (
+            module.get("format") == "v2" or 
+            output_contract.get("envelope", False)
+        )
+    
+    # Validate input
+    if validate_input and module["input_schema"]:
+        errors = validate_data(input_data, module["input_schema"], "Input")
+        if errors:
+            return {
+                "ok": False,
+                "error": {"code": "INVALID_INPUT", "message": str(errors)},
+                "partial_data": None
+            }
+    
+    # Build prompt and call LLM
+    full_prompt = build_prompt(module, input_data, use_envelope=should_use_envelope)
+    response = call_llm(full_prompt, model=model)
+    
+    # Parse response
+    try:
+        output_data = parse_llm_response(response)
+    except json.JSONDecodeError as e:
+        return {
+            "ok": False,
+            "error": {"code": "PARSE_ERROR", "message": f"Failed to parse JSON: {e}"},
+            "partial_data": None
+        }
+    
+    # Handle envelope format
+    if is_envelope_response(output_data):
+        result = parse_envelope_response(output_data)
+    else:
+        # Convert legacy format to envelope
+        result = convert_to_envelope(output_data)
+    
+    # Validate output (only for success responses)
+    if result["ok"] and validate_output and module["output_schema"]:
+        data_to_validate = result.get("data", {})
+        errors = validate_data(data_to_validate, module["output_schema"], "Output")
+        if errors:
+            return {
+                "ok": False,
+                "error": {"code": "OUTPUT_VALIDATION_ERROR", "message": str(errors)},
+                "partial_data": data_to_validate
+            }
+    
+    return result
+
+
+def run_module_legacy(
+    name_or_path: str,
+    input_data: dict,
+    validate_input: bool = True,
+    validate_output: bool = True,
+    model: Optional[str] = None,
+) -> dict:
+    """
+    Run a cognitive module (legacy API, returns raw output).
+    For backward compatibility.
+    """
+    result = run_module(
+        name_or_path,
+        input_data,
+        validate_input=validate_input,
+        validate_output=validate_output,
+        model=model,
+        use_envelope=False
+    )
+    
+    if result["ok"]:
+        return result["data"]
+    else:
+        raise ValueError(f"{result['error']['code']}: {result['error']['message']}")

{cognitive_modules-0.1.1 → cognitive_modules-0.3.0}/src/cognitive/templates.py

@@ -83,7 +83,7 @@ EXAMPLE_OUTPUT = {
 def get_schema_template(name: str) -> dict:
     """Generate schema template as dict."""
     return {
-        "$schema": "https://cognitive-modules.io/schema/v1",
+        "$schema": "https://ziel-io.github.io/cognitive-modules/schema/v1.json",
         "$id": name,
         "title": f"{name.replace('-', ' ').title()} Schema",
         "input": {

{cognitive_modules-0.1.1 → cognitive_modules-0.3.0/src/cognitive_modules.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cognitive-modules
-Version: 0.1.1
+Version: 0.3.0
 Summary: Structured LLM task runner with schema validation, confidence scoring, and subagent orchestration
 Author: ziel-io
 License: MIT
@@ -151,6 +151,7 @@ cog doctor
 | 模块 | 功能 | 示例 |
 |------|------|------|
 | `code-reviewer` | 代码审查 | `cog run code-reviewer --args "你的代码"` |
+| `code-simplifier` | 代码简化 | `cog run code-simplifier --args "复杂代码"` |
 | `task-prioritizer` | 任务优先级排序 | `cog run task-prioritizer --args "任务1,任务2"` |
 | `api-designer` | REST API 设计 | `cog run api-designer --args "订单系统"` |
 | `ui-spec-generator` | UI 规范生成 | `cog run ui-spec-generator --args "电商首页"` |
@@ -241,6 +242,134 @@ export LLM_PROVIDER=ollama
 cog doctor
 ```
 
+## 创建新模块（完整流程）
+
+以 `code-simplifier` 为例：
+
+### Step 1: 创建目录结构
+
+```bash
+mkdir -p cognitive/modules/code-simplifier
+```
+
+### Step 2: 编写 MODULE.md
+
+```bash
+cat > cognitive/modules/code-simplifier/MODULE.md << 'EOF'
+---
+name: code-simplifier
+version: 1.0.0
+responsibility: Simplify complex code while preserving functionality
+
+excludes:
+  - Changing the code's behavior
+  - Adding new features
+  - Removing functionality
+
+constraints:
+  no_network: true
+  no_side_effects: true
+  require_confidence: true
+  require_rationale: true
+---
+
+# Code Simplifier Module
+
+You are an expert at refactoring and simplifying code.
+
+## Input
+
+Code to simplify: $ARGUMENTS
+
+## Simplification Strategies
+
+1. **Remove redundancy** - Eliminate duplicate code
+2. **Improve naming** - Use clear, descriptive names
+3. **Reduce nesting** - Flatten deep conditionals
+4. **Simplify logic** - Use built-in functions
+
+## Output Requirements
+
+Return JSON containing:
+- `simplified_code`: The simplified version
+- `changes`: List of changes made
+- `summary`: Brief description
+- `rationale`: Explanation of decisions
+- `confidence`: Confidence score [0-1]
+EOF
+```
+
+### Step 3: 编写 schema.json
+
+```bash
+cat > cognitive/modules/code-simplifier/schema.json << 'EOF'
+{
+  "$schema": "https://ziel-io.github.io/cognitive-modules/schema/v1.json",
+  "input": {
+    "type": "object",
+    "properties": {
+      "code": { "type": "string" },
+      "language": { "type": "string" },
+      "$ARGUMENTS": { "type": "string" }
+    }
+  },
+  "output": {
+    "type": "object",
+    "required": ["simplified_code", "changes", "summary", "rationale", "confidence"],
+    "properties": {
+      "simplified_code": { "type": "string" },
+      "changes": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "type": { "type": "string" },
+            "description": { "type": "string" }
+          }
+        }
+      },
+      "summary": { "type": "string" },
+      "rationale": { "type": "string" },
+      "confidence": { "type": "number", "minimum": 0, "maximum": 1 }
+    }
+  }
+}
+EOF
+```
+
+### Step 4: 验证模块
+
+```bash
+cog validate code-simplifier
+cog list  # 确认模块出现在列表中
+```
+
+### Step 5: 测试运行
+
+```bash
+cog run code-simplifier --args "def calc(x): if x > 0: if x < 10: return x * 2 else: return x else: return 0" --pretty
+```
+
+### Step 6: 添加示例（可选）
+
+```bash
+mkdir -p cognitive/modules/code-simplifier/examples
+# 添加 input.json 和 output.json 作为测试用例
+```
+
+### 模块设计要点
+
+| 要素 | 必须 | 说明 |
+|------|------|------|
+| `name` | ✅ | 唯一标识符，kebab-case |
+| `version` | ✅ | 语义化版本 |
+| `responsibility` | ✅ | 一句话描述职责 |
+| `excludes` | ✅ | 明确列出不做的事 |
+| `$ARGUMENTS` | ✅ | 支持命令行参数 |
+| `confidence` | ✅ | 输出必须包含 0-1 置信度 |
+| `rationale` | ✅ | 输出必须包含推理过程 |
+| `schema.json` | ✅ | 定义输入输出契约 |
+
 ## 开发
 
 ```bash
@@ -254,7 +383,7 @@ pip install -e ".[dev]"
 # 运行测试
 pytest tests/ -v
 
-# 创建新模块
+# 创建新模块（使用模板）
 cog init my-module -d "模块描述"
 cog validate my-module
 ```

cognitive_modules-0.1.1/src/cognitive/loader.py

@@ -1,133 +0,0 @@
-"""
-Module Loader - Load cognitive modules in both old and new formats.
-
-Old format (6 files):
-  - module.md (YAML frontmatter)
-  - input.schema.json
-  - output.schema.json
-  - constraints.yaml
-  - prompt.txt
-  - examples/
-
-New format (2 files):
-  - MODULE.md (YAML frontmatter + prompt)
-  - schema.json (input + output combined)
-"""
-
-import json
-from pathlib import Path
-from typing import Optional
-
-import yaml
-
-
-def detect_format(module_path: Path) -> str:
-    """Detect module format: 'new' or 'old'."""
-    if (module_path / "MODULE.md").exists():
-        return "new"
-    elif (module_path / "module.md").exists():
-        return "old"
-    else:
-        raise FileNotFoundError(f"No MODULE.md or module.md found in {module_path}")
-
-
-def parse_frontmatter(content: str) -> tuple[dict, str]:
-    """Parse YAML frontmatter from markdown content."""
-    if not content.startswith('---'):
-        return {}, content
-    
-    parts = content.split('---', 2)
-    if len(parts) < 3:
-        return {}, content
-    
-    frontmatter = yaml.safe_load(parts[1]) or {}
-    body = parts[2].strip()
-    return frontmatter, body
-
-
-def load_new_format(module_path: Path) -> dict:
-    """Load module in new format (MODULE.md + schema.json)."""
-    # Load MODULE.md
-    with open(module_path / "MODULE.md", 'r', encoding='utf-8') as f:
-        content = f.read()
-    
-    metadata, prompt = parse_frontmatter(content)
-    
-    # Extract constraints from metadata
-    constraints = {
-        "operational": {
-            "no_external_network": metadata.get("constraints", {}).get("no_network", True),
-            "no_side_effects": metadata.get("constraints", {}).get("no_side_effects", True),
-            "no_inventing_data": metadata.get("constraints", {}).get("no_inventing_data", True),
-        },
-        "output_quality": {
-            "require_confidence": metadata.get("constraints", {}).get("require_confidence", True),
-            "require_rationale": metadata.get("constraints", {}).get("require_rationale", True),
-        }
-    }
-    
-    # Load schema.json
-    schema_path = module_path / "schema.json"
-    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", {})
-    else:
-        input_schema = {}
-        output_schema = {}
-    
-    return {
-        "name": metadata.get("name", module_path.name),
-        "path": module_path,
-        "format": "new",
-        "metadata": metadata,
-        "input_schema": input_schema,
-        "output_schema": output_schema,
-        "constraints": constraints,
-        "prompt": prompt,
-    }
-
-
-def load_old_format(module_path: Path) -> dict:
-    """Load module in old format (6 files)."""
-    # Load module.md
-    with open(module_path / "module.md", 'r', encoding='utf-8') as f:
-        content = f.read()
-    
-    metadata, _ = parse_frontmatter(content)
-    
-    # Load schemas
-    with open(module_path / "input.schema.json", 'r', encoding='utf-8') as f:
-        input_schema = json.load(f)
-    
-    with open(module_path / "output.schema.json", 'r', encoding='utf-8') as f:
-        output_schema = json.load(f)
-    
-    # Load constraints
-    with open(module_path / "constraints.yaml", 'r', encoding='utf-8') as f:
-        constraints = yaml.safe_load(f)
-    
-    # Load prompt
-    with open(module_path / "prompt.txt", 'r', encoding='utf-8') as f:
-        prompt = f.read()
-    
-    return {
-        "name": metadata.get("name", module_path.name),
-        "path": module_path,
-        "format": "old",
-        "metadata": metadata,
-        "input_schema": input_schema,
-        "output_schema": output_schema,
-        "constraints": constraints,
-        "prompt": prompt,
-    }
-
-
-def load_module(module_path: Path) -> dict:
-    """Load a module, auto-detecting format."""
-    fmt = detect_format(module_path)
-    if fmt == "new":
-        return load_new_format(module_path)
-    else:
-        return load_old_format(module_path)

cognitive_modules-0.1.1/src/cognitive/runner.py

@@ -1,140 +0,0 @@
-"""
-Module Runner - Execute cognitive modules with validation.
-Supports both old and new module formats.
-"""
-
-import json
-from pathlib import Path
-from typing import Optional
-
-import jsonschema
-import yaml
-
-from .registry import find_module
-from .loader import load_module
-from .providers import call_llm
-
-
-def validate_data(data: dict, schema: dict, label: str = "Data") -> list[str]:
-    """Validate data against schema. Returns list of errors."""
-    errors = []
-    if not schema:
-        return errors
-    try:
-        jsonschema.validate(instance=data, schema=schema)
-    except jsonschema.ValidationError as e:
-        errors.append(f"{label} validation error: {e.message} at {list(e.absolute_path)}")
-    except jsonschema.SchemaError as e:
-        errors.append(f"Schema error: {e.message}")
-    return errors
-
-
-def substitute_arguments(text: str, input_data: dict) -> str:
-    """Substitute $ARGUMENTS and $N placeholders in text."""
-    # Get arguments
-    args_value = input_data.get("$ARGUMENTS", input_data.get("query", ""))
-    
-    # Replace $ARGUMENTS
-    text = text.replace("$ARGUMENTS", str(args_value))
-    
-    # Replace $ARGUMENTS[N] and $N for indexed access
-    if isinstance(args_value, str):
-        args_list = args_value.split()
-        for i, arg in enumerate(args_list):
-            text = text.replace(f"$ARGUMENTS[{i}]", arg)
-            text = text.replace(f"${i}", arg)
-    
-    return text
-
-
-def build_prompt(module: dict, input_data: dict) -> str:
-    """Build the complete prompt for the LLM."""
-    # Substitute $ARGUMENTS in prompt
-    prompt = substitute_arguments(module["prompt"], input_data)
-    
-    parts = [
-        prompt,
-        "\n\n## Constraints\n",
-        yaml.dump(module["constraints"], default_flow_style=False),
-        "\n\n## Input\n",
-        "```json\n",
-        json.dumps(input_data, indent=2, ensure_ascii=False),
-        "\n```\n",
-        "\n## Instructions\n",
-        "Analyze the input and generate output matching the required schema.",
-        "Return ONLY valid JSON. Do not include any text before or after the JSON.",
-    ]
-    return "".join(parts)
-
-
-def parse_llm_response(response: str) -> dict:
-    """Parse LLM response, handling potential markdown code blocks."""
-    text = response.strip()
-    
-    # Remove markdown code blocks if present
-    if text.startswith("```"):
-        lines = text.split("\n")
-        start = 1
-        end = len(lines) - 1
-        for i, line in enumerate(lines[1:], 1):
-            if line.strip() == "```":
-                end = i
-                break
-        text = "\n".join(lines[start:end])
-    
-    return json.loads(text)
-
-
-def run_module(
-    name_or_path: str,
-    input_data: dict,
-    validate_input: bool = True,
-    validate_output: bool = True,
-    model: Optional[str] = None,
-) -> dict:
-    """
-    Run a cognitive module with the given input.
-    Supports both old and new module formats.
-    
-    Args:
-        name_or_path: Module name or path to module directory
-        input_data: Input data dictionary
-        validate_input: Whether to validate input against schema
-        validate_output: Whether to validate output against schema
-        model: Optional model override
-    
-    Returns:
-        The module output as a dictionary
-    """
-    # Find module path
-    path = Path(name_or_path)
-    if path.exists() and path.is_dir():
-        module_path = path
-    else:
-        module_path = find_module(name_or_path)
-        if not module_path:
-            raise FileNotFoundError(f"Module not found: {name_or_path}")
-    
-    # Load module (auto-detects format)
-    module = load_module(module_path)
-    
-    # Validate input
-    if validate_input and module["input_schema"]:
-        errors = validate_data(input_data, module["input_schema"], "Input")
-        if errors:
-            raise ValueError(f"Input validation failed: {errors}")
-    
-    # Build prompt and call LLM
-    full_prompt = build_prompt(module, input_data)
-    response = call_llm(full_prompt, model=model)
-    
-    # Parse response
-    output_data = parse_llm_response(response)
-    
-    # Validate output
-    if validate_output and module["output_schema"]:
-        errors = validate_data(output_data, module["output_schema"], "Output")
-        if errors:
-            raise ValueError(f"Output validation failed: {errors}")
-    
-    return output_data