nl2sql-engine 0.1.0__py3-none-any.whl

nl2sql/cli/reporting.py

@@ -0,0 +1,878 @@
+import csv
+import json
+import statistics
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Union
+
+from rich.columns import Columns
+from rich.console import Console, Group
+from rich.markdown import Markdown
+from rich.markup import escape
+from rich.panel import Panel
+from rich.table import Table
+from rich.tree import Tree
+from rich.live import Live
+from rich.spinner import Spinner
+from rich.style import Style
+from rich.text import Text
+
+
+class ConsolePresenter:
+    """
+    Console presentation utilities for the CLI.
+    """
+
+    def __init__(self, console: Optional[Console] = None):
+        self.console = console or Console()
+        self._status = None
+
+    # ------------------------------------------------------------------
+    # Status helpers
+    # ------------------------------------------------------------------
+    def status_context(self, message: str, spinner: str = "dots"):
+        return self.console.status(message, spinner=spinner)
+
+    def start_interactive_status(self, message: str, spinner: str = "dots") -> None:
+        if self._status:
+            self._status.stop()
+        self._status = self.console.status(message, spinner=spinner)
+        self._status.start()
+
+    def update_interactive_status(self, message: str) -> None:
+        if self._status:
+            self._status.update(message)
+        else:
+            self.start_interactive_status(message)
+
+    def stop_interactive_status(self) -> None:
+        if self._status:
+            self._status.stop()
+            self._status = None
+
+    def start_task_line(self, message: str, spinner: str = "dots") -> Live:
+        live = Live(Spinner(spinner, text=message), console=self.console, refresh_per_second=8, transient=False)
+        live.start()
+        return live
+
+    def finish_task_line(self, live: Live, message: str, success: bool = True) -> None:
+        label = "✓" if success else "✗"
+        style = "green" if success else "red"
+        live.update(Text(f"{label} {message}", style=style))
+        live.stop()
+
+    # ------------------------------------------------------------------
+    # Generic helpers
+    # ------------------------------------------------------------------
+    def _print_labeled(self, label: str, style: str, message: str) -> None:
+        self.console.print(f"[{style}]{escape(label)}[/{style}] {escape(str(message))}")
+
+    def print_success(self, message: str) -> None:
+        self._print_labeled("✓", "green", message)
+
+    def print_error(self, message: str) -> None:
+        self._print_labeled("[ERROR]", "red", message)
+
+    def print_warning(self, message: str) -> None:
+        self._print_labeled("[WARN]", "yellow", message)
+
+    def print_info(self, message: str) -> None:
+        self._print_labeled("[INFO]", "blue", message)
+
+    def print_header(self, message: str) -> None:
+        self.console.print(f"\n[bold magenta]--- {escape(str(message))} ---[/bold magenta]")
+
+    def print_panel(self, content: Any, title: str, style: str = "green") -> None:
+        if isinstance(content, (dict, list)):
+            content = json.dumps(content, indent=2, default=str)
+        if isinstance(content, str):
+            content = Text(content)
+        self.console.print(Panel(content, title=escape(str(title)), border_style=style))
+
+    def print_table(
+        self,
+        data: Union[Sequence[Dict[str, Any]], Sequence[Sequence[Any]]],
+        title: str = "",
+        columns: Optional[Sequence[str]] = None,
+    ) -> None:
+        if not data:
+            self.console.print("[dim]No data to display.[/dim]")
+            return
+
+        table = Table(title=title, show_header=True, header_style="bold cyan", expand=True)
+
+        first = data[0]
+        if isinstance(first, dict):
+            keys = list(columns) if columns else list(first.keys())
+            for key in keys:
+                table.add_column(str(key))
+            for row in data:
+                table.add_row(*[Text(str(row.get(k, ""))) for k in keys])
+        else:
+            if columns:
+                for col in columns:
+                    table.add_column(str(col))
+            else:
+                for idx in range(len(first)):
+                    table.add_column(f"Col {idx + 1}")
+            for row in data:
+                table.add_row(*[Text(str(val)) for val in row])
+
+        self.console.print(table)
+
+    def print_tree(self, tree: Tree, title: Optional[str] = None, style: str = "cyan") -> None:
+        if title:
+            self.console.print(Panel(tree, title=escape(str(title)), border_style=style))
+        else:
+            self.console.print(tree)
+
+    # ------------------------------------------------------------------
+    # Pipeline execution (run.py)
+    # ------------------------------------------------------------------
+    def print_pipeline_errors(self, errors: List[Any]) -> None:
+        if not errors:
+            return
+
+        table = Table(title="Pipeline Errors", show_header=True, header_style="bold red", expand=True)
+        table.add_column("Node", style="cyan")
+        table.add_column("Severity", justify="center")
+        table.add_column("Code", justify="center")
+        table.add_column("Message", style="white")
+
+        for e in errors:
+            if isinstance(e, dict):
+                severity = e.get("severity", "ERROR")
+                node = e.get("node", "unknown")
+                code = e.get("error_code", "-")
+                msg = e.get("message", "-")
+            else:
+                severity = e.severity.name if hasattr(e.severity, "name") else str(e.severity)
+                node = e.node
+                code = e.error_code
+                msg = e.message
+
+            sev_style = "red"
+            if "WARNING" in severity:
+                sev_style = "yellow"
+            if "CRITICAL" in severity:
+                sev_style = "bold red"
+
+            table.add_row(
+                Text(str(node).upper()),
+                f"[{sev_style}]{escape(str(severity))}[/{sev_style}]",
+                Text(str(code)),
+                Text(str(msg)),
+            )
+
+        self.console.print("\n")
+        self.console.print(table)
+        self.console.print("\n")
+
+    def print_query(self, query: str) -> None:
+        self.console.print(f"[bold blue]Query:[/bold blue] {escape(str(query))}")
+
+    def print_node_output(self, node_name: str, output: Any) -> None:
+        title = f"{node_name.capitalize()} Output"
+        self.print_panel(output, title=title, style="green")
+
+    def print_sql(self, sql: Any, title: str = "SQL Generated") -> None:
+        """Render SQL in a panel.
+
+        A plain string is shown verbatim: SQL is not markup, and T-SQL
+        bracket-quoted identifiers such as ``[dbo].[orders]`` would otherwise be
+        parsed as style tags and vanish from the output. Callers that want
+        styling pass a pre-built renderable (e.g. ``Text``).
+        """
+        body = Text(sql) if isinstance(sql, str) else sql
+        self.console.print(Panel(body, title=escape(str(title)), border_style="cyan", expand=False))
+
+    def print_final_answer(self, answer: str) -> None:
+        self.console.print(Panel(Markdown(answer), title="[bold green]Final Answer[/bold green]", expand=False))
+
+    def print_answer_synthesizer_output(self, answer: Dict[str, Any]) -> None:
+        summary = answer.get("summary")
+        format_type = answer.get("format_type")
+        content = answer.get("content")
+        warnings = answer.get("warnings") or []
+
+        if summary:
+            self.print_panel(Markdown(summary), title="Answer Summary", style="green")
+
+        if content:
+            title = "Answer Content"
+            if format_type:
+                title = f"Answer Content ({format_type})"
+            self.print_panel(Markdown(content), title=title, style="cyan")
+
+        if warnings:
+            for warning in warnings:
+                self.print_warning(str(warning))
+
+    def print_rows_returned(self, count: int) -> None:
+        self.console.print(f"[dim]Rows returned: {count}[/dim]")
+
+    def print_execution_result(self, execution: Any) -> None:
+        if not execution:
+            return
+
+        if isinstance(execution, list):
+            rows = execution
+            columns = list(rows[0].keys()) if rows and isinstance(rows[0], dict) else []
+        else:
+            rows = execution.get("rows", []) if isinstance(execution, dict) else getattr(execution, "rows", [])
+            columns = execution.get("columns", []) if isinstance(execution, dict) else getattr(execution, "columns", [])
+
+        if not rows:
+            self.console.print("[dim]No rows returned.[/dim]")
+            return
+
+        table = Table(title="Result Data", show_header=True, header_style="bold cyan", border_style="blue")
+        for col in columns:
+            table.add_column(Text(str(col)))
+
+        for row in rows:
+            row_vals = []
+            for col in columns:
+                val = row.get(col, "") if isinstance(row, dict) else getattr(row, col, "")
+                row_vals.append(str(val))
+            table.add_row(*[Text(v) for v in row_vals])
+
+        self.console.print("\n")
+        self.console.print(table)
+        self.console.print("\n")
+
+    def print_datasource_used(self, ds_id: str) -> None:
+        self.console.print(f"[bold blue]Datasource Used:[/bold blue] {escape(str(ds_id))}")
+
+    def print_performance_report(self, latency: Dict[str, Any], token_log: List[Dict[str, Any]]) -> None:
+        renderables = []
+
+        top_table = Table(title="Top Level Performance", show_header=True, header_style="bold magenta", expand=True)
+        top_table.add_column("Metric", style="dim")
+        top_table.add_column("Decomposer", justify="right")
+        top_table.add_column("Aggregator", justify="right")
+
+        datasources = set()
+        for key in latency.keys():
+            if ":" in key:
+                datasources.add(key.split(":")[0])
+        sorted_ds = sorted(list(datasources))
+
+        for ds in sorted_ds:
+            top_table.add_column(f"Exec ({ds})", justify="right")
+        top_table.add_column("Total", justify="right", style="bold")
+
+        lat_decomp = latency.get("decomposer", 0.0)
+        lat_agg = latency.get("aggregator", 0.0)
+
+        lat_row = ["Latency (s)", f"{lat_decomp:.4f}", f"{lat_agg:.4f}"]
+
+        max_branch_latency = 0.0
+        for ds in sorted_ds:
+            val = latency.get(f"{ds}:total", 0.0)
+            lat_row.append(f"{val:.4f}")
+            if val > max_branch_latency:
+                max_branch_latency = val
+
+        total_latency = lat_decomp + lat_agg + max_branch_latency
+        lat_row.append(f"{total_latency:.4f}")
+        top_table.add_row(*lat_row)
+
+        def sum_tokens(agent_prefix=None, ds_id=None):
+            total = 0
+            for entry in token_log:
+                if agent_prefix and entry["agent"].startswith(agent_prefix):
+                    total += entry["total_tokens"]
+                elif ds_id and entry.get("datasource_id") == ds_id:
+                    if not (
+                        entry["agent"].startswith("decomposer")
+                        or entry["agent"].startswith("aggregator")
+                    ):
+                        total += entry["total_tokens"]
+            return total
+
+        tok_decomp = sum_tokens(agent_prefix="decomposer")
+        tok_agg = sum_tokens(agent_prefix="aggregator")
+
+        tok_row = ["Token Usage", str(tok_decomp), str(tok_agg)]
+        total_tokens = tok_decomp + tok_agg
+        for ds in sorted_ds:
+            val = sum_tokens(ds_id=ds)
+            tok_row.append(str(val))
+            total_tokens += val
+        tok_row.append(str(total_tokens))
+        top_table.add_row(*tok_row)
+
+        renderables.append(top_table)
+        renderables.append("\n")
+
+        ai_nodes = {"planner", "intent", "router", "summarizer", "generator", "decomposer", "aggregator"}
+
+        ds_metrics = {}
+        for key, val in latency.items():
+            if ":" in key:
+                parts = key.split(":", 1)
+                ds_id = parts[0]
+                node = parts[1]
+                if node == "total":
+                    continue
+                if ds_id not in ds_metrics:
+                    ds_metrics[ds_id] = {}
+                ds_metrics[ds_id][node] = val
+
+        ds_tables = []
+        for ds_id in sorted_ds:
+            ds_table = Table(title=f"Performance: {ds_id}", show_header=True, header_style="bold cyan", expand=True)
+            ds_table.add_column("Node", style="dim")
+            ds_table.add_column("Type", justify="center")
+            ds_table.add_column("Model", justify="center")
+            ds_table.add_column("Latency (s)", justify="right")
+            ds_table.add_column("Tokens", justify="right")
+
+            metrics = ds_metrics.get(ds_id, {})
+            node_order = ["intent", "planner", "generator", "executor"]
+            other_nodes = sorted([n for n in metrics.keys() if n not in node_order])
+            sorted_nodes = [n for n in node_order if n in metrics] + other_nodes
+
+            for node in sorted_nodes:
+                duration = metrics[node]
+                is_ai = node in ai_nodes
+                node_type = "AI" if is_ai else "Non-AI"
+
+                model_name = "-"
+                tokens = 0
+                if is_ai:
+                    for entry in token_log:
+                        if entry.get("datasource_id") == ds_id and entry["agent"] == node:
+                            model_name = entry["model"]
+                            tokens += entry["total_tokens"]
+
+                ds_table.add_row(
+                    node.capitalize(),
+                    node_type,
+                    model_name,
+                    f"{duration:.4f}",
+                    str(tokens) if is_ai else "-",
+                )
+            ds_tables.append(ds_table)
+
+        if ds_tables:
+            renderables.append(Columns(ds_tables))
+
+        if renderables:
+            self.print_panel(Group(*renderables), title="Performance & Metrics", style="magenta")
+
+    def print_execution_tree(
+        self,
+        user_query: str,
+        query_history: List[Dict[str, Any]],
+        top_level_reasoning: Optional[List[Dict[str, Any]]] = None,
+    ) -> None:
+        if top_level_reasoning is None:
+            top_level_reasoning = []
+        tree = Tree(f"[bold blue]Root Query: {escape(str(user_query))}[/bold blue]")
+
+        node_styles = {
+            "decomposer": "bold magenta",
+            "router": "bold cyan",
+            "intent": "bold magenta",
+            "schema": "bold yellow",
+            "planner": "bold blue",
+            "validator": "bold red",
+            "summarizer": "bold orange1",
+            "generator": "bold green",
+            "executor": "bold white",
+            "aggregator": "bold magenta",
+        }
+
+        def add_reasoning_steps(parent_tree: Tree, reasoning_list: List[Dict[str, Any]]) -> None:
+            if not isinstance(reasoning_list, list):
+                return
+
+            for step in reasoning_list:
+                node = step.get("node", "unknown")
+                content = step.get("content")
+                msg_type = step.get("type", "info")
+
+                style = node_styles.get(node, "bold")
+
+                node_label = f"[{style}]{node.capitalize()}[/{style}]"
+                if msg_type == "error":
+                    node_label += " [bold red](Error)[/bold red]"
+
+                step_branch = parent_tree.add(node_label)
+
+                if isinstance(content, list):
+                    for line in content:
+                        step_branch.add(Text(str(line)))
+                else:
+                    step_branch.add(Text(str(content)))
+
+        if top_level_reasoning:
+            decomp_steps = [r for r in top_level_reasoning if r.get("node") == "decomposer"]
+            if decomp_steps:
+                add_reasoning_steps(tree, decomp_steps)
+
+        for i, item in enumerate(query_history):
+            sub_query = item.get("sub_query") or "Main Branch"
+            ds_id = item.get("datasource_id") or "Unknown"
+            reasoning = item.get("reasoning", [])
+
+            branch = tree.add(
+                f"[bold green]Branch {i+1}:[/bold green] {escape(str(sub_query))} "
+                f"[dim]({escape(str(ds_id))})[/dim]"
+            )
+
+            add_reasoning_steps(branch, reasoning)
+
+            sql = item.get("sql_draft")
+            if not sql:
+                sql = item.get("sql")
+
+            if sql:
+                branch.add(f"[bold]SQL:[/bold] {escape(str(sql))}")
+
+        if top_level_reasoning:
+            agg_steps = [r for r in top_level_reasoning if r.get("node") == "aggregator"]
+            if agg_steps:
+                add_reasoning_steps(tree, agg_steps)
+
+        self.console.print("\n")
+        self.console.print(tree)
+
+    def print_status_tree(
+        self,
+        tree_data: Dict[str, List[str]],
+        durations: Dict[str, float],
+        node_order: Optional[List[str]] = None,
+    ) -> None:
+        if not tree_data:
+            return
+
+        root_tree = Tree("Graph")
+
+        def build_branch(parent_name: str, tree_node: Tree):
+            children = tree_data.get(parent_name, [])
+            for child in children:
+                duration = durations.get(child, 0.0)
+                label = f"{child} [dim]({duration:.2f}s)[/dim]"
+                branch = tree_node.add(label)
+                build_branch(child, branch)
+
+        all_children = set()
+        for kids in tree_data.values():
+            all_children.update(kids)
+
+        all_nodes = set(durations.keys())
+        roots = list(all_nodes - all_children)
+
+        if node_order:
+            roots.sort(key=lambda x: node_order.index(x) if x in node_order else 9999)
+        else:
+            roots.sort()
+
+        for r in roots:
+            duration = durations.get(r, 0.0)
+            label = f"{r} [dim]({duration:.2f}s)[/dim]"
+            branch = root_tree.add(label)
+            build_branch(r, branch)
+
+        self.console.print("\n")
+        self.console.print(root_tree)
+
+    def print_performance_tree(
+        self,
+        tree_data: Dict[str, List[str]],
+        metrics_data: Dict[str, Any],
+        node_map: Optional[Dict[str, str]] = None,
+    ) -> None:
+        if not tree_data:
+            return
+        if node_map is None:
+            node_map = {}
+
+        root_tree = Tree("[bold magenta]Performance Execution Tree[/bold magenta]")
+
+        def get_dur_style(dur):
+            if dur > 5.0:
+                return "bold red"
+            if dur > 2.0:
+                return "yellow"
+            return "green"
+
+        def build_branch(parent_id: str, tree_node: Tree, path: set):
+            for child_id in tree_data.get(parent_id, []):
+                if child_id in path:
+                    name = node_map.get(child_id, child_id)
+                    tree_node.add(f"[dim]{name} (recursive)[/dim]")
+                    continue
+
+                meta = metrics_data.get(child_id)
+                name = node_map.get(child_id, child_id)
+
+                label = f"[bold]{name}[/bold]"
+
+                if meta:
+                    dur = meta.duration
+                    dur_style = get_dur_style(dur)
+                    label += f" [dim]in[/dim] [{dur_style}]{dur:.2f}s[/{dur_style}]"
+
+                    if meta.total_tokens > 0:
+                        label += f" | [cyan]{meta.total_tokens} tok[/cyan]"
+
+                    if meta.error:
+                        label += f" [bold red]FAILED: {escape(str(meta.error))}[/bold red]"
+
+                branch = tree_node.add(label)
+
+                new_path = set(path)
+                new_path.add(child_id)
+                build_branch(child_id, branch, new_path)
+
+        all_children = set()
+        for parent, kids in tree_data.items():
+            for k in kids:
+                if k != parent:
+                    all_children.add(k)
+
+        all_nodes = set(tree_data.keys())
+        roots = [n for n in all_nodes if n not in all_children]
+
+        roots.sort(
+            key=lambda r: metrics_data[r].duration if r in metrics_data else 0,
+            reverse=True,
+        )
+
+        for r_id in roots:
+            meta = metrics_data.get(r_id)
+            name = node_map.get(r_id, r_id)
+
+            label = f"[bold]{name}[/bold]"
+            if meta:
+                dur = meta.duration
+                dur_style = get_dur_style(dur)
+                label += f" [dim]in[/dim] [{dur_style}]{dur:.2f}s[/{dur_style}]"
+                if meta.total_tokens > 0:
+                    label += f" | [cyan]{meta.total_tokens} tok[/cyan]"
+
+            branch = root_tree.add(label)
+            build_branch(r_id, branch, {r_id})
+
+        self.console.print("\n")
+        self.console.print(Panel(root_tree, title="Trace Metrics", border_style="magenta"))
+        self.console.print("\n")
+
+    def print_cost_summary(self, total_duration: float, token_log: List[Dict[str, Any]]) -> None:
+        total_tokens = sum(entry["total_tokens"] for entry in token_log)
+        self.console.print(f"[dim]Total Duration: {total_duration:.2f}s | Total Tokens: {total_tokens}[/dim]")
+
+    # ------------------------------------------------------------------
+    # Benchmarking (benchmark.py)
+    # ------------------------------------------------------------------
+    def print_config_benchmark_results(self, results: List[Dict[str, Any]]) -> None:
+        table = Table(title="Benchmark Results", show_header=True, header_style="bold magenta")
+        table.add_column("Config", style="cyan")
+        table.add_column("Success Rate", justify="right")
+        table.add_column("Avg Latency", justify="right")
+        table.add_column("Avg Tokens", justify="right")
+
+        for res in results:
+            sr = res["success_rate"]
+            sr_style = "green" if sr == 100 else "yellow" if sr >= 50 else "red"
+
+            table.add_row(
+                res["config"],
+                f"[{sr_style}]{sr:.1f}%[/{sr_style}]",
+                f"{res['avg_latency']:.2f}s",
+                f"{res['avg_tokens']:.1f}",
+            )
+
+        self.console.print("\n")
+        self.console.print(table)
+
+    def print_dataset_benchmark_results(
+        self,
+        results: List[Dict[str, Any]],
+        iterations: int = 1,
+        routing_only: bool = False,
+    ) -> None:
+        if iterations > 1:
+            self._print_pass_k_table(results, iterations)
+        else:
+            self._print_standard_table(results, routing_only)
+
+    def _print_pass_k_table(self, results: List[Dict[str, Any]], iterations: int) -> None:
+        grouped = {}
+        for r in results:
+            qid = r["id"]
+            if qid not in grouped:
+                grouped[qid] = []
+            grouped[qid].append(r)
+
+        table = Table(
+            title=f"Evaluation Results (Pass@{iterations})",
+            show_header=True,
+            header_style="bold magenta",
+            expand=True,
+        )
+        table.add_column("ID", style="cyan", no_wrap=True)
+        table.add_column("Success Rate", justify="right")
+        table.add_column("Route Stab.", justify="right")
+        table.add_column("Exec Acc.", justify="right")
+        table.add_column("Sem Acc.", justify="right")
+        table.add_column("Avg Latency", justify="right")
+        table.add_column("Errors", justify="left", overflow="ellipsis")
+
+        for qid, runs in grouped.items():
+            n = len(runs)
+            success_count = sum(1 for r in runs if r["status"] == "PASS")
+            success_rate = (success_count / n) * 100
+
+            ds_counts = {}
+            for r in runs:
+                ds = r.get("actual_ds", "None")
+                ds_counts[ds] = ds_counts.get(ds, 0) + 1
+            most_common_ds = max(ds_counts, key=ds_counts.get)
+            stability_rate = (ds_counts[most_common_ds] / n) * 100
+
+            sql_match_count = sum(1 for r in runs if r.get("sql_match") is True)
+            exec_acc = (sql_match_count / n) * 100
+
+            sem_match_count = sum(1 for r in runs if r.get("semantic_sql_match") is True)
+            sem_acc = (sem_match_count / n) * 100
+
+            avg_latency = statistics.mean([r.get("routing_latency", 0) for r in runs])
+
+            errors_set = {r["error"] for r in runs if r.get("error")}
+            error_str = str(list(errors_set)[0]) if errors_set else "-"
+            if len(error_str) > 30:
+                error_str = error_str[:27] + "..."
+
+            sr_style = "green" if success_rate == 100 else "yellow" if success_rate >= 50 else "red"
+
+            table.add_row(
+                Text(str(qid)),
+                f"[{sr_style}]{success_rate:.0f}%[/{sr_style}]",
+                f"{stability_rate:.0f}%",
+                f"{exec_acc:.0f}%",
+                f"{sem_acc:.0f}%",
+                f"{avg_latency:.2f}s",
+                Text(error_str),
+            )
+
+        self.console.print(table)
+
+    def _print_standard_table(self, results: List[Dict[str, Any]], routing_only: bool) -> None:
+        table = Table(title="Evaluation Results", show_header=True, header_style="bold magenta", expand=True)
+        table.add_column("ID", style="cyan", no_wrap=True)
+        table.add_column("Status", justify="center")
+        table.add_column("Route", justify="center")
+        table.add_column("Layer", justify="center")
+
+        if not routing_only:
+            table.add_column("SQL Match", justify="center")
+            table.add_column("Sem Match", justify="center")
+            table.add_column("Rows", justify="right")
+        else:
+            table.add_column("Got/Exp DS", justify="left")
+
+        table.add_column("Reasoning", justify="left", max_width=40, overflow="ellipsis")
+        table.add_column("L1 Score", justify="right")
+        table.add_column("Tokens", justify="right")
+        table.add_column("Latency", justify="right")
+        table.add_column("Candidates", justify="left")
+
+        for r in results:
+            status_style = "green" if r["status"] == "PASS" else "red"
+            route_icon = "YES" if r["routing_match"] else "NO"
+
+            layer_raw = r.get("routing_layer", "unknown")
+            layer_map = {"layer_1": "L1", "layer_2": "L2", "layer_3": "L3", "fallback": "FB"}
+            layer_str = layer_map.get(layer_raw, layer_raw)
+
+            cols = [r["id"], f"[{status_style}]{r['status']}[/{status_style}]", route_icon, layer_str]
+
+            if not routing_only:
+                sql_icon = "YES" if r.get("sql_match") else "NO" if r.get("sql_match") is not None else "-"
+                sem_icon = (
+                    "YES"
+                    if r.get("semantic_sql_match")
+                    else "NO"
+                    if r.get("semantic_sql_match") is not None
+                    else "-"
+                )
+
+                rows_info = f"{r.get('gen_rows', '-')} / {r.get('exp_rows', '-')}"
+                cols.extend([sql_icon, sem_icon, rows_info])
+            else:
+                ds_info = f"{r.get('actual_ds')} / {r.get('expected_ds')}"
+                cols.append(ds_info)
+
+            reasoning = r.get("routing_reasoning", "-")
+            tokens = str(r.get("routing_tokens", "-"))
+            latency_val = r.get("routing_latency", 0)
+            latency_str = f"{latency_val:.2f}s" if isinstance(latency_val, (int, float)) else "-"
+            score_val = r.get("l1_score", 0.0)
+            score_str = f"{score_val:.3f}" if isinstance(score_val, (int, float)) else "-"
+
+            candidates = r.get("candidates", [])
+            cand_str = ""
+            if candidates:
+                cand_str = ", ".join([f"{c['id']}({c['score']:.2f})" for c in candidates[:3]])
+                if len(candidates) > 3:
+                    cand_str += "..."
+
+            cols.extend([Text(str(reasoning)), score_str, tokens, latency_str, cand_str])
+
+            table.add_row(*cols)
+
+        self.console.print(table)
+
+    def print_metrics_summary(
+        self,
+        metrics: Dict[str, Any],
+        results: List[Dict[str, Any]],
+        routing_only: bool = False,
+    ) -> None:
+        routing_acc = metrics.get("routing_accuracy", 0.0)
+        self.console.print(f"\n[bold]Routing Accuracy:[/bold]   {routing_acc:.1f}%")
+
+        self.console.print("\n[bold]Routing Layer Breakdown:[/bold]")
+        layer_counts = metrics.get("layer_distribution", {})
+        layer_pcts = metrics.get("layer_percentages", {})
+
+        for layer, count in layer_counts.items():
+            pct = layer_pcts.get(layer, 0.0)
+            self.console.print(f"  - {layer.replace('_', ' ').title()}: {count} ({pct:.1f}%)")
+
+        if not routing_only:
+            sql_acc = metrics.get("execution_accuracy", 0.0)
+            sem_acc = metrics.get("semantic_sql_accuracy", 0.0)
+            valid_sql_rate = metrics.get("valid_sql_rate", 0.0)
+            self.console.print(f"\n[bold]Execution Accuracy:[/bold]    {sql_acc:.1f}%")
+            self.console.print(f"[bold]Semantic SQL Accuracy:[/bold] {sem_acc:.1f}%")
+            self.console.print(f"[bold]Valid SQL Rate:[/bold]        {valid_sql_rate:.1f}%")
+
+        errors = [r for r in results if r["status"] in ["ERROR", "GT_FAIL", "EXEC_FAIL", "INVALID_GT", "INVALID_SQL"]]
+        if errors:
+            unique_errors = {}
+            for e in errors:
+                unique_errors[f"{e['id']}: {e.get('error')}"] = e
+
+            self.console.print("\n[bold red]Top Errors:[/bold red]")
+            for k in list(unique_errors.keys())[:5]:
+                self.console.print(Text(k))
+
+    def export_results(self, results: List[Dict[str, Any]], path: Path) -> None:
+        export_data = []
+        for r in results:
+            item = {
+                "id": r.get("id"),
+                "question": r.get("question", ""),
+                "status": r.get("status"),
+                "generated_sql": r.get("gen_sql"),
+                "expected_sql": r.get("exp_sql"),
+                "sql_match": r.get("sql_match"),
+                "semantic_match": r.get("semantic_sql_match"),
+                "routing_match": r.get("routing_match"),
+                "datasource": r.get("actual_ds"),
+                "expected_datasource": r.get("expected_ds"),
+                "error": r.get("error"),
+            }
+            export_data.append(item)
+
+        if path.suffix.lower() == ".json":
+            with open(path, "w", encoding="utf-8") as f:
+                json.dump(export_data, f, indent=2, default=str)
+            self.console.print(f"\n[bold green]Results exported to {escape(str(path))}[/bold green]")
+        elif path.suffix.lower() == ".csv":
+            if not export_data:
+                self.console.print(f"\n[yellow]No results to export.[/yellow]")
+            else:
+                keys = export_data[0].keys()
+                with open(path, "w", newline="", encoding="utf-8") as f:
+                    writer = csv.DictWriter(f, fieldnames=keys)
+                    writer.writeheader()
+                    writer.writerows(export_data)
+                self.console.print(f"\n[bold green]Results exported to {escape(str(path))}[/bold green]")
+        else:
+            self.console.print(
+                f"\n[bold red]Unsupported export format: {escape(str(path.suffix))}. Use .json or .csv[/bold red]"
+            )
+
+    # ------------------------------------------------------------------
+    # Indexing (indexing.py)
+    # ------------------------------------------------------------------
+    def print_indexing_start(self, path: str) -> None:
+        self.console.print(f"[bold blue]Indexing schema to:[/bold blue] {escape(str(path))}")
+
+    def print_indexing_error(self, ds_id: str, error: str) -> None:
+        self.console.print(f"[red]Failed to index {escape(str(ds_id))}: {escape(str(error))}[/red]")
+
+    def print_indexing_complete(self) -> None:
+        self.console.print("\n[bold green]Indexing complete![/bold green]")
+
+    def print_indexing_summary(self, stats: List[Dict[str, Any]]) -> None:
+        if not stats:
+            return
+
+        table = Table(title="Indexing Summary", show_header=True, header_style="bold magenta", expand=True)
+        table.add_column("Datasource", style="cyan")
+        table.add_column("Tables", justify="right")
+        table.add_column("Columns", justify="right")
+        table.add_column("Examples", justify="right")
+
+        total_tables = 0
+        total_cols = 0
+        total_examples = 0
+
+        for s in stats:
+            t = s.get("tables", 0)
+            c = s.get("columns", 0)
+            e = s.get("examples", 0)
+
+            total_tables += t
+            total_cols += c
+            total_examples += e
+
+            table.add_row(Text(str(s.get("id", "Unknown"))), str(t), str(c), str(e))
+
+        table.add_row(
+            "[bold]TOTAL[/bold]",
+            f"[bold]{total_tables}[/bold]",
+            f"[bold]{total_cols}[/bold]",
+            f"[bold]{total_examples}[/bold]",
+            style="green",
+        )
+
+        self.console.print("\n")
+        self.console.print(table)
+
+    def create_progress(self):
+        from rich.progress import BarColumn, Progress, SpinnerColumn, TaskProgressColumn, TextColumn
+
+        return Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            BarColumn(),
+            TaskProgressColumn(),
+            console=self.console,
+        )
+
+    # ------------------------------------------------------------------
+    # Visualization (visualize.py)
+    # ------------------------------------------------------------------
+    def print_graph_saved(self, path: str) -> None:
+        import os
+
+        abs_path = os.path.abspath(path)
+        link = Text(abs_path, style=Style(bold=True, underline=True, link=f"file:///{abs_path}"))
+        self.console.print("Graph visualization saved to: ", link)
+
+    def print_graph_save_error(self, error: str) -> None:
+        self.console.print(f"[bold red]Failed to save graph image:[/bold red] {escape(str(error))}")
+
+    def track(self, sequence: Iterable[Any], description: str = "Working...", total: Optional[float] = None):
+        from rich.progress import track
+
+        return track(sequence, description=description, total=total, console=self.console)
+