stt4 / backend /tools /python_contract.py
vynor's picture
Deploy QORIN CPU Research Platform & Inference Backend
1bd0d2b verified
Raw History Blame Contribute Delete
6.94 kB
"""
QORIN Python Execution Contract & Reliability Layer
Defines strict input pre-validation, AST security inspection, deterministic execution,
structured failure taxonomy, and documented capabilities.
"""
import ast
from dataclasses import dataclass, asdict
from enum import Enum
import os
from pathlib import Path
import subprocess
import sys
import tempfile
import time
from typing import Any, Dict, List, Optional, Set, Tuple
class PythonFailureCategory(str, Enum):
NONE = "NONE"
SYNTAX_ERROR = "SYNTAX_ERROR"
UNSUPPORTED_API = "UNSUPPORTED_API"
RUNTIME_EXCEPTION = "RUNTIME_EXCEPTION"
TIMEOUT = "TIMEOUT"
SECURITY_VIOLATION = "SECURITY_VIOLATION"
EMPTY_PAYLOAD = "EMPTY_PAYLOAD"
@dataclass
class PythonExecutionResult:
stdout: str
stderr: str
exit_code: int
execution_time_ms: float
status: str # "SUCCESS" | "FAILED" | "TIMEOUT"
failure_category: PythonFailureCategory
error_message: Optional[str] = None
def to_dict(self) -> Dict[str, Any]:
d = asdict(self)
d["failure_category"] = self.failure_category.value
d["execution_time_ms"] = round(self.execution_time_ms, 2)
return d
class PythonExecutionContract:
"""Standardized Python sandbox execution contract with strict failure taxonomy."""
ALLOWED_MODULES: Set[str] = {
"math", "statistics", "random", "datetime", "itertools",
"collections", "re", "json", "decimal", "fractions", "cmath"
}
DISALLOWED_MODULES: Set[str] = {
"os", "sys", "subprocess", "shutil", "socket", "urllib", "http",
"ftplib", "smtplib", "webbrowser", "requests", "pip"
}
TIMEOUT_SECONDS: float = 6.0
MAX_OUTPUT_CHARS: int = 20_000
def __init__(self, timeout_seconds: float = 6.0):
self.timeout_seconds = timeout_seconds
def pre_validate_ast(self, code: str) -> Tuple[bool, PythonFailureCategory, Optional[str]]:
"""Static AST inspection for syntax errors and disallowed imports."""
if not code or not code.strip():
return False, PythonFailureCategory.EMPTY_PAYLOAD, "Python code payload is empty."
try:
tree = ast.parse(code)
except SyntaxError as e:
return (
False,
PythonFailureCategory.SYNTAX_ERROR,
f"SyntaxError: {e.msg} (line {e.lineno}, offset {e.offset})"
)
# Inspect imports
for node in ast.walk(tree):
if isinstance(node, ast.Import):
for alias in node.names:
root_mod = alias.name.split(".")[0]
if root_mod in self.DISALLOWED_MODULES:
return (
False,
PythonFailureCategory.SECURITY_VIOLATION,
f"SecurityViolation: Import of disallowed module '{root_mod}' is prohibited."
)
elif isinstance(node, ast.ImportFrom):
if node.module:
root_mod = node.module.split(".")[0]
if root_mod in self.DISALLOWED_MODULES:
return (
False,
PythonFailureCategory.SECURITY_VIOLATION,
f"SecurityViolation: Import from disallowed module '{root_mod}' is prohibited."
)
return True, PythonFailureCategory.NONE, None
def execute(self, code: str) -> PythonExecutionResult:
"""Executes Python code in an isolated subprocess with strict safety and failure categorization."""
t0 = time.perf_counter()
# Step 1: Pre-validation
is_valid, fail_cat, err_msg = self.pre_validate_ast(code)
if not is_valid:
duration_ms = (time.perf_counter() - t0) * 1000.0
return PythonExecutionResult(
stdout="",
stderr=err_msg or "",
exit_code=1,
execution_time_ms=duration_ms,
status="FAILED",
failure_category=fail_cat,
error_message=err_msg
)
# Step 2: Prepare temporary execution file
with tempfile.NamedTemporaryFile("w", suffix=".py", delete=False, encoding="utf-8") as f:
script_path = Path(f.name)
# Inject safe import restrictions header
f.write("# QORIN Sandbox Script\n")
f.write(code)
try:
proc = subprocess.run(
[sys.executable, str(script_path)],
capture_output=True,
text=True,
timeout=self.timeout_seconds,
encoding="utf-8",
errors="replace"
)
duration_ms = (time.perf_counter() - t0) * 1000.0
stdout = proc.stdout[:self.MAX_OUTPUT_CHARS]
stderr = proc.stderr[:self.MAX_OUTPUT_CHARS]
if proc.returncode == 0:
return PythonExecutionResult(
stdout=stdout,
stderr=stderr,
exit_code=0,
execution_time_ms=duration_ms,
status="SUCCESS",
failure_category=PythonFailureCategory.NONE,
error_message=None
)
else:
# Classify runtime exception
fail_cat = PythonFailureCategory.RUNTIME_EXCEPTION
if "AttributeError" in stderr and "module" in stderr:
fail_cat = PythonFailureCategory.UNSUPPORTED_API
elif "NameError" in stderr or "TypeError" in stderr or "ZeroDivisionError" in stderr:
fail_cat = PythonFailureCategory.RUNTIME_EXCEPTION
return PythonExecutionResult(
stdout=stdout,
stderr=stderr,
exit_code=proc.returncode,
execution_time_ms=duration_ms,
status="FAILED",
failure_category=fail_cat,
error_message=stderr.strip().splitlines()[-1] if stderr.strip() else "Unknown runtime error"
)
except subprocess.TimeoutExpired:
duration_ms = (time.perf_counter() - t0) * 1000.0
return PythonExecutionResult(
stdout="",
stderr=f"Execution timed out after {self.timeout_seconds} seconds.",
exit_code=124,
execution_time_ms=duration_ms,
status="TIMEOUT",
failure_category=PythonFailureCategory.TIMEOUT,
error_message=f"TimeoutExpired: Execution exceeded {self.timeout_seconds}s limit."
)
finally:
if script_path.exists():
try:
script_path.unlink()
except Exception:
pass