focus-data-toolkit 0.11.0__py3-none-any.whl

focus_data_toolkit/studio/frontend/app.js

@@ -0,0 +1,214 @@
+"use strict";
+// Focus Data Toolkit Studio — minimal no-build client. The access token comes from the URL the
+// user opened (?token=…) and is sent on every API call; the full file is never loaded here.
+
+const TOKEN = new URLSearchParams(location.search).get("token") || "";
+const $ = (id) => document.getElementById(id);
+const state = { source: null, jobId: null, cwd: "", config: null };
+
+function withToken(url) {
+  return url + (url.includes("?") ? "&" : "?") + "token=" + encodeURIComponent(TOKEN);
+}
+async function api(path, { method = "GET", json, form } = {}) {
+  const opts = { method, headers: { "X-FDT-Token": TOKEN } };
+  if (json !== undefined) { opts.headers["Content-Type"] = "application/json"; opts.body = JSON.stringify(json); }
+  if (form !== undefined) { opts.body = form; }
+  const res = await fetch(path, opts);
+  const data = res.headers.get("content-type")?.includes("application/json") ? await res.json() : await res.text();
+  if (!res.ok) throw new Error((data && data.error) || ("HTTP " + res.status));
+  return data;
+}
+
+function setSource(source, label) {
+  state.source = source;
+  const el = $("sourceLabel");
+  el.textContent = "source: " + label;
+  el.classList.remove("hidden");
+  $("detectBtn").disabled = false;
+  $("convertBtn").disabled = false;
+}
+
+// --- tabs ---
+$("tabs").addEventListener("click", (e) => {
+  const btn = e.target.closest("button[data-tab]");
+  if (!btn) return;
+  document.querySelectorAll("#tabs button").forEach((b) => b.classList.toggle("active", b === btn));
+  ["server", "upload", "generate"].forEach((t) => $("tab-" + t).classList.toggle("hidden", t !== btn.dataset.tab));
+});
+
+// --- server file browser ---
+async function browse(subpath) {
+  const data = await api("/api/files?subpath=" + encodeURIComponent(subpath || ""));
+  state.cwd = data.path || "";
+  const crumbs = $("crumbs");
+  const parts = state.cwd ? state.cwd.split("/") : [];
+  crumbs.innerHTML = `<a data-p="">root</a>` + parts.map((p, i) =>
+    ` / <a data-p="${parts.slice(0, i + 1).join("/")}">${escapeHtml(p)}</a>`).join("");
+  crumbs.querySelectorAll("a").forEach((a) => a.onclick = () => browse(a.dataset.p));
+  const ul = $("browser");
+  ul.innerHTML = "";
+  for (const entry of data.entries) {
+    const li = document.createElement("li");
+    const rel = (state.cwd ? state.cwd + "/" : "") + entry.name;
+    li.className = entry.is_dir ? "dir" : "file";
+    li.innerHTML = `<span>${entry.is_dir ? "📁 " : "📄 "}${escapeHtml(entry.name)}</span>` +
+      `<span class="muted">${entry.is_dir ? "" : fmtSize(entry.size)}</span>`;
+    li.onclick = () => entry.is_dir ? browse(rel) : setSource({ path: rel }, rel);
+    ul.appendChild(li);
+  }
+}
+
+// --- upload ---
+$("uploadBtn").onclick = async () => {
+  const f = $("uploadFile").files[0];
+  if (!f) return;
+  const form = new FormData();
+  form.append("file", f);
+  try {
+    const r = await api("/api/upload", { method: "POST", form });
+    setSource({ source_id: r.source_id, source_name: r.source_name }, r.source_name + " (uploaded)");
+  } catch (e) { alert(e.message); }
+};
+
+// --- generate ---
+$("genBtn").onclick = async () => {
+  try {
+    const r = await api("/api/generate", { method: "POST", json: {
+      provider: $("genProvider").value, focus_version: $("genVersion").value,
+      rows: Number($("genRows").value), seed: Number($("genSeed").value),
+    }});
+    setSource({ source_id: r.source_id, source_name: r.source_name },
+      r.source_name + ` (generated, ${r.rows} rows)`);
+  } catch (e) { alert(e.message); }
+};
+
+// --- detect ---
+$("detectBtn").onclick = async () => {
+  try {
+    const r = await api("/api/detect", { method: "POST", json: state.source });
+    const out = $("detectOut");
+    out.textContent = `${r.dataset || "?"} · FOCUS ${r.detected_version || "?"} · confidence ${r.confidence} (score ${r.score})`
+      + (r.missing_columns?.length ? `\nmissing: ${r.missing_columns.join(", ")}` : "")
+      + (r.unknown_columns?.length ? `\nunknown: ${r.unknown_columns.join(", ")}` : "");
+    out.classList.remove("hidden");
+  } catch (e) { alert(e.message); }
+};
+
+// --- convert + progress (SSE) ---
+$("convertBtn").onclick = async () => {
+  try {
+    const body = Object.assign({}, state.source, {
+      mode: $("mode").value, output_format: $("format").value, on_exists: $("onExists").value,
+    });
+    const r = await api("/api/jobs", { method: "POST", json: body });
+    state.jobId = r.job_id;
+    $("resultCard").classList.add("hidden");
+    $("progressCard").classList.remove("hidden");
+    $("barFill").style.width = "0";
+    $("progressText").textContent = "starting…";
+    streamProgress(r.job_id);
+  } catch (e) { alert(e.message); }
+};
+
+function streamProgress(jobId) {
+  const es = new EventSource(withToken(`/api/jobs/${jobId}/events`));
+  es.onmessage = (ev) => {
+    const p = JSON.parse(ev.data);
+    const pct = p.fraction != null ? Math.round(p.fraction * 100) : null;
+    $("barFill").style.width = (pct != null ? pct : 8) + "%";
+    const total = p.total != null ? "/" + p.total.toLocaleString() : "";
+    $("progressText").textContent =
+      `${p.phase} · ${p.completed.toLocaleString()}${total} ${p.unit}` +
+      (pct != null ? ` (${pct}%)` : "") + (p.message ? ` — ${p.message}` : "");
+  };
+  es.addEventListener("done", (ev) => {
+    es.close();
+    $("barFill").style.width = "100%";
+    loadResult(jobId);
+  });
+  es.onerror = () => { es.close(); loadResult(jobId); };
+}
+
+$("cancelBtn").onclick = async () => {
+  if (state.jobId) { try { await api(`/api/jobs/${state.jobId}/cancel`, { method: "POST" }); } catch (e) {} }
+};
+
+// --- results ---
+async function loadResult(jobId) {
+  const r = await api(`/api/jobs/${jobId}/result`);
+  $("progressCard").classList.add("hidden");
+  $("resultCard").classList.remove("hidden");
+  const cls = r.status === "succeeded" ? "status-ok" : r.status === "cancelled" ? "status-warn" : "status-err";
+  $("resultStatus").innerHTML = `<span class="${cls}">${r.status}</span>` +
+    (r.error ? ` — ${escapeHtml(r.error)}` : "") +
+    (r.assumptions_present ? ` · <span class="status-warn">contains ASSUMED (synthetic) values</span>` : "");
+
+  const dt = $("datasets");
+  if (r.datasets) {
+    dt.innerHTML = "<tr><th>Dataset</th><th>Status</th><th>Conformance</th><th>Rows</th></tr>" +
+      Object.entries(r.datasets).map(([n, e]) =>
+        `<tr><td>${escapeHtml(n)}</td><td>${escapeHtml(e.status)}</td><td>${escapeHtml(e.conformance || "")}</td><td>${e.row_count ?? ""}</td></tr>`).join("");
+  } else { dt.innerHTML = ""; }
+
+  const dl = $("downloads");
+  dl.innerHTML = "";
+  const links = [];
+  const dataFiles = (r.files || []).filter((f) => !f.is_dir);
+  if (dataFiles.some((f) => f.name === "focus_1_4_manifest.json")) links.push(["manifest", `/api/jobs/${jobId}/manifest`]);
+  if (dataFiles.some((f) => f.name === "SHA256SUMS")) links.push(["checksums", `/api/jobs/${jobId}/checksums`]);
+  links.push(["diagnostics.json", `/api/jobs/${jobId}/diagnostics?format=json`]);
+  links.push(["diagnostics.csv", `/api/jobs/${jobId}/diagnostics?format=csv`]);
+  links.push(["summary.html", `/api/jobs/${jobId}/summary.html`]);
+  for (const f of dataFiles) links.push([f.name, `/api/jobs/${jobId}/download?file=${encodeURIComponent(f.name)}`]);
+  for (const [label, url] of links) {
+    const a = document.createElement("a");
+    a.href = withToken(url); a.textContent = "⬇ " + label; a.target = "_blank"; a.rel = "noopener";
+    dl.appendChild(a);
+  }
+
+  const sel = $("previewFile");
+  sel.innerHTML = "";
+  for (const f of (r.files || [])) {
+    if (/\.(csv|parquet)$/.test(f.name) || f.is_dir) {
+      const o = document.createElement("option"); o.value = f.name; o.textContent = f.name; sel.appendChild(o);
+    }
+  }
+}
+
+$("previewBtn").onclick = async () => {
+  const file = $("previewFile").value;
+  if (!state.jobId || !file) return;
+  try {
+    const p = await api(`/api/jobs/${state.jobId}/preview?file=${encodeURIComponent(file)}&limit=50`);
+    const cols = p.columns || [];
+    const head = "<tr>" + cols.map((c) => `<th>${escapeHtml(c)}</th>`).join("") + "</tr>";
+    const rows = (p.rows || []).map((row) =>
+      "<tr>" + cols.map((c) => `<td>${escapeHtml(String(row[c] ?? ""))}</td>`).join("") + "</tr>").join("");
+    $("previewTable").innerHTML = `<table>${head}${rows}</table>` +
+      `<p class="muted">rows ${p.offset}–${p.offset + (p.rows || []).length} (sampled)</p>`;
+  } catch (e) { alert(e.message); }
+};
+
+// --- helpers ---
+function escapeHtml(s) { return String(s).replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c])); }
+function fmtSize(n) { if (n == null) return ""; const u = ["B", "KB", "MB", "GB"]; let i = 0; while (n >= 1000 && i < u.length - 1) { n /= 1000; i++; } return n.toFixed(i ? 1 : 0) + " " + u[i]; }
+
+// --- init ---
+(async function init() {
+  if (!TOKEN) { $("tokenWarn").classList.remove("hidden"); return; }
+  try {
+    const cfg = await api("/api/config");
+    state.config = cfg;
+    $("rootLabel").textContent = cfg.root;
+    $("uploadCap").textContent = fmtSize(cfg.max_upload_bytes);
+    $("genNote").textContent = `max ${cfg.max_generate_rows.toLocaleString()} rows in the Studio; use the CLI/Runner for larger sets.`;
+    fill($("genProvider"), cfg.providers);
+    fill($("genVersion"), cfg.focus_versions);
+    fill($("format"), cfg.output_formats);
+    await browse("");
+  } catch (e) {
+    $("tokenWarn").classList.remove("hidden");
+    $("tokenWarn").innerHTML = "<strong>Cannot reach the Studio API.</strong> " + escapeHtml(e.message);
+  }
+})();
+function fill(sel, values) { sel.innerHTML = ""; for (const v of values) { const o = document.createElement("option"); o.value = v; o.textContent = v; sel.appendChild(o); } }

focus_data_toolkit/studio/frontend/index.html

@@ -0,0 +1,101 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Focus Data Toolkit Studio</title>
+  <link rel="stylesheet" href="/static/style.css">
+</head>
+<body>
+  <header>
+    <h1>Focus Data Toolkit <span class="badge">Studio</span></h1>
+    <p id="meta" class="muted">local · your data never leaves this machine</p>
+  </header>
+
+  <main>
+    <section id="tokenWarn" class="card warn hidden">
+      <strong>Missing access token.</strong> Open the URL printed by
+      <code>focus-toolkit ui</code> — it contains <code>?token=…</code>.
+    </section>
+
+    <section class="card">
+      <h2>1 · Source</h2>
+      <div class="tabs" id="tabs">
+        <button data-tab="server" class="active">Server file</button>
+        <button data-tab="upload">Upload</button>
+        <button data-tab="generate">Generate test data</button>
+      </div>
+
+      <div id="tab-server" class="tab">
+        <p class="muted">Files under the allowed root (<code id="rootLabel"></code>). Best for large files.</p>
+        <div id="crumbs" class="crumbs"></div>
+        <ul id="browser" class="browser"></ul>
+      </div>
+
+      <div id="tab-upload" class="tab hidden">
+        <p class="muted">For small/medium files only (capped, <span id="uploadCap"></span>).</p>
+        <input type="file" id="uploadFile">
+        <button id="uploadBtn">Upload</button>
+      </div>
+
+      <div id="tab-generate" class="tab hidden">
+        <div class="row">
+          <label>Provider <select id="genProvider"></select></label>
+          <label>FOCUS <select id="genVersion"></select></label>
+          <label>Rows <input type="number" id="genRows" value="1000" min="1"></label>
+          <label>Seed <input type="number" id="genSeed" value="1202"></label>
+        </div>
+        <button id="genBtn">Generate</button>
+        <p class="muted" id="genNote"></p>
+      </div>
+
+      <p id="sourceLabel" class="pill hidden"></p>
+      <button id="detectBtn" disabled>Detect</button>
+      <pre id="detectOut" class="hidden"></pre>
+    </section>
+
+    <section class="card">
+      <h2>2 · Convert</h2>
+      <div class="row">
+        <label>Mode
+          <select id="mode">
+            <option value="strict">strict</option>
+            <option value="synthetic">synthetic</option>
+          </select>
+        </label>
+        <label>Output <select id="format"></select></label>
+        <label>On exists
+          <select id="onExists">
+            <option value="refuse">refuse</option>
+            <option value="replace">replace</option>
+            <option value="version">version</option>
+          </select>
+        </label>
+      </div>
+      <button id="convertBtn" disabled>Convert</button>
+    </section>
+
+    <section class="card hidden" id="progressCard">
+      <h2>3 · Progress</h2>
+      <div class="bar"><div id="barFill"></div></div>
+      <p id="progressText" class="muted">starting…</p>
+      <button id="cancelBtn">Cancel</button>
+    </section>
+
+    <section class="card hidden" id="resultCard">
+      <h2>4 · Results</h2>
+      <p id="resultStatus"></p>
+      <table id="datasets" class="grid"></table>
+      <div id="downloads" class="downloads"></div>
+      <h3>Preview <span class="muted">(sampled — the full file is never loaded)</span></h3>
+      <div class="row">
+        <label>File <select id="previewFile"></select></label>
+        <button id="previewBtn">Preview</button>
+      </div>
+      <div id="previewTable" class="scroll"></div>
+    </section>
+  </main>
+
+  <script src="/static/app.js"></script>
+</body>
+</html>

focus_data_toolkit/studio/frontend/style.css

@@ -0,0 +1,60 @@
+:root {
+  --bg: #ffffff; --fg: #1a1a1a; --muted: #666; --card: #f6f7f9; --border: #dcdfe4;
+  --accent: #2b6cb0; --accent-fg: #fff; --warn: #b7791f; --ok: #2f855a; --err: #c53030;
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #14171c; --fg: #e6e8eb; --muted: #9aa2ad; --card: #1c2027; --border: #2c323b;
+    --accent: #4a97e0; --accent-fg: #0b0e12; --warn: #d69e2e; --ok: #68d391; --err: #fc8181;
+  }
+}
+* { box-sizing: border-box; }
+body {
+  margin: 0; font: 15px/1.5 system-ui, -apple-system, Segoe UI, Roboto, sans-serif;
+  background: var(--bg); color: var(--fg);
+}
+header { padding: 1.2rem 1.5rem; border-bottom: 1px solid var(--border); }
+h1 { margin: 0; font-size: 1.4rem; }
+h2 { margin: 0 0 .8rem; font-size: 1.1rem; }
+h3 { margin: 1rem 0 .5rem; font-size: 1rem; }
+.badge { background: var(--accent); color: var(--accent-fg); border-radius: 6px; padding: 0 .4rem; font-size: .8rem; }
+.muted { color: var(--muted); }
+main { max-width: 900px; margin: 0 auto; padding: 1.2rem 1.5rem; display: grid; gap: 1.2rem; }
+.card { background: var(--card); border: 1px solid var(--border); border-radius: 10px; padding: 1.1rem 1.2rem; }
+.card.warn { border-color: var(--warn); }
+.hidden { display: none !important; }
+.row { display: flex; flex-wrap: wrap; gap: 1rem; align-items: end; margin-bottom: .8rem; }
+label { display: flex; flex-direction: column; gap: .25rem; font-size: .85rem; color: var(--muted); }
+select, input[type=number], input[type=file] {
+  font: inherit; padding: .4rem .5rem; border: 1px solid var(--border); border-radius: 6px;
+  background: var(--bg); color: var(--fg);
+}
+button {
+  font: inherit; padding: .45rem .9rem; border: 1px solid var(--accent); border-radius: 6px;
+  background: var(--accent); color: var(--accent-fg); cursor: pointer;
+}
+button:disabled { opacity: .5; cursor: not-allowed; }
+button.ghost { background: transparent; color: var(--accent); }
+.tabs { display: flex; gap: .3rem; margin-bottom: .8rem; }
+.tabs button { background: transparent; color: var(--fg); border-color: var(--border); }
+.tabs button.active { background: var(--accent); color: var(--accent-fg); border-color: var(--accent); }
+.browser { list-style: none; margin: 0; padding: 0; max-height: 260px; overflow: auto; border: 1px solid var(--border); border-radius: 6px; }
+.browser li { padding: .35rem .6rem; border-bottom: 1px solid var(--border); cursor: pointer; display: flex; justify-content: space-between; }
+.browser li:hover { background: var(--bg); }
+.browser li.dir { font-weight: 600; }
+.crumbs { margin-bottom: .5rem; font-size: .85rem; }
+.crumbs a { color: var(--accent); cursor: pointer; }
+.pill { display: inline-block; background: var(--bg); border: 1px solid var(--border); border-radius: 999px; padding: .2rem .7rem; }
+pre { background: var(--bg); border: 1px solid var(--border); border-radius: 6px; padding: .7rem; overflow: auto; }
+.bar { height: 12px; background: var(--bg); border: 1px solid var(--border); border-radius: 999px; overflow: hidden; }
+#barFill { height: 100%; width: 0; background: var(--accent); transition: width .2s; }
+table.grid, table.grid th, table.grid td { border: 1px solid var(--border); border-collapse: collapse; }
+table.grid { width: 100%; margin: .5rem 0; }
+table.grid th, table.grid td { padding: .35rem .5rem; text-align: left; font-size: .85rem; }
+.downloads { display: flex; flex-wrap: wrap; gap: .5rem; margin: .6rem 0; }
+.downloads a { color: var(--accent); text-decoration: none; border: 1px solid var(--border); border-radius: 6px; padding: .3rem .6rem; }
+.scroll { overflow-x: auto; }
+.scroll table { border-collapse: collapse; font-size: .8rem; }
+.scroll th, .scroll td { border: 1px solid var(--border); padding: .25rem .45rem; white-space: nowrap; }
+.status-ok { color: var(--ok); } .status-err { color: var(--err); } .status-warn { color: var(--warn); }
+code { background: var(--bg); padding: 0 .3rem; border-radius: 4px; }

focus_data_toolkit/studio/jobs.py

@@ -0,0 +1,142 @@
+"""Background conversion jobs + managed sources for the Studio.
+
+By default a single worker runs one conversion at a time (extra submissions queue), so two large
+conversions cannot exhaust the machine. Each job/source gets its own directory under the work
+root; a TTL sweep (and a startup sweep) removes old ones and recovers any interrupted atomic
+publishes. Conversions run the Core streaming engine with the progress/cancel hooks, so the
+Studio's outputs are identical to a CLI run and cancellation never leaves partial output.
+"""
+
+from __future__ import annotations
+
+import os
+import queue
+import shutil
+import threading
+import time
+import uuid
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from focus_data_toolkit.io.atomic_writer import clean_leftovers
+from focus_data_toolkit.studio.security import resolve_within_root
+
+
+@dataclass
+class Job:
+    """State of one conversion job (mutated by the worker thread; read by the API)."""
+
+    id: str
+    out_dir: Path
+    status: str = "queued"  # queued | running | succeeded | failed | cancelled
+    events: list[dict] = field(default_factory=list)
+    error: str | None = None
+    error_code: str | None = None
+    created: float = field(default_factory=time.monotonic)
+    cancel: threading.Event = field(default_factory=threading.Event)
+    finished: threading.Event = field(default_factory=threading.Event)
+
+    @property
+    def done(self) -> bool:
+        return self.status in ("succeeded", "failed", "cancelled")
+
+    def summary(self) -> dict:
+        last = self.events[-1] if self.events else None
+        return {
+            "id": self.id,
+            "status": self.status,
+            "error": self.error,
+            "error_code": self.error_code,
+            "last_event": last,
+            "event_count": len(self.events),
+        }
+
+
+class JobManager:
+    """Owns the work root, a bounded worker pool, and the job/source registries."""
+
+    def __init__(self, work_dir: Path, *, max_concurrency: int = 1, ttl_seconds: int = 86400):
+        self._work = Path(work_dir)
+        self._jobs_dir = self._work / "jobs"
+        self._sources_dir = self._work / "sources"
+        self._jobs_dir.mkdir(parents=True, exist_ok=True)
+        self._sources_dir.mkdir(parents=True, exist_ok=True)
+        self._ttl = ttl_seconds
+        self._jobs: dict[str, Job] = {}
+        self._lock = threading.Lock()
+        self._queue: queue.Queue = queue.Queue()
+        self._workers = [
+            threading.Thread(target=self._worker, name=f"fdt-studio-{i}", daemon=True)
+            for i in range(max(1, max_concurrency))
+        ]
+        for worker in self._workers:
+            worker.start()
+        self._sweep_disk_startup()
+
+    # --- managed sources (uploads / generated files) ------------------------------------
+    def new_source_dir(self) -> tuple[str, Path]:
+        source_id = uuid.uuid4().hex
+        path = self._sources_dir / source_id
+        path.mkdir(parents=True, exist_ok=True)
+        return source_id, path
+
+    def source_file(self, source_id: str, name: str) -> Path:
+        # Resolve the (user-supplied) id + name in one pass against the server-owned sources dir,
+        # so the confinement root is never itself derived from user input.
+        return resolve_within_root(os.path.join(source_id, name), self._sources_dir)
+
+    # --- jobs ---------------------------------------------------------------------------
+    def get(self, job_id: str) -> Job | None:
+        with self._lock:
+            return self._jobs.get(job_id)
+
+    def job_file(self, job_id: str, name: str) -> Path:
+        job = self.get(job_id)
+        if job is None:
+            raise KeyError(job_id)
+        return resolve_within_root(name, job.out_dir)
+
+    def submit_convert(self, run: Callable[[Job], None]) -> Job:
+        """Register a job and enqueue ``run(job)`` (executed on a worker thread)."""
+        self._sweep_ttl()
+        job_id = uuid.uuid4().hex
+        job_root = self._jobs_dir / job_id
+        job_root.mkdir(parents=True, exist_ok=True)
+        job = Job(id=job_id, out_dir=job_root / "result")
+        with self._lock:
+            self._jobs[job_id] = job
+        self._queue.put((job, run))
+        return job
+
+    def _worker(self) -> None:
+        while True:
+            job, run = self._queue.get()
+            try:
+                if job.cancel.is_set():
+                    job.status = "cancelled"
+                else:
+                    job.status = "running"
+                    run(job)
+            except Exception as exc:  # backstop: a job callable must never kill the worker
+                job.status = "failed"
+                job.error = f"{type(exc).__name__}: {exc}"
+            finally:
+                job.finished.set()
+                self._queue.task_done()
+
+    # --- cleanup ------------------------------------------------------------------------
+    def _sweep_ttl(self) -> None:
+        cutoff = time.monotonic() - self._ttl
+        stale = [j for j in list(self._jobs.values()) if j.done and j.created < cutoff]
+        for job in stale:
+            with self._lock:
+                self._jobs.pop(job.id, None)
+            shutil.rmtree(self._jobs_dir / job.id, ignore_errors=True)
+
+    def _sweep_disk_startup(self) -> None:
+        # Recover any interrupted atomic publish and drop leftover staging under the work root.
+        try:
+            clean_leftovers(self._work)
+        except OSError:
+            pass  # best-effort startup hygiene

focus_data_toolkit/studio/preview.py

@@ -0,0 +1,32 @@
+"""Bounded, paginated preview of a produced file — never materialises the whole dataset."""
+
+from __future__ import annotations
+
+import contextlib
+from pathlib import Path
+
+from focus_data_toolkit.io.row_source import open_row_source
+
+
+def sampled_page(
+    path: str | Path, *, dataset: str | None = None, offset: int = 0, limit: int = 50
+) -> dict:
+    """Return ``limit`` rows starting at ``offset`` from ``path`` (CSV/Parquet, incl. partitioned).
+
+    Reads at most ``offset + limit`` rows and stops — memory is bounded regardless of file size,
+    so a multi-GB result previews the same way a tiny one does. The full file is never loaded into
+    the backend or sent to the browser.
+    """
+    offset = max(0, offset)
+    limit = max(1, limit)
+    columns: list[str] = []
+    rows: list[dict[str, str]] = []
+    with contextlib.closing(open_row_source(path, dataset=dataset)) as reader:
+        columns = list(reader.source_columns)
+        for index, record in enumerate(reader):
+            if index < offset:
+                continue
+            if len(rows) >= limit:
+                break
+            rows.append(dict(record.values))
+    return {"columns": columns, "rows": rows, "offset": offset, "limit": limit}