cognitive-modules 0.1.1__py3-none-any.whl → 0.2.0__py3-none-any.whl

cognitive/loader.py

@@ -1,17 +1,22 @@
 """
-Module Loader - Load cognitive modules in both old and new formats.
+Module Loader - Load cognitive modules in all formats.
 
-Old format (6 files):
+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
-  - examples/
-
-New format (2 files):
-  - MODULE.md (YAML frontmatter + prompt)
-  - schema.json (input + output combined)
 """
 
 import json
@@ -22,13 +27,15 @@ import yaml
 
 
 def detect_format(module_path: Path) -> str:
-    """Detect module format: 'new' or 'old'."""
-    if (module_path / "MODULE.md").exists():
-        return "new"
+    """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 "old"
+        return "v0"
     else:
-        raise FileNotFoundError(f"No MODULE.md or module.md found in {module_path}")
+        raise FileNotFoundError(f"No module.yaml, MODULE.md, or module.md found in {module_path}")
 
 
 def parse_frontmatter(content: str) -> tuple[dict, str]:
@@ -45,8 +52,79 @@ def parse_frontmatter(content: str) -> tuple[dict, str]:
     return frontmatter, body
 
 
-def load_new_format(module_path: Path) -> dict:
-    """Load module in new format (MODULE.md + schema.json)."""
+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
+    constraints_raw = manifest.get("constraints", {})
+    constraints = {
+        "operational": {
+            "no_external_network": constraints_raw.get("no_network", True),
+            "no_side_effects": constraints_raw.get("no_side_effects", True),
+            "no_file_write": constraints_raw.get("no_file_write", True),
+            "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),
+        }
+    }
+    
+    # Extract tools policy
+    tools = manifest.get("tools", {})
+    
+    # Extract output contract
+    output_contract = manifest.get("output", {})
+    
+    # Extract failure contract
+    failure_contract = manifest.get("failure", {})
+    
+    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,
+        "tools": tools,
+        "output_contract": output_contract,
+        "failure_contract": failure_contract,
+        "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()
@@ -79,8 +157,11 @@ def load_new_format(module_path: Path) -> dict:
     
     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": "new",
+        "format": "v1",
         "metadata": metadata,
         "input_schema": input_schema,
         "output_schema": output_schema,
@@ -89,8 +170,8 @@ def load_new_format(module_path: Path) -> dict:
     }
 
 
-def load_old_format(module_path: Path) -> dict:
-    """Load module in old format (6 files)."""
+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()
@@ -114,8 +195,11 @@ def load_old_format(module_path: Path) -> dict:
     
     return {
         "name": metadata.get("name", module_path.name),
+        "version": metadata.get("version", "1.0.0"),
+        "responsibility": metadata.get("responsibility", ""),
+        "excludes": [],
         "path": module_path,
-        "format": "old",
+        "format": "v0",
         "metadata": metadata,
         "input_schema": input_schema,
         "output_schema": output_schema,
@@ -127,7 +211,37 @@ def load_old_format(module_path: Path) -> dict:
 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)
+    if fmt == "v2":
+        return load_v2_format(module_path)
+    elif fmt == "v1":
+        return load_v1_format(module_path)
     else:
-        return load_old_format(module_path)
+        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/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.dist-info → cognitive_modules-0.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cognitive-modules
-Version: 0.1.1
+Version: 0.2.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.dist-info → cognitive_modules-0.2.0.dist-info}/RECORD

@@ -1,15 +1,15 @@
 cognitive/__init__.py,sha256=uSX5NuOWyW0qtq1bnxbzabZ0OQakAtsjF0MWbjQBvwE,401
 cognitive/cli.py,sha256=q0vHCHFmig9gQ85KRyIrX6vrJZFm5nXF_bW5qQRGEPU,14608
-cognitive/loader.py,sha256=E_lSuy2ERBWfziOHr3f13nLq-wEYvBqIKrGlPk4PQyA,4031
+cognitive/loader.py,sha256=i9ulJtd5Itj4QYhUYfuHOXtzCBBtY8L1EkMu5yM-0SU,8094
 cognitive/registry.py,sha256=aBkkpg5PtL_tKDIOXpv6vblB7x_Ax0eVaWgejuQTfCE,8851
 cognitive/runner.py,sha256=9uxBAGd3gtXnwUm5x2CjhXi_S1gd2nfjRfM3Q_1f30Q,4362
 cognitive/subagent.py,sha256=fb7LWwNF6YcJtC_T1dK0EvzqWMBnav-kiCIpvVohEBw,8142
-cognitive/templates.py,sha256=fEd1Tj5A12PUE256dC7-cnsulWzm6MTrcQ0yLPWrtx0,4692
+cognitive/templates.py,sha256=lKC197X9aQIA-npUvVCaplSwvhxjsH_KYVCQtrTZrL4,4712
 cognitive/validator.py,sha256=1v1HUHYOlAc2sYCkIq_gnUMMnca0fdtQwr7UMBFpp04,12200
 cognitive/providers/__init__.py,sha256=hqhVA1IEXpVtyCAteXhO5yD8a8ikQpVIPEKJVHLtRFY,7492
-cognitive_modules-0.1.1.dist-info/licenses/LICENSE,sha256=NXFYUy2hPJdh3NHRxMChTnMiQD9k8zFxkmR7gWefexc,1064
-cognitive_modules-0.1.1.dist-info/METADATA,sha256=oonLUUD0fO3t7bo8DVZKlqC1vM5ZyHFUw7KXP46SLdI,8242
-cognitive_modules-0.1.1.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-cognitive_modules-0.1.1.dist-info/entry_points.txt,sha256=PKHlfrFmve5K2349ryipySKbOOsKxo_vIq1NNT-iBV0,42
-cognitive_modules-0.1.1.dist-info/top_level.txt,sha256=kGIfDucCKylo8cRBtxER_v3DHIea-Sol9x9YSJo1u3Y,10
-cognitive_modules-0.1.1.dist-info/RECORD,,
+cognitive_modules-0.2.0.dist-info/licenses/LICENSE,sha256=NXFYUy2hPJdh3NHRxMChTnMiQD9k8zFxkmR7gWefexc,1064
+cognitive_modules-0.2.0.dist-info/METADATA,sha256=d6Jm2ALcRX56UBBvKDWn8uiLx8MIcnUhK4RLl8x2uvg,11381
+cognitive_modules-0.2.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+cognitive_modules-0.2.0.dist-info/entry_points.txt,sha256=PKHlfrFmve5K2349ryipySKbOOsKxo_vIq1NNT-iBV0,42
+cognitive_modules-0.2.0.dist-info/top_level.txt,sha256=kGIfDucCKylo8cRBtxER_v3DHIea-Sol9x9YSJo1u3Y,10
+cognitive_modules-0.2.0.dist-info/RECORD,,