algomath-extract 1.0.0

package/src/extraction/boundaries.py

@@ -0,0 +1,281 @@
+"""Algorithm boundary detection for extraction.
+
+Identifies algorithm sections including headers, inputs, outputs,
+and step boundaries within mathematical text.
+
+Per D-12, D-13, D-14, D-15, D-16, D-17 from 02-CONTEXT.md.
+"""
+import re
+from typing import Dict, List, Optional, Tuple, NamedTuple
+from dataclasses import dataclass
+
+
+@dataclass
+class AlgorithmBoundaries:
+    """Represents detected algorithm boundaries."""
+    name: str
+    name_line: Optional[int] = None
+    input_start: Optional[int] = None
+    input_end: Optional[int] = None
+    output_start: Optional[int] = None
+    output_end: Optional[int] = None
+    steps_start: Optional[int] = None
+    steps_end: Optional[int] = None
+
+
+# Patterns for detecting algorithm headers
+HEADER_PATTERNS = [
+    r'^\s*(?:Algorithm|ALGORITHM)[\s:]+([A-Za-z][A-Za-z0-9_\s]*)',
+    r'^\s*(?:Procedure|PROCEDURE)[\s:]+([A-Za-z][A-Za-z0-9_\s]*)',
+    r'^\s*(?:Function|FUNCTION)[\s:]+([A-Za-z][A-Za-z0-9_\s]*)',
+    r'^\s*(?:Method|METHOD)[\s:]+([A-Za-z][A-Za-z0-9_\s]*)',
+]
+
+# Patterns for input sections
+INPUT_PATTERNS = [
+    r'^\s*(?:Input|INPUT|Inputs|INPUTS)[\s:]*',
+    r'^\s*(?:Given|GIVEN)[\s:]*',
+    r'^\s*(?:Parameters|PARAMETERS)[\s:]*',
+    r'^\s*(?:Takes|TAKES)[\s:]*',
+    r'^\s*(?:Requires|REQUIRES)[\s:]*',
+    r'^\s*(?:Precondition|PRECONDITION)[\s:]*',
+]
+
+# Patterns for output sections
+OUTPUT_PATTERNS = [
+    r'^\s*(?:Output|OUTPUT|Outputs|OUTPUTS)[\s:]*',
+    r'^\s*(?:Returns|RETURNS)[\s:]*',
+    r'^\s*(?:Result|RESULT|Results|RESULTS)[\s:]*',
+    r'^\s*(?:Produces|PRODUCES)[\s:]*',
+    r'^\s*(?:Postcondition|POSTCONDITION)[\s:]*',
+]
+
+
+def find_algorithm_name(text: str) -> Tuple[str, Optional[int]]:
+    """
+    Find algorithm name from header.
+
+    Searches for patterns like:
+    - "Algorithm: Name"
+    - "Algorithm Name"
+    - "Procedure: Name"
+    - "Function Name"
+
+    Args:
+        text: Algorithm text
+
+    Returns:
+        Tuple of (name, line_number) or ("unnamed", None)
+
+    Per D-13 from 02-CONTEXT.md.
+    """
+    lines = text.split('\n')
+
+    for line_num, line in enumerate(lines, 1):
+        for pattern in HEADER_PATTERNS:
+            match = re.match(pattern, line, re.IGNORECASE)
+            if match:
+                name = match.group(1).strip()
+                # Clean up the name
+                name = re.sub(r'\s+', ' ', name)
+                if name:
+                    return name, line_num
+
+    return "unnamed", None
+
+
+def extract_input_section(text: str) -> Tuple[Optional[int], Optional[int], List[str]]:
+    """
+    Extract input section from algorithm text.
+
+    Identifies input section boundaries and returns the content.
+
+    Args:
+        text: Algorithm text
+
+    Returns:
+        Tuple of (start_line, end_line, input_descriptions)
+        Lines are 1-indexed, None if not found
+
+    Per D-15 from 02-CONTEXT.md.
+    """
+    lines = text.split('\n')
+    start_line = None
+    end_line = None
+
+    # Find input section header
+    for line_num, line in enumerate(lines, 1):
+        for pattern in INPUT_PATTERNS:
+            if re.match(pattern, line, re.IGNORECASE):
+                start_line = line_num
+                break
+        if start_line:
+            break
+
+    if not start_line:
+        return None, None, []
+
+    # Extract input descriptions until next section or end
+    input_descriptions = []
+    end_line = start_line
+
+    for line_num in range(start_line, len(lines) + 1):
+        line = lines[line_num - 1]
+
+        # Check for end of input section (output section or steps)
+        if line_num > start_line:
+            if _is_section_boundary(line):
+                break
+
+        # Skip the header line itself
+        if line_num == start_line:
+            # Remove header part
+            clean_line = re.sub(r'^\s*(?:Input|INPUT)[\s:]*', '', line).strip()
+            if clean_line:
+                input_descriptions.append(clean_line)
+        else:
+            stripped = line.strip()
+            if stripped and not _is_section_boundary(line):
+                input_descriptions.append(stripped)
+
+        end_line = line_num
+
+    return start_line, end_line, input_descriptions
+
+
+def extract_output_section(text: str) -> Tuple[Optional[int], Optional[int], List[str]]:
+    """
+    Extract output section from algorithm text.
+
+    Identifies output section boundaries and returns the content.
+
+    Args:
+        text: Algorithm text
+
+    Returns:
+        Tuple of (start_line, end_line, output_descriptions)
+        Lines are 1-indexed, None if not found
+
+    Per D-16 from 02-CONTEXT.md.
+    """
+    lines = text.split('\n')
+    start_line = None
+    end_line = None
+
+    # Find output section header
+    for line_num, line in enumerate(lines, 1):
+        for pattern in OUTPUT_PATTERNS:
+            if re.match(pattern, line, re.IGNORECASE):
+                start_line = line_num
+                break
+        if start_line:
+            break
+
+    if not start_line:
+        return None, None, []
+
+    # Extract output descriptions until next section or end
+    output_descriptions = []
+    end_line = start_line
+
+    for line_num in range(start_line, len(lines) + 1):
+        line = lines[line_num - 1]
+
+        # Check for end of output section
+        if line_num > start_line:
+            if _is_section_boundary(line):
+                break
+
+        # Skip the header line itself
+        if line_num == start_line:
+            clean_line = re.sub(r'^\s*(?:Output|OUTPUT)[\s:]*', '', line).strip()
+            if clean_line:
+                output_descriptions.append(clean_line)
+        else:
+            stripped = line.strip()
+            if stripped and not _is_section_boundary(line):
+                output_descriptions.append(stripped)
+
+        end_line = line_num
+
+    return start_line, end_line, output_descriptions
+
+
+def detect_algorithm_boundaries(text: str) -> AlgorithmBoundaries:
+    """
+    Detect all algorithm boundaries in text.
+
+    Per D-12, D-13, D-14 from 02-CONTEXT.md.
+
+    Args:
+        text: Algorithm text
+
+    Returns:
+        AlgorithmBoundaries with detected sections
+    """
+    name, name_line = find_algorithm_name(text)
+
+    input_start, input_end, _ = extract_input_section(text)
+    output_start, output_end, _ = extract_output_section(text)
+
+    # Detect steps section (after outputs or after name if no I/O)
+    lines = text.split('\n')
+    steps_start = None
+    steps_end = len(lines)
+
+    # Start after the latest of: name, input, output
+    potential_start = name_line or 1
+    if input_end:
+        potential_start = max(potential_start, input_end + 1)
+    if output_end:
+        potential_start = max(potential_start, output_end + 1)
+
+    # Look for numbered steps
+    for line_num in range(potential_start, len(lines) + 1):
+        line = lines[line_num - 1]
+        if re.match(r'^\s*\d+[.\)]\s+', line) or re.match(r'^\s*[Ss]tep\s+\d+', line):
+            steps_start = line_num
+            break
+
+    # If no numbered steps found, use the line after sections
+    if not steps_start:
+        steps_start = potential_start
+
+    return AlgorithmBoundaries(
+        name=name,
+        name_line=name_line,
+        input_start=input_start,
+        input_end=input_end,
+        output_start=output_start,
+        output_end=output_end,
+        steps_start=steps_start,
+        steps_end=steps_end
+    )
+
+
+def _is_section_boundary(line: str) -> bool:
+    """
+    Check if line marks a section boundary.
+
+    Returns True for:
+    - Empty lines (double newline)
+    - Output headers after input
+    - Step indicators
+    - Algorithm boundaries
+    """
+    stripped = line.strip()
+
+    if not stripped:
+        return True
+
+    # Check for section headers
+    all_headers = HEADER_PATTERNS + INPUT_PATTERNS + OUTPUT_PATTERNS
+    for pattern in all_headers:
+        if re.match(pattern, line, re.IGNORECASE):
+            return True
+
+    # Check for numbered steps
+    if re.match(r'^\s*\d+[.\)]', line):
+        return True
+
+    return False

package/src/extraction/errors.py

@@ -0,0 +1,156 @@
+"""Extraction error types for AlgoMath."""
+from typing import Optional, List
+from dataclasses import dataclass
+
+
+@dataclass
+class ExtractionError(Exception):
+    """Base class for extraction errors."""
+
+    message: str
+    line_number: Optional[int] = None
+    suggestion: Optional[str] = None
+
+    def __str__(self) -> str:
+        parts = [self.message]
+        if self.line_number:
+            parts.append(f" (at line {self.line_number})")
+        if self.suggestion:
+            parts.append(f"\nSuggestion: {self.suggestion}")
+        return "".join(parts)
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "type": self.__class__.__name__,
+            "message": self.message,
+            "line_number": self.line_number,
+            "suggestion": self.suggestion
+        }
+
+
+class ParseError(ExtractionError):
+    """
+    Raised when text cannot be parsed.
+
+    Per D-23 from 02-CONTEXT.md.
+    """
+
+    def __init__(self, message: str, line_number: Optional[int] = None,
+                 suggestion: Optional[str] = None):
+        super().__init__(
+            message=f"Parse error: {message}",
+            line_number=line_number,
+            suggestion=suggestion or "Check syntax and try again"
+        )
+
+
+class AmbiguityError(ExtractionError):
+    """
+    Raised when multiple valid interpretations exist.
+
+    Per D-23 from 02-CONTEXT.md.
+    """
+
+    def __init__(self, message: str, line_number: Optional[int] = None,
+                 interpretations: Optional[List[str]] = None,
+                 suggestion: Optional[str] = None):
+        super().__init__(
+            message=f"Ambiguity: {message}",
+            line_number=line_number,
+            suggestion=suggestion or "Provide more context"
+        )
+        self.interpretations = interpretations or []
+
+
+class IncompleteError(ExtractionError):
+    """
+    Raised when algorithm appears incomplete.
+
+    Per D-23 from 02-CONTEXT.md.
+    """
+
+    def __init__(self, message: str, line_number: Optional[int] = None,
+                 missing: Optional[List[str]] = None,
+                 suggestion: Optional[str] = None):
+        super().__init__(
+            message=f"Incomplete: {message}",
+            line_number=line_number,
+            suggestion=suggestion or "Add missing information"
+        )
+        self.missing = missing or []
+
+
+def categorize_error(error_text: str, line_number: Optional[int] = None) -> ExtractionError:
+    """
+    Categorize an error message into appropriate error type.
+
+    Args:
+        error_text: Raw error message
+        line_number: Line where error occurred
+
+    Returns:
+        Categorized ExtractionError
+
+    Per D-23 from 02-CONTEXT.md.
+    """
+    text_lower = error_text.lower()
+
+    # Parse errors
+    parse_patterns = [
+        "unmatched", "unexpected", "invalid syntax", "parse",
+        "cannot parse", "syntax error", "malformed"
+    ]
+    if any(p in text_lower for p in parse_patterns):
+        return ParseError(
+            message=error_text,
+            line_number=line_number,
+            suggestion="Check for matching parentheses, brackets, or quotes"
+        )
+
+    # Ambiguity errors
+    ambiguity_patterns = [
+        "ambiguous", "could mean", "could be", "unclear",
+        "multiple interpretations", "not sure if", "could refer to"
+    ]
+    if any(p in text_lower for p in ambiguity_patterns):
+        return AmbiguityError(
+            message=error_text,
+            line_number=line_number,
+            suggestion="Clarify the meaning with more specific language"
+        )
+
+    # Incomplete errors
+    incomplete_patterns = [
+        "incomplete", "missing", "not found", "expected",
+        "end of input", "unexpected end", "truncated"
+    ]
+    if any(p in text_lower for p in incomplete_patterns):
+        return IncompleteError(
+            message=error_text,
+            line_number=line_number,
+            suggestion="Ensure the algorithm has a complete description"
+        )
+
+    # Default to generic extraction error
+    return ExtractionError(
+        message=error_text,
+        line_number=line_number,
+        suggestion="Review the text and try again"
+    )
+
+
+def format_errors_for_user(errors: List[ExtractionError]) -> str:
+    """
+    Format multiple errors into user-friendly message.
+
+    Per D-24 from 02-CONTEXT.md.
+    """
+    if not errors:
+        return "No errors found."
+
+    lines = ["Extraction completed with issues:"]
+    for i, error in enumerate(errors, 1):
+        lines.append(f"\n{i}. {error}")
+
+    return "\n".join(lines)

package/src/extraction/llm_extraction.py

@@ -0,0 +1,225 @@
+"""LLM-based extraction with hybrid fallback to rule-based parser."""
+
+import json
+import re
+from typing import Optional, List, Any
+from dataclasses import dataclass
+
+from .schema import Algorithm, Step, StepType
+from .parser import RuleBasedParser
+from .prompts import EXTRACTION_SYSTEM_PROMPT, format_extraction_prompt
+
+
+@dataclass
+class ExtractionResult:
+    """Result of extraction with metadata."""
+    algorithm: Algorithm
+    success: bool
+    method: str  # "llm" or "rule_based"
+    errors: List[str]
+    line_references: List[List[int]]
+
+    def __post_init__(self):
+        if self.errors is None:
+            self.errors = []
+
+
+def extract_algorithm_llm(
+    text: str,
+    timeout: int = 30
+) -> ExtractionResult:
+    """
+    Extract algorithm using LLM with rule-based fallback.
+
+    Args:
+        text: Algorithm description text
+        timeout: Maximum time in seconds (per D-27)
+
+    Returns:
+        ExtractionResult with algorithm and metadata
+
+    Per D-01, D-04 from 02-CONTEXT.md.
+    """
+    errors = []
+
+    try:
+        # Format prompt with line numbers
+        user_prompt = format_extraction_prompt(text)
+
+        # Call LLM (using agent's completion capability)
+        llm_response = _call_llm(
+            system=EXTRACTION_SYSTEM_PROMPT,
+            user=user_prompt,
+            timeout=timeout
+        )
+
+        if llm_response:
+            # Parse JSON response
+            algorithm = _parse_llm_response(llm_response, text)
+            if algorithm:
+                return ExtractionResult(
+                    algorithm=algorithm,
+                    success=True,
+                    method="llm",
+                    errors=[],
+                    line_references=[step.line_refs for step in algorithm.steps]
+                )
+
+        errors.append("LLM extraction returned no valid result")
+
+    except Exception as e:
+        errors.append(f"LLM extraction failed: {str(e)}")
+
+    # Fallback to rule-based parser
+    try:
+        parser = RuleBasedParser()
+        algorithm = parser.parse(text)
+
+        return ExtractionResult(
+            algorithm=algorithm,
+            success=True,
+            method="rule_based",
+            errors=errors + ["Fell back to rule-based parser"],
+            line_references=[step.line_refs for step in algorithm.steps]
+        )
+
+    except Exception as e:
+        errors.append(f"Rule-based fallback failed: {str(e)}")
+
+    # Return empty algorithm
+    return ExtractionResult(
+        algorithm=Algorithm(name="unnamed", source_text=text),
+        success=False,
+        method="failed",
+        errors=errors,
+        line_references=[]
+    )
+
+
+def _call_llm(system: str, user: str, timeout: int) -> Optional[str]:
+    """
+    Call LLM for extraction. Uses agent's native capabilities.
+
+    In actual implementation, this would call the AI assistant.
+    For now, returns None to trigger fallback.
+    """
+    # Placeholder - actual implementation would use agent
+    return None
+
+
+def _parse_llm_response(response: str, original_text: str) -> Optional[Algorithm]:
+    """
+    Parse LLM JSON response into Algorithm object.
+
+    Args:
+        response: JSON string from LLM
+        original_text: Original algorithm text
+
+    Returns:
+        Algorithm object or None if parsing fails
+    """
+    try:
+        # Extract JSON from response (in case of markdown code blocks)
+        json_match = re.search(r'```(?:json)?\s*\n?(.*?)```', response, re.DOTALL)
+        if json_match:
+            json_str = json_match.group(1)
+        else:
+            json_str = response
+
+        # Clean up
+        json_str = json_str.strip()
+
+        # Parse JSON
+        data = json.loads(json_str)
+
+        # Build Algorithm
+        algorithm = Algorithm(
+            name=data.get("name", "unnamed"),
+            description=data.get("description", ""),
+            source_text=original_text
+        )
+
+        # Parse inputs
+        algorithm.inputs = data.get("inputs", [])
+
+        # Parse outputs
+        algorithm.outputs = data.get("outputs", [])
+
+        # Parse steps
+        steps = []
+        for step_data in data.get("steps", []):
+            step_type_str = step_data.get("type", "comment")
+            try:
+                step_type = StepType(step_type_str)
+            except ValueError:
+                step_type = StepType.COMMENT
+
+            step = Step(
+                id=step_data.get("id", len(steps) + 1),
+                type=step_type,
+                description=step_data.get("description", ""),
+                inputs=step_data.get("inputs", []),
+                outputs=step_data.get("outputs", []),
+                line_refs=step_data.get("line_refs", []),
+                condition=step_data.get("condition"),
+                body=step_data.get("body", []),
+                else_body=step_data.get("else_body", []),
+                iter_var=step_data.get("iter_var"),
+                iter_range=step_data.get("iter_range"),
+                expression=step_data.get("expression"),
+                call_target=step_data.get("call_target"),
+                arguments=step_data.get("arguments", []),
+                annotation=step_data.get("annotation")
+            )
+            steps.append(step)
+
+        algorithm.steps = steps
+
+        return algorithm
+
+    except Exception:
+        return None
+
+
+class HybridExtractor:
+    """
+    Hybrid extractor combining rule-based and LLM extraction.
+
+    Per D-01, D-02 from 02-CONTEXT.md.
+    """
+
+    def __init__(self):
+        self.rule_parser = RuleBasedParser()
+        self.use_llm = True
+
+    def extract(self, text: str, prefer_llm: bool = True) -> ExtractionResult:
+        """
+        Extract algorithm using preferred method.
+
+        Args:
+            text: Algorithm description
+            prefer_llm: If True, try LLM first; else use rule-based
+
+        Returns:
+            ExtractionResult with extracted algorithm
+        """
+        if prefer_llm and self.use_llm:
+            return extract_algorithm_llm(text)
+        else:
+            try:
+                algorithm = self.rule_parser.parse(text)
+                return ExtractionResult(
+                    algorithm=algorithm,
+                    success=True,
+                    method="rule_based",
+                    errors=[],
+                    line_references=[step.line_refs for step in algorithm.steps]
+                )
+            except Exception as e:
+                return ExtractionResult(
+                    algorithm=Algorithm(name="unnamed", source_text=text),
+                    success=False,
+                    method="failed",
+                    errors=[str(e)],
+                    line_references=[]
+                )