mudm-mcp 0.1.0__py3-none-any.whl

mudm_mcp/__init__.py

@@ -0,0 +1,4 @@
+"""muDM MCP — a local MCP server (client of the static muDM catalog) for agent/LLM discovery,
+access, and local analysis of muDM spatial datasets."""
+
+__version__ = "0.1.0"

mudm_mcp/catalog_client.py

@@ -0,0 +1,236 @@
+"""Read the static muDM catalog: a CLIENT of `pyramids.json` (mudm.PyramidJSON) + per-dataset
+`tilejson.json` (mudm.TileModel) + derived `croissant.json`. No backend — fetches static files over
+http(s) (cached to a local dir) or reads a local build dir (`file://` / plain path) for dev/tests.
+"""
+from __future__ import annotations
+
+import difflib
+import json
+import os
+import time
+from pathlib import Path
+from urllib.parse import urlparse
+
+DEFAULT_JSON_TTL_S = 24 * 3600.0
+
+
+def default_cache_dir(host: str) -> Path:
+    return Path.home() / ".cache" / "mudm-mcp" / (host or "local")
+
+
+class DatasetNotFound(KeyError):
+    """Unknown dataset id; ``suggestions`` holds up to 5 close catalog ids."""
+
+    def __init__(self, dataset_id: str, known_ids: list[str]):
+        super().__init__(f"dataset {dataset_id!r} not found in pyramids.json")
+        self.dataset_id = dataset_id
+        self.suggestions = difflib.get_close_matches(dataset_id, known_ids, n=5, cutoff=0.5)
+
+
+def _zoom_of(part: str) -> int:
+    """'zoom=9/cells_part_000.mu.parquet' -> 9."""
+    return int(part.split("/", 1)[0].split("=", 1)[1])
+
+
+class CatalogClient:
+    """Resolve + cache the catalog artifacts. ``base_url`` may be an http(s) origin (default
+    ``https://ngrf.mudm.io``) or a local directory (a `build_site --out` dir, as `file://…` or a path).
+
+    Cached catalog JSON is refetched once it is older than ``json_ttl_s`` (default 24 h), so a long-lived
+    install follows catalog updates; if the refetch fails (offline) the stale copy is served."""
+
+    def __init__(self, base_url: str, cache_dir: str | Path | None = None,
+                 json_ttl_s: float = DEFAULT_JSON_TTL_S):
+        self.base_url = str(base_url).rstrip("/")
+        self.json_ttl_s = float(json_ttl_s)
+        parsed = urlparse(self.base_url)
+        self.is_http = parsed.scheme in ("http", "https")
+        if self.is_http:
+            self.cache_dir = Path(cache_dir) if cache_dir else default_cache_dir(parsed.netloc)
+            self._local_root: Path | None = None
+        else:  # file:// or a plain local path
+            self._local_root = Path(parsed.path if parsed.scheme == "file" else self.base_url)
+            self.cache_dir = Path(cache_dir) if cache_dir else self._local_root
+
+    # --- paths ---
+    @staticmethod
+    def _rel(parts) -> str:
+        return "/".join(str(p).strip("/") for p in parts if str(p).strip("/"))
+
+    def url(self, *parts: str) -> str:
+        """Absolute URL (http origin) or local path (local origin) of a site-relative path."""
+        rel = self._rel(parts)
+        return f"{self.base_url}/{rel}" if self.is_http else str(self._local_root / rel)
+
+    # --- fetch / cache ---
+    def fetch(self, *parts: str) -> bytes:
+        """Bytes of a catalog-relative path (e.g. ``fetch("datasets", id, "tilejson.json")``)."""
+        rel = self._rel(parts)
+        if not self.is_http:
+            return (self._local_root / rel).read_bytes()
+        cached = self.cache_dir / rel
+        have = cached.is_file()
+        if have and (time.time() - cached.stat().st_mtime) < self.json_ttl_s:
+            return cached.read_bytes()
+        import httpx  # lazy: file:// dev/tests need no network/httpx
+        try:
+            resp = httpx.get(f"{self.base_url}/{rel}", follow_redirects=True, timeout=60.0)
+            resp.raise_for_status()
+        except httpx.HTTPError:
+            if have:  # expired but unreachable: a stale catalog beats no catalog
+                return cached.read_bytes()
+            raise
+        cached.parent.mkdir(parents=True, exist_ok=True)
+        tmp = cached.with_name(cached.name + ".part")
+        tmp.write_bytes(resp.content)
+        os.replace(tmp, cached)
+        return resp.content
+
+    def fetch_json(self, *parts: str) -> dict:
+        return json.loads(self.fetch(*parts))
+
+    def _try_fetch_json(self, *parts: str) -> dict | None:
+        """``fetch_json`` that returns None when the file does not exist (local miss / HTTP 4xx)."""
+        try:
+            return self.fetch_json(*parts)
+        except FileNotFoundError:
+            return None
+        except Exception as exc:  # httpx.HTTPStatusError without importing httpx eagerly
+            status = getattr(getattr(exc, "response", None), "status_code", None)
+            if status is not None and 400 <= status < 500:  # S3/CloudFront answer 403 for a missing key
+                return None
+            raise
+
+    def download_file(self, rel_parts, out_path) -> int:
+        """Stream a (possibly large) leaf file to ``out_path`` (http GET or local copy); returns bytes
+        written. Atomic: the data goes to ``<out_path>.part`` and is renamed only when complete, so an
+        interrupted download never leaves a truncated file under the final name. Unlike ``fetch`` this
+        does not hold the body in memory or use the JSON cache (parquet leaves are served uncompressed)."""
+        rel = self._rel(rel_parts)
+        out = Path(out_path)
+        out.parent.mkdir(parents=True, exist_ok=True)
+        tmp = out.with_name(out.name + ".part")
+        try:
+            if not self.is_http:
+                with open(self._local_root / rel, "rb") as src, open(tmp, "wb") as fh:
+                    while chunk := src.read(1 << 20):
+                        fh.write(chunk)
+            else:
+                import httpx  # lazy
+                with httpx.stream("GET", f"{self.base_url}/{rel}", follow_redirects=True,
+                                  timeout=120.0) as resp:
+                    resp.raise_for_status()
+                    with open(tmp, "wb") as fh:
+                        for chunk in resp.iter_bytes():
+                            fh.write(chunk)
+            size = tmp.stat().st_size
+            os.replace(tmp, out)
+        except BaseException:
+            tmp.unlink(missing_ok=True)
+            raise
+        return size
+
+    # --- sizes ---
+    def part_size(self, base: str, part: str) -> int | None:
+        """Size in bytes of one leaf (local ``stat``; HTTP ``HEAD``, else a 1-byte ranged GET). None if
+        it cannot be determined."""
+        rel = self._rel([base, part])
+        if not self.is_http:
+            p = self._local_root / rel
+            return p.stat().st_size if p.is_file() else None
+        import httpx  # lazy
+        url = f"{self.base_url}/{rel}"
+        try:
+            r = httpx.head(url, follow_redirects=True, timeout=30.0)
+            if r.status_code == 200 and "content-length" in r.headers:
+                return int(r.headers["content-length"])
+            r = httpx.get(url, headers={"Range": "bytes=0-0"}, follow_redirects=True, timeout=30.0)
+            total = r.headers.get("content-range", "").rsplit("/", 1)[-1]
+            return int(total) if total.isdigit() else None
+        except httpx.HTTPError:
+            return None
+
+    def estimate_bytes(self, base: str, parts: list[str], sample: int = 4) -> int | None:
+        """Total size of ``parts``: exact when there are at most ``sample`` of them, else the mean of
+        ``sample`` evenly spaced parts times the count. None if no size could be read."""
+        if not parts:
+            return 0
+        if len(parts) <= sample:
+            sizes = [self.part_size(base, p) for p in parts]
+            return None if any(s is None for s in sizes) else sum(sizes)
+        step = len(parts) / sample
+        sizes = [s for s in (self.part_size(base, parts[int(i * step)]) for i in range(sample)) if s is not None]
+        return round(sum(sizes) / len(sizes) * len(parts)) if sizes else None
+
+    # --- catalog accessors ---
+    def pyramids(self) -> dict:
+        """The unified 2D+3D catalog (mudm.PyramidJSON)."""
+        return self.fetch_json("pyramids.json")
+
+    def entries(self) -> list[dict]:
+        return self.pyramids().get("pyramids", [])
+
+    def entry(self, dataset_id: str) -> dict:
+        """The catalog entry (PyramidEntry: id/label/kind + OPEN facet metadata) for one dataset."""
+        entries = self.entries()
+        for e in entries:
+            if e.get("id") == dataset_id:
+                return e
+        raise DatasetNotFound(dataset_id, [str(e.get("id")) for e in entries])
+
+    def descriptor(self, dataset_id: str) -> dict:
+        """The per-dataset muDM TileModel descriptor (assets[] + TileLayer schema + multiscale coords)."""
+        return self.fetch_json("datasets", dataset_id, "tilejson.json")
+
+    def croissant(self, dataset_id: str) -> dict:
+        """The derived Croissant JSON-LD (schema.org/Dataset + cr:)."""
+        return self.fetch_json("datasets", dataset_id, "croissant.json")
+
+    def viewer_descriptor(self, dataset_id: str) -> tuple[str, dict] | None:
+        """The VIEWER's descriptor ``(<site-relative dir>, tilejson)`` that sits next to the tiles
+        (``tiles/<id>/`` for 3D, ``tiles2d/<id>/`` for 2D). Its asset hrefs are relative to that dir. Used
+        as a fallback when the agent descriptor (``datasets/<id>/tilejson.json``) omits an asset."""
+        entry = self.entry(dataset_id)
+        feats = (entry.get("features") or "").strip("/")
+        dirs = [feats.rsplit("/", 1)[0]] if "/" in feats else []
+        dirs += [d for d in (f"tiles/{dataset_id}", f"tiles2d/{dataset_id}") if d not in dirs]
+        for d in dirs:
+            doc = self._try_fetch_json(d, "tilejson.json")
+            if doc is not None:
+                return d, doc
+        return None
+
+    @staticmethod
+    def _asset(descriptor: dict, role: str) -> dict | None:
+        return next((a for a in descriptor.get("assets") or [] if a.get("role") == role), None)
+
+    def features(self, dataset_id: str) -> dict | None:
+        """The download index of a dataset's ``features.parquet``:
+        ``{base, parts, zooms, full_res_zoom, source}`` — ``base`` is the site-relative directory holding
+        the ``zoom=<z>/…`` leaves, ``source`` is ``"agent"`` or ``"viewer"`` (which descriptor carried it).
+        None when neither descriptor lists parquet parts."""
+        entry = self.entry(dataset_id)
+        entry_base = (entry.get("features") or "").strip("/")
+        asset = self._asset(self.descriptor(dataset_id), "features")
+        source, viewer_dir = "agent", None
+        if not (asset and asset.get("parts")):
+            found = self.viewer_descriptor(dataset_id)
+            asset = self._asset(found[1], "features") if found else None
+            if not (asset and asset.get("parts")):
+                return None
+            source, viewer_dir = "viewer", found[0]
+        href = str(asset.get("href") or "")
+        if entry_base:
+            base = entry_base
+        elif viewer_dir is not None:
+            base = self._rel([viewer_dir, href or "features.parquet"])
+        elif href.startswith(self.base_url + "/"):
+            base = href[len(self.base_url) + 1:].strip("/")
+        else:
+            raise ValueError(f"{dataset_id}: cannot locate features.parquet (href {asset.get('href')!r} is "
+                             f"outside {self.base_url})")
+        parts = list(asset["parts"])
+        zooms = sorted(int(z) for z in (asset.get("zooms") or {_zoom_of(p) for p in parts}))
+        full = asset.get("full_res_zoom")
+        return {"base": base, "parts": parts, "zooms": zooms,
+                "full_res_zoom": int(full) if full is not None else zooms[-1], "source": source}

mudm_mcp/facets.py

@@ -0,0 +1,68 @@
+"""query_facets — SQL over a dataset's facet store (a per-cell / per-neuron attribute table published
+as ONE parquet file next to the tiles), read in place over HTTP range requests: no download.
+
+Facet stores by assay: Xenium ``expression`` (long: cell_id, gene, count) · CODEX / CosMx / MERSCOPE /
+MIBI ``markers`` (wide: one column per marker or gene) · connectomes and reference anatomy ``properties``
+(wide: one row per neuron / structure with cell_type, synapse counts, …). Visium has none.
+"""
+from __future__ import annotations
+
+from .catalog_client import CatalogClient
+from .sandbox import open_sandbox, run_select
+from .tools import facet_assets
+
+MAX_SCHEMA_COLUMNS = 60
+
+
+def _names(cols: list[str], cap: int = MAX_SCHEMA_COLUMNS) -> str:
+    more = f", … (+{len(cols) - cap} more)" if len(cols) > cap else ""
+    return ", ".join(cols[:cap]) + more
+
+
+def query_facets(client: CatalogClient, dataset_id: str, sql: str, facet: str | None = None,
+                 max_rows: int = 200) -> dict:
+    """Run ONE read-only SELECT against a dataset's facet store, exposed as the view ``facets`` (the
+    store's own name, e.g. ``expression`` or ``properties``, works as an alias).
+
+    ``facet`` picks the store by name when a dataset has several. Returns the bounded result of
+    ``run_select`` plus ``facet``, ``source`` (the file's URL) and ``schema`` — the file's REAL columns,
+    which can differ from what the descriptor advertises (``missing_columns`` lists advertised-but-absent
+    ones)."""
+    import duckdb  # lazy
+
+    client.entry(dataset_id)  # unknown id -> DatasetNotFound with suggestions
+    stores = facet_assets(client, dataset_id)
+    if not stores:
+        raise ValueError(f"{dataset_id} has no facet store (Visium datasets have none). "
+                         "describe_dataset lists a dataset's facets; download + query reads the features.")
+    names = [s["name"] for s in stores]
+    if facet:
+        store = next((s for s in stores if s["name"] == facet), None)
+        if store is None:
+            raise ValueError(f"{dataset_id} has no facet store named {facet!r}; available: {', '.join(names)}")
+    elif len(stores) > 1:
+        raise ValueError(f"{dataset_id} has several facet stores; pass facet= one of: {', '.join(names)}")
+    else:
+        store = stores[0]
+
+    con = open_sandbox("facets", store["url"])
+    try:
+        # Agents often write FROM <store name> (e.g. FROM expression) because that is the name
+        # describe_dataset shows: accept it as an alias of the `facets` view instead of failing.
+        if store["name"].isidentifier() and store["name"].lower() != "facets":
+            con.execute(f'CREATE VIEW "{store["name"]}" AS SELECT * FROM facets')
+        schema = [{"name": r[0], "type": r[1]} for r in con.execute("DESCRIBE facets").fetchall()]
+        cols = [c["name"] for c in schema]
+        try:
+            result = run_select(con, sql, max_rows=max_rows)
+        except (duckdb.BinderException, duckdb.CatalogException) as exc:
+            first = str(exc).split("\n", 1)[0]
+            raise ValueError(f"{first} The view is named `facets`. Available columns: {_names(cols)}") from exc
+    finally:
+        con.close()
+    out = {**result, "facet": store["name"], "layout": store["layout"], "source": store["url"],
+           "n_columns": len(schema), "schema": schema[:MAX_SCHEMA_COLUMNS]}
+    missing = [c for c in store["columns"] if c not in cols]
+    if missing:
+        out["missing_columns"] = missing[:MAX_SCHEMA_COLUMNS]
+    return out

mudm_mcp/geometry.py

@@ -0,0 +1,56 @@
+"""Decode muDM binary tile geometry (the `features.parquet` `positions`/`indices`/`ring_lengths` columns).
+
+This is muDM's OWN binary layout — **NOT GeoParquet/WKB**, so `ST_*`/`shapely.wkb` do not apply. Verified
+against real `features.parquet` leaves (2026-06-23):
+  - `positions` = packed little-endian float32, vertices interleaved `[x,y(,z)…]` (image-pixel µm, NOT lon/lat).
+  - `indices`   = packed little-endian uint32 triangle indices — present only for mesh types; EMPTY for
+                  point/line/polygon.
+  - `ring_lengths` = per-ring vertex counts (polygons/lines); EMPTY for points.
+  - point  `geom_type=1`: 8 bytes → 1 vertex, no rings.   polygon `geom_type=3`: packed verts + ring_lengths.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+# OGC-style geometry-type codes used by muDM tile geometry.
+POINT, LINESTRING, POLYGON = 1, 2, 3
+
+
+def decode_geometry(
+    positions: bytes,
+    indices: bytes,
+    ring_lengths,
+    geom_type: int,
+    dims: int | None = None,
+) -> dict:
+    """Decode one muDM tile-geometry row into NumPy arrays (zero-copy via ``frombuffer``).
+
+    Args:
+        positions: packed little-endian float32 vertex coordinates (`[x,y(,z)…]`).
+        indices: packed little-endian uint32 triangle indices (mesh types; ``b""`` otherwise).
+        ring_lengths: per-ring vertex counts (polygons/lines); empty/None for points.
+        geom_type: OGC-style code (1=Point, 2=LineString, 3=Polygon; mesh types carry ``indices``).
+        dims: 2 or 3. If None, inferred from ``ring_lengths`` (or a single-vertex point), defaulting to 2.
+
+    Returns:
+        ``{geom_type, dims, coords: float32[N,dims], rings?: [float32[ni,dims]], triangles?: uint32[T,3]}``.
+    """
+    floats = np.frombuffer(positions, dtype="<f4")
+    rings = [int(n) for n in (ring_lengths or [])]
+    if dims is None:
+        total = sum(rings)
+        if total:
+            dims = len(floats) // total
+        elif geom_type == POINT and len(floats):
+            dims = len(floats)  # a single vertex
+        else:
+            dims = 2
+    dims = int(dims) or 2
+    coords = floats.reshape(-1, dims)
+    out: dict = {"geom_type": int(geom_type), "dims": dims, "coords": coords}
+    if rings:
+        bounds = np.cumsum([0, *rings])
+        out["rings"] = [coords[bounds[i]:bounds[i + 1]] for i in range(len(rings))]
+    if indices:
+        out["triangles"] = np.frombuffer(indices, dtype="<u4").reshape(-1, 3)
+    return out

mudm_mcp/sandbox.py

@@ -0,0 +1,147 @@
+"""A locked-down DuckDB connection for agent-written SQL, and a bounded SELECT runner.
+
+The SQL comes from an LLM, so the connection may read exactly ONE source (a parquet file, a directory of
+parquet leaves, or one https URL) and nothing else: no other local files, no other URLs, no writes
+(COPY/ATTACH/EXPORT), no extension installs, and the configuration is locked so none of it can be
+switched back on. Results are capped in rows and in characters so they fit an MCP host's output budget.
+"""
+from __future__ import annotations
+
+import math
+from pathlib import Path
+from typing import Any
+
+MAX_ROWS_LIMIT = 5000
+MAX_CELL_CHARS = 500
+MAX_COLUMNS = 500
+MAX_RESULT_CHARS = 15_000  # serialized rows budget (the whole tool response must stay under 20k)
+
+
+def _q(text: str) -> str:
+    return str(text).replace("'", "''")
+
+
+def _ca_bundle() -> str | None:
+    try:
+        import certifi
+        return certifi.where()
+    except Exception:
+        return None
+
+
+def open_sandbox(view: str, source: str, *, is_dir: bool = False, hive: bool | None = None):
+    """A DuckDB connection whose only readable data is ``source``, exposed as the view ``view``.
+
+    ``source``: a local parquet file, a local directory (``is_dir=True`` → every ``*.parquet`` below
+    it), or an http(s) URL of one parquet file. ``hive``: force ``hive_partitioning`` on/off (default:
+    DuckDB's auto-detection). The caller closes the connection."""
+    import duckdb  # lazy
+
+    source = str(source)
+    remote = source.startswith(("http://", "https://"))
+    con = duckdb.connect()
+    try:
+        if remote:
+            con.execute("INSTALL httpfs")  # before the lockdown: installing needs file + network access
+            con.execute("LOAD httpfs")
+        con.execute("SET allow_persistent_secrets=false")  # else CREATE VIEW probes ~/.duckdb after lockdown
+        if is_dir:
+            root = str(Path(source).resolve())
+            con.execute(f"SET allowed_directories=['{_q(root)}/']")
+            scan_src = f"{root}/**/*.parquet"
+        else:
+            scan_src = source if remote else str(Path(source).resolve())
+            allowed = [scan_src]
+            if remote:
+                # DuckDB >= 2.0 reads a CA bundle from disk for TLS, which the lockdown would forbid:
+                # allow exactly one bundle (certifi's public root list) and point httpfs at it.
+                bundle = _ca_bundle()
+                if bundle:
+                    allowed.append(bundle)
+                    try:
+                        con.execute(f"SET ca_cert_file='{_q(bundle)}'")
+                    except duckdb.Error:
+                        pass  # older httpfs without the setting needs no bundle
+            con.execute("SET allowed_paths=[" + ", ".join(f"'{_q(a)}'" for a in allowed) + "]")
+        con.execute("SET enable_external_access=false")
+        opts = "" if hive is None else f", hive_partitioning={'true' if hive else 'false'}"
+        con.execute(f'CREATE VIEW "{view}" AS SELECT * FROM read_parquet(\'{_q(scan_src)}\'{opts})')
+        con.execute("SET lock_configuration=true")
+    except BaseException:
+        con.close()
+        raise
+    return con
+
+
+def jsonable(v: Any, cap: int = MAX_CELL_CHARS) -> Any:
+    """A JSON-safe, size-bounded rendering of one DuckDB value: strings are cut at ``cap`` characters,
+    nested values (maps, lists, structs) at ``4 * cap`` characters of their JSON."""
+    if v is None or isinstance(v, (bool, int)):
+        return v
+    if isinstance(v, float):
+        return v if math.isfinite(v) else None
+    if isinstance(v, (bytes, bytearray, memoryview)):
+        return f"<binary {len(v)}B>"  # muDM geometry blobs: decode via sample_patches / count_features
+    if isinstance(v, str):
+        return v if len(v) <= cap else v[:cap] + "..."
+    if isinstance(v, (dict, list, tuple)):
+        import json
+        items = ({str(k): jsonable(x, cap) for k, x in list(v.items())[:100]} if isinstance(v, dict)
+                 else [jsonable(x, cap) for x in v[:100]])
+        text = json.dumps(items)
+        return items if len(text) <= 4 * cap else text[:4 * cap] + "..."
+    return jsonable(str(v), cap)  # dates, decimals, UUIDs, …
+
+
+def _single_select(con, sql: str) -> str:
+    import duckdb  # lazy
+
+    text = str(sql or "").strip()
+    while text.endswith(";"):
+        text = text[:-1].rstrip()
+    if not text:
+        raise ValueError("Empty SQL. Only a single SELECT statement is allowed.")
+    try:
+        statements = con.extract_statements(text)
+    except duckdb.Error as exc:
+        raise ValueError(f"SQL syntax error: {exc}") from exc
+    if len(statements) != 1 or statements[0].type != duckdb.StatementType.SELECT:
+        raise ValueError("Only a single SELECT statement is allowed.")
+    return text
+
+
+def run_select(con, sql: str, max_rows: int = 200) -> dict:
+    """Run one SELECT and return ``{"columns", "n_rows", "rows", "truncated"[, "note"]}``.
+
+    At most ``max_rows`` rows (clamped to 1..5000) and about 15,000 characters of rows come back;
+    ``truncated`` says whether more rows existed. A trailing ``;`` is accepted; anything that is not
+    exactly one SELECT raises ``ValueError``."""
+    import json
+
+    text = _single_select(con, sql)
+    max_rows = max(1, min(int(max_rows), MAX_ROWS_LIMIT))
+    rel = con.execute(text)
+    cols = [d[0] for d in rel.description]
+    if len(cols) > MAX_COLUMNS:
+        raise ValueError(f"The result has {len(cols)} columns; select at most {MAX_COLUMNS} "
+                         "(name the columns you need instead of SELECT *).")
+    # The column header and every cell share one character budget, so a wide result gets shorter cells
+    # and fewer rows rather than an oversized response.
+    budget = MAX_RESULT_CHARS - len(json.dumps(cols))
+    cap = max(16, min(MAX_CELL_CHARS, budget // (4 * max(1, len(cols)))))
+    fetched = rel.fetchmany(max_rows + 1)
+    rows, used, note = [], 0, None
+    for raw in fetched[:max_rows]:
+        row = [jsonable(v, cap) for v in raw]
+        used += len(json.dumps(row))  # ASCII-escaped: the worst case
+        if rows and used > budget:
+            note = (f"Stopped after {len(rows)} rows to keep the response small; select fewer columns, "
+                    "aggregate, or add LIMIT/OFFSET.")
+            break
+        rows.append(row)
+    truncated = len(fetched) > max_rows or note is not None
+    out = {"columns": cols, "n_rows": len(rows), "rows": rows, "truncated": truncated}
+    if truncated:
+        out["note"] = note or (f"More than {max_rows} rows matched; only the first {max_rows} are shown. "
+                               "Aggregate, filter, or raise max_rows (up to 5000).")
+    return out