error-translator-cli-v2 2.0.0__tar.gz → 3.0.2__tar.gz

{error_translator_cli_v2-2.0.0 → error_translator_cli_v2-3.0.2}/PKG-INFO

@@ -1,30 +1,9 @@
 Metadata-Version: 2.4
 Name: error-translator-cli-v2
-Version: 2.0.0
+Version: 3.0.2
 Summary: Offline Python traceback translator and error explainer CLI that converts exceptions into clear explanations and actionable fixes.
 Author-email: Gourabananda Datta <gourabanandadatta@zohomail.in>
-License: MIT License
-        
-        Copyright (c) 2026 Gourabananda Datta
-        
-        Permission is hereby granted, free of charge, to any person obtaining a copy
-        of this software and associated documentation files (the "Software"), to deal
-        in the Software without restriction, including without limitation the rights
-        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-        copies of the Software, and to permit persons to whom the Software is
-        furnished to do so, subject to the following conditions:
-        
-        The above copyright notice and this permission notice shall be included in all
-        copies or substantial portions of the Software.
-        
-        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-        SOFTWARE.
-        
+License: MIT
 Project-URL: Homepage, https://github.com/gourabanandad/error-translator-cli-v2
 Project-URL: Source, https://github.com/gourabanandad/error-translator-cli-v2
 Project-URL: Documentation, https://gourabanandad.github.io/error-translator-cli-v2/

{error_translator_cli_v2-2.0.0 → error_translator_cli_v2-3.0.2}/pyproject.toml

@@ -4,11 +4,11 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "error-translator-cli-v2"
-version = "2.0.0"
+version = "3.0.2"
 description = "Offline Python traceback translator and error explainer CLI that converts exceptions into clear explanations and actionable fixes."
 readme = "README.md"
 requires-python = ">=3.9"
-license = { file = "LICENSE" }
+license = { text = "MIT" }
 authors = [
     { name = "Gourabananda Datta", email = "gourabanandadatta@zohomail.in" }
 ]
@@ -62,12 +62,13 @@ server = ["fastapi>=0.110", "pydantic>=2.6", "uvicorn>=0.29"]
 docs = ["mkdocs>=1.6", "mkdocs-material>=9.7", "pymdown-extensions>=10.0"]
 dev = ["pytest>=8.0", "build>=1.2", "twine>=5.0"]
 
-[tool.setuptools]
-package-dir = {"" = "src"}
-packages = ["error_translator"]
+[tool.setuptools.packages.find]
+where = ["src"]
 
 [tool.pytest.ini_options]
+testpaths = ["tests"]
 pythonpath = ["src"]
+addopts = "--cov=error_translator --cov-report=term-missing"
 
 [tool.setuptools.package-data]
 error_translator = ["rules.json", "static/*.html", "static/*.css"]

error_translator_cli_v2-3.0.2/setup.py

@@ -0,0 +1,16 @@
+from setuptools import setup, Extension
+import sys
+
+# Windows (MSVC) uses /O2, Linux/Mac (GCC/Clang) uses -O3
+compile_args = ['/O2'] if sys.platform == 'win32' else ['-O3']
+
+fast_matcher_module = Extension(
+    'error_translator.fast_matcher',
+    sources=['src/error_translator/ext/fast_matcher.c'],
+    extra_compile_args=compile_args
+)
+
+if __name__ == "__main__":
+    setup(
+        ext_modules=[fast_matcher_module]
+    )

error_translator_cli_v2-3.0.2/src/error_translator/__init__.py

@@ -0,0 +1,7 @@
+"""
+Error Translator
+Turn cryptic Python tracebacks into clear, actionable advice.
+"""
+from .core import translate_error
+
+__all__ = ["translate_error"]

error_translator_cli_v2-3.0.2/src/error_translator/api/server.py

@@ -0,0 +1,94 @@
+"""
+FastAPI Server for Error Translation.
+
+This module exposes the error translation functionality as a RESTful web API.
+It includes endpoints for single and batch translations, and serves a static 
+web interface. Useful for integrating the translator into web apps or distributed systems.
+"""
+from src.error_translator.core import translate_error
+from pydantic import BaseModel
+from fastapi import FastAPI
+from fastapi.staticfiles import StaticFiles
+from fastapi.responses import FileResponse
+import os
+from importlib.metadata import version, PackageNotFoundError
+import asyncio
+from typing import List
+
+# Try to determine the package version to expose in the API metadata.
+try:
+    VERSION = version("error-translator-cli-v2")
+except PackageNotFoundError:
+    VERSION = "unknown (not installed via pip)"
+
+# Initialize the FastAPI application with basic metadata
+app = FastAPI(
+    title="Error translator API",
+    description="An API that translates Python errors into human-readable English.",
+    version=VERSION
+)
+
+# --- Pydantic Models for Request Validation ---
+
+class ErrorRequest(BaseModel):
+    """Schema for a single error translation request."""
+    traceback_setting: str
+
+class BatchErrorRequest(BaseModel):
+    """Schema for translating multiple errors in a single request."""
+    tracebacks: List[str]
+
+# --- API Endpoints ---
+
+@app.post("/translate")
+def translation_endpoint(request: ErrorRequest):
+    """
+    Translates a single Python traceback.
+    Accepts a JSON payload with a `traceback_setting` field and returns the translation.
+    """
+    translation_result = translate_error(request.traceback_setting)
+    return translation_result
+
+
+@app.post("/translate/batch")
+async def batch_translation_endoint(request: BatchErrorRequest):
+    """
+    Translates an array of tracebacks concurrently using asyncio. 
+    Ideal for processing bulk logs from message queues or distributed systems.
+    """
+    # Create an async task for each traceback to run them in parallel
+    tasks = [
+        asyncio.to_thread(translate_error, tb) for tb in request.tracebacks
+    ]
+
+    # Gather results from all tasks
+    results = await asyncio.gather(*tasks)
+    return {"translate_errors": results}
+
+
+@app.get("/")
+def read_root():
+    """
+    Serves the web UI index.html file at the root URL.
+    Provides a simple browser-based interface for the translator.
+    """
+    index_path = os.path.join(os.path.dirname(__file__), "static", "index.html")
+    if os.path.exists(index_path):
+        return FileResponse(index_path)
+    return {
+        "message": "Error translation API is running. Web UI not found. Please ensure static/index.html exists."
+    }
+
+
+@app.get("/health")
+def health_check():
+    """
+    Health check endpoint useful for monitoring systems (e.g., Kubernetes, Docker).
+    """
+    return {"status": "ok"}
+
+
+# Mount static files directory (CSS, JS, images, etc.) so they can be loaded by the web UI
+static_path = os.path.join(os.path.dirname(__file__), "static")
+if os.path.exists(static_path):
+    app.mount("/static", StaticFiles(directory=static_path), name="static")

error_translator_cli_v2-3.0.2/src/error_translator/ast/ast_engine.py

@@ -0,0 +1,132 @@
+import ast
+import difflib
+import os
+
+class ScopedSymbolCollector(ast.NodeVisitor):
+    """
+    Walks the Abstract Syntax Tree (AST) of the target Python file.
+    It collects variables, functions, classes, and attributes defined in the code.
+    
+    Crucially, it respects lexical scope by using the crash line number.
+    It will only descend into function or class bodies if the crash actually 
+    happened inside them, preventing it from suggesting variables from unrelated scopes.
+    """
+    def __init__(self, target_line: int):
+        self.target_line = target_line
+        self.names = set()        # Variables (e.g., local/global variable assignments)
+        self.attributes = set()   # Object attributes/methods (e.g., obj.method_name)
+        self.classes = set()      # Class names defined in the scope
+        self.functions = set()    # Function names defined in the scope
+        self.imports = set()      # Imported modules or aliases
+
+    def visit_Name(self, node):
+        """Collects variable names when they are assigned (Store context)."""
+        if isinstance(node.ctx, ast.Store):
+            self.names.add(node.id)
+        self.generic_visit(node)
+
+    def visit_FunctionDef(self, node):
+        """
+        Collects the function name into the current scope.
+        Only visits the function's internal body if the error line is within it.
+        """
+        # The function's name is always added to the enclosing scope
+        self.names.add(node.name)
+        self.functions.add(node.name)
+        
+        # SCOPING LOGIC: Only visit the body if the crash happened INSIDE this function
+        if hasattr(node, 'lineno') and hasattr(node, 'end_lineno'):
+            if node.lineno <= self.target_line <= node.end_lineno:
+                self.generic_visit(node)
+        else:
+            self.generic_visit(node)
+
+    def visit_ClassDef(self, node):
+        """
+        Collects the class name into the current scope.
+        Only visits the class's internal body if the error line is within it.
+        """
+        # The class name is always added to the enclosing scope
+        self.names.add(node.name)
+        self.classes.add(node.name)
+        
+        # SCOPING LOGIC: Only visit the body if the crash happened INSIDE this class
+        if hasattr(node, 'lineno') and hasattr(node, 'end_lineno'):
+            if node.lineno <= self.target_line <= node.end_lineno:
+                self.generic_visit(node)
+        else:
+            self.generic_visit(node)
+
+    def visit_Attribute(self, node):
+        """Collects attribute accesses (e.g., node.attr)."""
+        self.attributes.add(node.attr)
+        self.generic_visit(node)
+
+    def visit_Import(self, node):
+        """Collects basic import names or aliases."""
+        for alias in node.names:
+            name = alias.asname if alias.asname else alias.name
+            self.imports.add(name)
+            self.names.add(name)
+        self.generic_visit(node)
+
+    def visit_ImportFrom(self, node):
+        """Collects specific names imported from a module."""
+        for alias in node.names:
+            name = alias.asname if alias.asname else alias.name
+            self.imports.add(name)
+            self.names.add(name)
+        self.generic_visit(node)
+
+
+def get_ast_suggestions(filepath: str, line_number: str, target_word: str, error_type: str) -> str:
+    """
+    Parses a Python file into an AST, extracts available symbols for the crashing scope,
+    and uses string matching (difflib) to find the closest suggestion to a misspelled word.
+    
+    Args:
+        filepath: Absolute path to the Python file that crashed.
+        line_number: The line number where the error was thrown.
+        target_word: The misspelled variable, attribute, or import.
+        error_type: The type of error (NameError, AttributeError, etc.) to determine the pool of words.
+        
+    Returns:
+        str: The suggested correct spelling, or None if no close match is found.
+    """
+    if not os.path.exists(filepath) or filepath == "Unknown File":
+        return None
+
+    try:
+        target_line = int(line_number) if line_number.isdigit() else 0
+        
+        # Read the crashing source file
+        with open(filepath, 'r', encoding='utf-8') as f:
+            source_code = f.read()
+        
+        # Parse it into an Abstract Syntax Tree
+        tree = ast.parse(source_code)
+        
+        # Walk the tree and collect symbols visible at the target line
+        collector = ScopedSymbolCollector(target_line)
+        collector.visit(tree)
+        
+        # Determine the search pool based on the type of error
+        pool = set()
+        if error_type == "NameError":
+            pool = collector.names | collector.functions | collector.classes
+        elif error_type == "AttributeError":
+            pool = collector.attributes | collector.functions 
+        elif error_type in ("ImportError", "ModuleNotFoundError"):
+            pool = collector.classes | collector.functions | collector.names | collector.imports
+        
+        # Use difflib to find the most similar symbol in the pool
+        # Cutoff=0.6 means the suggestion must be at least 60% similar to the target word
+        matches = difflib.get_close_matches(target_word, pool, n=1, cutoff=0.6)
+        
+        if matches:
+            return matches[0]
+        return None
+        
+    except Exception:
+        # If parsing or processing fails (e.g., SyntaxError in the file), fail gracefully
+        return None

error_translator_cli_v2-3.0.2/src/error_translator/ast/ast_handlers.py

@@ -0,0 +1,63 @@
+"""
+AST Handlers for error translation.
+
+This module contains strategy functions (handlers) that provide deeper insights into 
+specific error types (like NameError, AttributeError, ImportError). It uses Abstract 
+Syntax Tree (AST) analysis to look at the exact code context and suggest valid 
+alternative variable names, attributes, or imports based on what is actually available 
+in the scope.
+"""
+from .ast_engine import get_ast_suggestions
+
+# --- 1. THE INDIVIDUAL STRATEGIES (PLUGINS) ---
+# Each handler is responsible for analyzing the AST for a specific type of error
+# and returning actionable insights to the user.
+
+def handle_name_error(file_path: str, line_number: str, extracted_values: list) -> str:
+    """
+    Handles NameError: name 'X' is not defined.
+    Uses AST analysis to look for typos in variable names within the scope.
+    """
+    bad_name = extracted_values[0] if extracted_values else ""
+
+    suggestion = get_ast_suggestions(file_path, line_number, bad_name, "NameError")
+
+    if suggestion:
+        return f"Did you mean '{suggestion}'? There appears to be a typo."
+    return f"The variable '{bad_name}' was not found in the file's scope. Ensure it is defined before this line."    
+
+def handle_attribute_error(file_path: str, line_number: str, extracted_values: list) -> str:
+    """
+    Handles AttributeError: 'X' object has no attribute 'Y'.
+    Uses AST analysis to suggest similarly-named attributes or methods on the object.
+    """
+    # Assuming the last extracted value is the missing attribute (e.g., 'apend')
+    bad_attr = extracted_values[-1] if extracted_values else ""
+    suggestion = get_ast_suggestions(file_path, line_number, bad_attr, "AttributeError")
+    
+    if suggestion:
+        return f"Did you mean the attribute or method '{suggestion}'?"
+    return f"The attribute or method '{bad_attr}' was not found in the file's scope. Ensure it is defined before this line."
+
+def handle_import_error(file_path: str, line_number: str, extracted_values: list) -> str:
+    """
+    Handles ImportError / ModuleNotFoundError.
+    Uses AST analysis to verify if the class/function being imported exists or suggests fixes.
+    """
+    bad_name = extracted_values[0] if extracted_values else ""
+
+    suggestion = get_ast_suggestions(file_path, line_number, bad_name, "ImportError")
+    if suggestion:
+        return f"Did you mean to import '{suggestion}' instead?"
+    return f"Verify that the class/function exists in the target module and is spelled correctly."
+    
+# --- 2. THE REGISTRY (THE MAGIC ROUTER) ---
+# We map the string name of the error to the function that handles it.
+# The core engine uses this registry to dynamically dispatch AST insights based on the error type.
+AST_REGISTRY = {
+    "NameError": handle_name_error,
+    "AttributeError": handle_attribute_error,
+    "ImportError": handle_import_error,
+    # Additional error handlers can be registered here as new strategies are developed.
+    # "SyntaxError": handle_syntax_error,
+}

error_translator_cli_v2-3.0.2/src/error_translator/auto.py

@@ -0,0 +1,37 @@
+"""
+Auto-translator hook module.
+
+When imported, this module automatically overrides the default Python exception handler 
+(sys.excepthook). Instead of a standard traceback, it intercepts any unhandled exception, 
+translates it, and prints a user-friendly explanation using the CLI output formatting.
+"""
+import sys
+import traceback
+from .core import translate_error
+from .ui import print_result
+
+def magic_hook(exc_type, exc_value, tb):
+    """
+    Custom exception hook that intercepts unhandled Python exceptions before
+    they are printed to the terminal. It formats the standard traceback,
+    translates the error into human-readable advice, and prints it using
+    the rich UI components.
+    
+    Args:
+        exc_type: The type of the exception (e.g., ValueError, NameError).
+        exc_value: The exception instance itself.
+        tb: The traceback object containing the call stack.
+    """
+    # 1. Convert the raw crash data into a standard traceback string
+    tb_lines = traceback.format_exception(exc_type, exc_value, tb)
+    tb_string = "".join(tb_lines)
+    
+    # 2. Pass the standard traceback through our translation engine
+    result = translate_error(tb_string)
+    
+    # 3. Print our beautiful colorized output instead of the default Python crash
+    print_result(result)
+
+# Replace Python's default sys.excepthook with our custom translation hook.
+# Any unhandled exception will now automatically be intercepted and translated.
+sys.excepthook = magic_hook

error_translator_cli_v2-3.0.2/src/error_translator/banner.py

@@ -0,0 +1,53 @@
+"""
+Installation banner module for Error Translator CLI.
+This module prints a stylish banner to the terminal during installation.
+"""
+
+def print_install_banner():
+    """Prints a stylish banner using ANSI escape codes for colors."""
+    RED = '\033[91m'
+    BLUE = '\033[94m'
+    CYAN = '\033[96m'
+    MAGENTA = '\033[95m'
+    YELLOW = '\033[93m'
+    WHITE = '\033[97m'
+    RESET = '\033[0m'
+    BOLD = '\033[1m'
+
+    error_art = r"""
+███████╗██████╗ ██████╗  ██████╗ ██████╗
+██╔════╝██╔══██╗██╔══██╗██╔═══██╗██╔══██╗
+█████╗  ██████╔╝██████╔╝██║   ██║██████╔╝
+██╔══╝  ██╔══██╗██╔══██╗██║   ██║██╔══██╗
+███████╗██║  ██║██║  ██║╚██████╔╝██║  ██║
+╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝ ╚═════╝ ╚═╝  ╚═╝
+"""
+
+    translator_art = r"""
+████████╗██████╗  █████╗ ███╗   ██╗███████╗██╗      █████╗ ████████╗ ██████╗ ██████╗
+╚══██╔══╝██╔══██╗██╔══██╗████╗  ██║██╔════╝██║     ██╔══██╗╚══██╔══╝██╔═══██╗██╔══██╗
+   ██║   ██████╔╝███████║██╔██╗ ██║███████╗██║     ███████║   ██║   ██║   ██║██████╔╝
+   ██║   ██╔══██╗██╔══██║██║╚██╗██║╚════██║██║     ██╔══██║   ██║   ██║   ██║██╔══██╗
+   ██║   ██║  ██║██║  ██║██║ ╚████║███████║███████╗██║  ██║   ██║   ╚██████╔╝██║  ██║
+   ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═══╝╚══════╝╚══════╝╚═╝  ╚═╝   ╚═╝    ╚═════╝ ╚═╝  ╚═╝
+"""
+
+    cli_v2_art = r"""
+ ██████╗██╗     ██╗    ██╗   ██╗██████╗
+██╔════╝██║     ██║    ██║   ██║╚════██╗
+██║     ██║     ██║    ██║   ██║ █████╔╝
+██║     ██║     ██║    ╚██╗ ██╔╝██╔═══╝
+╚██████╗███████╗██║     ╚████╔╝ ███████╗
+ ╚═════╝╚══════╝╚═╝      ╚═══╝  ╚══════╝
+"""
+    
+    print(f"\n{BOLD}{RED}{error_art.strip()}{RESET}")
+    print(f"{BOLD}{BLUE}{translator_art.strip()}{RESET}")
+    print(f"{BOLD}{CYAN}{cli_v2_art.strip()}{RESET}")
+    print(f"\n{BOLD}{MAGENTA}================================================================================{RESET}")
+    print(f"{BOLD}{YELLOW}⚡ Fatal to Fabulous ⚡{RESET}")
+    print(f"{BOLD}{WHITE} ⇆ Offline Python Traceback Explainer V2 ⇆ {RESET}")
+    print(f"{BOLD}{MAGENTA}================================================================================{RESET}\n")
+
+if __name__ == "__main__":
+    print_install_banner()

error_translator_cli_v2-3.0.2/src/error_translator/cli.py

@@ -0,0 +1,75 @@
+"""
+Command Line Interface (CLI) module for the Error Translator.
+
+This module provides the terminal entry point (`explain-error`). It parses arguments,
+handles standard input streams, and orchestrates the translation process.
+"""
+import argparse
+import sys
+from .core import translate_error
+from .ui import print_about, print_help, print_result, print_result_json, VERSION, console
+from .runner import run_script
+
+def main():
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(
+        prog="explain-error",
+        description="Error Translator — Turn cryptic Python tracebacks into clear, actionable advice.",
+        epilog="""
+Examples:
+  explain-error run my_script.py
+  explain-error "NameError: name 'usr_count' is not defined"
+  cat error.log | explain-error
+        """,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        add_help=False
+    )
+
+    parser.add_argument("-a", "--about", action="store_true", help="Display information about the tool.")
+    parser.add_argument("-v", "--version", action="store_true", help="Show the current version of the tool.")
+    parser.add_argument("--json", action="store_true", dest="as_json", help="Output the translated error as a JSON object.")
+    parser.add_argument("-h", "--help", action="store_true", help="Help user through documentation.")
+    parser.add_argument("args", nargs="*", help="Positional arguments.")
+
+    parsed_args = parser.parse_args()
+
+    # Handle meta-flags
+    if parsed_args.about:
+        print_about()
+        sys.exit(0)
+    
+    if parsed_args.version:
+        console.print(f"Error Translator CLI Version: [bold green]{VERSION}[/]")
+        sys.exit(0)
+    
+    if parsed_args.help:
+        console.print(f"Error Translator CLI Version: [bold green]{VERSION}[/]")
+        print_help()
+        sys.exit(0)
+
+    # Choose output strategy
+    emit = print_result_json if parsed_args.as_json else print_result
+
+    # Handle piped input (e.g. `cat error.log | explain-error`)
+    if not sys.stdin.isatty():
+        error_input = sys.stdin.read()
+        if error_input.strip():
+            emit(translate_error(error_input))
+            return
+
+    # Provide help if no arguments are passed
+    if not parsed_args.args:
+        print_help()
+        sys.exit(1)
+
+    # Detect the "run <script.py>" sub-command
+    if parsed_args.args[0] == "run" and len(parsed_args.args) > 1:
+        script_name = parsed_args.args[1]
+        run_script(script_name, as_json=parsed_args.as_json)
+    else:
+        # Otherwise, treat the entire string of arguments as a raw traceback text
+        error_input = " ".join(parsed_args.args)
+        emit(translate_error(error_input))
+
+if __name__ == "__main__":
+    main()

error_translator_cli_v2-3.0.2/src/error_translator/core.py

@@ -0,0 +1,109 @@
+"""
+Core translation engine for the Error Translator CLI.
+
+This module is responsible for:
+1. Orchestrating error translation.
+2. Using a fast C extension for matching if available, with a Python fallback.
+3. Delegating to AST handlers for deep, code-specific insights.
+"""
+from .ast.ast_handlers import AST_REGISTRY
+from .rules import load_rules, compiled_rules
+from .parser import extract_location, extract_code_context
+
+# Attempt to load the ultra-fast C extension for matching rules,
+# and fallback to the Python implementation if it's unavailable.
+try:
+    from .fast_matcher import match_loop  # type: ignore
+    C_EXTENSION_AVAILABLE = True
+except ImportError:
+    C_EXTENSION_AVAILABLE = False
+
+
+def translate_error(traceback_text: str) -> dict:
+    """
+    Translate a raw traceback string into a detailed explanation dictionary.
+    
+    Args:
+        traceback_text (str): The raw traceback string.
+        
+    Returns:
+        dict: A dictionary containing the explanation, suggested fix,
+              AST-based insight (if any), file, line number, code context, 
+              and the matched error line.
+    """
+    # Load configuration rules and pre-compiled regex patterns
+    data = load_rules()
+    rules = compiled_rules()
+    default_error = data["default"]
+
+    # Extract non-empty lines from the traceback
+    lines = [line.strip() for line in traceback_text.strip().split("\n") if line.strip()]
+    if not lines:
+        return {"explanation": "No error text provided.", "fix": "Provide a valid Python error."}
+
+    # The actual error message is typically the last line in a traceback
+    actual_error_line = lines[-1]
+
+    # Extract the origin of the error (file name and line number)
+    file_name, line_number = extract_location(traceback_text)
+
+    # Attempt to read the exact line of code that caused the error
+    code_context = extract_code_context(file_name, line_number)
+
+    # ==========================================
+    # FAST MATCHING ENGINE (C Extension + Python Fallback)
+    # ==========================================
+    match = None
+    rule = None
+
+    if C_EXTENSION_AVAILABLE:
+        # Execute the C extension for maximum performance
+        result = match_loop(actual_error_line, rules)
+        if result:
+            match, rule = result
+    else:
+        # Fallback to standard Python regex loop
+        for pattern, r in rules:
+            m = pattern.search(actual_error_line)
+            if m:
+                match, rule = m, r
+                break
+
+    # If we found a matching rule, format the explanation and fix
+    if match and rule:
+        # Extract variables from the regex groups (e.g., variable names, functions)
+        extracted_values = list(match.groups())
+        
+        # Inject the extracted values into the template fix string
+        fix_text = rule["fix"].format(*extracted_values)
+
+        # Parse the error type (e.g., "NameError", "TypeError") to dispatch AST insights
+        error_type = actual_error_line.split(":")[0].strip()
+        
+        # Check if there's a specialized AST handler for this specific error type
+        handler_function = AST_REGISTRY.get(error_type)
+        insight = None
+        
+        # If an AST handler exists and the file is accessible, run deep code analysis
+        if handler_function and file_name != "Unknown File":
+            insight = handler_function(file_name, line_number, extracted_values)
+        
+        return {
+            "explanation": rule["explanation"].format(*extracted_values),
+            "fix": fix_text,
+            "ast_insight": insight,
+            "matched_error": actual_error_line,
+            "file": file_name,
+            "line": line_number,
+            "code": code_context,
+        }
+
+    # Fallback when the error doesn't match any known rules
+    return {
+        "explanation": default_error["explanation"],
+        "fix": default_error["fix"],
+        "matched_error": actual_error_line,
+        "file": file_name,
+        "line": line_number,
+        "code": code_context,
+    }