Download backend/tools/python_contract.py from vynor/stt4: direct link, hf CLI and curl.
- Browser
- Download file 6.94 kB
-
https://huggingface.co/spaces/vynor/stt4/resolve/main/backend/tools/python_contract.py
- Command line
-
hf download hf://spaces/vynor/stt4/backend/tools/python_contract.py
-
curl -L -o python_contract.py https://huggingface.co/spaces/vynor/stt4/resolve/main/backend/tools/python_contract.py
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" | |
| 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 | |