algomath-extract 1.0.0

package/src/execution/errors.py

@@ -0,0 +1,158 @@
+"""Error categorization and translation for execution results.
+
+Covers EXE-05 (status reporting) and EXE-06 (meaningful error messages).
+Implements decisions D-17 through D-20 from 04-CONTEXT.md.
+"""
+
+import re
+from enum import Enum
+from dataclasses import dataclass
+from typing import Optional
+from subprocess import TimeoutExpired
+
+
+class ExecutionError(Enum):
+    """Execution error categories per D-17.
+
+    Categorizes errors into mathematician-friendly types:
+    - SYNTAX_ERROR: Code parsing issues
+    - RUNTIME_ERROR: General execution failures
+    - TIMEOUT_ERROR: Execution exceeded time limit
+    - MEMORY_ERROR: Execution exceeded memory limit
+    - SUCCESS: No error
+    """
+    SYNTAX_ERROR = "syntax_error"
+    RUNTIME_ERROR = "runtime_error"
+    TIMEOUT_ERROR = "timeout_error"
+    MEMORY_ERROR = "memory_error"
+    SUCCESS = "success"
+
+
+@dataclass
+class ErrorDetails:
+    """Error details with user-friendly translation per D-19.
+
+    Attributes:
+        category: The error category (ExecutionError enum)
+        user_message: Human-friendly description of what happened
+        hint: Suggestion for how to fix (per D-20)
+        technical_details: Full traceback/debug info for developers (optional)
+        line_number: Line where error occurred (optional)
+    """
+    category: ExecutionError
+    user_message: str
+    hint: str
+    technical_details: Optional[str] = None
+    line_number: Optional[int] = None
+
+
+class ErrorTranslator:
+    """Translate technical errors to mathematician-friendly language per D-18.
+
+    Converts Python exceptions and error messages into accessible descriptions
+    that mathematicians without programming background can understand.
+    """
+
+    TRANSLATIONS = {
+        ExecutionError.SYNTAX_ERROR: {
+            'message': 'Generated code has a syntax issue',
+            'hint': 'This is likely a translation error. Try regenerating with clearer pseudocode.'
+        },
+        ExecutionError.TIMEOUT_ERROR: {
+            'message': 'Algorithm took too long to complete',
+            'hint': 'Check for infinite loops or consider optimizing the algorithm.'
+        },
+        ExecutionError.MEMORY_ERROR: {
+            'message': 'Algorithm used too much memory',
+            'hint': 'Consider using more memory-efficient data structures or algorithms.'
+        },
+        ExecutionError.RUNTIME_ERROR: {
+            'message': 'Algorithm encountered an error while running',
+            'hint': 'Review the technical details below for debugging information.'
+        },
+        ExecutionError.SUCCESS: {
+            'message': 'Algorithm executed successfully',
+            'hint': 'No issues detected.'
+        }
+    }
+
+    @classmethod
+    def translate(cls, error: ExecutionError, technical: str = "") -> ErrorDetails:
+        """Translate error category to user-friendly message.
+
+        Args:
+            error: The error category
+            technical: Technical details for debugging (traceback, etc.)
+
+        Returns:
+            ErrorDetails with user-friendly message and hint per D-18, D-20
+        """
+        translation = cls.TRANSLATIONS.get(error, cls.TRANSLATIONS[ExecutionError.RUNTIME_ERROR])
+        return ErrorDetails(
+            category=error,
+            user_message=translation['message'],
+            hint=translation['hint'],
+            technical_details=technical if technical else None
+        )
+
+
+def categorize_error(error: Exception, stderr: str = "") -> ExecutionError:
+    """Categorize exception into ExecutionError type per D-17.
+
+    Analyzes the exception type and stderr output to classify errors
+    into mathematician-friendly categories.
+
+    Args:
+        error: The exception that occurred
+        stderr: Standard error output from execution (optional)
+
+    Returns:
+        ExecutionError category
+    """
+    # Check by exception type
+    if isinstance(error, TimeoutExpired):
+        return ExecutionError.TIMEOUT_ERROR
+    if isinstance(error, MemoryError):
+        return ExecutionError.MEMORY_ERROR
+    if isinstance(error, SyntaxError):
+        return ExecutionError.SYNTAX_ERROR
+
+    # Check stderr content for error indicators
+    stderr_lower = stderr.lower()
+    if "SyntaxError" in stderr:
+        return ExecutionError.SYNTAX_ERROR
+    if "MemoryError" in stderr or "out of memory" in stderr_lower:
+        return ExecutionError.MEMORY_ERROR
+    if "timeout" in stderr_lower or "time limit" in stderr_lower:
+        return ExecutionError.TIMEOUT_ERROR
+
+    # Default to runtime error for anything else
+    return ExecutionError.RUNTIME_ERROR
+
+
+def extract_line_number(traceback: str) -> Optional[int]:
+    """Extract line number from Python traceback for debugging per D-19.
+
+    Args:
+        traceback: The full traceback string
+
+    Returns:
+        Line number if found, None otherwise
+    """
+    if not traceback:
+        return None
+
+    # Match "File "path", line N" pattern
+    match = re.search(r'File "[^"]+", line (\d+)', traceback)
+    if match:
+        return int(match.group(1))
+    return None
+
+
+__all__ = [
+    'ExecutionError',
+    'ErrorDetails',
+    'ErrorTranslator',
+    'categorize_error',
+    'extract_line_number',
+]

package/src/execution/executor.py

@@ -0,0 +1,253 @@
+"""High-level execution interface for AlgoMath workflows.
+
+Per D-21, D-22, D-23, D-25: Workflow-facing execution interface that:
+- Auto-triggers after code approval
+- Shows progress during execution
+- Can be skipped (user controls flow)
+- Handles inputs and passes them to executed code
+- Integrates with ContextManager for saving results
+
+This module provides execute_code() as the primary interface for
+running generated Python code within the AlgoMath workflow.
+"""
+
+import json
+import sys
+from pathlib import Path
+from dataclasses import dataclass
+from typing import Optional, Dict, Any, List
+
+from .sandbox import SandboxExecutor, ExecutionResult, ExecutionStatus
+
+
+@dataclass
+class ExecutionConfig:
+    """Configuration for code execution.
+
+    Per D-05: Default timeout is 30 seconds.
+    Per D-02: Default memory limit is 512MB.
+    Per D-30: capture_return_value enables return value capture.
+
+    Attributes:
+        timeout: Maximum execution time in seconds
+        max_memory_mb: Maximum memory allowed in megabytes
+        working_dir: Optional working directory for file operations
+        capture_return_value: Whether to capture function return values
+    """
+    timeout: int = 30
+    max_memory_mb: int = 512
+    working_dir: Optional[Path] = None
+    capture_return_value: bool = True
+
+
+def _inject_inputs(code: str, inputs: Dict[str, Any]) -> str:
+    """Prepend inputs as JSON and inject reading code.
+
+    Per D-29: Support stdin redirection for algorithms requiring input.
+    This injects a get_input() function that reads from a JSON-serialized
+    inputs dictionary.
+
+    Args:
+        code: Original Python code
+        inputs: Dictionary of input values
+
+    Returns:
+        Code with input injection wrapper prepended
+    """
+    # Serialize inputs to JSON
+    inputs_json = json.dumps(inputs)
+
+    # Create wrapper code that defines get_input() function
+    inputs_code = f'''
+import json
+__ALGO_INPUTS = json.loads({repr(inputs_json)})
+
+def get_input(key: str, default: Any = None) -> Any:
+    """Get input value by key.
+
+    Args:
+        key: Input key to retrieve
+        default: Default value if key not found
+
+    Returns:
+        Input value or default
+    """
+    return __ALGO_INPUTS.get(key, default)
+'''
+    return inputs_code + "\n\n" + code
+
+
+def _categorize_error(result: ExecutionResult) -> ExecutionResult:
+    """Categorize and translate errors to user-friendly messages.
+
+    Per D-17, D-18: Convert common errors to mathematician-friendly language.
+    - SyntaxError → "Generated code has a syntax issue"
+    - TimeoutError → "Algorithm took too long — check for infinite loops"
+    - MemoryError → "Algorithm used too much memory"
+    - RuntimeError → "Algorithm encountered an error during execution"
+
+    Args:
+        result: Raw execution result
+
+    Returns:
+        ExecutionResult with translated error message
+    """
+    if result.status == ExecutionStatus.TIMEOUT:
+        result.error_message = (
+            f"Algorithm took too long to complete ({result.runtime_seconds:.1f}s). "
+            "Check for infinite loops."
+        )
+    elif result.status == ExecutionStatus.MEMORY_ERROR:
+        result.error_message = (
+            f"Algorithm used too much memory. "
+            f"Limit: {result.error_message or 'exceeded'}"
+        )
+    elif result.status == ExecutionStatus.SYNTAX_ERROR:
+        result.error_message = (
+            f"Generated code has a syntax issue: {result.error_message or 'Unknown error'}"
+        )
+    elif result.status == ExecutionStatus.RUNTIME_ERROR:
+        result.error_message = (
+            f"Algorithm encountered an error during execution: {result.error_message or 'Unknown error'}"
+        )
+
+    return result
+
+
+def execute_code(
+    code: str,
+    inputs: Optional[Dict[str, Any]] = None,
+    config: Optional[ExecutionConfig] = None
+) -> ExecutionResult:
+    """Execute Python code with sandboxing.
+
+    Per D-21: Called automatically after code approval.
+    Per D-23: Shows progress during execution.
+    Per D-25: Can be skipped (returns mock results).
+    Per D-26: Python 3.11+ compatibility via sys.executable.
+    Per D-27: Standard library only.
+
+    This is the main entry point for executing generated code in the
+    AlgoMath workflow. It handles:
+    - Input injection (D-29)
+    - Sandboxed execution (D-01)
+    - Error categorization (D-17)
+    - Result formatting
+
+    Args:
+        code: Python code to execute
+        inputs: Optional input dictionary passed to the code
+        config: Optional execution configuration
+
+    Returns:
+        ExecutionResult with status, output, and metadata
+
+    Example:
+        >>> result = execute_code(
+        ...     code='print(get_input("x", 0))',
+        ...     inputs={"x": 42},
+        ...     config=ExecutionConfig(timeout=60)
+        ... )
+        >>> print(result.stdout)
+        "42"
+    """
+    # Use default config if not provided
+    config = config or ExecutionConfig()
+
+    # Wrap inputs if provided per D-29
+    if inputs:
+        code = _inject_inputs(code, inputs)
+
+    # Per D-30: Check if code defines main() and wrap for return value capture
+    if config.capture_return_value and 'def main(' in code:
+        # The sandbox already handles return value capture via wrapper
+        pass
+
+    # Create sandbox executor per D-01
+    executor = SandboxExecutor(
+        timeout=config.timeout,
+        max_memory_mb=config.max_memory_mb
+    )
+
+    # Execute code
+    result = executor.execute(code, working_dir=config.working_dir)
+
+    # Categorize and translate errors per D-17, D-18
+    if result.status != ExecutionStatus.SUCCESS:
+        result = _categorize_error(result)
+
+    return result
+
+
+def format_results_for_context(result: ExecutionResult) -> Dict[str, Any]:
+    """Format execution results for ContextManager.save_results().
+
+    Per D-16: Execution metadata captured alongside outputs.
+
+    Args:
+        result: Execution result
+
+    Returns:
+        Dictionary formatted for context storage
+    """
+    from datetime import datetime
+
+    return {
+        'status': result.status.value,
+        'stdout': result.stdout,
+        'stderr': result.stderr,
+        'execution_time': result.runtime_seconds,
+        'return_value': result.return_value,
+        'error_type': result.error_type,
+        'error_message': result.error_message,
+        'timestamp': datetime.now().isoformat()
+    }
+
+
+def build_execution_response(
+    result: ExecutionResult,
+    truncate_stdout: int = 2000,
+    truncate_stderr: int = 1000
+) -> Dict[str, Any]:
+    """Build response dict for workflow functions.
+
+    Per D-15: Show output with truncation (50 lines max, then summarize).
+    Per D-23: Progress indicator included in response.
+
+    Args:
+        result: Execution result
+        truncate_stdout: Max chars for stdout (per D-15)
+        truncate_stderr: Max chars for stderr
+
+    Returns:
+        Response dictionary for workflow
+    """
+    # Truncate output per D-15
+    stdout_display = result.stdout[:truncate_stdout] if result.stdout else ''
+    stderr_display = result.stderr[:truncate_stderr] if result.stderr else ''
+
+    # Build user message per D-18
+    if result.status == ExecutionStatus.SUCCESS:
+        message = f"✓ Execution complete in {result.runtime_seconds:.3f}s"
+    elif result.status == ExecutionStatus.TIMEOUT:
+        message = (
+            "⚠ Execution timed out. "
+            "Check loop conditions for infinite loops."
+        )
+    else:
+        message = f"✗ Execution failed: {result.error_message or result.error_type or 'Unknown error'}"
+
+    return {
+        'status': result.status.value,
+        'execution_time': result.runtime_seconds,
+        'stdout': stdout_display,
+        'stderr': stderr_display,
+        'error': result.error_message if result.status != ExecutionStatus.SUCCESS else None,
+        'return_value': result.return_value,
+        'message': message,
+        'next_steps': [
+            'Verify results with /algo-verify',
+            'Run again with /algo-run',
+            'Regenerate code with /algo-generate'
+        ]
+    }