verbose live UI + tool-level SSE events + Groq default + regression tests

api/tools/types.py

@@ -0,0 +1,128 @@
+"""Public data shapes for the Tools layer.
+
+Behavior modules in api/tools/ import from here. Keeping types in one file
+makes the layer's surface visible at a glance.
+
+Secondary constructors (`from_inspector`, `from_spec`, …) live as
+classmethods so call sites read as one line instead of multi-line kwarg
+blocks.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+# ── Schema model ──
+
+@dataclass
+class Column:
+    name: str
+    sql_type: str
+    nullable: bool
+    description: str | None = None
+
+    @classmethod
+    def from_inspector(cls, info: dict[str, Any], description: str | None = None) -> "Column":
+        """Build from a SQLAlchemy Inspector column dict."""
+        return cls(
+            name=info["name"],
+            sql_type=str(info["type"]).upper(),
+            nullable=bool(info["nullable"]),
+            description=description,
+        )
+
+
+@dataclass
+class Table:
+    name: str
+    description: str | None
+    columns: list[Column]
+
+
+@dataclass
+class Metric:
+    name: str
+    description: str
+    sql: str
+    from_table: str
+    filter: str | None
+    unit: str | None
+
+    @classmethod
+    def from_spec(cls, name: str, spec: dict[str, Any]) -> "Metric":
+        """Build from a metrics.yaml entry."""
+        return cls(
+            name=name,
+            description=spec.get("description", ""),
+            sql=spec["sql"],
+            from_table=spec["from_table"],
+            filter=spec.get("filter"),
+            unit=spec.get("unit"),
+        )
+
+
+@dataclass
+class SchemaContext:
+    schema: str
+    tables: dict[str, Table]
+    metrics: dict[str, Metric]
+
+    def table_names(self) -> list[str]:
+        return sorted(self.tables)
+
+    def metric_names(self) -> list[str]:
+        return sorted(self.metrics)
+
+    def render_tables(self, names: list[str] | None = None) -> str:
+        """CREATE TABLE-like rendering for prompt context."""
+        sel = [self.tables[n] for n in (names or self.table_names()) if n in self.tables]
+        out: list[str] = []
+        for t in sel:
+            header = f"-- {t.description}\n" if t.description else ""
+            cols: list[str] = []
+            for c in t.columns:
+                line = f'  "{c.name}" {c.sql_type}'
+                if not c.nullable:
+                    line += " NOT NULL"
+                if c.description:
+                    line += f"  -- {c.description}"
+                cols.append(line)
+            out.append(header + f'CREATE TABLE "{t.name}" (\n' + ",\n".join(cols) + "\n);")
+        return "\n\n".join(out)
+
+    def render_metrics(self) -> str:
+        if not self.metrics:
+            return "(no metrics defined)"
+        lines: list[str] = []
+        for m in self.metrics.values():
+            lines.append(
+                f"- {m.name} ({m.unit or 'unitless'}): {m.description}\n"
+                f"    sql: {m.sql}\n"
+                f"    from: {m.from_table}"
+                + (f"\n    filter: {m.filter}" if m.filter else "")
+            )
+        return "\n".join(lines)
+
+
+# ── Query execution ──
+
+@dataclass
+class QueryResult:
+    columns: list[str]
+    rows: list[list[Any]]
+    row_count: int
+    truncated: bool
+
+    def as_dicts(self) -> list[dict[str, Any]]:
+        return [dict(zip(self.columns, r)) for r in self.rows]
+
+
+# ── Text-to-SQL output ──
+
+@dataclass
+class T2SResult:
+    sql: str
+    used_tables: list[str]
+    explanation: str | None = None