codeshield-runtime 0.1.0__tar.gz

codeshield_runtime-0.1.0/.gitignore

@@ -0,0 +1,150 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# poetry
+poetry.lock
+
+# pdm
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+.idea/
+
+# VS Code
+.vscode/
+
+# Local execution engine sandboxes and workspaces
+.sandboxes/
+workspaces/
+tmp/
+*.sandbox

codeshield_runtime-0.1.0/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.

codeshield_runtime-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,241 @@
+# 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.