codeshield-runtime 0.1.2__tar.gz → 0.1.3__tar.gz

{codeshield_runtime-0.1.2 → codeshield_runtime-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codeshield-runtime
-Version: 0.1.2
+Version: 0.1.3
 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
@@ -40,6 +40,8 @@ Description-Content-Type: text/markdown
 [![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)
+[![PyPI](https://img.shields.io/pypi/v/codeshield-runtime.svg)](https://pypi.org/project/codeshield-runtime/)
+[![PyPI Downloads](https://img.shields.io/pypi/dm/codeshield-runtime.svg)](https://pypi.org/project/codeshield-runtime/)
 
 > Deterministic, Isolated, and Self-Healing Python Execution Runtime for AI Agents.
 
@@ -142,12 +144,18 @@ pip install -e ".[test,lint,llm,dev]"
 ### Offline Usage (No API Key)
 
 ```python
-from codeshield.loop import SelfHealingEngine
+from codeshield import SelfHealingEngine
 
+# The sandbox is created and destroyed automatically on every ``run`` call.
 engine = SelfHealingEngine(use_llm=False)
-with engine:
-    result, diagnosis = engine.run("print('hello world')")
-    print(result.stdout)
+result, diagnosis = engine.run("print('hello world')")
+print(result.stdout)
+
+# Use a ``with`` block to reuse a single sandbox across multiple runs.
+with SelfHealingEngine(use_llm=False) as reusable_engine:
+    first, _ = reusable_engine.run("print(1 + 1)")
+    second, _ = reusable_engine.run("print(2 + 2)")
+    print(first.stdout, second.stdout)
 ```
 
 ### Model-Agnostic Self-Healing (Plug-and-Play)
@@ -155,13 +163,13 @@ with engine:
 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
+from codeshield import SelfHealingEngine
 
 
 def custom_llm_patcher(code: str, diagnosis) -> str:
-    # Compatible with any frontier provider: GPT-5.4, Claude Sonnet 5, DeepSeek V4, Ollama
+    # Compatible with any frontier provider: GPT-5.6, Claude Sonnet 5, DeepSeek V4, Ollama
     response = client.chat.completions.create(
-        model="gpt-5.4-mini",  # or "claude-sonnet-5", "deepseek-v4-flash"
+        model="gpt-5.6-luna",  # or "claude-sonnet-5", "deepseek-v4-flash"
         messages=[
             {
                 "role": "user",
@@ -173,6 +181,11 @@ def custom_llm_patcher(code: str, diagnosis) -> str:
 
 
 engine = SelfHealingEngine(patch_generator=custom_llm_patcher)
+
+# Broken code -> AST gate -> sandbox execution -> traceback classification ->
+# custom patch -> AST re-validation -> re-execution, all in a single call.
+result, diagnosis = engine.run('print("Result: " + 42)')
+print(result.stdout)  # Result: 42
 ```
 
 ### Zero-Config Self-Healing with Gemini Flash
@@ -186,7 +199,8 @@ GEMINI_MODEL=gemini-3.7-flash
 
 ```python
 from dotenv import load_dotenv
-from codeshield.loop import SelfHealingEngine
+
+from codeshield import SelfHealingEngine
 
 load_dotenv()
 
@@ -218,12 +232,41 @@ python -m codeshield run script.py --no-llm     # force local fallback
 ```python
 from codeshield import create_code_execution_tool
 
-# Pass the tool directly to your agent
+# Standard usage: built-in Gemini healing when configured, local heuristic otherwise
 tools = [create_code_execution_tool()]
+
+# Or bring your own model: the patcher is forwarded to the internal engine
+tools = [create_code_execution_tool(patch_generator=custom_llm_patcher)]
 ```
 
 `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`.
 
+The callable exposes real type hints and a Google-style docstring, so any SDK that builds a function schema from a plain Python callable can register it directly.
+
+---
+
+## Public API
+
+Everything is re-exported at the package root, so imports never need internal submodules:
+
+```python
+from codeshield import (
+    ASTSecurityError,
+    CodeExecutionRequest,
+    ErrorDiagnosis,
+    ExecutionResult,
+    SandboxManager,
+    SelfHealingEngine,
+    SelfHealingError,
+    SubprocessRunner,
+    TracebackClassifier,
+    create_code_execution_tool,
+    validate_syntax_and_safety,
+)
+```
+
+`ASTSecurityError` subclasses `SelfHealingError` and is raised whenever the static AST gate blocks either the original snippet or a generated patch.
+
 ---
 
 ## Verified Examples
@@ -233,7 +276,7 @@ The `examples/` folder contains ready-to-run recipes that have been executed and
 - `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.
+- `04_agent_tool_dropin.py`: dual-phase agentic trace, printing agent thought, tool call, sandbox runtime and final answer for both a legitimate analytics round and a security-defense round where the AST gate blocks a shell escape.
 - `05_custom_llm_openai_compatible.py`: model-agnostic, API-key-free self-healing with a custom `patch_generator`.
 
 ```bash
@@ -246,7 +289,7 @@ python examples/05_custom_llm_openai_compatible.py
 
 ## Running Tests & Lint
 
-The suite currently has **53 tests** with **>82% code coverage** on `src/codeshield`.
+The suite currently has **54 tests** with **>83% code coverage** on `src/codeshield`.
 
 ```bash
 ruff check src tests examples

{codeshield_runtime-0.1.2 → codeshield_runtime-0.1.3}/README.md

@@ -4,6 +4,8 @@
 [![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)
+[![PyPI](https://img.shields.io/pypi/v/codeshield-runtime.svg)](https://pypi.org/project/codeshield-runtime/)
+[![PyPI Downloads](https://img.shields.io/pypi/dm/codeshield-runtime.svg)](https://pypi.org/project/codeshield-runtime/)
 
 > Deterministic, Isolated, and Self-Healing Python Execution Runtime for AI Agents.
 
@@ -106,12 +108,18 @@ pip install -e ".[test,lint,llm,dev]"
 ### Offline Usage (No API Key)
 
 ```python
-from codeshield.loop import SelfHealingEngine
+from codeshield import SelfHealingEngine
 
+# The sandbox is created and destroyed automatically on every ``run`` call.
 engine = SelfHealingEngine(use_llm=False)
-with engine:
-    result, diagnosis = engine.run("print('hello world')")
-    print(result.stdout)
+result, diagnosis = engine.run("print('hello world')")
+print(result.stdout)
+
+# Use a ``with`` block to reuse a single sandbox across multiple runs.
+with SelfHealingEngine(use_llm=False) as reusable_engine:
+    first, _ = reusable_engine.run("print(1 + 1)")
+    second, _ = reusable_engine.run("print(2 + 2)")
+    print(first.stdout, second.stdout)
 ```
 
 ### Model-Agnostic Self-Healing (Plug-and-Play)
@@ -119,13 +127,13 @@ with engine:
 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
+from codeshield import SelfHealingEngine
 
 
 def custom_llm_patcher(code: str, diagnosis) -> str:
-    # Compatible with any frontier provider: GPT-5.4, Claude Sonnet 5, DeepSeek V4, Ollama
+    # Compatible with any frontier provider: GPT-5.6, Claude Sonnet 5, DeepSeek V4, Ollama
     response = client.chat.completions.create(
-        model="gpt-5.4-mini",  # or "claude-sonnet-5", "deepseek-v4-flash"
+        model="gpt-5.6-luna",  # or "claude-sonnet-5", "deepseek-v4-flash"
         messages=[
             {
                 "role": "user",
@@ -137,6 +145,11 @@ def custom_llm_patcher(code: str, diagnosis) -> str:
 
 
 engine = SelfHealingEngine(patch_generator=custom_llm_patcher)
+
+# Broken code -> AST gate -> sandbox execution -> traceback classification ->
+# custom patch -> AST re-validation -> re-execution, all in a single call.
+result, diagnosis = engine.run('print("Result: " + 42)')
+print(result.stdout)  # Result: 42
 ```
 
 ### Zero-Config Self-Healing with Gemini Flash
@@ -150,7 +163,8 @@ GEMINI_MODEL=gemini-3.7-flash
 
 ```python
 from dotenv import load_dotenv
-from codeshield.loop import SelfHealingEngine
+
+from codeshield import SelfHealingEngine
 
 load_dotenv()
 
@@ -182,12 +196,41 @@ python -m codeshield run script.py --no-llm     # force local fallback
 ```python
 from codeshield import create_code_execution_tool
 
-# Pass the tool directly to your agent
+# Standard usage: built-in Gemini healing when configured, local heuristic otherwise
 tools = [create_code_execution_tool()]
+
+# Or bring your own model: the patcher is forwarded to the internal engine
+tools = [create_code_execution_tool(patch_generator=custom_llm_patcher)]
 ```
 
 `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`.
 
+The callable exposes real type hints and a Google-style docstring, so any SDK that builds a function schema from a plain Python callable can register it directly.
+
+---
+
+## Public API
+
+Everything is re-exported at the package root, so imports never need internal submodules:
+
+```python
+from codeshield import (
+    ASTSecurityError,
+    CodeExecutionRequest,
+    ErrorDiagnosis,
+    ExecutionResult,
+    SandboxManager,
+    SelfHealingEngine,
+    SelfHealingError,
+    SubprocessRunner,
+    TracebackClassifier,
+    create_code_execution_tool,
+    validate_syntax_and_safety,
+)
+```
+
+`ASTSecurityError` subclasses `SelfHealingError` and is raised whenever the static AST gate blocks either the original snippet or a generated patch.
+
 ---
 
 ## Verified Examples
@@ -197,7 +240,7 @@ The `examples/` folder contains ready-to-run recipes that have been executed and
 - `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.
+- `04_agent_tool_dropin.py`: dual-phase agentic trace, printing agent thought, tool call, sandbox runtime and final answer for both a legitimate analytics round and a security-defense round where the AST gate blocks a shell escape.
 - `05_custom_llm_openai_compatible.py`: model-agnostic, API-key-free self-healing with a custom `patch_generator`.
 
 ```bash
@@ -210,7 +253,7 @@ python examples/05_custom_llm_openai_compatible.py
 
 ## Running Tests & Lint
 
-The suite currently has **53 tests** with **>82% code coverage** on `src/codeshield`.
+The suite currently has **54 tests** with **>83% code coverage** on `src/codeshield`.
 
 ```bash
 ruff check src tests examples

{codeshield_runtime-0.1.2 → codeshield_runtime-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "codeshield-runtime"
-version = "0.1.2"
+version = "0.1.3"
 description = "A secure, isolated, and self-healing Python code execution engine powered by uv and AST analysis."
 readme = "README.md"
 license = { text = "MIT" }

codeshield_runtime-0.1.3/src/codeshield/__init__.py

@@ -0,0 +1,46 @@
+"""CodeShield.
+
+A secure, isolated, and self-healing Python code execution engine.
+"""
+
+__version__ = "0.1.3"
+
+from codeshield.analyzer import validate_syntax_and_safety
+from codeshield.classifier import TracebackClassifier
+from codeshield.environment import SandboxError, SandboxManager
+from codeshield.loop import (
+    ASTSecurityError,
+    GeminiPatchGenerator,
+    LLMPatchError,
+    SelfHealingEngine,
+    SelfHealingError,
+)
+from codeshield.runner import SubprocessRunner, SubprocessRunnerError
+from codeshield.schemas import (
+    CodeExecutionRequest,
+    ErrorDiagnosis,
+    ExecutionResult,
+    PatchProposal,
+    ValidationReport,
+)
+from codeshield.tools import create_code_execution_tool
+
+__all__ = [
+    "ASTSecurityError",
+    "CodeExecutionRequest",
+    "ErrorDiagnosis",
+    "ExecutionResult",
+    "GeminiPatchGenerator",
+    "LLMPatchError",
+    "PatchProposal",
+    "SandboxError",
+    "SandboxManager",
+    "SelfHealingEngine",
+    "SelfHealingError",
+    "SubprocessRunner",
+    "SubprocessRunnerError",
+    "TracebackClassifier",
+    "ValidationReport",
+    "create_code_execution_tool",
+    "validate_syntax_and_safety",
+]

{codeshield_runtime-0.1.2 → codeshield_runtime-0.1.3}/src/codeshield/environment.py

@@ -65,7 +65,7 @@ class SandboxManager:
 
     @property
     def workspace_path(self) -> Path:
-        """Alias for the root sandbox workspace directory."""
+        """Alias of :attr:`workspace` used for explicit lifecycle checks."""
         return self._workspace
 
     @property
@@ -200,6 +200,10 @@ class SandboxManager:
     ) -> Path:
         """Write package specifiers to ``workspace/requirements.txt``.
 
+        Args:
+            packages: Package specifiers to write, one per line.
+            file_name: Name of the requirements file inside the workspace.
+
         Returns:
             Path of the written file.
         """
@@ -218,10 +222,12 @@ class SandboxManager:
             logger.warning("Could not remove workspace %s: %s", self._workspace, exc)
 
     def __enter__(self) -> SandboxManager:
+        """Create the virtual environment and return the manager."""
         self.create()
         return self
 
     def __exit__(self, *exc: object) -> None:
+        """Remove the workspace when leaving the context."""
         self.cleanup()
 
     def _resolve_backend(self, backend: str | None) -> str:

{codeshield_runtime-0.1.2 → codeshield_runtime-0.1.3}/src/codeshield/loop.py

@@ -34,6 +34,10 @@ class SelfHealingError(RuntimeError):
     """Raised when the self-healing loop cannot complete execution safely."""
 
 
+class ASTSecurityError(SelfHealingError):
+    """Raised when code or a generated patch is blocked by the static AST gate."""
+
+
 class LLMPatchError(RuntimeError):
     """Raised when the LLM patch generator cannot produce a safe correction."""
 
@@ -239,6 +243,8 @@ class SelfHealingEngine:
         Raises:
             SelfHealingError: when the loop exhausts all iterations without a
                 clean result.
+            ASTSecurityError: when the code or a generated patch is blocked by
+                the static AST gate.
         """
         if isinstance(request, str):
             request = CodeExecutionRequest(code=request)
@@ -276,7 +282,7 @@ class SelfHealingEngine:
                 )
                 patched = self._generate_and_validate_patch(request.code, diagnosis)
                 if patched is None:
-                    raise SelfHealingError(
+                    raise ASTSecurityError(
                         f"Static safety violations cannot be auto-patched: {report.violations}"
                     )
                 request = self._apply_patch(request, patched, attempt)
@@ -337,9 +343,21 @@ class SelfHealingEngine:
         proposal: PatchProposal,
         attempt: int,
     ) -> CodeExecutionRequest:
-        """Return a new request with the patched code and an updated file name."""
+        """Return a new request with the patched code and an updated file name.
+
+        Args:
+            request: The request that produced the failing execution.
+            proposal: The AST-validated patch proposal to apply.
+            attempt: Current healing iteration, used to name the patched script.
+
+        Returns:
+            A new ``CodeExecutionRequest`` carrying the patched source.
+
+        Raises:
+            ASTSecurityError: when the proposal failed static AST validation.
+        """
         if not proposal.is_syntax_valid:
-            raise SelfHealingError(
+            raise ASTSecurityError(
                 f"Proposed patch failed AST validation: {proposal.patched_code[:200]}"
             )
 

{codeshield_runtime-0.1.2 → codeshield_runtime-0.1.3}/src/codeshield/runner.py

@@ -10,6 +10,7 @@ import subprocess
 import threading
 import time
 from collections.abc import Iterable
+from typing import IO
 
 from codeshield.environment import SandboxError, SandboxManager
 from codeshield.schemas import CodeExecutionRequest, ExecutionResult
@@ -146,7 +147,7 @@ class SubprocessRunner:
         stdout_lines: list[str] = []
         stderr_lines: list[str] = []
 
-        def reader(pipe, sink: list[str]) -> None:
+        def reader(pipe: IO[str], sink: list[str]) -> None:
             """Read lines from a pipe without blocking the main thread."""
             try:
                 for line in pipe:

{codeshield_runtime-0.1.2 → codeshield_runtime-0.1.3}/src/codeshield/tools.py

@@ -5,9 +5,11 @@ 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
+Annotations in this module are intentionally *not* postponed: agent SDKs such as
+``google-genai`` introspect ``execute_python_code.__annotations__`` at runtime to
+build the function-calling schema, and string annotations break that conversion.
+"""
 
 from collections.abc import Callable
 from typing import Optional
@@ -51,9 +53,7 @@ def create_code_execution_tool(
         with _engine:
             try:
                 result, diagnosis = _engine.run(code)
-            except SelfHealingError as exc:
-                return f"error_type: SelfHealingError\nmessage: {exc}"
-            except (SandboxError, SubprocessRunnerError) as exc:
+            except (SelfHealingError, SandboxError, SubprocessRunnerError) as exc:
                 return f"error_type: {type(exc).__name__}\nmessage: {exc}"
 
         if (

{codeshield_runtime-0.1.2 → codeshield_runtime-0.1.3}/tests/test_coverage.py

@@ -9,15 +9,17 @@ from unittest.mock import MagicMock
 
 import pytest
 
-from codeshield.classifier import TracebackClassifier
-from codeshield.environment import SandboxError, SandboxManager
-from codeshield.loop import (
+from codeshield import (
+    CodeExecutionRequest,
+    ErrorDiagnosis,
     GeminiPatchGenerator,
+    SandboxError,
+    SandboxManager,
     SelfHealingEngine,
     SelfHealingError,
+    SubprocessRunner,
+    TracebackClassifier,
 )
-from codeshield.runner import SubprocessRunner
-from codeshield.schemas import CodeExecutionRequest, ErrorDiagnosis
 
 
 @pytest.fixture

{codeshield_runtime-0.1.2 → codeshield_runtime-0.1.3}/tests/test_engine.py

@@ -4,13 +4,14 @@ from __future__ import annotations
 
 import pytest
 
-from codeshield.analyzer import validate_syntax_and_safety
-from codeshield.classifier import TracebackClassifier
-from codeshield.environment import SandboxManager
-from codeshield.loop import SelfHealingEngine, SelfHealingError
-from codeshield.runner import SubprocessRunner
-from codeshield.schemas import (
+from codeshield import (
+    ASTSecurityError,
     ExecutionResult,
+    SandboxManager,
+    SelfHealingEngine,
+    SubprocessRunner,
+    TracebackClassifier,
+    validate_syntax_and_safety,
 )
 
 
@@ -277,5 +278,5 @@ def test_custom_patch_generator_ast_rejection() -> None:
         use_llm=False,
     )
 
-    with pytest.raises(SelfHealingError):
+    with pytest.raises(ASTSecurityError):
         engine.run("print(undefined_value)")

{codeshield_runtime-0.1.2 → codeshield_runtime-0.1.3}/tests/test_tools.py

@@ -2,8 +2,16 @@
 
 from __future__ import annotations
 
-from codeshield import create_code_execution_tool
-from codeshield.loop import SelfHealingEngine
+from codeshield import SelfHealingEngine, create_code_execution_tool
+
+
+def test_tool_exposes_runtime_type_annotations() -> None:
+    """Agent SDKs build the schema from ``__annotations__``, so they must be types."""
+    tool = create_code_execution_tool()
+
+    assert tool.__name__ == "execute_python_code"
+    assert tool.__annotations__["code"] is str
+    assert tool.__annotations__["return"] is str
 
 
 def test_tool_returns_stdout_on_success() -> None:

codeshield_runtime-0.1.2/src/codeshield/__init__.py

@@ -1,17 +0,0 @@
-"""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",
-]