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

cognitive/loader.py

@@ -79,22 +79,28 @@ def load_v2_format(module_path: Path) -> dict:
         output_schema = {}
         error_schema = {}
     
-    # Extract constraints
+    # 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),
-            "no_side_effects": constraints_raw.get("no_side_effects", True),
-            "no_file_write": constraints_raw.get("no_file_write", True),
+            "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", {})
     
@@ -104,6 +110,9 @@ def load_v2_format(module_path: Path) -> dict:
     # 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"),
@@ -116,9 +125,11 @@ def load_v2_format(module_path: Path) -> dict:
         "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,
     }
 

cognitive/runner.py

@@ -1,11 +1,11 @@
 """
 Module Runner - Execute cognitive modules with validation.
-Supports both old and new module formats.
+Supports v2 envelope format and legacy formats.
 """
 
 import json
 from pathlib import Path
-from typing import Optional
+from typing import Optional, TypedDict, Union
 
 import jsonschema
 import yaml
@@ -15,6 +15,25 @@ 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 = []
@@ -32,7 +51,7 @@ def validate_data(data: dict, schema: dict, label: str = "Data") -> list[str]:
 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", ""))
+    args_value = input_data.get("$ARGUMENTS", input_data.get("query", input_data.get("code", "")))
     
     # Replace $ARGUMENTS
     text = text.replace("$ARGUMENTS", str(args_value))
@@ -47,7 +66,7 @@ def substitute_arguments(text: str, input_data: dict) -> str:
     return text
 
 
-def build_prompt(module: dict, input_data: dict) -> str:
+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)
@@ -60,10 +79,23 @@ def build_prompt(module: dict, input_data: dict) -> str:
         "```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.",
     ]
+    
+    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)
 
 
@@ -85,16 +117,56 @@ def parse_llm_response(response: str) -> dict:
     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,
-) -> dict:
+    use_envelope: Optional[bool] = None,
+) -> EnvelopeResponse:
     """
     Run a cognitive module with the given input.
-    Supports both old and new module formats.
+    Returns envelope format response.
     
     Args:
         name_or_path: Module name or path to module directory
@@ -102,9 +174,10 @@ def run_module(
         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:
-        The module output as a dictionary
+        EnvelopeResponse with ok=True/False and data/error
     """
     # Find module path
     path = Path(name_or_path)
@@ -113,28 +186,91 @@ def run_module(
     else:
         module_path = find_module(name_or_path)
         if not module_path:
-            raise FileNotFoundError(f"Module not found: {name_or_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:
-            raise ValueError(f"Input validation failed: {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)
+    full_prompt = build_prompt(module, input_data, use_envelope=should_use_envelope)
     response = call_llm(full_prompt, model=model)
     
     # Parse response
-    output_data = parse_llm_response(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
+        }
     
-    # Validate output
-    if validate_output and module["output_schema"]:
-        errors = validate_data(output_data, module["output_schema"], "Output")
+    # 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:
-            raise ValueError(f"Output validation failed: {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
+    )
     
-    return output_data
+    if result["ok"]:
+        return result["data"]
+    else:
+        raise ValueError(f"{result['error']['code']}: {result['error']['message']}")

{cognitive_modules-0.2.0.dist-info → cognitive_modules-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cognitive-modules
-Version: 0.2.0
+Version: 0.3.0
 Summary: Structured LLM task runner with schema validation, confidence scoring, and subagent orchestration
 Author: ziel-io
 License: MIT

{cognitive_modules-0.2.0.dist-info → cognitive_modules-0.3.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=i9ulJtd5Itj4QYhUYfuHOXtzCBBtY8L1EkMu5yM-0SU,8094
+cognitive/loader.py,sha256=3_ShEfefOMP2EJjpQ1VGTGio4K_GUWLZMQHa0RgvBwg,8715
 cognitive/registry.py,sha256=aBkkpg5PtL_tKDIOXpv6vblB7x_Ax0eVaWgejuQTfCE,8851
-cognitive/runner.py,sha256=9uxBAGd3gtXnwUm5x2CjhXi_S1gd2nfjRfM3Q_1f30Q,4362
+cognitive/runner.py,sha256=KFO_pV7YTluYaL98_5bPp_HTNgwsTvlUjgNYlI8mo-w,8467
 cognitive/subagent.py,sha256=fb7LWwNF6YcJtC_T1dK0EvzqWMBnav-kiCIpvVohEBw,8142
 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.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,,
+cognitive_modules-0.3.0.dist-info/licenses/LICENSE,sha256=NXFYUy2hPJdh3NHRxMChTnMiQD9k8zFxkmR7gWefexc,1064
+cognitive_modules-0.3.0.dist-info/METADATA,sha256=PcUIJeGz7wr78MHPEdmDRxqKuFLEzX5aEgpMRHfGN-w,11381
+cognitive_modules-0.3.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+cognitive_modules-0.3.0.dist-info/entry_points.txt,sha256=PKHlfrFmve5K2349ryipySKbOOsKxo_vIq1NNT-iBV0,42
+cognitive_modules-0.3.0.dist-info/top_level.txt,sha256=kGIfDucCKylo8cRBtxER_v3DHIea-Sol9x9YSJo1u3Y,10
+cognitive_modules-0.3.0.dist-info/RECORD,,