algomath-extract 1.0.0

package/src/extraction/schema.py

@@ -0,0 +1,173 @@
+"""Schema definitions for algorithm extraction.
+
+This module defines the core data structures for representing algorithms
+and their steps in a structured, machine-readable format.
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+
+class StepType(Enum):
+    """Enumeration of step types for algorithm steps."""
+    ASSIGNMENT = "assignment"
+    LOOP_FOR = "loop_for"
+    LOOP_WHILE = "loop_while"
+    CONDITIONAL = "conditional"
+    RETURN = "return"
+    CALL = "call"
+    COMMENT = "comment"
+
+
+@dataclass
+class Step:
+    """
+    Represents a single step in an algorithm.
+
+    Attributes:
+        id: Unique identifier for the step
+        type: Type of step (assignment, loop, conditional, etc.)
+        description: Human-readable description of the step
+        inputs: List of variable names read by this step
+        outputs: List of variable names written by this step
+        line_refs: Line numbers in the original source text
+        condition: Condition for loops/conditionals
+        body: List of step IDs in the body (for loops/conditionals)
+        else_body: List of step IDs in the else branch (for conditionals)
+        iter_var: Loop variable (for for loops)
+        iter_range: Range specification (for for loops)
+        expression: Expression (for assignments and returns)
+        call_target: Function name (for calls)
+        arguments: Arguments (for calls)
+        annotation: Comment text (for comments)
+    """
+    id: int
+    type: StepType
+    description: str
+    inputs: List[str] = field(default_factory=list)
+    outputs: List[str] = field(default_factory=list)
+    line_refs: List[int] = field(default_factory=list)
+    condition: Optional[str] = None
+    body: List[int] = field(default_factory=list)
+    else_body: List[int] = field(default_factory=list)
+    iter_var: Optional[str] = None
+    iter_range: Optional[str] = None
+    expression: Optional[str] = None
+    call_target: Optional[str] = None
+    arguments: List[str] = field(default_factory=list)
+    annotation: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert step to dictionary representation."""
+        return {
+            "id": self.id,
+            "type": self.type.value,
+            "description": self.description,
+            "inputs": self.inputs,
+            "outputs": self.outputs,
+            "line_refs": self.line_refs,
+            "condition": self.condition,
+            "body": self.body,
+            "else_body": self.else_body,
+            "iter_var": self.iter_var,
+            "iter_range": self.iter_range,
+            "expression": self.expression,
+            "call_target": self.call_target,
+            "arguments": self.arguments,
+            "annotation": self.annotation
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Step":
+        """Create step from dictionary."""
+        return cls(
+            id=data["id"],
+            type=StepType(data["type"]),
+            description=data["description"],
+            inputs=data.get("inputs", []),
+            outputs=data.get("outputs", []),
+            line_refs=data.get("line_refs", []),
+            condition=data.get("condition"),
+            body=data.get("body", []),
+            else_body=data.get("else_body", []),
+            iter_var=data.get("iter_var"),
+            iter_range=data.get("iter_range"),
+            expression=data.get("expression"),
+            call_target=data.get("call_target"),
+            arguments=data.get("arguments", []),
+            annotation=data.get("annotation")
+        )
+
+
+@dataclass
+class Algorithm:
+    """
+    Represents a complete algorithm with its steps.
+
+    Attributes:
+        name: Algorithm name
+        description: Brief description
+        inputs: List of input variables with types and descriptions
+        outputs: List of output variables with types and descriptions
+        steps: List of algorithm steps
+        source_text: Original source text
+    """
+    name: str
+    description: str = ""
+    inputs: List[Dict[str, Any]] = field(default_factory=list)
+    outputs: List[Dict[str, Any]] = field(default_factory=list)
+    steps: List[Step] = field(default_factory=list)
+    source_text: str = ""
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert algorithm to dictionary representation."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "inputs": self.inputs,
+            "outputs": self.outputs,
+            "steps": [step.to_dict() for step in self.steps],
+            "source_text": self.source_text
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Algorithm":
+        """Create algorithm from dictionary."""
+        return cls(
+            name=data.get("name", "unnamed"),
+            description=data.get("description", ""),
+            inputs=data.get("inputs", []),
+            outputs=data.get("outputs", []),
+            steps=[Step.from_dict(s) for s in data.get("steps", [])],
+            source_text=data.get("source_text", "")
+        )
+
+
+def algorithm_to_json(algorithm: Algorithm) -> str:
+    """
+    Convert an Algorithm object to JSON string.
+
+    Args:
+        algorithm: Algorithm to convert
+
+    Returns:
+        JSON string representation
+    """
+    import json
+    return json.dumps(algorithm.to_dict(), indent=2)
+
+
+def algorithm_from_json(json_str: str) -> Algorithm:
+    """
+    Convert a JSON string to an Algorithm object.
+
+    Args:
+        json_str: JSON string to parse
+
+    Returns:
+        Algorithm object
+    """
+    import json
+    data = json.loads(json_str)
+    return Algorithm.from_dict(data)

package/src/extraction/validation.py

@@ -0,0 +1,202 @@
+"""Validation for extracted algorithms."""
+from typing import List, Set, Dict, Tuple
+from dataclasses import dataclass, field
+
+from .schema import Algorithm, Step, StepType
+from .errors import ExtractionError, ParseError, IncompleteError
+
+
+@dataclass
+class ValidationResult:
+    """Result of algorithm validation."""
+
+    is_valid: bool
+    errors: List[ExtractionError] = field(default_factory=list)
+    warnings: List[str] = field(default_factory=list)
+
+    def add_error(self, error: ExtractionError):
+        """Add an error and mark as invalid."""
+        self.errors.append(error)
+        self.is_valid = False
+
+    def add_warning(self, warning: str):
+        """Add a warning (does not invalidate)."""
+        self.warnings.append(warning)
+
+    def __str__(self) -> str:
+        if self.is_valid and not self.warnings:
+            return "Algorithm is valid"
+
+        lines = []
+        if not self.is_valid:
+            lines.append(f"Validation failed with {len(self.errors)} error(s)")
+        if self.warnings:
+            lines.append(f"{len(self.warnings)} warning(s)")
+        return "\n".join(lines)
+
+
+def validate_algorithm(algorithm: Algorithm) -> ValidationResult:
+    """
+    Validate an algorithm for correctness.
+
+    Args:
+        algorithm: Algorithm to validate
+
+    Returns:
+        ValidationResult with errors and warnings
+
+    Per D-20 from 02-CONTEXT.md.
+    """
+    result = ValidationResult(is_valid=True)
+
+    # Check algorithm has minimum structure
+    if not algorithm.name or algorithm.name == "unnamed":
+        result.add_warning("Algorithm has no name")
+
+    if not algorithm.steps:
+        result.add_error(IncompleteError(
+            message="Algorithm has no steps",
+            suggestion="Add at least one algorithm step"
+        ))
+
+    # Check for unique step IDs
+    step_ids = [step.id for step in algorithm.steps]
+    if len(step_ids) != len(set(step_ids)):
+        duplicates = set([x for x in step_ids if step_ids.count(x) > 1])
+        result.add_error(ParseError(
+            message=f"Duplicate step IDs found: {duplicates}",
+            suggestion="Ensure each step has a unique identifier"
+        ))
+
+    # Check step connectivity
+    connectivity = check_step_connectivity(algorithm)
+    if not connectivity.is_valid:
+        result.errors.extend(connectivity.errors)
+        result.is_valid = False
+
+    # Check variable flow
+    var_flow = check_variable_flow(algorithm)
+    if not var_flow.is_valid:
+        result.errors.extend(var_flow.errors)
+        result.is_valid = False
+
+    # Check each step individually
+    for step in algorithm.steps:
+        _validate_step(step, result)
+
+    return result
+
+
+def check_step_connectivity(algorithm: Algorithm) -> ValidationResult:
+    """
+    Check that all step references are valid.
+
+    Validates that body/else_body references point to existing steps.
+
+    Args:
+        algorithm: Algorithm to check
+
+    Returns:
+        ValidationResult
+    """
+    result = ValidationResult(is_valid=True)
+    step_ids = {step.id for step in algorithm.steps}
+
+    for step in algorithm.steps:
+        # Check body references
+        for ref_id in step.body:
+            if ref_id not in step_ids:
+                result.add_error(ParseError(
+                    message=f"Step {step.id} references non-existent step {ref_id} in body",
+                    line_number=step.line_refs[0] if step.line_refs else None,
+                    suggestion="Update reference to point to an existing step"
+                ))
+
+        # Check else_body references
+        for ref_id in step.else_body:
+            if ref_id not in step_ids:
+                result.add_error(ParseError(
+                    message=f"Step {step.id} references non-existent step {ref_id} in else_body",
+                    line_number=step.line_refs[0] if step.line_refs else None,
+                    suggestion="Update reference to point to an existing step"
+                ))
+
+    return result
+
+
+def check_variable_flow(algorithm: Algorithm) -> ValidationResult:
+    """
+    Check that variables are defined before use.
+
+    Args:
+        algorithm: Algorithm to check
+
+    Returns:
+        ValidationResult
+    """
+    result = ValidationResult(is_valid=True)
+    defined_vars: Set[str] = set()
+
+    # Add input variables as initially defined
+    for inp in algorithm.inputs:
+        var_name = inp.get("name", "")
+        if var_name:
+            defined_vars.add(var_name.split('[')[0])  # Handle array notation
+
+    # Track defined variables through steps
+    for step in algorithm.steps:
+        # Check inputs are defined
+        for var in step.inputs:
+            base_var = var.split('[')[0]  # Handle array indexing
+            if base_var not in defined_vars and not _is_builtin_or_constant(base_var):
+                result.add_warning(
+                    f"Step {step.id}: Variable '{var}' may not be defined before use"
+                )
+
+        # Add outputs to defined set
+        for var in step.outputs:
+            base_var = var.split('[')[0]
+            defined_vars.add(base_var)
+
+    return result
+
+
+def _is_builtin_or_constant(var: str) -> bool:
+    """Check if variable is a builtin or constant."""
+    builtins = {'True', 'False', 'None', 'len', 'range', 'sum', 'min', 'max'}
+    constants = {'n', 'm', 'i', 'j', 'k', 'x', 'y', 'z'}
+    return var in builtins or var in constants or var.isdigit()
+
+
+def _validate_step(step: Step, result: ValidationResult):
+    """Validate a single step."""
+
+    # Check step has description
+    if not step.description or not step.description.strip():
+        result.add_error(IncompleteError(
+            message=f"Step {step.id} has no description",
+            line_number=step.line_refs[0] if step.line_refs else None
+        ))
+
+    # Type-specific validation
+    if step.type == StepType.ASSIGNMENT:
+        if not step.expression and '=' not in step.description:
+            result.add_warning(f"Step {step.id}: Assignment without clear expression")
+
+    elif step.type in (StepType.LOOP_FOR, StepType.LOOP_WHILE):
+        if step.type == StepType.LOOP_FOR and not step.iter_var:
+            result.add_warning(f"Step {step.id}: For loop without iteration variable")
+        if not step.body:
+            result.add_warning(f"Step {step.id}: Loop has empty body")
+
+    elif step.type == StepType.CONDITIONAL:
+        if not step.condition and 'if' in step.description.lower():
+            result.add_warning(f"Step {step.id}: Conditional without explicit condition")
+
+    elif step.type == StepType.RETURN:
+        if not step.expression:
+            result.add_warning(f"Step {step.id}: Return without value")
+
+    # Check line references exist
+    if not step.line_refs:
+        result.add_warning(f"Step {step.id}: No line references (traceability reduced)")

package/src/generation/__init__.py

@@ -0,0 +1,79 @@
+"""Code generation module for AlgoMath.
+
+This module provides tools for converting structured algorithms
+into executable Python code.
+"""
+
+from src.generation.types import (
+    TypeInferrer,
+    PythonType,
+    FunctionSignature,
+    ValidationResult,
+)
+from src.generation.templates import (
+    TemplateRegistry,
+    CodeTemplates,
+)
+from src.generation.code_generator import (
+    TemplateCodeGenerator,
+    GeneratedCode,
+)
+from src.generation.llm_generator import (
+    LLMCodeGenerator,
+)
+from src.generation.hybrid import (
+    HybridCodeGenerator,
+    HybridGenerationResult,
+)
+from src.generation.errors import (
+    GenerationError,
+    SyntaxGenerationError,
+    ImportGenerationError,
+    LLMGenerationError,
+    ValidationError,
+)
+from src.generation.validation import (
+    ValidationResult,
+    CodeValidator,
+)
+from src.generation.review import (
+    CodeReviewInterface,
+    ReviewState,
+    create_review,
+)
+from src.generation.persistence import (
+    CodePersistence,
+    save_to_context,
+)
+
+__all__ = [
+    # Types
+    "TypeInferrer",
+    "PythonType",
+    "FunctionSignature",
+    "ValidationResult",
+    # Templates
+    "TemplateRegistry",
+    "CodeTemplates",
+    # Generators
+    "TemplateCodeGenerator",
+    "LLMCodeGenerator",
+    "HybridCodeGenerator",
+    "HybridGenerationResult",
+    "GeneratedCode",
+    # Errors
+    "GenerationError",
+    "SyntaxGenerationError",
+    "ImportGenerationError",
+    "LLMGenerationError",
+    "ValidationError",
+    # Validation
+    "CodeValidator",
+    # Review
+    "CodeReviewInterface",
+    "ReviewState",
+    "create_review",
+    # Persistence
+    "CodePersistence",
+    "save_to_context",
+]