pretensor 0.1.0__py3-none-any.whl

pretensor/benchmark/l1/pipeline.py

@@ -0,0 +1,188 @@
+"""Pipeline orchestration for L1 metric collection.
+
+Glues the existing :class:`GraphBuilder` + :class:`KuzuStore` +
+:class:`ClusteringEngine` + :func:`classify_database_tables` plumbing
+into a single helper that returns the artifacts the four L1 metrics
+need. Lives separately from :mod:`pretensor.benchmark.l1.metrics` so
+the pure metric helpers stay testable without spinning up Kuzu.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from pretensor.benchmark.l1.metrics import JoinKey
+from pretensor.connectors.models import SchemaSnapshot
+from pretensor.core.builder import GraphBuilder
+from pretensor.core.store import KuzuStore
+from pretensor.intelligence.clustering import ClusteringEngine
+from pretensor.intelligence.discovery import RelationshipDiscovery
+from pretensor.intelligence.graph_export import GraphExporter
+from pretensor.intelligence.heuristic import HeuristicScorer
+from pretensor.intelligence.schema_classification import classify_database_tables
+from pretensor.intelligence.scoring import ScorerRegistry
+
+__all__ = [
+    "L1_EMBEDDING_JOIN_THRESHOLD",
+    "L1Artifacts",
+    "build_l1_artifacts",
+    "discover_inferred_joins_blind",
+]
+
+# Cosine threshold used by the L1 embeddings lane for the embedding
+# relationship scorer. ``EmbeddingsConfig.join_threshold`` has no
+# production default (None = scorer off); the benchmark pins the
+# documented "typical" value so the lane measures one fixed, reproducible
+# operating point. Bump deliberately and regenerate the
+# ``<dataset>-l1-embeddings.json`` baselines when retuning.
+L1_EMBEDDING_JOIN_THRESHOLD = 0.85
+
+
+@dataclass(frozen=True, slots=True)
+class L1Artifacts:
+    """Per-run outputs collected from the intelligence pipeline."""
+
+    clusters: list[frozenset[str]] = field(default_factory=list)
+    """One frozenset of table node IDs per cluster."""
+
+    roles: dict[str, str] = field(default_factory=dict)
+    """Map of bare table name → role literal (matches ``TableRole``)."""
+
+
+def build_l1_artifacts(
+    snapshot: SchemaSnapshot,
+    *,
+    work_dir: Path,
+) -> L1Artifacts:
+    """Run the production pipeline once and collect L1-relevant outputs.
+
+    The pipeline runs over the snapshot as authored, with declared FKs
+    in place — clustering and role classification both take advantage
+    of that signal in production, and the L1 metric must reflect that.
+
+    The blind-discovery leg (FKs masked, used for inferred-join P/R)
+    runs separately via :func:`discover_inferred_joins_blind` so the
+    two legs don't share state.
+    """
+    work_dir.mkdir(parents=True, exist_ok=True)
+    store = KuzuStore(work_dir / "graph.kuzu")
+    try:
+        GraphBuilder().build(snapshot, store)
+
+        graph = GraphExporter(store).to_igraph(snapshot.database)
+        clusters_raw = ClusteringEngine().cluster(graph)
+        clusters = sorted(
+            (frozenset(c.table_ids) for c in clusters_raw),
+            key=lambda fs: tuple(sorted(fs)),
+        )
+
+        classifications = classify_database_tables(store, snapshot.database)
+        roles = {
+            _bare_table_name(node_id, snapshot.connection_name): cls.role
+            for node_id, cls in classifications.items()
+        }
+    finally:
+        store.close()
+
+    return L1Artifacts(clusters=list(clusters), roles=roles)
+
+
+def discover_inferred_joins_blind(
+    snapshot: SchemaSnapshot,
+    *,
+    work_dir: Path,
+    embeddings: bool = False,
+) -> list[JoinKey]:
+    """Run heuristic discovery against an FK-masked snapshot.
+
+    Production discovery filters out candidates that match declared FKs,
+    so a metric that compares the inferred set against declared FKs only
+    makes sense when those FKs are hidden from the heuristic. This
+    helper masks the snapshot, runs the heuristic, and returns the
+    candidate joins as canonical (table-name, column) pairs ready for
+    :func:`pretensor.benchmark.l1.metrics.inferred_join_pr`.
+
+    With ``embeddings=True`` (the L1 embeddings lane), table vectors are
+    computed on the masked store first and an
+    :class:`EmbeddingRelationshipScorer` is registered after the heuristic
+    at :data:`L1_EMBEDDING_JOIN_THRESHOLD` — the same staging production
+    uses — so ``inferred_join_precision`` / ``recall`` measure the
+    heuristic + embedding scorer combination.
+    """
+    work_dir.mkdir(parents=True, exist_ok=True)
+    masked = _mask_foreign_keys(snapshot)
+    store = KuzuStore(work_dir / "graph.kuzu")
+    try:
+        # Build the FK-masked graph so RelationshipDiscovery has node
+        # context (column metadata, neighbours) to score candidates.
+        GraphBuilder().build(masked, store, run_relationship_discovery=False)
+        scorers = None
+        if embeddings:
+            from pretensor.intelligence.semantic import (
+                extend_with_embedding_scorer,
+            )
+            from pretensor.intelligence.steps_embedding import (
+                compute_table_embeddings,
+            )
+
+            compute_table_embeddings(store, masked.database)
+            if not store.has_any_table_embeddings():
+                # Mirror the L2 guard: the production embed path degrades
+                # silently on download failure, but a benchmark lane that
+                # measures the heuristic-only path under an embeddings
+                # baseline reports a bogus regression. Fail loudly.
+                msg = (
+                    "L1 was invoked with --embeddings but no table vectors "
+                    "were computed; the embedding model is likely "
+                    "unavailable (download failure / rate limit)."
+                )
+                raise RuntimeError(msg)
+            scorers = extend_with_embedding_scorer(
+                ScorerRegistry([HeuristicScorer()]),
+                store=store,
+                database_key=masked.database,
+                threshold=L1_EMBEDDING_JOIN_THRESHOLD,
+            )
+        candidates = RelationshipDiscovery(store, scorers=scorers).discover(masked)
+    finally:
+        store.close()
+
+    keys: list[JoinKey] = []
+    for cand in candidates:
+        src = _bare_table_name(cand.source_node_id, snapshot.connection_name)
+        dst = _bare_table_name(cand.target_node_id, snapshot.connection_name)
+        keys.append((src, cand.source_column, dst, cand.target_column))
+    keys.sort()
+    return keys
+
+
+def collect_declared_fks(snapshot: SchemaSnapshot) -> list[JoinKey]:
+    """Return the canonical declared-FK ground-truth set for the snapshot."""
+    keys: list[JoinKey] = []
+    for table in snapshot.tables:
+        for fk in table.foreign_keys:
+            src = f"{fk.source_schema}.{fk.source_table}"
+            dst = f"{fk.target_schema}.{fk.target_table}"
+            keys.append((src, fk.source_column, dst, fk.target_column))
+    keys.sort()
+    return keys
+
+
+def _mask_foreign_keys(snapshot: SchemaSnapshot) -> SchemaSnapshot:
+    """Return a copy of ``snapshot`` with every table's ``foreign_keys`` cleared.
+
+    Used so :class:`RelationshipDiscovery` has to rediscover the joins
+    from column-level signals rather than reading them off the FK list.
+    """
+    masked_tables = []
+    for table in snapshot.tables:
+        masked_tables.append(table.model_copy(update={"foreign_keys": []}))
+    return snapshot.model_copy(update={"tables": masked_tables})
+
+
+def _bare_table_name(node_id: str, connection_name: str) -> str:
+    """Turn a Kuzu ``node_id`` (``conn::schema::table``) into ``schema.table``."""
+    prefix = f"{connection_name}::"
+    rest = node_id[len(prefix) :] if node_id.startswith(prefix) else node_id
+    return rest.replace("::", ".", 1)

pretensor/benchmark/l1/runner.py

@@ -0,0 +1,245 @@
+"""``run_l1`` — collect L1 metrics into a deterministic JSON document."""
+
+from __future__ import annotations
+
+import hashlib
+import importlib
+import importlib.metadata
+import json
+import sys
+import tempfile
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import yaml
+
+from pretensor.benchmark.fixtures import load_dataset
+from pretensor.benchmark.l1.metrics import (
+    canonicalise_join_key,
+    cluster_stability_jaccard,
+    inferred_join_pr,
+    role_f1,
+)
+from pretensor.benchmark.l1.pipeline import (
+    L1_EMBEDDING_JOIN_THRESHOLD,
+    build_l1_artifacts,
+    collect_declared_fks,
+    discover_inferred_joins_blind,
+)
+from pretensor.benchmark.results import BenchmarkResult, Metric, write_json
+from pretensor.connectors.models import SchemaSnapshot
+
+if TYPE_CHECKING:
+    from pretensor.benchmark.runner import Dataset
+
+__all__ = ["run_l1"]
+
+
+_DETERMINISTIC_RAN_AT = "1970-01-01T00:00:00Z"
+"""Pinned timestamp so two consecutive runs produce byte-identical JSON.
+
+Matches the precedent in ``tests/benchmark/test_results.py``. Real
+wall-clock would break the determinism gate baked into the spec.
+"""
+
+_EMBEDDINGS_SENTINEL = "onnxruntime"
+"""Importable module that ships with the ``[embeddings]`` extra.
+
+The runner uses this as a probe: if ``import onnxruntime`` fails the
+extra is not installed, and we report the install hint rather than
+silently emitting heuristic-only numbers as if embeddings were on.
+"""
+
+_FIXTURES_ROOT = Path(__file__).resolve().parents[3].parent / "tests" / "fixtures"
+"""``<repo>/tests/fixtures`` resolved relative to the source tree.
+
+Used to locate gold-role companion files (``<dataset>_roles.yaml``).
+``parents[3]`` walks up ``runner.py → l1 → benchmark → pretensor`` and
+``.parent`` strips ``src/``; the result is the repo root.
+"""
+
+
+def run_l1(
+    dataset: Dataset,
+    out: Path | None,
+    graph_dir: Path,  # noqa: ARG001 — L1 builds a fresh in-process graph
+    *,
+    embeddings: bool,
+) -> None:
+    """Run the four OSS L1 metrics for ``dataset`` and emit a ``BenchmarkResult``.
+
+    ``graph_dir`` is part of the CLI contract for L2 / L3 but unused here —
+    L1 indexes the fixture into a fresh per-call temporary store so the
+    metric is reproducible from a clean checkout. It's accepted (and
+    ignored) to keep ``run_l1`` interchangeable with the other runners.
+    """
+    fixture = load_dataset(dataset)
+    snapshot_text = fixture.schema_yaml_path.read_text(encoding="utf-8")
+    snapshot = SchemaSnapshot.from_yaml(snapshot_text)
+    fixture_sha = (
+        "sha256:" + hashlib.sha256(fixture.schema_yaml_path.read_bytes()).hexdigest()
+    )
+
+    notes: list[str] = []
+    embeddings_enabled = _resolve_embeddings_flag(embeddings, notes)
+
+    if embeddings_enabled:
+        notes.append(
+            "inferred_join metrics include the embedding relationship "
+            f"scorer at cosine threshold {L1_EMBEDDING_JOIN_THRESHOLD} "
+            "(heuristic + embedding lane)."
+        )
+
+    with tempfile.TemporaryDirectory() as tmp_root:
+        tmp = Path(tmp_root)
+        artifacts_a = build_l1_artifacts(snapshot, work_dir=tmp / "run-a")
+        artifacts_b = build_l1_artifacts(snapshot, work_dir=tmp / "run-b")
+        inferred = discover_inferred_joins_blind(
+            snapshot, work_dir=tmp / "blind", embeddings=embeddings_enabled
+        )
+
+    declared_fks = collect_declared_fks(snapshot)
+    p, r = inferred_join_pr(inferred, declared_fks)
+    jacc = cluster_stability_jaccard(artifacts_a.clusters, artifacts_b.clusters)
+
+    gold_roles = _load_gold_roles(dataset)
+    if gold_roles is None:
+        rf: float | None = None
+        notes.append(
+            f"role_f1 unavailable for dataset '{dataset.value}': "
+            f"no gold-role annotation file (only adversarial has labels today)."
+        )
+    else:
+        # Normalise predicted keys (``schema.table``) to bare table names so
+        # they line up with the gold-role file's bare-name keys.
+        predicted_bare: dict[str, str] = {}
+        for key, role in artifacts_a.roles.items():
+            bare = key.split(".", 1)[1] if "." in key else key
+            predicted_bare[bare] = role
+        rf = role_f1(predicted_bare, gold_roles)
+
+    metrics = {
+        "inferred_join_precision": Metric(value=p, direction="higher_is_better"),
+        "inferred_join_recall": Metric(value=r, direction="higher_is_better"),
+        "cluster_stability_jaccard": Metric(value=jacc, direction="higher_is_better"),
+        "role_f1": Metric(value=rf, direction="higher_is_better"),
+    }
+
+    result = BenchmarkResult(
+        level="l1",
+        dataset=dataset.value,
+        pretensor_version=_resolve_version(),
+        embeddings_enabled=embeddings_enabled,
+        ran_at=_DETERMINISTIC_RAN_AT,
+        fixture_sha=fixture_sha,
+        metrics=metrics,
+        per_item=_collect_per_item(
+            inferred=inferred,
+            declared_fks=declared_fks,
+            predicted_roles=artifacts_a.roles,
+            gold_roles=gold_roles,
+        ),
+        notes=notes,
+    )
+
+    if out is None:
+        sys.stdout.write(json.dumps(result.to_dict(), sort_keys=True, indent=2) + "\n")
+    else:
+        write_json(result, out)
+
+
+def _resolve_embeddings_flag(requested: bool, notes: list[str]) -> bool:
+    """Resolve the user's ``--embeddings`` request against the install state.
+
+    Returns the ``embeddings_enabled`` value the JSON envelope should
+    record. Appends an install-hint to ``notes`` when the user asked
+    for embeddings but the optional extra is not present.
+    """
+    if not requested:
+        return False
+    try:
+        importlib.import_module(_EMBEDDINGS_SENTINEL)
+    except ImportError:
+        notes.append(
+            "--embeddings was requested but the 'embeddings' extra is not "
+            "installed; emitted heuristic-only metrics. Install with "
+            "`uv sync --extra embeddings` to enable the embedding path."
+        )
+        return False
+    return True
+
+
+def _resolve_version() -> str:
+    try:
+        return importlib.metadata.version("pretensor")
+    except importlib.metadata.PackageNotFoundError:
+        return "0.0.0+unknown"
+
+
+def _load_gold_roles(dataset: Dataset) -> dict[str, str] | None:
+    path = _FIXTURES_ROOT / "schemas" / f"{dataset.value}_roles.yaml"
+    if not path.exists():
+        return None
+    raw = yaml.safe_load(path.read_text(encoding="utf-8"))
+    if not isinstance(raw, dict):
+        return None
+    roles = raw.get("roles") if "roles" in raw else raw
+    if not isinstance(roles, dict):
+        return None
+    return {str(k): str(v) for k, v in roles.items()}
+
+
+def _collect_per_item(
+    *,
+    inferred: list[tuple[str, str, str, str]],
+    declared_fks: list[tuple[str, str, str, str]],
+    predicted_roles: dict[str, str],
+    gold_roles: dict[str, str] | None,
+) -> list[dict[str, object]]:
+    """Emit a deterministic per-assertion record list for the JSON output."""
+    items: list[dict[str, object]] = []
+
+    declared_canon = {canonicalise_join_key(k) for k in declared_fks}
+    inferred_canon = {canonicalise_join_key(k) for k in inferred}
+    edge_ids = sorted(declared_canon | inferred_canon)
+    for edge in edge_ids:
+        (src_t, src_c), (dst_t, dst_c) = edge
+        items.append(
+            {
+                "id": f"{src_t}.{src_c}↔{dst_t}.{dst_c}",
+                "kind": "inferred_join",
+                "expected": edge in declared_canon,
+                "predicted": edge in inferred_canon,
+            }
+        )
+
+    if gold_roles is not None:
+        for table_name in sorted(gold_roles):
+            # The bare table name lookup matches the format produced by
+            # ``build_l1_artifacts`` (``schema.table``) — gold uses bare
+            # names without schema, so we resolve via suffix match.
+            predicted = _resolve_predicted_role(predicted_roles, table_name)
+            items.append(
+                {
+                    "id": f"role:{table_name}",
+                    "kind": "role_classification",
+                    "expected": gold_roles[table_name],
+                    "predicted": predicted,
+                }
+            )
+
+    return items
+
+
+def _resolve_predicted_role(
+    predicted: dict[str, str],
+    bare_table_name: str,
+) -> str | None:
+    """Look up a role by bare table name across the predictor's keyed-by-schema dict."""
+    if bare_table_name in predicted:
+        return predicted[bare_table_name]
+    for key, role in predicted.items():
+        # Predicted keys are ``schema.table``; gold is bare ``table``.
+        if key.endswith(f".{bare_table_name}"):
+            return role
+    return None

pretensor/benchmark/l2/__init__.py

@@ -0,0 +1,27 @@
+"""L2 MCP-tool-quality benchmark — metric implementations and runner.
+
+See ``docs/specs/benchmark/spec.md`` §L2 metric definitions for the
+contract this module fulfils. Metric values are wrapped in the
+``{value, direction}`` envelope from
+:mod:`pretensor.benchmark.results`.
+"""
+
+from __future__ import annotations
+
+from pretensor.benchmark.l2.metrics import (
+    compile_metric_correctness,
+    query_recall_at_k,
+    semantic_search_recall_at_k,
+    top_k_with_ties,
+    traverse_correctness,
+)
+from pretensor.benchmark.l2.runner import run_l2
+
+__all__ = [
+    "compile_metric_correctness",
+    "query_recall_at_k",
+    "run_l2",
+    "semantic_search_recall_at_k",
+    "top_k_with_ties",
+    "traverse_correctness",
+]

pretensor/benchmark/l2/gold.py

@@ -0,0 +1,236 @@
+"""Gold-data loaders for the L2 benchmark.
+
+Reads the per-dataset NL→SQL bench JSON and the metric-templates YAML
+file into typed dataclasses the runner consumes. Centralised here so
+the runner stays thin and the loaders are independently testable.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+import yaml
+
+from pretensor.benchmark.fixtures import Fixture
+from pretensor.benchmark.l2.metrics import JoinPair
+from pretensor.connectors.lineage_sqlglot import table_refs_from_sql
+
+__all__ = [
+    "MetricTemplateEntry",
+    "QueryGoldEntry",
+    "TraverseGoldEntry",
+    "bare_table_name",
+    "default_schema_for",
+    "load_metric_templates",
+    "load_query_gold",
+    "load_traverse_gold",
+]
+
+
+# Default schema applied to unqualified table references in expected_sql.
+# Every gold SQL we ship today either uses public.* (Pagila, TPC-H) or is
+# fully schema-qualified (AdventureWorks: humanresources.*, sales.*, etc.),
+# so the default is only an absolute-last-resort fallback. Datasets we
+# don't list here use ``"public"`` for the same reason.
+_DEFAULT_SCHEMAS: dict[str, str] = {
+    "pagila": "public",
+    "tpch": "public",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class QueryGoldEntry:
+    """One question→tables observation for the ``query`` Recall@K metric."""
+
+    id: str
+    question: str
+    expected_sql: str
+    tables_touched: frozenset[str]
+
+
+@dataclass(frozen=True, slots=True)
+class TraverseGoldEntry:
+    """One ``(from_table, to_table, gold_path)`` entry for traverse correctness.
+
+    ``gold_path`` is the canonical sequence of ``(from_table, to_table)``
+    hops (schema-qualified bare names). The first hop's ``from_table`` is
+    the traverse start; the last hop's ``to_table`` is the destination.
+    """
+
+    id: str
+    from_table: str
+    to_table: str
+    gold_path: tuple[JoinPair, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class MetricTemplateEntry:
+    """One semantic-layer metric template for ``compile_metric``."""
+
+    metric: str
+    semantic_yaml: str
+    database: str
+    # Optional sidecar for diagnostics — never used by the metric value.
+    notes: str = field(default="")
+
+
+def default_schema_for(dataset_name: str) -> str:
+    """Return the default schema to use when SQL refs are unqualified."""
+    return _DEFAULT_SCHEMAS.get(dataset_name, "public")
+
+
+def load_query_gold(fixture: Fixture) -> list[QueryGoldEntry]:
+    """Load the bench JSON and resolve ``tables_touched`` for each entry.
+
+    When an entry already has an explicit ``tables_touched`` array we use
+    it verbatim. When absent, we parse ``expected_sql`` via sqlglot and
+    extract the bare table names. Entries whose ``expected_sql`` fails to
+    parse are returned with an empty ``tables_touched`` set so the
+    metric loop skips them — the runner notes the parse failure.
+    """
+    if fixture.questions_path is None:
+        return []
+    raw = json.loads(fixture.questions_path.read_text(encoding="utf-8"))
+    if not isinstance(raw, list):
+        return []
+
+    default_schema = default_schema_for(fixture.name.value)
+    entries: list[QueryGoldEntry] = []
+    for item in raw:
+        if not isinstance(item, dict):
+            continue
+        identifier = str(item.get("id", "")).strip()
+        question = str(item.get("question", ""))
+        expected_sql = str(item.get("expected_sql", ""))
+        if not identifier:
+            continue
+
+        tables = item.get("tables_touched")
+        if isinstance(tables, list) and all(isinstance(t, str) for t in tables):
+            tables_set = frozenset(bare_table_name(t) for t in tables)
+        else:
+            tables_set = frozenset(
+                t
+                for _, t in table_refs_from_sql(
+                    expected_sql,
+                    dialect="postgres",
+                    default_schema=default_schema,
+                )
+            )
+
+        entries.append(
+            QueryGoldEntry(
+                id=identifier,
+                question=question,
+                expected_sql=expected_sql,
+                tables_touched=tables_set,
+            )
+        )
+    return entries
+
+
+def load_traverse_gold(fixture: Fixture) -> list[TraverseGoldEntry]:
+    """Pull ``gold_path`` entries out of the bench JSON.
+
+    Only entries that explicitly carry a ``gold_path`` array are returned
+    — the metric ignores entries authored only for ``query`` Recall@K.
+    """
+    if fixture.questions_path is None:
+        return []
+    raw = json.loads(fixture.questions_path.read_text(encoding="utf-8"))
+    if not isinstance(raw, list):
+        return []
+
+    out: list[TraverseGoldEntry] = []
+    for item in raw:
+        if not isinstance(item, dict):
+            continue
+        gold_path_raw = item.get("gold_path")
+        if not isinstance(gold_path_raw, list) or not gold_path_raw:
+            continue
+
+        hops: list[JoinPair] = []
+        for hop in gold_path_raw:
+            if not isinstance(hop, dict):
+                continue
+            frm = hop.get("from_table")
+            to = hop.get("to_table")
+            if isinstance(frm, str) and isinstance(to, str):
+                hops.append((frm, to))
+        if not hops:
+            continue
+
+        identifier = str(item.get("id", "")).strip()
+        out.append(
+            TraverseGoldEntry(
+                id=identifier or f"{hops[0][0]}->{hops[-1][1]}",
+                from_table=hops[0][0],
+                to_table=hops[-1][1],
+                gold_path=tuple(hops),
+            )
+        )
+    return out
+
+
+def load_metric_templates(fixture: Fixture) -> list[MetricTemplateEntry]:
+    """Parse the per-dataset metric-templates YAML.
+
+    The YAML file lives at ``scripts/data/<dataset>_metric_templates.yaml``
+    and shadows :class:`Fixture.metric_templates_path`. Returns an empty
+    list when the file is absent — the metric reports
+    :class:`compile_metric_correctness` as ``None`` upstream.
+
+    Format:
+
+    .. code-block:: yaml
+
+        connection_name: pagila
+        templates:
+          - metric: total_rentals
+            notes: Optional human-readable rationale
+            semantic_yaml: |
+              connection_name: pagila
+              domains:
+                - name: rentals
+                  ...
+
+    The ``connection_name`` at the top level is forwarded as the
+    ``database`` argument to ``compile_metric_payload``.
+    """
+    path = fixture.metric_templates_path
+    if path is None or not path.exists():
+        return []
+
+    raw: Any = yaml.safe_load(path.read_text(encoding="utf-8"))
+    if not isinstance(raw, dict):
+        return []
+
+    database = str(raw.get("connection_name", fixture.name.value))
+    templates_raw = raw.get("templates", [])
+    if not isinstance(templates_raw, list):
+        return []
+
+    out: list[MetricTemplateEntry] = []
+    for item in templates_raw:
+        if not isinstance(item, dict):
+            continue
+        metric = str(item.get("metric", "")).strip()
+        semantic_yaml = str(item.get("semantic_yaml", ""))
+        if not metric or not semantic_yaml.strip():
+            continue
+        out.append(
+            MetricTemplateEntry(
+                metric=metric,
+                semantic_yaml=semantic_yaml,
+                database=database,
+                notes=str(item.get("notes", "")),
+            )
+        )
+    return out
+
+
+def bare_table_name(name: str) -> str:
+    """Strip the schema prefix from a possibly-qualified table name."""
+    return name.split(".", 1)[1] if "." in name else name