Metadata-Version: 2.5
Name: codeshield-runtime
Version: 0.1.1
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.
