codeshield-runtime 0.1.0__py3-none-any.whl

codeshield/schemas.py

@@ -0,0 +1,120 @@
+"""Pydantic models for the execution engine."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class CodeExecutionRequest(BaseModel):
+    """Request to execute a piece of Python code safely."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    code: str = Field(..., min_length=1, description="Python source code to execute.")
+    timeout_seconds: float = Field(
+        default=60.0,
+        gt=0.0,
+        le=3600.0,
+        description="Maximum execution time in seconds.",
+    )
+    requirements: list[str] = Field(
+        default_factory=list,
+        description="Optional list of PyPI packages to install in the sandbox.",
+    )
+    file_name: str | None = Field(
+        default=None,
+        description="Optional file name used when persisting code in the sandbox.",
+    )
+
+    @field_validator("code")
+    @classmethod
+    def _code_must_be_non_empty(cls, value: str) -> str:
+        if not value.strip():
+            raise ValueError("Code must contain non-whitespace characters.")
+        return value
+
+
+class ExecutionResult(BaseModel):
+    """Result of an isolated code execution."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    stdout: str = Field(default="", description="Captured standard output.")
+    stderr: str = Field(default="", description="Captured standard error.")
+    exit_code: int | None = Field(
+        default=None,
+        description="Process exit code; None if the process did not terminate normally.",
+    )
+    duration_seconds: float = Field(
+        default=0.0,
+        ge=0.0,
+        description="Total wall-clock execution time in seconds.",
+    )
+    silent_failure_detected: bool = Field(
+        default=False,
+        description="True when exit_code is 0 but suspicious patterns were detected in output.",
+    )
+    timed_out: bool = Field(
+        default=False,
+        description="True when the process was terminated due to timeout.",
+    )
+
+
+class ErrorDiagnosis(BaseModel):
+    """Structured diagnosis extracted from a runtime traceback."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    error_type: str = Field(..., description="Exception class name, e.g. NameError.")
+    root_cause_line: int | None = Field(
+        default=None,
+        description="Line number in the original source where the failure originated.",
+    )
+    message: str = Field(default="", description="Exception message or human-readable summary.")
+    context: list[str] = Field(
+        default_factory=list,
+        description="Surrounding source lines for the failing line, if available.",
+    )
+
+
+class PatchProposal(BaseModel):
+    """A validated patch proposal ready to be applied to a source file."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    file_path: Path = Field(..., description="Target source file in the sandbox.")
+    patched_code: str = Field(..., description="Proposed replacement source code.")
+    is_syntax_valid: bool = Field(
+        default=False,
+        description="True when the patched code passed AST validation.",
+    )
+    diagnosis: ErrorDiagnosis | None = Field(
+        default=None,
+        description="Diagnosis that motivated the patch.",
+    )
+
+
+class ValidationReport(BaseModel):
+    """Report produced by static AST validation."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid", arbitrary_types_allowed=True)
+
+    is_valid: bool = Field(..., description="True when no syntax or safety violations were found.")
+    violations: list[str] = Field(
+        default_factory=list,
+        description="Human-readable list of syntax and safety violations.",
+    )
+    exception: SyntaxError | None = Field(
+        default=None,
+        description="Original SyntaxError instance, if any.",
+    )
+
+    def model_post_init(self, __context: Any) -> None:  # noqa: N807
+        """Ensure is_valid remains consistent with the violations list."""
+        if self.is_valid and self.violations:
+            object.__setattr__(self, "is_valid", False)
+        elif not self.is_valid and not self.violations and self.exception is None:
+            object.__setattr__(self, "is_valid", True)

codeshield/tools.py

@@ -0,0 +1,76 @@
+"""Universal agent tool wrapper for CodeShield.
+
+The function returned by ``create_code_execution_tool`` can be registered as a
+tool in any agent framework (LangChain, CrewAI, Google Gen AI, etc.). It runs
+the provided Python source inside a self-healing sandbox and returns either the
+stdout or a structured error report.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from codeshield.environment import SandboxError
+from codeshield.loop import SelfHealingEngine, SelfHealingError
+from codeshield.runner import SubprocessRunnerError
+
+
+def create_code_execution_tool(
+    engine: SelfHealingEngine | None = None,
+) -> Callable[[str], str]:
+    """Return a drop-in ``execute_python_code(code: str) -> str`` tool.
+
+    Args:
+        engine: Optional ``SelfHealingEngine`` instance. When ``None``, a fresh
+            engine is created for each tool call.
+
+    Returns:
+        A callable ready to be registered as an agent tool.
+    """
+
+    def execute_python_code(code: str) -> str:
+        """Execute Python code in an isolated, self-healing sandbox.
+
+        Use this tool to run numerical, statistical or data-processing
+        computations that cannot be done directly in the conversation.
+
+        Args:
+            code: A valid Python script as a string.
+
+        Returns:
+            The stdout of the script if execution succeeds, or a structured
+            error report if it fails after all self-healing attempts.
+        """
+        _engine = engine or SelfHealingEngine()
+        with _engine:
+            try:
+                result, diagnosis = _engine.run(code)
+            except SelfHealingError as exc:
+                return f"error_type: SelfHealingError\nmessage: {exc}"
+            except (SandboxError, SubprocessRunnerError) as exc:
+                return f"error_type: {type(exc).__name__}\nmessage: {exc}"
+
+        if (
+            result.exit_code == 0
+            and not result.silent_failure_detected
+            and not result.timed_out
+        ):
+            return result.stdout.strip()
+
+        report: list[str] = ["The Python script did not execute successfully."]
+        if diagnosis is not None:
+            report.append(f"error_type: {diagnosis.error_type}")
+            if diagnosis.root_cause_line is not None:
+                report.append(f"root_cause_line: {diagnosis.root_cause_line}")
+            if diagnosis.message:
+                report.append(f"message: {diagnosis.message}")
+        if result.stderr.strip():
+            report.append(f"stderr: {result.stderr.strip()}")
+        if result.timed_out:
+            report.append("timed_out: true")
+        if result.silent_failure_detected:
+            report.append("silent_failure_detected: true")
+
+        return "\n".join(report)
+
+    return execute_python_code

codeshield_runtime-0.1.0.dist-info/METADATA

@@ -0,0 +1,277 @@
+Metadata-Version: 2.5
+Name: codeshield-runtime
+Version: 0.1.0
+Summary: A secure, isolated, and self-healing Python code execution engine powered by uv and AST analysis.
+Project-URL: Homepage, https://github.com/AlgorithmicMind/codeshield
+Project-URL: Repository, https://github.com/AlgorithmicMind/codeshield
+Project-URL: Issues, https://github.com/AlgorithmicMind/codeshield/issues
+Author: Senior Python Core Engineer
+License: MIT
+License-File: LICENSE
+Keywords: ast,code,execution,sandbox,self-healing,uv
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.0
+Requires-Dist: tenacity>=8.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0.0; extra == 'dev'
+Requires-Dist: twine>=5.0.0; extra == 'dev'
+Provides-Extra: lint
+Requires-Dist: ruff>=0.5.0; extra == 'lint'
+Provides-Extra: llm
+Requires-Dist: google-genai>=0.1.0; extra == 'llm'
+Requires-Dist: python-dotenv>=1.0.0; extra == 'llm'
+Provides-Extra: test
+Requires-Dist: pytest-cov>=4.0; extra == 'test'
+Requires-Dist: pytest>=7.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# CodeShield: Autonomous Code Execution Engine
+
+[![CI](https://img.shields.io/github/actions/workflow/status/AlgorithmicMind/codeshield/ci.yml?branch=main&label=CI)](https://github.com/AlgorithmicMind/codeshield/actions)
+[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Code Style: Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
+
+> Deterministic, Isolated, and Self-Healing Python Execution Runtime for AI Agents.
+
+This open-source engine executes Python code generated by LLMs inside a disposable, isolated sandbox, validates it statically with the Python `ast` module, and recovers from runtime errors through a deterministic self-healing loop backed by local heuristics and plug-and-play LLM-guided patch generation (OpenAI, Anthropic Claude, DeepSeek, Ollama, Google Gemini).
+
+## Comparison
+
+| Feature | Vanilla `subprocess` | Docker Container | CodeShield (This Engine) |
+| :--- | :--- | :--- | :--- |
+| **Startup Overhead** | ~5 – 10 ms | ~1,500 – 3,000 ms | **Sub-second (~30–250 ms via `uv`)** |
+| **Isolation Mechanism** | None (Host Process) | Container Namespaces / cgroups | **Ephemeral Virtualenv (`tempfile` + `uv`)** |
+| **AST Security Gate** | ❌ None | ❌ None | **✅ Static AST inspection (`os.system`, `eval`)** |
+| **Silent Failure Detection** | ❌ None | ❌ None | **✅ Regex scanning for empty DataFrames/NaNs** |
+| **Self-Healing Loop** | ❌ None | ❌ None | **✅ 3-Tier Traceback Diagnosis + LLM Patch (Any Provider)** |
+
+---
+
+## Architecture
+
+```text
+[LLM Generated Code]
+        │
+        ▼
+[AST Static Gate] ──(Syntax/Security Violation)──► [Validation Error Report]
+        │ (Passed)
+        ▼
+[uv Isolated Sandbox] ──(Runtime Error/Silent Failure)──► [Traceback Classifier]
+        │                                                          │
+        │ (Clean Execution: exit 0)                                ▼
+        ▼                                               [LLM Self-Healing (Any Provider) / Local Heuristic]
+[Verified Output (JSON)] ◄──(AST Validated Patch)─────────────────┘
+```
+
+---
+
+## Key Features
+
+### 1. Ephemeral Sandboxing with Dual-Mode Backend
+
+- **Primary**: `uv venv` for ultra-fast environment creation and package installation.
+- **Fallback**: native `python -m venv` + `pip` when `uv` is unavailable, so the engine works out of the box on any machine.
+- Each execution lands in its own temporary workspace that is destroyed after use.
+
+### 2. Deterministic AST Security Gates
+
+The engine parses every snippet with the standard `ast` module and rejects:
+
+- `SyntaxError`s before execution.
+- Bare `except:` / `except Exception:` / `except BaseException:` handlers.
+- Calls to dangerous parametrizable functions: `eval()`, `exec()`, `compile()`.
+- Calls to system/subprocess primitives: `os.system()`, `subprocess.call()`, `subprocess.run()`, `subprocess.Popen()`.
+
+### 3. Silent Failure Detection
+
+Even when a process exits with `0`, the engine flags suspicious output patterns such as:
+
+- `empty DataFrame`
+- `all NaN`
+- `Traceback`
+- `Pipeline failed`
+- `Fatal Error`
+
+### 4. Model-Agnostic Self-Healing Loop
+
+```text
+AST Validation ──► Sandbox Execution ──► Traceback Classification ──► Patch ──► Re-run
+                                      (3 attempts max)
+```
+
+- **Local heuristic fallback**: handles `NameError`, `ImportError`, `ModuleNotFoundError` by injecting safe imports or placeholder definitions.
+- **LLM-guided healing**: when an LLM is configured (built-in Gemini Flash by default, or any custom provider via `patch_generator`), it asks the model for a corrected version of the code, validates it with the AST gate, and re-executes the patched snippet.
+
+---
+
+## Quickstart
+
+### Installation
+
+```bash
+# Install from PyPI
+pip install codeshield-runtime
+
+# Install with all extras (LLM + Dev tools)
+pip install "codeshield-runtime[llm,dev]"
+
+# Or clone for development
+git clone https://github.com/AlgorithmicMind/codeshield.git
+cd codeshield
+
+# With uv (recommended)
+uv venv
+uv pip install -e ".[test,lint,llm,dev]"
+
+# Or with pip
+python -m venv .venv
+.venv\Scripts\activate  # Windows
+pip install -e ".[test,lint,llm,dev]"
+```
+
+### Offline Usage (No API Key)
+
+```python
+from codeshield.loop import SelfHealingEngine
+
+engine = SelfHealingEngine(use_llm=False)
+with engine:
+    result, diagnosis = engine.run("print('hello world')")
+    print(result.stdout)
+```
+
+### Model-Agnostic Self-Healing (Plug-and-Play)
+
+CodeShield is not locked into a single LLM. Pass any Python callable as the `patch_generator` to use OpenAI, Anthropic Claude, DeepSeek, Ollama, LiteLLM or your own service:
+
+```python
+from codeshield.loop import SelfHealingEngine
+
+
+def custom_openai_patcher(code: str, diagnosis) -> str:
+    # Any LLM call (OpenAI, Anthropic, DeepSeek, Ollama, LiteLLM)
+    response = client.chat.completions.create(
+        model="gpt-4o-mini",
+        messages=[
+            {
+                "role": "user",
+                "content": f"Fix this code:\n{code}\nError: {diagnosis.message}",
+            }
+        ],
+    )
+    return response.choices[0].message.content
+
+
+engine = SelfHealingEngine(patch_generator=custom_openai_patcher)
+```
+
+### Zero-Config Self-Healing with Gemini Flash
+
+For the built-in zero-config experience, create a `.env` file from `.env.example`:
+
+```text
+GEMINI_API_KEY=your_key_here
+GEMINI_MODEL=gemini-3.7-flash
+```
+
+```python
+from dotenv import load_dotenv
+from codeshield.loop import SelfHealingEngine
+
+load_dotenv()
+
+engine = SelfHealingEngine()
+with engine:
+    result, diagnosis = engine.run('print("Result: " + 42)')
+    print(result.stdout)  # Result: 42
+```
+
+Run the included demo:
+
+```bash
+python demo.py
+```
+
+### CLI Usage
+
+Execute any Python file directly from the terminal with the built-in CLI:
+
+```bash
+python -m codeshield run script.py
+python -m codeshield run script.py --timeout 30
+python -m codeshield run script.py --llm        # try LLM self-healing if configured
+python -m codeshield run script.py --no-llm     # force local fallback
+```
+
+## 🤖 Agent Tool Integration (LangChain, CrewAI, OpenAI, Gen AI)
+
+```python
+from codeshield import create_code_execution_tool
+
+# Pass the tool directly to your agent
+tools = [create_code_execution_tool()]
+```
+
+`create_code_execution_tool()` returns a ready-to-register `execute_python_code(code: str) -> str` function. It runs the provided Python in a self-healing sandbox and returns either the stdout or a structured error report with `error_type` and `stderr`.
+
+---
+
+## Verified Examples
+
+The `examples/` folder contains ready-to-run recipes that have been executed and verified:
+
+- `01_basic_sandboxing.py`: isolated execution with timing measurements.
+- `02_security_gatekeeper.py`: AST rejection of unsafe code.
+- `03_llm_healing_workflow.py`: self-healing workflow with an LLM or local fallback.
+- `04_agent_tool_dropin.py`: end-to-end agentic tool-calling workflow with dynamic code generation.
+
+```bash
+python examples/01_basic_sandboxing.py
+python examples/02_security_gatekeeper.py
+python examples/03_llm_healing_workflow.py
+python examples/04_agent_tool_dropin.py
+```
+
+## Running Tests & Lint
+
+The suite currently has **50 tests** with **>82% code coverage** on `src/codeshield`.
+
+```bash
+ruff check src tests examples
+pytest tests -v --cov=src/codeshield
+```
+
+---
+
+## Enterprise Architecture & Custom Deployments
+
+This repository ships the **core execution and healing engine**. For production multi-tenant deployments, the enterprise extension adds:
+
+- **Multi-tenant orchestrator** with queue-based job scheduling.
+- **PostgreSQL state persistence** for execution history, audit trails and replay.
+- **Automated billing and token governance** (cost caps per tenant, per-execution budgets).
+- **Prometheus/Grafana observability**, RBAC, and signed artifact provenance.
+- **SLA-backed support** and custom agentic architecture consulting.
+
+**Want the production-grade version or a tailored integration for your platform?**
+
+- [Open a GitHub issue](https://github.com/AlgorithmicMind/codeshield/issues)
+- [Connect on LinkedIn](https://www.linkedin.com/in/pedro-castejon-jodar/)
+
+We offer enterprise licensing, dedicated onboarding and custom agentic-architecture consulting.
+
+---
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.

codeshield_runtime-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+codeshield/__init__.py,sha256=eIwleitreZatH9h9UeTlGzq4MEuK8z8QNPcCWSkSek4,407
+codeshield/__main__.py,sha256=7FgV8lAFEGbFbb7J83AO9r6xQeUiCKMc2kpc8jRMiws,186
+codeshield/analyzer.py,sha256=3gkVnexxGZCR5rBlb5qYUE3qW_lDUz9jQe8_RRpvrxg,5346
+codeshield/classifier.py,sha256=v0dZl8Ba0nhfiqtGKd_-UwjUpBeNiF3fxRd6c-JRL-g,5991
+codeshield/cli.py,sha256=da2SIcVS_pw1D0ja0JDjlCoxRJI-srOqvxhKPzQDG_E,2880
+codeshield/environment.py,sha256=2vgu_VUE-DXXPv8pmdKogai-jAV2TMdmKtpnWyPCU_w,9387
+codeshield/loop.py,sha256=teWZ7csdjOGCJOV0upQt5gYtNyzC4IbtLxNXTaI2TG0,15654
+codeshield/runner.py,sha256=AGb55tpCP87biSw2XRoSgSg_tQP45cRZcHV8aBCLR88,7819
+codeshield/schemas.py,sha256=hkpedvTylyn5TfjVz-iFWL0ugGkZm9dzSnNbN4vXlYU,4248
+codeshield/tools.py,sha256=bKVIFx20e2d-fjOw1QBre0sNNcCf7RSPyXaWTadAsB8,2803
+codeshield_runtime-0.1.0.dist-info/METADATA,sha256=I1S11xdx1hcZjFVWkQa_LFK91pr2cMMXr99rLgiTogI,10050
+codeshield_runtime-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+codeshield_runtime-0.1.0.dist-info/licenses/LICENSE,sha256=AOVzp38xpBSknCuDOjR2lgdX1-Xj-k129vwvLKr07Go,1102
+codeshield_runtime-0.1.0.dist-info/RECORD,,

codeshield_runtime-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

codeshield_runtime-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Autonomous Code Execution Engine contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.