cognitive-modules 0.1.0__py3-none-any.whl

cognitive/providers/__init__.py

@@ -0,0 +1,236 @@
+"""
+LLM Providers - Unified interface for calling different LLM backends.
+"""
+
+import json
+import os
+from pathlib import Path
+from typing import Optional
+
+
+def call_llm(prompt: str, model: Optional[str] = None) -> str:
+    """
+    Call the configured LLM with the given prompt.
+    
+    Configure via environment variables:
+    - LLM_PROVIDER: "openai", "anthropic", "ollama", "minimax", "stub"
+    - OPENAI_API_KEY / ANTHROPIC_API_KEY / MINIMAX_API_KEY
+    - LLM_MODEL: model override
+    
+    Args:
+        prompt: The prompt to send
+        model: Optional model override
+    
+    Returns:
+        The LLM's response as a string
+    """
+    provider = os.environ.get("LLM_PROVIDER", "stub").lower()
+    
+    if provider == "openai":
+        return _call_openai(prompt, model)
+    elif provider == "anthropic":
+        return _call_anthropic(prompt, model)
+    elif provider == "ollama":
+        return _call_ollama(prompt, model)
+    elif provider == "minimax":
+        return _call_minimax(prompt, model)
+    else:
+        return _call_stub(prompt)
+
+
+def _call_openai(prompt: str, model: Optional[str] = None) -> str:
+    """Call OpenAI API."""
+    try:
+        from openai import OpenAI
+    except ImportError:
+        raise ImportError("OpenAI not installed. Run: pip install cognitive[openai]")
+    
+    api_key = os.environ.get("OPENAI_API_KEY")
+    if not api_key:
+        raise ValueError("OPENAI_API_KEY environment variable not set")
+    
+    client = OpenAI(api_key=api_key)
+    model = model or os.environ.get("LLM_MODEL", "gpt-4o")
+    
+    response = client.chat.completions.create(
+        model=model,
+        messages=[
+            {"role": "system", "content": "You output only valid JSON matching the required schema."},
+            {"role": "user", "content": prompt}
+        ],
+        temperature=0.2,
+        response_format={"type": "json_object"}
+    )
+    
+    return response.choices[0].message.content
+
+
+def _call_anthropic(prompt: str, model: Optional[str] = None) -> str:
+    """Call Anthropic Claude API."""
+    try:
+        import anthropic
+    except ImportError:
+        raise ImportError("Anthropic not installed. Run: pip install cognitive[anthropic]")
+    
+    api_key = os.environ.get("ANTHROPIC_API_KEY")
+    if not api_key:
+        raise ValueError("ANTHROPIC_API_KEY environment variable not set")
+    
+    client = anthropic.Anthropic(api_key=api_key)
+    model = model or os.environ.get("LLM_MODEL", "claude-sonnet-4-20250514")
+    
+    response = client.messages.create(
+        model=model,
+        max_tokens=8192,
+        system="You output only valid JSON matching the required schema.",
+        messages=[{"role": "user", "content": prompt}]
+    )
+    
+    return response.content[0].text
+
+
+def _call_minimax(prompt: str, model: Optional[str] = None) -> str:
+    """Call MiniMax API (OpenAI-compatible)."""
+    try:
+        from openai import OpenAI
+    except ImportError:
+        raise ImportError("OpenAI SDK not installed. Run: pip install openai")
+    
+    api_key = os.environ.get("MINIMAX_API_KEY")
+    if not api_key:
+        raise ValueError("MINIMAX_API_KEY environment variable not set")
+    
+    client = OpenAI(
+        api_key=api_key,
+        base_url="https://api.minimax.chat/v1"
+    )
+    model = model or os.environ.get("LLM_MODEL", "MiniMax-Text-01")
+    
+    response = client.chat.completions.create(
+        model=model,
+        messages=[
+            {"role": "system", "content": "You output only valid JSON matching the required schema. Do not include any text before or after the JSON."},
+            {"role": "user", "content": prompt}
+        ],
+        temperature=0.2,
+    )
+    
+    return response.choices[0].message.content
+
+
+def _call_ollama(prompt: str, model: Optional[str] = None) -> str:
+    """Call local Ollama instance."""
+    try:
+        import requests
+    except ImportError:
+        raise ImportError("Requests not installed. Run: pip install cognitive[ollama]")
+    
+    host = os.environ.get("OLLAMA_HOST", "http://localhost:11434")
+    model = model or os.environ.get("LLM_MODEL", "llama3.1")
+    
+    response = requests.post(
+        f"{host}/api/generate",
+        json={
+            "model": model,
+            "prompt": prompt,
+            "stream": False,
+            "format": "json",
+            "options": {"temperature": 0.2}
+        }
+    )
+    response.raise_for_status()
+    
+    return response.json()["response"]
+
+
+def _call_stub(prompt: str) -> str:
+    """
+    Stub implementation for testing without LLM.
+    Returns example output if available.
+    """
+    # Try to find example output from a module
+    # This is a heuristic - look for cognitive/modules directories
+    search_paths = [
+        Path.cwd() / "cognitive" / "modules",
+        Path.home() / ".cognitive" / "modules",
+    ]
+    
+    for base in search_paths:
+        if not base.exists():
+            continue
+        for module_dir in base.iterdir():
+            if not module_dir.is_dir():
+                continue
+            prompt_file = module_dir / "prompt.txt"
+            output_file = module_dir / "examples" / "output.json"
+            if prompt_file.exists() and output_file.exists():
+                with open(prompt_file, 'r') as f:
+                    module_prompt = f.read()
+                # Check if this module's prompt is in the request
+                if module_prompt[:100] in prompt:
+                    with open(output_file, 'r') as f:
+                        return f.read()
+    
+    # Fallback minimal response
+    return json.dumps({
+        "specification": {},
+        "rationale": {
+            "decisions": [{"aspect": "stub", "decision": "stub", "reasoning": "No LLM configured"}],
+            "assumptions": [],
+            "open_questions": ["Set LLM_PROVIDER environment variable"]
+        },
+        "confidence": 0.0
+    })
+
+
+def check_provider_status() -> dict:
+    """Check which providers are available and configured."""
+    status = {}
+    
+    # OpenAI
+    try:
+        import openai
+        status["openai"] = {
+            "installed": True,
+            "configured": bool(os.environ.get("OPENAI_API_KEY")),
+        }
+    except ImportError:
+        status["openai"] = {"installed": False, "configured": False}
+    
+    # Anthropic
+    try:
+        import anthropic
+        status["anthropic"] = {
+            "installed": True,
+            "configured": bool(os.environ.get("ANTHROPIC_API_KEY")),
+        }
+    except ImportError:
+        status["anthropic"] = {"installed": False, "configured": False}
+    
+    # MiniMax (uses OpenAI SDK)
+    try:
+        import openai
+        status["minimax"] = {
+            "installed": True,
+            "configured": bool(os.environ.get("MINIMAX_API_KEY")),
+        }
+    except ImportError:
+        status["minimax"] = {"installed": False, "configured": False}
+    
+    # Ollama
+    try:
+        import requests
+        host = os.environ.get("OLLAMA_HOST", "http://localhost:11434")
+        try:
+            r = requests.get(f"{host}/api/tags", timeout=2)
+            status["ollama"] = {"installed": True, "configured": r.status_code == 200}
+        except:
+            status["ollama"] = {"installed": True, "configured": False}
+    except ImportError:
+        status["ollama"] = {"installed": False, "configured": False}
+    
+    # Current provider
+    status["current_provider"] = os.environ.get("LLM_PROVIDER", "stub")
+    status["current_model"] = os.environ.get("LLM_MODEL", "(default)")
+    
+    return status

cognitive/registry.py

@@ -0,0 +1,276 @@
+"""
+Module Registry - Discover, manage, and install cognitive modules.
+
+Search order:
+1. ./cognitive/modules (project-local)
+2. ~/.cognitive/modules (user-global)
+3. /usr/local/share/cognitive/modules (system-wide, optional)
+
+Registry:
+- cognitive-registry.json indexes public modules
+"""
+
+import json
+import os
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Optional
+from urllib.request import urlopen
+from urllib.error import URLError
+
+# Standard module search paths
+SEARCH_PATHS = [
+    Path.cwd() / "cognitive" / "modules",  # Project-local
+    Path.home() / ".cognitive" / "modules",  # User-global
+    Path("/usr/local/share/cognitive/modules"),  # System-wide
+]
+
+# User global install location
+USER_MODULES_DIR = Path.home() / ".cognitive" / "modules"
+
+# Default registry URL
+DEFAULT_REGISTRY_URL = "https://raw.githubusercontent.com/leizii/cognitive-modules/main/cognitive-registry.json"
+
+# Local registry cache
+REGISTRY_CACHE = Path.home() / ".cognitive" / "registry-cache.json"
+
+
+def get_search_paths() -> list[Path]:
+    """Get all module search paths, including custom paths from env."""
+    paths = SEARCH_PATHS.copy()
+    
+    # Add custom paths from environment
+    custom = os.environ.get("COGNITIVE_MODULES_PATH")
+    if custom:
+        for p in custom.split(":"):
+            paths.insert(0, Path(p))
+    
+    return paths
+
+
+def find_module(name: str) -> Optional[Path]:
+    """Find a module by name, searching all paths in order."""
+    for base_path in get_search_paths():
+        module_path = base_path / name
+        # Support both new and old format
+        if module_path.exists():
+            if (module_path / "MODULE.md").exists() or (module_path / "module.md").exists():
+                return module_path
+    return None
+
+
+def list_modules() -> list[dict]:
+    """List all available modules from all search paths."""
+    modules = []
+    seen = set()
+    
+    for base_path in get_search_paths():
+        if not base_path.exists():
+            continue
+        
+        for module_dir in base_path.iterdir():
+            if not module_dir.is_dir():
+                continue
+            if module_dir.name in seen:
+                continue
+            # Support both formats
+            if not ((module_dir / "MODULE.md").exists() or (module_dir / "module.md").exists()):
+                continue
+            
+            # Detect format
+            fmt = "new" if (module_dir / "MODULE.md").exists() else "old"
+            
+            seen.add(module_dir.name)
+            modules.append({
+                "name": module_dir.name,
+                "path": module_dir,
+                "location": "local" if base_path == SEARCH_PATHS[0] else "global",
+                "format": fmt,
+            })
+    
+    return modules
+
+
+def ensure_user_modules_dir() -> Path:
+    """Ensure user global modules directory exists."""
+    USER_MODULES_DIR.mkdir(parents=True, exist_ok=True)
+    return USER_MODULES_DIR
+
+
+def install_from_local(source: Path, name: Optional[str] = None) -> Path:
+    """Install a module from a local path."""
+    source = Path(source).resolve()
+    if not source.exists():
+        raise FileNotFoundError(f"Source not found: {source}")
+    
+    # Check for valid module (either format)
+    if not ((source / "MODULE.md").exists() or (source / "module.md").exists()):
+        raise ValueError(f"Not a valid module (missing MODULE.md or module.md): {source}")
+    
+    module_name = name or source.name
+    target = ensure_user_modules_dir() / module_name
+    
+    if target.exists():
+        shutil.rmtree(target)
+    
+    shutil.copytree(source, target)
+    return target
+
+
+def install_from_git(url: str, subdir: Optional[str] = None, name: Optional[str] = None) -> Path:
+    """
+    Install a module from a git repository.
+    
+    Supports:
+    - github:org/repo/path/to/module
+    - git+https://github.com/org/repo#subdir=path/to/module
+    - https://github.com/org/repo (with subdir parameter)
+    """
+    # Parse github: shorthand
+    if url.startswith("github:"):
+        parts = url[7:].split("/", 2)
+        if len(parts) < 2:
+            raise ValueError(f"Invalid github URL: {url}")
+        org, repo = parts[0], parts[1]
+        if len(parts) == 3:
+            subdir = parts[2]
+        url = f"https://github.com/{org}/{repo}.git"
+    
+    # Parse git+https:// with fragment
+    elif url.startswith("git+"):
+        url = url[4:]
+        if "#" in url:
+            url, fragment = url.split("#", 1)
+            for part in fragment.split("&"):
+                if part.startswith("subdir="):
+                    subdir = part[7:]
+    
+    # Clone to temp directory
+    with tempfile.TemporaryDirectory() as tmpdir:
+        tmppath = Path(tmpdir)
+        
+        # Shallow clone
+        result = subprocess.run(
+            ["git", "clone", "--depth", "1", url, str(tmppath / "repo")],
+            capture_output=True,
+            text=True
+        )
+        if result.returncode != 0:
+            raise RuntimeError(f"Git clone failed: {result.stderr}")
+        
+        # Find module source
+        source = tmppath / "repo"
+        if subdir:
+            source = source / subdir
+        
+        if not source.exists():
+            raise FileNotFoundError(f"Subdir not found: {subdir}")
+        
+        # Determine module name
+        module_name = name or source.name
+        
+        # Install from cloned source
+        return install_from_local(source, module_name)
+
+
+def install_from_registry(module_name: str) -> Path:
+    """Install a module from the public registry."""
+    registry = fetch_registry()
+    
+    if module_name not in registry.get("modules", {}):
+        raise ValueError(f"Module not found in registry: {module_name}")
+    
+    module_info = registry["modules"][module_name]
+    source = module_info.get("source")
+    
+    if not source:
+        raise ValueError(f"No source defined for module: {module_name}")
+    
+    return install_module(source, name=module_name)
+
+
+def install_module(source: str, name: Optional[str] = None) -> Path:
+    """
+    Install a module from various sources.
+    
+    Sources:
+    - local:/path/to/module
+    - github:org/repo/path/to/module
+    - git+https://github.com/org/repo#subdir=path
+    - /absolute/path (treated as local)
+    - ./relative/path (treated as local)
+    - registry:module-name (from public registry)
+    """
+    if source.startswith("local:"):
+        return install_from_local(Path(source[6:]), name)
+    elif source.startswith("registry:"):
+        return install_from_registry(source[9:])
+    elif source.startswith("github:") or source.startswith("git+"):
+        return install_from_git(source, name=name)
+    elif source.startswith("/") or source.startswith("./") or source.startswith(".."):
+        return install_from_local(Path(source), name)
+    elif source.startswith("https://github.com"):
+        return install_from_git(source, name=name)
+    else:
+        # Try registry first, then local
+        try:
+            return install_from_registry(source)
+        except:
+            return install_from_local(Path(source), name)
+
+
+def uninstall_module(name: str) -> bool:
+    """Uninstall a module from user global location."""
+    target = USER_MODULES_DIR / name
+    if target.exists():
+        shutil.rmtree(target)
+        return True
+    return False
+
+
+def fetch_registry(url: Optional[str] = None, use_cache: bool = True) -> dict:
+    """Fetch the public module registry."""
+    url = url or os.environ.get("COGNITIVE_REGISTRY_URL", DEFAULT_REGISTRY_URL)
+    
+    # Try cache first
+    if use_cache and REGISTRY_CACHE.exists():
+        try:
+            with open(REGISTRY_CACHE, 'r') as f:
+                return json.load(f)
+        except:
+            pass
+    
+    # Fetch from URL
+    try:
+        with urlopen(url, timeout=5) as response:
+            data = json.loads(response.read().decode())
+        
+        # Cache it
+        REGISTRY_CACHE.parent.mkdir(parents=True, exist_ok=True)
+        with open(REGISTRY_CACHE, 'w') as f:
+            json.dump(data, f)
+        
+        return data
+    except (URLError, json.JSONDecodeError) as e:
+        # Return empty registry if fetch fails
+        return {"modules": {}, "error": str(e)}
+
+
+def search_registry(query: str) -> list[dict]:
+    """Search the registry for modules matching query."""
+    registry = fetch_registry()
+    results = []
+    
+    query_lower = query.lower()
+    for name, info in registry.get("modules", {}).items():
+        if query_lower in name.lower() or query_lower in info.get("description", "").lower():
+            results.append({
+                "name": name,
+                "description": info.get("description", ""),
+                "source": info.get("source", ""),
+                "version": info.get("version", ""),
+            })
+    
+    return results

cognitive/runner.py

@@ -0,0 +1,140 @@
+"""
+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