algomath-extract 1.0.0

package/src/cli/commands.py

@@ -0,0 +1,339 @@
+"""
+CLI Commands for AlgoMath - User-facing command implementations.
+
+This module provides command functions that can be called directly
+or through the intent routing system. Commands follow a consistent
+return format with status, progress, message, and next_steps.
+"""
+
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+import sys
+from pathlib import Path
+
+# Add project root to Python path
+project_root = Path(__file__).parent.parent.parent
+if str(project_root) not in sys.path:
+    sys.path.insert(0, str(project_root))
+
+from algomath.context import ContextManager
+from algomath.state import WorkflowState
+from src.workflows.run import run_execution
+
+
+def extract_command(text: str, name: Optional[str] = None) -> Dict[str, Any]:
+    """
+    Extract algorithm from mathematical text.
+
+    Args:
+        text: Mathematical text describing an algorithm
+        name: Optional name for the algorithm
+
+    Returns:
+        Dict with extraction status and results
+    """
+    from src.workflows.extract import extract_algorithm
+
+    ctx = ContextManager()
+    ctx.start_session()
+
+    if name:
+        ctx.create_algorithm(name)
+
+    result = extract_algorithm(ctx, text)
+    return result
+
+
+def generate_command() -> Dict[str, Any]:
+    """
+    Generate code from extracted algorithm steps.
+
+    Returns:
+        Dict with generation status and results
+    """
+    from src.workflows.generate import generate_code
+
+    ctx = ContextManager()
+    ctx.start_session()
+
+    result = generate_code(ctx)
+    return result
+
+
+def run_command(
+    skip: bool = False,
+    inputs: Optional[Dict[str, Any]] = None
+) -> Dict[str, Any]:
+    """
+    Execute generated code with /algo-run.
+
+    Per D-21: Auto-triggered after code approval
+    Per D-25: Can skip with skip=True to proceed directly to verification
+
+    Args:
+        skip: If True, skip execution and proceed to verification
+        inputs: Optional input data for the algorithm
+
+    Returns:
+        Dict with execution status and results
+    """
+    ctx = ContextManager()
+    ctx.start_session()
+
+    current = ctx.get_current()
+
+    # Check current state
+    if current.current_state == WorkflowState.EXECUTION_COMPLETE:
+        # Already executed - show results
+        results = current.data.get('results', {})
+        return {
+            'status': 'already_executed',
+            'message': 'Algorithm already executed. Run again to re-execute.',
+            'results': results,
+            'next_steps': [
+                'Verify results with /algo-verify',
+                'Re-run with /algo-run',
+                'Regenerate with /algo-generate'
+            ]
+        }
+
+    if current.current_state != WorkflowState.CODE_GENERATED:
+        return {
+            'status': 'invalid_state',
+            'message': f"Cannot execute: current state is {current.current_state.value}",
+            'required_state': 'code_generated',
+            'next_steps': [
+                'Generate code first with /algo-generate',
+                'Check status with /algo-status'
+            ]
+        }
+
+    # Check if skip requested per D-25
+    if skip:
+        # Skip execution, proceed to verification
+        ctx.save_results({
+            'status': 'skipped',
+            'message': 'Execution skipped by user',
+            'timestamp': datetime.now().isoformat()
+        })
+
+        return {
+            'status': 'skipped',
+            'message': 'Execution skipped. Proceeding to verification.',
+            'next_steps': [
+                'Verify with /algo-verify',
+                'Run later with /algo-run'
+            ]
+        }
+
+    # Execute
+    print(f"Executing algorithm: {current.current_algorithm or '(unnamed)'}...")
+    result = run_execution(ctx, inputs=inputs)
+
+    return result
+
+
+def verify_command(
+    expected: Optional[Any] = None,
+    step: Optional[int] = None,
+    detailed: bool = False,
+    diagnostic: bool = False
+) -> Dict[str, Any]:
+    """
+    Verify execution results with /algo-verify.
+
+    Per D-01: Quick inline summary shown automatically
+    Per D-02: Full verification via this command
+    Per D-03: Diagnostic mode for failed executions
+    Per D-06: Detailed explanation with --detailed
+    Per D-09: Interactive expected results prompt
+    Per D-22: Diagnostic mode with --diagnostic
+
+    Args:
+        expected: Optional expected output for comparison
+        step: Optional step ID for detailed explanation (VER-05)
+        detailed: If True, generate detailed step-by-step explanation
+        diagnostic: If True, run diagnostic mode for failed executions
+
+    Returns:
+        Dict with verification status and results
+    """
+    from src.workflows.verify import run_verification, verify_step
+
+    ctx = ContextManager()
+    ctx.start_session()
+
+    current = ctx.get_current()
+
+    # Check current state per D-02, D-25
+    if current.current_state == WorkflowState.VERIFIED:
+        # Already verified - show cached report
+        algorithm_data = ctx.store.load_session()
+        return {
+            'status': 'already_verified',
+            'message': 'Algorithm already verified. Run again for fresh verification.',
+            'last_verification': algorithm_data.get('verification', {}),
+            'next_steps': [
+                'Re-verify with /algo-verify',
+                'Extract new with /algo-extract',
+                'Check status with /algo-status'
+            ]
+        }
+
+    if current.current_state not in [WorkflowState.EXECUTION_COMPLETE, WorkflowState.CODE_GENERATED]:
+        return {
+            'status': 'not_ready',
+            'message': f"Cannot verify: current state is {current.current_state.value}",
+            'required_state': 'execution_complete',
+            'next_steps': [
+                'Run code first with /algo-run',
+                'Check status with /algo-status'
+            ]
+        }
+
+    # Handle step-specific explanation per VER-05
+    if step is not None:
+        result = verify_step(ctx, step)
+        return result
+
+    # Interactive prompt for expected results per D-09
+    if expected is None and not diagnostic:
+        # Note: In actual CLI, this would prompt user
+        # For now, proceed without comparison
+        pass
+
+    # Run full verification per D-02
+    print(f"Verifying algorithm: {current.current_algorithm or '(unnamed)'}...")
+    result = run_verification(
+        ctx,
+        expected=expected,
+        detailed=detailed,
+        diagnostic=diagnostic
+    )
+
+    return result
+
+
+def status_command() -> Dict[str, Any]:
+    """
+    Show current algorithm status and progress.
+
+    Returns:
+        Dict with current state information
+    """
+    ctx = ContextManager()
+    ctx.start_session()
+
+    current = ctx.get_current()
+    progress = ctx.get_progress()
+    progress_bar = ctx.get_progress_bar()
+
+    return {
+        'status': 'success',
+        'algorithm': progress['algorithm_name'],
+        'state': current.current_state.value,
+        'progress_bar': progress_bar,
+        'steps_completed': progress['steps_completed'],
+        'steps_total': progress['steps_total'],
+        'data_status': progress['data_status'],
+        'has_text': 'text' in current.data,
+        'has_steps': 'steps' in current.data,
+        'has_code': 'code' in current.data,
+        'has_results': 'results' in current.data,
+        'next_steps': [
+            f"Current: {current.current_state.value}",
+            "Continue with workflow commands",
+            "Use /algo-help for command list"
+        ]
+    }
+
+
+def list_command() -> Dict[str, Any]:
+    """
+    List all saved algorithms.
+
+    Returns:
+        Dict with list of algorithms
+    """
+    ctx = ContextManager()
+    algorithms = ctx.list_algorithms()
+
+    return {
+        'status': 'success',
+        'count': len(algorithms),
+        'algorithms': [
+            {'name': name, 'updated': updated}
+            for name, updated in algorithms
+        ],
+        'next_steps': [
+            'Load algorithm with /algo-extract [name]',
+            'Start new with /algo-extract',
+            'Check status with /algo-status'
+        ]
+    }
+
+
+def help_command() -> Dict[str, Any]:
+    """
+    Show help and available commands.
+
+    Returns:
+        Dict with command reference
+    """
+    commands = [
+        ('/algo-extract "text" [name]', 'Extract algorithm from text', 'Initial'),
+        ('/algo-generate', 'Generate code from steps', 'STEPS_STRUCTURED'),
+        ('/algo-run', 'Execute generated code', 'CODE_GENERATED'),
+        ('/algo-run --skip', 'Skip execution (proceed to verify)', 'CODE_GENERATED'),
+        ('/algo-verify', 'Verify execution results', 'EXECUTION_COMPLETE'),
+        ('/algo-verify --step N', 'Explain step N in detail', 'EXECUTION_COMPLETE'),
+        ('/algo-verify --detailed', 'Show detailed explanation', 'EXECUTION_COMPLETE'),
+        ('/algo-verify --diagnostic', 'Diagnose failed execution', 'EXECUTION_COMPLETE'),
+        ('/algo-status', 'Show current state and progress', 'Any'),
+        ('/algo-list', 'List saved algorithms', 'Any'),
+        ('/algo-help', 'Show this help', 'Any'),
+    ]
+
+    return {
+        'status': 'success',
+        'commands': [
+            {
+                'command': cmd,
+                'description': desc,
+                'requires': req
+            }
+            for cmd, desc, req in commands
+        ],
+        'tip': 'Commands can be used naturally, e.g., "extract algorithm from this text"',
+        'next_steps': [
+            'Try /algo-extract to start',
+            'Check /algo-status any time',
+            'Ask for /algo-help when needed'
+        ]
+    }
+
+
+# Command map for routing
+COMMAND_MAP = {
+    'extract': extract_command,
+    'generate': generate_command,
+    'run': run_command,
+    'verify': verify_command,
+    'status': status_command,
+    'list': list_command,
+    'help': help_command,
+}
+
+
+# Exports
+__all__ = [
+    'COMMAND_MAP',
+    'extract_command',
+    'generate_command',
+    'run_command',
+    'verify_command',
+    'status_command',
+    'list_command',
+    'help_command',
+]

package/src/execution/__init__.py

@@ -0,0 +1,74 @@
+"""Execution module for AlgoMath.
+
+Provides safe, sandboxed code execution with resource limits,
+timeout protection, and comprehensive output capture.
+
+Per Phase 4 decisions D-01 through D-30:
+- D-01: Subprocess-based isolation
+- D-02: Resource limits (CPU, memory)
+- D-05: 30-second default timeout
+- D-09, D-10: Temp directory sandbox with auto-cleanup
+- D-16: Execution metadata capture
+- D-17: Error categorization
+- D-28: Import restrictions
+- D-29: Input handling
+- D-30: Return value capture
+
+Example:
+    >>> from src.execution import execute_code, ExecutionConfig
+    >>> config = ExecutionConfig(timeout=60, max_memory_mb=1024)
+    >>> result = execute_code('print("Hello")', config=config)
+    >>> print(result.stdout)
+    "Hello"
+    >>> print(result.status)
+    "success"
+"""
+
+# Core sandbox and executor components
+from .sandbox import SandboxExecutor, ExecutionResult, ExecutionStatus, execute_sandboxed
+from .executor import execute_code, ExecutionConfig, format_results_for_context, build_execution_response
+
+# Error handling and display (from existing modules)
+from .errors import (
+    ExecutionError,
+    ErrorTranslator,
+    ErrorDetails,
+    categorize_error,
+    extract_line_number,
+)
+from .display import (
+    ExecutionFormatter,
+    FormattedResult,
+    truncate_output,
+    show_progress,
+    show_execution_summary,
+    format_execution_log,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Sandbox components
+    'SandboxExecutor',
+    'ExecutionResult',
+    'ExecutionStatus',
+    'execute_sandboxed',
+    # High-level interface
+    'execute_code',
+    'ExecutionConfig',
+    'format_results_for_context',
+    'build_execution_response',
+    # Error handling
+    'ExecutionError',
+    'ErrorTranslator',
+    'ErrorDetails',
+    'categorize_error',
+    'extract_line_number',
+    # Display formatting
+    'ExecutionFormatter',
+    'FormattedResult',
+    'truncate_output',
+    'show_progress',
+    'show_execution_summary',
+    'format_execution_log',
+]

package/src/execution/display.py

@@ -0,0 +1,261 @@
+"""Output formatting and display for execution results.
+
+Covers EXE-05 (status reporting) and output formatting per D-13 through D-16.
+Reuses progress indicator pattern from Phase 1 (D-09).
+"""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional, Any
+
+from .errors import ErrorDetails, ExecutionError
+
+
+# Constants per D-15
+MAX_INLINE_LINES = 50
+TRUNCATION_MESSAGE = "\n... ({} more lines - see full log for details)\n"
+
+
+@dataclass
+class FormattedResult:
+    """Formatted execution result per D-14, D-16.
+
+    Attributes:
+        display_text: Formatted text for display
+        status_emoji: Visual status indicator
+        status_text: Text status (Success/Failed/Timed Out)
+        execution_time: Human-readable execution time
+        output_truncated: Whether output was truncated
+        full_log_path: Path to full log file (if exists)
+    """
+    display_text: str
+    status_emoji: str
+    status_text: str
+    execution_time: str
+    output_truncated: bool
+    full_log_path: Optional[str]
+
+
+class ExecutionFormatter:
+    """Format execution results for display per D-14, D-15, D-16.
+
+    Takes raw execution results and formats them for user presentation
+    with status indicators, truncated output, and log references.
+    """
+
+    def __init__(self, algorithm_name: Optional[str] = None):
+        """Initialize formatter with optional algorithm name.
+
+        Args:
+            algorithm_name: Name of the algorithm (for log path)
+        """
+        self.algorithm_name = algorithm_name
+        self.log_dir = Path(".algomath/algorithms") / algorithm_name if algorithm_name else None
+
+    def format_results(self, result: Any) -> FormattedResult:
+        """Format execution result for display per D-14, D-15, D-16.
+
+        Args:
+            result: Execution result object with status, stdout, stderr, runtime_seconds
+
+        Returns:
+            FormattedResult with display-ready text
+        """
+        # Status indicators per EXE-05
+        if result.status == 'success':
+            emoji = '✓'
+            status = 'Success'
+        elif result.status == 'timeout':
+            emoji = '⏱'
+            status = 'Timed Out'
+        else:
+            emoji = '✗'
+            status = 'Failed'
+
+        # Build display text
+        lines = []
+        lines.append(f"{emoji} Execution: {status}")
+
+        # Execution time per D-16
+        runtime = getattr(result, 'runtime_seconds', 0)
+        lines.append(f"Time: {runtime:.3f}s")
+
+        # Output per D-13 (dual capture) and D-15 (truncation)
+        stdout = getattr(result, 'stdout', '') or ''
+        stderr = getattr(result, 'stderr', '') or ''
+
+        if stdout:
+            lines.append("\n--- Output ---")
+            output = truncate_output(stdout, MAX_INLINE_LINES)
+            lines.append(output)
+
+        # Errors (fewer lines shown)
+        if stderr:
+            lines.append("\n--- Errors ---")
+            errors = truncate_output(stderr, 20)  # Fewer error lines
+            lines.append(errors)
+
+        # Full log path per D-14
+        log_path = str(self.log_dir / "execution.log") if self.log_dir else None
+        output_truncated = len(stdout.split('\n')) > MAX_INLINE_LINES if stdout else False
+
+        if log_path and output_truncated:
+            lines.append(f"\nFull log: {log_path}")
+
+        return FormattedResult(
+            display_text='\n'.join(lines),
+            status_emoji=emoji,
+            status_text=status,
+            execution_time=f"{runtime:.3f}s",
+            output_truncated=output_truncated,
+            full_log_path=log_path
+        )
+
+
+def truncate_output(text: str, max_lines: int = MAX_INLINE_LINES) -> str:
+    """Truncate output to max_lines with summary per D-15.
+
+    Args:
+        text: Output text to truncate
+        max_lines: Maximum number of lines to show
+
+    Returns:
+        Truncated text with summary message if needed
+    """
+    if not text:
+        return text
+
+    lines = text.split('\n')
+    if len(lines) <= max_lines:
+        return text
+
+    truncated = '\n'.join(lines[:max_lines])
+    remaining = len(lines) - max_lines
+    return truncated + TRUNCATION_MESSAGE.format(remaining)
+
+
+def show_progress(phase: str, current: int, total: int) -> str:
+    """Generate progress bar string per Phase 1 D-09.
+
+    Args:
+        phase: Name of the current phase
+        current: Current step number
+        total: Total number of steps
+
+    Returns:
+        Formatted progress bar string like "Execute: █████░░░░░ 50%"
+    """
+    if total <= 0:
+        return f"{phase}: ░░░░░░░░░░ 0%"
+
+    filled = int(10 * current / total)
+    filled = max(0, min(filled, 10))  # Clamp to 0-10 range
+    bar = '█' * filled + '░' * (10 - filled)
+    pct = int(100 * current / total)
+    return f"{phase}: {bar} {pct}%"
+
+
+def show_execution_summary(
+    result: Any,
+    error_details: Optional[ErrorDetails] = None
+) -> str:
+    """Show execution summary with error translation if needed per EXE-05, EXE-06.
+
+    Args:
+        result: Execution result object
+        error_details: Optional error translation details
+
+    Returns:
+        Formatted summary string
+    """
+    lines = []
+
+    # Status line per EXE-05
+    runtime = getattr(result, 'runtime_seconds', 0)
+    if result.status == 'success':
+        lines.append(f"✓ Algorithm executed successfully in {runtime:.3f}s")
+    else:
+        lines.append(f"✗ Execution {result.status}")
+
+    # Error translation per EXE-06
+    if error_details:
+        lines.append(f"\n{error_details.user_message}")
+        lines.append(f"\n💡 {error_details.hint}")
+
+        # Technical details in collapsed section per D-19
+        if error_details.technical_details:
+            lines.append(f"\n<details>")
+            lines.append(f"<summary>Technical Details (for debugging)</summary>")
+            lines.append(f"\n```\n{error_details.technical_details}\n```")
+            lines.append(f"</details>")
+
+    return '\n'.join(lines)
+
+
+def format_execution_log(
+    algorithm_name: str,
+    status: str,
+    runtime_seconds: float,
+    stdout: str,
+    stderr: str,
+    error_type: Optional[str] = None,
+    error_message: Optional[str] = None
+) -> str:
+    """Format complete execution log for file persistence per D-14.
+
+    Args:
+        algorithm_name: Name of the algorithm
+        status: Execution status
+        runtime_seconds: Execution time in seconds
+        stdout: Standard output
+        stderr: Standard error
+        error_type: Type of error if failed
+        error_message: Error message if failed
+
+    Returns:
+        Formatted log content for saving to file
+    """
+    from datetime import datetime
+
+    lines = [
+        f"Algorithm: {algorithm_name}",
+        f"Status: {status}",
+        f"Timestamp: {datetime.now().isoformat()}",
+        f"Runtime: {runtime_seconds:.3f}s",
+        "",
+        "=" * 50,
+        "OUTPUT",
+        "=" * 50,
+        stdout if stdout else "(no output)",
+    ]
+
+    if stderr:
+        lines.extend([
+            "",
+            "=" * 50,
+            "ERRORS",
+            "=" * 50,
+            stderr
+        ])
+
+    if error_type:
+        lines.extend([
+            "",
+            "=" * 50,
+            "ERROR DETAILS",
+            "=" * 50,
+            f"Type: {error_type}",
+            f"Message: {error_message or '(no message)'}"
+        ])
+
+    return '\n'.join(lines)
+
+
+__all__ = [
+    'ExecutionFormatter',
+    'FormattedResult',
+    'truncate_output',
+    'show_progress',
+    'show_execution_summary',
+    'format_execution_log',
+]