codeshield-runtime 0.1.0__py3-none-any.whl

codeshield/__init__.py

@@ -0,0 +1,17 @@
+"""CodeShield.
+
+A secure, isolated, and self-healing Python code execution engine.
+"""
+
+__version__ = "0.1.0"
+
+from codeshield.loop import SelfHealingEngine
+from codeshield.schemas import CodeExecutionRequest, ExecutionResult
+from codeshield.tools import create_code_execution_tool
+
+__all__ = [
+    "SelfHealingEngine",
+    "CodeExecutionRequest",
+    "ExecutionResult",
+    "create_code_execution_tool",
+]

codeshield/__main__.py

@@ -0,0 +1,10 @@
+"""Entry point for `python -m codeshield`."""
+
+from __future__ import annotations
+
+import sys
+
+from codeshield.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

codeshield/analyzer.py

@@ -0,0 +1,151 @@
+"""Static syntax and safety analysis using only the standard ``ast`` module."""
+
+from __future__ import annotations
+
+import ast
+import logging
+from dataclasses import dataclass, field
+
+from codeshield.schemas import ValidationReport
+
+logger = logging.getLogger(__name__)
+
+
+# Parametrizable functions considered dangerous when invoked directly.
+_DANGEROUS_NAMES: frozenset[str] = frozenset({
+    "eval",
+    "exec",
+    "compile",
+    "os.system",
+    "subprocess.call",
+    "subprocess.run",
+    "subprocess.Popen",
+})
+_GENERIC_EXCEPTIONS: frozenset[str] = frozenset({"Exception", "BaseException"})
+
+
+@dataclass
+class _SafetyContext:
+    """Mutable collector used by the AST visitor."""
+
+    violations: list[str] = field(default_factory=list)
+    line_numbers: dict[int, str] = field(default_factory=dict)
+
+    def add_violation(self, message: str, *, line: int | None = None) -> None:
+        """Append a violation with an optional source line hint."""
+        if line is not None:
+            message = f"Line {line}: {message}"
+        self.violations.append(message)
+
+
+class _SafetyVisitor(ast.NodeVisitor):
+    """AST visitor that flags generic exception handlers and dangerous calls."""
+
+    def __init__(self, context: _SafetyContext) -> None:
+        self._context = context
+
+    def visit_ExceptHandler(self, node: ast.ExceptHandler) -> None:  # noqa: N802
+        """Detect overly broad exception handlers."""
+        self._check_generic_except(node)
+        self.generic_visit(node)
+
+    def visit_Call(self, node: ast.Call) -> None:  # noqa: N802
+        """Detect dangerous parametrizable function calls."""
+        self._check_dangerous_call(node)
+        self.generic_visit(node)
+
+    def _check_generic_except(self, node: ast.ExceptHandler) -> None:
+        """Flag ``except:``, ``except Exception:`` and ``except BaseException:``."""
+        if node.type is None:
+            self._context.add_violation(
+                "Bare ``except:`` clause is not allowed because it catches all exceptions",
+                line=node.lineno,
+            )
+            return
+
+        name = self._name_from_node(node.type)
+        if name in _GENERIC_EXCEPTIONS:
+            self._context.add_violation(
+                f"Overly generic exception handler ``except {name}:`` is not allowed",
+                line=node.lineno,
+            )
+
+    def _check_dangerous_call(self, node: ast.Call) -> None:
+        """Flag direct calls to eval/exec/compile."""
+        name = self._name_from_node(node.func)
+        if name in _DANGEROUS_NAMES:
+            self._context.add_violation(
+                f"Dangerous parametrizable function call ``{name}()`` is not allowed",
+                line=node.lineno,
+            )
+
+    @staticmethod
+    def _name_from_node(node: ast.AST | None) -> str:
+        """Return a best-effort dotted name for an AST node."""
+        if node is None:
+            return ""
+        if isinstance(node, ast.Name):
+            return node.id
+        if isinstance(node, ast.Attribute):
+            return f"{_SafetyVisitor._name_from_node(node.value)}.{node.attr}"
+        if isinstance(node, ast.Subscript):
+            return _SafetyVisitor._name_from_node(node.value)
+        return ""
+
+
+def _lines_from_source(code: str) -> dict[int, str]:
+    """Map 1-indexed line numbers to stripped source lines."""
+    return {idx + 1: line for idx, line in enumerate(code.splitlines())}
+
+
+def _split_first_line(code: str) -> tuple[str, ...]:
+    """Return source lines as a tuple to keep them hashable when needed."""
+    return tuple(code.splitlines())
+
+
+def validate_syntax_and_safety(code: str) -> ValidationReport:
+    """Validate ``code`` using the standard ``ast`` module.
+
+    The validation detects:
+    - Syntax errors raised by ``ast.parse``.
+    - Bare ``except:`` clauses and handlers using ``Exception``/``BaseException``.
+    - Direct calls to dangerous parametrizable functions: ``eval``, ``exec`` and ``compile``.
+
+    Args:
+        code: Python source code to validate.
+
+    Returns:
+        A ``ValidationReport`` containing the result and any violations.
+    """
+    lines = _lines_from_source(code)
+    try:
+        tree = ast.parse(code, filename="<dynamic>", mode="exec")
+    except SyntaxError as exc:
+        location = f"line {exc.lineno}" if exc.lineno else "unknown location"
+        text = lines.get(exc.lineno, "") if exc.lineno else ""
+        pointer = f"\n{text}\n{' ' * ((exc.offset or 1) - 1)}^" if exc.offset and text else ""
+        message = f"SyntaxError at {location}: {exc.msg}{pointer}"
+        logger.debug("Syntax validation failed: %s", message)
+        return ValidationReport(
+            is_valid=False,
+            violations=[message],
+            exception=exc,
+        )
+
+    context = _SafetyContext(line_numbers=lines)
+    visitor = _SafetyVisitor(context)
+    visitor.visit(tree)
+
+    is_valid = not context.violations
+    logger.debug(
+        "Safety validation completed: %d violation(s) found.",
+        len(context.violations),
+    )
+    return ValidationReport(
+        is_valid=is_valid,
+        violations=context.violations,
+        exception=None,
+    )
+
+
+__all__: list[str] = ["validate_syntax_and_safety"]

codeshield/classifier.py

@@ -0,0 +1,163 @@
+"""Traceback parsing and error classification utilities."""
+
+from __future__ import annotations
+
+import logging
+import re
+
+from codeshield.schemas import ErrorDiagnosis
+
+logger = logging.getLogger(__name__)
+
+
+class TracebackClassifier:
+    """Extract structured diagnostics from Python tracebacks."""
+
+    def __init__(self, context_radius: int = 2) -> None:
+        """Initialize the classifier.
+
+        Args:
+            context_radius: Number of source lines to include before and after
+                the failing line.
+        """
+        self._context_radius = max(0, context_radius)
+
+    def classify(self, code: str, stderr: str) -> ErrorDiagnosis | None:
+        """Extract an ``ErrorDiagnosis`` from ``stderr``.
+
+        Args:
+            code: Original source code used to provide context.
+            stderr: Standard error produced by the executed process.
+
+        Returns:
+            An ``ErrorDiagnosis`` if a traceback could be parsed, otherwise ``None``.
+        """
+        if not stderr.strip():
+            return None
+
+        if "Traceback" not in stderr:
+            return None
+
+        exception_match = self._extract_exception_line(stderr)
+        if not exception_match:
+            return None
+
+        exc_type, exc_message = exception_match
+        line_no = self._extract_failing_line(stderr, code)
+        context = self._extract_context(code, line_no)
+
+        logger.debug(
+            "Classified %s at line %s: %s",
+            exc_type,
+            line_no,
+            exc_message,
+        )
+        return ErrorDiagnosis(
+            error_type=exc_type,
+            root_cause_line=line_no,
+            message=exc_message,
+            context=context,
+        )
+
+    def classify_from_result(self, code: str, stderr: str) -> ErrorDiagnosis:
+        """Return a diagnosis, falling back to a generic one when parsing fails."""
+        diagnosis = self.classify(code, stderr)
+        if diagnosis is not None:
+            return diagnosis
+
+        return ErrorDiagnosis(
+            error_type="UnknownError",
+            root_cause_line=None,
+            message=stderr.strip() or "An unknown error occurred during execution.",
+            context=[],
+        )
+
+    def _extract_exception_line(self, stderr: str) -> tuple[str, str] | None:
+        """Parse the final traceback line ``ExceptionName: message``.
+
+        Returns:
+            A tuple ``(exception_name, message)`` or ``None``.
+        """
+        # Find the last line starting after the traceback header that matches
+        # an exception declaration. We scan all lines and keep the last valid one.
+        in_traceback = False
+        last_match: tuple[str, str] | None = None
+
+        for raw_line in stderr.splitlines():
+            line = raw_line.rstrip()
+            if in_traceback:
+                pattern = r"^([A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*):\s*(.*)$"
+                match = re.match(pattern, line)
+                if match:
+                    exception_name = match.group(1)
+                    message = match.group(2).strip()
+                    # Ignore built-in notes that follow the exception line.
+                    last_match = (exception_name, message)
+            if line.startswith("Traceback"):
+                in_traceback = True
+
+        return last_match
+
+    def _extract_failing_line(self, stderr: str, code: str) -> int | None:
+        """Determine the most relevant failing source line from the traceback.
+
+        The method looks for the deepest file in the executed code, and if the
+        script is not external, returns its line number. If only external frames
+        are available, the last line number is returned as a fallback.
+        """
+        # Pattern: File "...", line X, in ...
+        pattern = re.compile(r'File "([^"]+)", line (\d+), in (.+)')
+        lines = code.splitlines()
+
+        last_line: int | None = None
+        for raw in reversed(stderr.splitlines()):
+            match = pattern.search(raw)
+            if not match:
+                continue
+            file_path, line_no_str, _ = match.groups()
+            line_no = int(line_no_str)
+            last_line = line_no
+
+            # If the frame references the inline script, use it directly.
+            if "<string>" in file_path or file_path.endswith("script.py"):
+                return line_no
+
+            # Heuristic: line number is inside the provided source range.
+            if 1 <= line_no <= len(lines):
+                return line_no
+
+        return last_line
+
+    def _extract_context(self, code: str, line_no: int | None) -> list[str]:
+        """Return surrounding source lines for ``line_no``."""
+        if line_no is None:
+            return []
+
+        lines = code.splitlines()
+        if not lines:
+            return []
+
+        start = max(1, line_no - self._context_radius)
+        end = min(len(lines), line_no + self._context_radius)
+        return [f"{idx}: {lines[idx - 1]}" for idx in range(start, end + 1)]
+
+    def extract_missing_name(self, diagnosis: ErrorDiagnosis) -> str | None:
+        """For ``NameError``, try to extract the missing identifier."""
+        if diagnosis.error_type != "NameError":
+            return None
+        match = re.search(r"name '([^']+)' is not defined", diagnosis.message)
+        if match:
+            return match.group(1)
+        return None
+
+    def extract_missing_module(self, diagnosis: ErrorDiagnosis) -> str | None:
+        """For ``ImportError``/``ModuleNotFoundError``, try to extract the module name."""
+        if diagnosis.error_type not in {"ImportError", "ModuleNotFoundError"}:
+            return None
+        match = re.search(r"No module named '([^']+)'", diagnosis.message)
+        if match:
+            return match.group(1)
+        return None
+
+
+__all__: list[str] = ["TracebackClassifier"]

codeshield/cli.py

@@ -0,0 +1,101 @@
+"""Command-line interface for the execution engine."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+from pathlib import Path
+
+from codeshield.loop import SelfHealingEngine
+
+logger = logging.getLogger(__name__)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """Return the argument parser for the CLI."""
+    parser = argparse.ArgumentParser(
+        prog="codeshield",
+        description="Deterministic, isolated, and self-healing Python code execution.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    run_parser = subparsers.add_parser(
+        "run",
+        help="Execute a Python source file inside a sandbox.",
+    )
+    run_parser.add_argument(
+        "file",
+        type=Path,
+        help="Path to the Python file to execute.",
+    )
+    run_parser.add_argument(
+        "--timeout",
+        type=float,
+        default=60.0,
+        help="Execution timeout in seconds (default: 60).",
+    )
+    run_parser.add_argument(
+        "--llm",
+        action="store_true",
+        default=True,
+        help="Enable LLM-guided self-healing when GEMINI_API_KEY is set (default: on).",
+    )
+    run_parser.add_argument(
+        "--no-llm",
+        action="store_true",
+        help="Disable LLM-guided self-healing and use the local fallback.",
+    )
+
+    return parser
+
+
+def _read_file(file_path: Path) -> str:
+    """Read and return the contents of ``file_path``."""
+    try:
+        return file_path.read_text(encoding="utf-8")
+    except OSError as exc:
+        logger.error("Could not read %s: %s", file_path, exc)
+        raise SystemExit(1) from exc
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point for the CLI."""
+    logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
+
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command != "run":
+        parser.print_help()
+        return 2
+
+    if not args.file.exists():
+        logger.error("File not found: %s", args.file)
+        return 1
+
+    code = _read_file(args.file)
+    use_llm = not args.no_llm if args.no_llm else args.llm
+
+    engine = SelfHealingEngine(use_llm=use_llm)
+    with engine:
+        result, diagnosis = engine.run(code, timeout=args.timeout)
+
+    print("--- STDOUT ---")
+    print(result.stdout)
+    if result.stderr:
+        print("--- STDERR ---")
+        print(result.stderr)
+
+    if result.timed_out:
+        print("Execution timed out")
+    if result.silent_failure_detected:
+        print("Silent failure detected")
+    if diagnosis:
+        print(f"Diagnosis: {diagnosis.error_type} - {diagnosis.message}")
+
+    return 0 if result.exit_code == 0 and not result.silent_failure_detected else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

codeshield/environment.py

@@ -0,0 +1,256 @@
+"""Management of isolated ``uv`` virtual environments used as sandboxes."""
+
+from __future__ import annotations
+
+import logging
+import shutil
+import subprocess
+import sys
+import tempfile
+from collections.abc import Sequence
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+class SandboxError(RuntimeError):
+    """Raised when a sandbox cannot be created, destroyed or updated."""
+
+
+class SandboxManager:
+    """Create, populate and clean up an isolated virtual environment.
+
+    The manager prefers the ``uv`` toolchain when available, and transparently
+    falls back to the standard ``venv``/``pip`` tooling otherwise. This makes
+    the package usable on systems where ``uv`` has not yet been installed while
+    still taking advantage of ``uv`` when it is present.
+    """
+
+    def __init__(
+        self,
+        workspace: Path | str | None = None,
+        venv_name: str = ".venv",
+        python: str | None = None,
+        keep: bool = False,
+        backend: str | None = None,
+    ) -> None:
+        """Initialize a sandbox manager.
+
+        Args:
+            workspace: Directory that will host the virtual environment. If ``None``,
+                a temporary directory is created.
+            venv_name: Name of the virtual environment directory inside ``workspace``.
+            python: Python version or interpreter requested for the backend.
+            keep: If ``False`` (default), the workspace is removed when the manager
+                is garbage collected or ``cleanup`` is called.
+            backend: Environment backend to use. ``"uv"`` or ``"venv"``. When ``None``,
+                ``uv`` is auto-detected and preferred.
+        """
+        self._workspace = (
+            Path(workspace)
+            if workspace
+            else Path(tempfile.mkdtemp(prefix="codeshield_"))
+        )
+        self._venv_name = venv_name
+        self._python = python or sys.executable
+        self._keep = keep
+        self._backend = self._resolve_backend(backend)
+        self._uv_path: Path | None = None
+        self._venv_path = self._workspace / self._venv_name
+
+    @property
+    def workspace(self) -> Path:
+        """Return the root sandbox workspace directory."""
+        return self._workspace
+
+    @property
+    def venv_path(self) -> Path:
+        """Return the virtual environment directory."""
+        return self._venv_path
+
+    @property
+    def python_executable(self) -> Path:
+        """Return the interpreter path inside the virtual environment."""
+        if self._is_windows():
+            return self._venv_path / "Scripts" / "python.exe"
+        return self._venv_path / "bin" / "python"
+
+    def uv_executable(self) -> Path:
+        """Resolve and cache the ``uv`` executable path.
+
+        Raises:
+            SandboxError: when ``uv`` is not available on ``PATH``.
+        """
+        if self._uv_path is None:
+            uv = shutil.which("uv")
+            if uv is None:
+                raise SandboxError(
+                    "The `uv` executable was not found on PATH. "
+                    "Install uv from https://github.com/astral-sh/uv"
+                )
+            self._uv_path = Path(uv)
+        return self._uv_path
+
+    def create(self) -> Path:
+        """Create the virtual environment.
+
+        Returns:
+            The path to the virtual environment.
+
+        Raises:
+            SandboxError: if the backend fails to create the environment.
+        """
+        self._workspace.mkdir(parents=True, exist_ok=True)
+
+        if self._backend == "uv":
+            self._create_with_uv()
+        else:
+            self._create_with_venv()
+
+        if not self.python_executable.exists():
+            raise SandboxError(
+                f"Virtual environment was created but interpreter not found at "
+                f"{self.python_executable}"
+            )
+
+        logger.info("Virtual environment ready at %s", self._venv_path)
+        return self._venv_path
+
+    def _create_with_uv(self) -> None:
+        """Create a virtual environment using ``uv venv``."""
+        cmd: list[str] = [str(self.uv_executable()), "venv"]
+        if self._python:
+            cmd.extend(["--python", self._python])
+        cmd.append(str(self._venv_name))
+
+        logger.info("Creating uv venv at %s", self._venv_path)
+        result = self._run_command(cmd, cwd=self._workspace)
+        if result.returncode != 0:
+            raise SandboxError(
+                f"`uv venv` failed (exit {result.returncode}): "
+                f"{result.stderr or result.stdout}"
+            )
+
+    def _create_with_venv(self) -> None:
+        """Create a virtual environment using the standard ``venv`` module."""
+        cmd = [self._python, "-m", "venv", str(self._venv_name)]
+        logger.info("Creating venv with %s at %s", self._python, self._venv_path)
+        result = self._run_command(cmd, cwd=self._workspace)
+        if result.returncode != 0:
+            raise SandboxError(
+                f"`python -m venv` failed (exit {result.returncode}): "
+                f"{result.stderr or result.stdout}"
+            )
+
+    def install_requirements(self, requirements: Sequence[str] | Path | str) -> None:
+        """Install packages from a list or a ``requirements.txt`` path.
+
+        Args:
+            requirements: Either a sequence of package specifiers or a path
+                to a requirements file.
+
+        Raises:
+            SandboxError: if the installation fails.
+        """
+        if isinstance(requirements, (str, Path)):
+            requirements_path = Path(requirements)
+            if not requirements_path.exists():
+                raise SandboxError(f"Requirements file not found: {requirements_path}")
+
+            if self._backend == "uv":
+                cmd = [
+                    str(self.uv_executable()),
+                    "pip",
+                    "install",
+                    "-r",
+                    str(requirements_path),
+                ]
+            else:
+                cmd = [
+                    str(self.python_executable),
+                    "-m",
+                    "pip",
+                    "install",
+                    "-r",
+                    str(requirements_path),
+                ]
+        else:
+            if not requirements:
+                return
+            if self._backend == "uv":
+                cmd = [str(self.uv_executable()), "pip", "install", *requirements]
+            else:
+                cmd = [str(self.python_executable), "-m", "pip", "install", *requirements]
+
+        logger.info("Installing requirements in sandbox: %s", cmd)
+        result = self._run_command(cmd, cwd=self._workspace)
+        if result.returncode != 0:
+            raise SandboxError(
+                f"Requirement installation failed (exit {result.returncode}): "
+                f"{result.stderr or result.stdout}"
+            )
+
+    def write_requirements_file(
+        self, packages: Sequence[str], file_name: str = "requirements.txt"
+    ) -> Path:
+        """Write package specifiers to ``workspace/requirements.txt``.
+
+        Returns:
+            Path of the written file.
+        """
+        path = self._workspace / file_name
+        path.write_text("\n".join(packages) + "\n", encoding="utf-8")
+        return path
+
+    def cleanup(self) -> None:
+        """Remove the workspace unless ``keep`` was set to ``True``."""
+        if self._keep or not self._workspace.exists():
+            return
+        logger.info("Cleaning up sandbox workspace: %s", self._workspace)
+        try:
+            shutil.rmtree(self._workspace, ignore_errors=True)
+        except OSError as exc:
+            logger.warning("Could not remove workspace %s: %s", self._workspace, exc)
+
+    def __enter__(self) -> SandboxManager:
+        self.create()
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.cleanup()
+
+    def _resolve_backend(self, backend: str | None) -> str:
+        """Resolve the environment backend, preferring ``uv`` when available."""
+        if backend in {"uv", "venv"}:
+            return backend
+        if backend is not None:
+            raise SandboxError(f"Unknown backend '{backend}'; choose 'uv' or 'venv'")
+        if shutil.which("uv") is not None:
+            return "uv"
+        logger.warning(
+            "uv was not found on PATH; falling back to the standard venv/pip backend. "
+            "Install uv from https://github.com/astral-sh/uv for faster sandboxes."
+        )
+        return "venv"
+
+    def _run_command(
+        self,
+        cmd: list[str],
+        cwd: Path,
+    ) -> subprocess.CompletedProcess[str]:
+        """Run a command and return a ``CompletedProcess`` with text output."""
+        try:
+            return subprocess.run(
+                cmd,
+                cwd=cwd,
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+        except OSError as exc:
+            raise SandboxError(f"Failed to spawn command {cmd[0]!r}: {exc}") from exc
+
+    @staticmethod
+    def _is_windows() -> bool:
+        """Return ``True`` when running on Windows."""
+        return sys.platform.startswith("win")