cct-cli 0.7.9.0__py3-none-any.whl

calc_terminal/capabilities/adapters/scientific_comp.py

@@ -0,0 +1,123 @@
+"""
+Scientific Computing Capability Adapter per §43:
+- matlab.execute
+- numpy.compute
+- scipy.optimize
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from typing import Any, Dict, Optional, Tuple
+
+from ..schema import (
+    AvailabilityStatus,
+    Capability,
+    CapabilityCategory,
+    CapabilitySpec,
+    ExecutionResult,
+)
+
+
+def _check_matlab_health() -> Tuple[AvailabilityStatus, str]:
+    if shutil.which("matlab"):
+        return AvailabilityStatus.AVAILABLE, "MATLAB CLI executable found"
+    try:
+        import matlab.engine  # noqa: F401
+        return AvailabilityStatus.AVAILABLE, "MATLAB Python Engine available"
+    except ImportError:
+        return AvailabilityStatus.SOFTWARE_NOT_FOUND, "MATLAB is not installed on this system"
+
+
+def _check_scientific_health() -> Tuple[AvailabilityStatus, str]:
+    try:
+        import numpy  # noqa: F401
+        import scipy  # noqa: F401
+        return AvailabilityStatus.AVAILABLE, f"NumPy {numpy.__version__}, SciPy {scipy.__version__} ready"
+    except ImportError as e:
+        return AvailabilityStatus.SOFTWARE_NOT_FOUND, f"Scientific packages missing: {e}"
+
+
+def _matlab_execute_handler(args: Dict[str, Any], context: Optional[Dict[str, Any]] = None) -> ExecutionResult:
+    script = args.get("script", "")
+    code = args.get("code", "")
+    if not script and not code:
+        return ExecutionResult(success=False, error="script or code argument is required")
+
+    exe = shutil.which("matlab")
+    if not exe:
+        return ExecutionResult(
+            success=False,
+            error="MATLAB executable not found on host machine. Please install and license MATLAB.",
+            status=AvailabilityStatus.SOFTWARE_NOT_FOUND,
+        )
+
+    matlab_cmd = f"-batch \"{code}\"" if code else f"-batch \"run('{script}')\""
+    try:
+        proc = subprocess.run([exe, "-nodisplay", "-nosplash", "-batch", code or f"run('{script}')"], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, timeout=120)
+        return ExecutionResult(
+            success=(proc.returncode == 0),
+            output=proc.stdout,
+            error=proc.stderr if proc.returncode != 0 else None,
+            metadata={"exit_code": proc.returncode},
+        )
+    except Exception as e:
+        return ExecutionResult(success=False, error=f"MATLAB execution failed: {e}")
+
+
+def _numpy_compute_handler(args: Dict[str, Any], context: Optional[Dict[str, Any]] = None) -> ExecutionResult:
+    expr = args.get("expression", "")
+    if not expr:
+        return ExecutionResult(success=False, error="expression argument is required")
+
+    try:
+        import numpy as np
+        # Evaluate safely within numpy scope
+        scope = {"np": np}
+        # Disallow dangerous builtins
+        res = eval(expr, {"__builtins__": {}}, scope)
+        if isinstance(res, np.ndarray):
+            out = {
+                "shape": list(res.shape),
+                "dtype": str(res.dtype),
+                "data": res.tolist() if res.size <= 1000 else "Array too large to serialize; summary displayed",
+                "mean": float(np.mean(res)) if res.size > 0 else None,
+            }
+        else:
+            out = res
+        return ExecutionResult(success=True, output=out)
+    except Exception as e:
+        return ExecutionResult(success=False, error=f"NumPy computation error: {e}")
+
+
+def register_scientific_capabilities(bus):
+    bus.register(Capability(
+        spec=CapabilitySpec(
+            name="matlab.execute",
+            version="1.0.0",
+            category=CapabilityCategory.SCIENTIFIC,
+            description="Execute MATLAB script or expressions in non-display batch mode.",
+            input_schema={"code": "string?", "script": "string?"},
+            output_schema={"output": "string"},
+            permissions=["execute_terminal"],
+            documentation="Executes MATLAB commands where licensed.",
+        ),
+        handler=_matlab_execute_handler,
+        health_checker=_check_matlab_health,
+    ))
+
+    bus.register(Capability(
+        spec=CapabilitySpec(
+            name="numpy.compute",
+            version="1.0.0",
+            category=CapabilityCategory.SCIENTIFIC,
+            description="Perform numerical array calculations using NumPy.",
+            input_schema={"expression": "string"},
+            output_schema={"result": "any"},
+            permissions=["read_workspace"],
+            documentation="Evaluates mathematical numpy expressions.",
+        ),
+        handler=_numpy_compute_handler,
+        health_checker=_check_scientific_health,
+    ))

calc_terminal/capabilities/adapters/structural_bio.py

@@ -0,0 +1,161 @@
+"""
+Structural Biology Capability Adapter per §44:
+- pymol.open
+- chimerax.open
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from typing import Any, Dict, Optional, Tuple
+
+from ..schema import (
+    AvailabilityStatus,
+    Capability,
+    CapabilityCategory,
+    CapabilitySpec,
+    ExecutionResult,
+)
+
+
+def _find_pymol() -> Optional[str]:
+    cmd = shutil.which("pymol")
+    if cmd:
+        return cmd
+    candidates = [
+        r"C:\Program Files\PyMOL\PyMOLWin.exe",
+        r"C:\Program Files\PyMOL\PyMOL.exe",
+        r"C:\Program Files (x86)\Schrodinger\PyMOL\PyMOLWin.exe",
+        "/usr/bin/pymol",
+        "/usr/local/bin/pymol",
+        "/Applications/PyMOL.app/Contents/MacOS/PyMOL",
+    ]
+    for c in candidates:
+        if os.path.exists(c):
+            return c
+    return None
+
+
+def _find_chimerax() -> Optional[str]:
+    cmd = shutil.which("chimerax")
+    if cmd:
+        return cmd
+    candidates = [
+        r"C:\Program Files\ChimeraX\bin\ChimeraX.exe",
+        r"C:\Program Files\ChimeraX 1.7\bin\ChimeraX.exe",
+        "/usr/bin/chimerax",
+        "/usr/local/bin/chimerax",
+        "/Applications/ChimeraX.app/Contents/MacOS/ChimeraX",
+    ]
+    for c in candidates:
+        if os.path.exists(c):
+            return c
+    return None
+
+
+def _check_structural_health() -> Tuple[AvailabilityStatus, str]:
+    pymol = _find_pymol()
+    chimerax = _find_chimerax()
+    if pymol or chimerax:
+        found = []
+        if pymol:
+            found.append(f"PyMOL: {pymol}")
+        if chimerax:
+            found.append(f"ChimeraX: {chimerax}")
+        return AvailabilityStatus.AVAILABLE, ", ".join(found)
+    return AvailabilityStatus.SOFTWARE_NOT_FOUND, "Neither PyMOL nor ChimeraX executable found on system"
+
+
+def _pymol_open_handler(args: Dict[str, Any], context: Optional[Dict[str, Any]] = None) -> ExecutionResult:
+    structure_path = args.get("path", "")
+    if not structure_path:
+        return ExecutionResult(success=False, error="path argument (PDB/mmCIF) is required")
+    structure_path = os.path.abspath(os.path.expanduser(structure_path))
+    if not os.path.exists(structure_path):
+        return ExecutionResult(success=False, error=f"Structure file not found: {structure_path}")
+
+    exe = _find_pymol()
+    if not exe:
+        return ExecutionResult(
+            success=False,
+            error="PyMOL executable not found on host machine. Please install PyMOL.",
+            status=AvailabilityStatus.SOFTWARE_NOT_FOUND,
+        )
+
+    script = args.get("script", "")
+    cmd = [exe, structure_path]
+    if script:
+        cmd.extend(["-d", script])
+
+    try:
+        # Launch non-blocking
+        subprocess.Popen(cmd)
+        return ExecutionResult(
+            success=True,
+            output=f"Opened {structure_path} in PyMOL ({exe})",
+            metadata={"executable": exe, "structure": structure_path},
+        )
+    except Exception as e:
+        return ExecutionResult(success=False, error=f"Failed to launch PyMOL: {e}")
+
+
+def _chimerax_open_handler(args: Dict[str, Any], context: Optional[Dict[str, Any]] = None) -> ExecutionResult:
+    structure_path = args.get("path", "")
+    if not structure_path:
+        return ExecutionResult(success=False, error="path argument (PDB/mmCIF) is required")
+    structure_path = os.path.abspath(os.path.expanduser(structure_path))
+    if not os.path.exists(structure_path):
+        return ExecutionResult(success=False, error=f"Structure file not found: {structure_path}")
+
+    exe = _find_chimerax()
+    if not exe:
+        return ExecutionResult(
+            success=False,
+            error="ChimeraX executable not found on host machine. Please install ChimeraX.",
+            status=AvailabilityStatus.SOFTWARE_NOT_FOUND,
+        )
+
+    cmd = [exe, structure_path]
+    try:
+        subprocess.Popen(cmd)
+        return ExecutionResult(
+            success=True,
+            output=f"Opened {structure_path} in ChimeraX ({exe})",
+            metadata={"executable": exe, "structure": structure_path},
+        )
+    except Exception as e:
+        return ExecutionResult(success=False, error=f"Failed to launch ChimeraX: {e}")
+
+
+def register_structural_bio_capabilities(bus):
+    bus.register(Capability(
+        spec=CapabilitySpec(
+            name="pymol.open",
+            version="1.0.0",
+            category=CapabilityCategory.BIO,
+            description="Open protein/molecular structure in PyMOL for 3D visualization.",
+            input_schema={"path": "string", "script": "string?"},
+            output_schema={"status": "string"},
+            permissions=["execute_terminal"],
+            documentation="Launches PyMOL with the target structure.",
+        ),
+        handler=_pymol_open_handler,
+        health_checker=_check_structural_health,
+    ))
+
+    bus.register(Capability(
+        spec=CapabilitySpec(
+            name="chimerax.open",
+            version="1.0.0",
+            category=CapabilityCategory.BIO,
+            description="Open biomolecular structure in UCSF ChimeraX for visualization and analysis.",
+            input_schema={"path": "string"},
+            output_schema={"status": "string"},
+            permissions=["execute_terminal"],
+            documentation="Launches ChimeraX with the target structure.",
+        ),
+        handler=_chimerax_open_handler,
+        health_checker=_check_structural_health,
+    ))

calc_terminal/capabilities/adapters/terminal.py

@@ -0,0 +1,99 @@
+"""
+Terminal / Process Execution Capability Adapter:
+- terminal.execute
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import time
+from typing import Any, Dict, Optional, Tuple
+
+from ..schema import (
+    AvailabilityStatus,
+    Capability,
+    CapabilityCategory,
+    CapabilitySpec,
+    ExecutionResult,
+)
+
+
+def _check_terminal_health() -> Tuple[AvailabilityStatus, str]:
+    return AvailabilityStatus.AVAILABLE, "System shell execution available"
+
+
+def _execute_handler(args: Dict[str, Any], context: Optional[Dict[str, Any]] = None) -> ExecutionResult:
+    command = args.get("command", "")
+    if not command:
+        return ExecutionResult(success=False, error="command argument is required")
+
+    cwd = args.get("cwd", os.getcwd())
+    timeout = float(args.get("timeout", 60.0))
+    env_overrides = args.get("env", {})
+
+    env = os.environ.copy()
+    if isinstance(env_overrides, dict):
+        env.update(env_overrides)
+
+    t0 = time.perf_counter()
+    try:
+        proc = subprocess.run(
+            command,
+            cwd=cwd,
+            env=env,
+            shell=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            timeout=timeout,
+        )
+        duration = round((time.perf_counter() - t0) * 1000.0, 2)
+        success = (proc.returncode == 0)
+
+        return ExecutionResult(
+            success=success,
+            output=proc.stdout,
+            error=proc.stderr if not success else None,
+            duration_ms=duration,
+            metadata={
+                "exit_code": proc.returncode,
+                "command": command,
+                "cwd": cwd,
+                "stdout": proc.stdout,
+                "stderr": proc.stderr,
+            },
+        )
+    except subprocess.TimeoutExpired as e:
+        duration = round((time.perf_counter() - t0) * 1000.0, 2)
+        return ExecutionResult(
+            success=False,
+            error=f"Command timed out after {timeout} seconds",
+            duration_ms=duration,
+            metadata={"exit_code": -1, "command": command, "timeout": timeout},
+        )
+    except Exception as e:
+        duration = round((time.perf_counter() - t0) * 1000.0, 2)
+        return ExecutionResult(
+            success=False,
+            error=str(e),
+            duration_ms=duration,
+            metadata={"exit_code": -1, "command": command},
+        )
+
+
+def register_terminal_capabilities(bus):
+    bus.register(Capability(
+        spec=CapabilitySpec(
+            name="terminal.execute",
+            version="1.0.0",
+            category=CapabilityCategory.TERMINAL,
+            description="Execute a shell command with stdout, stderr and exit code capture.",
+            input_schema={"command": "string", "cwd": "string?", "timeout": "number?", "env": "object?"},
+            output_schema={"output": "string", "exit_code": "integer"},
+            permissions=["execute_terminal"],
+            documentation="Executes a command line string in the host shell.",
+        ),
+        handler=_execute_handler,
+        health_checker=_check_terminal_health,
+    ))

calc_terminal/capabilities/bus.py

@@ -0,0 +1,178 @@
+"""
+CAT Capability Bus — Central Architecture per §4, §56, §57.
+Modes request capabilities through this bus; tools and integrations are never
+owned privately by individual modes.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
+
+from .schema import (
+    AvailabilityStatus,
+    Capability,
+    CapabilityCategory,
+    CapabilitySpec,
+    ExecutionError,
+    ExecutionResult,
+)
+
+_LOG = logging.getLogger("cct.capabilities")
+
+
+class CapabilityBus:
+    """Central registry and execution dispatch for all CAT capabilities."""
+
+    _instance: Optional[CapabilityBus] = None
+    _lock = threading.Lock()
+
+    def __new__(cls) -> CapabilityBus:
+        with cls._lock:
+            if cls._instance is None:
+                cls._instance = super(CapabilityBus, cls).__new__(cls)
+                cls._instance._capabilities: Dict[str, Capability] = {}
+                cls._instance._initialized = False
+            return cls._instance
+
+    def register(self, capability: Capability) -> None:
+        """Register a new capability in the bus."""
+        name = capability.name.strip().lower()
+        self._capabilities[name] = capability
+        _LOG.debug("Registered capability: %s (version %s)", name, capability.spec.version)
+
+    def get(self, name: str) -> Optional[Capability]:
+        """Look up a capability by canonical name."""
+        canonical = (name or "").strip().lower()
+        return self._capabilities.get(canonical)
+
+    def get_capability(self, name: str) -> Optional[Capability]:
+        """Look up a capability by canonical name."""
+        return self.get(name)
+
+    def has(self, name: str) -> bool:
+        """Check whether a capability is registered."""
+        return name.strip().lower() in self._capabilities
+
+    def list_capabilities(
+        self,
+        category: Optional[Union[CapabilityCategory, str]] = None,
+        status: Optional[AvailabilityStatus] = None,
+    ) -> List[Capability]:
+        """Return registered capabilities filtered by category or status."""
+        caps = list(self._capabilities.values())
+        if category:
+            cat_val = category.value if isinstance(category, CapabilityCategory) else str(category).lower()
+            caps = [c for c in caps if c.spec.category.value.lower() == cat_val]
+        if status:
+            caps = [c for c in caps if c.status == status]
+        return sorted(caps, key=lambda c: c.name)
+
+    def execute(
+        self,
+        name: str,
+        args: Optional[Dict[str, Any]] = None,
+        context: Optional[Dict[str, Any]] = None,
+        task_id: str = "",
+        mode: str = "",
+        permission_callback: Optional[Callable[[str, str, str, str], str]] = None,
+    ) -> ExecutionResult:
+        """Execute a capability with permission checking and event emission."""
+        canonical = (name or "").strip().lower()
+        cap = self.get(canonical)
+        if not cap:
+            return ExecutionResult(
+                success=False,
+                error=f"Capability '{canonical}' is not registered in the Capability Bus.",
+                status=AvailabilityStatus.UNAVAILABLE,
+            )
+
+        args = args or {}
+        context = context or {}
+
+        # 1. Permission check
+        if cap.spec.permissions:
+            try:
+                from .. import permissions as perm
+                for req_perm in cap.spec.permissions:
+                    if perm.manager.refused_by_always_deny(req_perm):
+                        return ExecutionResult(
+                            success=False,
+                            error=f"Permission denied: {req_perm} is permanently denied for this session.",
+                            status=AvailabilityStatus.PERMISSION_DENIED,
+                        )
+                    if perm.manager.needs_prompt(req_perm):
+                        decision = "allow_once"
+                        if permission_callback:
+                            decision = permission_callback(
+                                req_perm,
+                                f"Execute {canonical}",
+                                str(args.get("path", "") or args.get("target", "")),
+                                f"Required by capability {canonical}",
+                            )
+                        if not perm.manager.decide(req_perm, decision, canonical, "Capability execution"):
+                            return ExecutionResult(
+                                success=False,
+                                error=f"Permission rejected by user for capability '{canonical}'.",
+                                status=AvailabilityStatus.PERMISSION_DENIED,
+                            )
+            except Exception as e:
+                _LOG.warning("Permission validation check failed: %s", e)
+
+        # 2. Emit ToolStarted event
+        try:
+            from ..workflow_engine import workflow_engine, EVENT_TOOL_STARTED, ExecutionEvent, STATE_RUNNING
+            workflow_engine.record_tool_start(
+                tool=canonical,
+                args=args,
+                turn_id=task_id or context.get("turn_id", ""),
+            )
+        except Exception:
+            pass
+
+        # 3. Execution
+        result = cap.execute(args, context)
+
+        # 4. Attach Provenance
+        result.provenance = {
+            "capability": canonical,
+            "version": cap.spec.version,
+            "task_id": task_id,
+            "mode": mode,
+            "timestamp": time.time(),
+            "duration_ms": result.duration_ms,
+            "success": result.success,
+        }
+
+        # 5. Emit ToolFinished event
+        try:
+            from ..workflow_engine import workflow_engine
+            workflow_engine.record_tool_completion(
+                tool=canonical,
+                result=str(result.output if result.success else result.error)[:200],
+                turn_id=task_id or context.get("turn_id", ""),
+                duration_ms=int(result.duration_ms),
+            )
+        except Exception:
+            pass
+
+        return result
+
+    def health_check_all(self, force: bool = False) -> Dict[str, Dict[str, Any]]:
+        """Run health check across all registered capabilities."""
+        report = {}
+        for name, cap in self._capabilities.items():
+            status, message = cap.check_health(force=force)
+            report[name] = {
+                "category": cap.spec.category.value,
+                "status": status.value,
+                "message": message,
+                "version": cap.spec.version,
+                "auth_required": cap.spec.auth_required,
+            }
+        return report
+
+
+capability_bus = CapabilityBus()