local-data-studio 1.0.0__py3-none-any.whl

local_data_studio/server/api/datasets.py

@@ -0,0 +1,176 @@
+"""Dataset discovery, upload, preview, and sample endpoints."""
+
+import datetime
+import mimetypes
+from pathlib import Path
+from typing import Any
+
+from fastapi import APIRouter, File, HTTPException, Query, UploadFile
+from fastapi.responses import FileResponse
+
+from ..config import (
+    ALLOW_DELETE_DATA,
+    DATA_ROOT,
+    DEFAULT_LIMIT,
+    EMBEDDER_MODELS_DIR,
+    FILE_SERVE_ROOTS,
+    SINGLE_FILE,
+    UPLOAD_EXTENSIONS,
+    VIS_EXCLUDE_DIRS,
+    VIS_EXCLUDE_FILES,
+)
+from ..db import open_connection, quote_ident, relation_sql
+from ..deleted_rows import deleted_row_ids_for
+from ..embedder_capabilities import library_versions
+from ..embedder_models import discover_embedder_models
+from ..files import refresh_dataset_file_catalog, resolve_data_file, resolve_raw_image_file, unique_path
+from ..readers import fetch_preview_page, fetch_raw_row, load_dataset_metadata
+from ..serialization import serialize_raw_value, serialize_value
+from ..sql import fetch_raw_query_row_guarded
+from .schemas import RawRowRequest
+from .services import reject_large_sync_operation
+
+router = APIRouter()
+UPLOAD_FILES = File(...)
+
+
+@router.get("/api/files")
+def list_files() -> dict[str, Any]:
+    """Refresh the dataset allowlist and return file sizes and modification times."""
+    files: list[dict[str, Any]] = []
+    for name, path in refresh_dataset_file_catalog().items():
+        stat = path.stat()
+        files.append(
+            {
+                "name": name,
+                "size": stat.st_size,
+                "modified": datetime.datetime.fromtimestamp(stat.st_mtime).isoformat(),
+            }
+        )
+    return {"files": files}
+
+
+@router.get("/api/config")
+def get_config() -> dict[str, Any]:
+    """Return non-secret UI configuration and local file-serving roots."""
+    return {
+        "allow_delete_data": ALLOW_DELETE_DATA,
+        "file_serve_roots": [str(path) for path in FILE_SERVE_ROOTS],
+        "vis_exclude_dirs": VIS_EXCLUDE_DIRS,
+        "vis_exclude_files": VIS_EXCLUDE_FILES,
+    }
+
+
+@router.get("/api/embedder_models")
+def embedder_models() -> dict[str, Any]:
+    """Discover locally installed encoder model directories."""
+    return {"models": discover_embedder_models(EMBEDDER_MODELS_DIR), "libraries": library_versions()}
+
+
+@router.get("/api/raw")
+def raw_file(path: str = Query(..., description="Absolute file path on the server")) -> FileResponse:
+    """Serve an allowed local image path after root-boundary validation."""
+    resolved = resolve_raw_image_file(path, FILE_SERVE_ROOTS)
+    media_type, _ = mimetypes.guess_type(str(resolved))
+    return FileResponse(str(resolved), media_type=media_type or "application/octet-stream")
+
+
+@router.post("/api/upload")
+async def upload_files(files: list[UploadFile] = UPLOAD_FILES) -> dict[str, Any]:
+    """Stream supported uploads into the data directory in 1 MiB chunks.
+
+    Filenames are reduced to their basename and collisions receive a unique suffix.
+    Unsupported uploads are closed and reported without being written.
+
+    Raises:
+        HTTPException: Uploads are disabled or no supported file was supplied.
+    """
+    if SINGLE_FILE:
+        raise HTTPException(status_code=400, detail="uploads are disabled")
+    DATA_ROOT.mkdir(parents=True, exist_ok=True)
+    saved: list[str] = []
+    skipped: list[str] = []
+
+    for upload in files:
+        filename = Path(upload.filename or "").name
+        if not filename:
+            continue
+        if Path(filename).suffix.lower() not in UPLOAD_EXTENSIONS:
+            skipped.append(filename)
+            await upload.close()
+            continue
+        destination = unique_path(DATA_ROOT, filename)
+        with destination.open("wb") as output:
+            while chunk := await upload.read(1024 * 1024):
+                output.write(chunk)
+        await upload.close()
+        saved.append(destination.name)
+
+    if not saved:
+        raise HTTPException(status_code=400, detail="unsupported file extension")
+    refresh_dataset_file_catalog()
+    return {"saved": saved, "skipped": skipped}
+
+
+@router.get("/api/schema")
+def get_schema(file: str = Query(...)) -> dict[str, Any]:
+    """Return bounded format-specific metadata for an allowlisted dataset."""
+    metadata = load_dataset_metadata(resolve_data_file(file))
+    return metadata.to_response(file)
+
+
+@router.get("/api/preview")
+def preview(
+    file: str = Query(...),
+    limit: int | None = Query(DEFAULT_LIMIT),
+    offset: int | None = Query(0),
+    page_token: str | None = Query(None),
+) -> dict[str, Any]:
+    """Return one bounded preview page using a cursor token when supplied."""
+    path = resolve_data_file(file)
+    return fetch_preview_page(file, path, limit=limit, offset=offset, page_token=page_token, deleted_ids=deleted_row_ids_for(path))
+
+
+@router.post("/api/raw_row")
+def raw_row(payload: RawRowRequest) -> dict[str, Any]:
+    """Return an untruncated dataset row or validated SQL result row.
+
+    Raises:
+        HTTPException: Neither a one-based dataset row ID nor SQL was supplied.
+    """
+    path = resolve_data_file(payload.file)
+    if payload.row_id is not None:
+        columns, values = fetch_raw_row(path, payload.row_id)
+        row_id = payload.row_id
+    elif payload.sql:
+        columns, values = fetch_raw_query_row_guarded(path=path, sql=payload.sql, offset=max(0, payload.offset or 0))
+        row_id = None
+    else:
+        raise HTTPException(status_code=400, detail="row_id or sql is required")
+    return {
+        "file": payload.file,
+        "row_id": row_id,
+        "columns": columns,
+        "row": [serialize_raw_value(value) for value in values],
+    }
+
+
+@router.get("/api/column_sample")
+def column_sample(
+    file: str = Query(...),
+    column: str = Query(...),
+    limit: int | None = Query(20),
+) -> dict[str, Any]:
+    """Return up to 100 serialized non-null values from one column."""
+    path = resolve_data_file(file)
+    reject_large_sync_operation(path, "synchronous column sample")
+    relation, params = relation_sql(path)
+    limit_value = max(1, min(100, limit or 20))
+    quoted_column = quote_ident(column)
+    with open_connection() as connection:
+        sample = connection.execute(
+            f"SELECT {quoted_column} FROM {relation} WHERE {quoted_column} IS NOT NULL LIMIT {limit_value}",
+            params,
+        )
+        rows = [serialize_value(row[0]) for row in sample.fetchall()]
+    return {"file": file, "column": column, "values": rows}

local_data_studio/server/api/jobs.py

@@ -0,0 +1,231 @@
+"""Background job API endpoints."""
+
+from typing import Any, cast
+
+from fastapi import APIRouter, HTTPException, Request
+
+from ..atlas_components.runtime import AtlasRuntime
+from ..cache import count_cache_path, search_cache_path
+from ..config import ATLAS_MAX_INSTANCES
+from ..db import normalize_pagination
+from ..deleted_rows import deleted_row_ids_for
+from ..files import resolve_data_file
+from ..jobs import JOB_STORE, JobContext, JobStore
+from ..readers import build_line_index_with_progress, count_rows_with_progress, search_dataset
+from ..sql import execute_query_guarded
+from .schemas import (
+    AtlasQueryRequest,
+    AtlasRequest,
+    CountJobRequest,
+    EdaQueryRequest,
+    EdaRequest,
+    IndexJobRequest,
+    QueryRequest,
+    SearchJobRequest,
+    StatsJobRequest,
+)
+from .services import atlas_service, compute_cached_column_stats, eda_reports_service, load_cached_result, write_cached_result
+
+router = APIRouter()
+DEFAULT_ATLAS_RUNTIME = AtlasRuntime(max_instances=ATLAS_MAX_INSTANCES)
+REQUEST_DEFAULT = cast(Request, None)
+
+
+def _job_store(request: Request | None) -> JobStore:
+    if request is not None:
+        return request.app.state.job_store
+    return JOB_STORE
+
+
+def _atlas_runtime(request: Request | None) -> AtlasRuntime:
+    if request is not None:
+        return request.app.state.atlas_runtime
+    return DEFAULT_ATLAS_RUNTIME
+
+
+@router.post("/api/jobs/count")
+def start_count_job(payload: CountJobRequest, request: Request = REQUEST_DEFAULT) -> dict[str, Any]:
+    """Submit a cancellable row-count job with fingerprinted cache reuse."""
+    path = resolve_data_file(payload.file)
+    deleted_ids = deleted_row_ids_for(path)
+
+    def _work(context: JobContext) -> dict[str, Any]:
+        cache_path = count_cache_path(path, deleted_ids=deleted_ids)
+        cached = load_cached_result(cache_path)
+        if cached is not None and isinstance(cached.get("count"), int):
+            context.update(progress=1.0, message="Count loaded from cache")
+            return {**cached, "cached": True}
+        result = {"file": payload.file, "count": count_rows_with_progress(path, context, deleted_ids=deleted_ids)}
+        write_cached_result(cache_path, result)
+        return {**result, "cached": False}
+
+    return _job_store(request).submit("count", _work).to_response()
+
+
+@router.post("/api/jobs/index")
+def start_index_job(payload: IndexJobRequest, request: Request = REQUEST_DEFAULT) -> dict[str, Any]:
+    """Submit incremental sparse-index construction for a line dataset."""
+    path = resolve_data_file(payload.file)
+
+    def _work(context: JobContext) -> dict[str, Any]:
+        return {"file": payload.file, **build_line_index_with_progress(path, context)}
+
+    return _job_store(request).submit("index", _work).to_response()
+
+
+@router.post("/api/jobs/search")
+def start_search_job(payload: SearchJobRequest, request: Request = REQUEST_DEFAULT) -> dict[str, Any]:
+    """Submit a cancellable bounded search with fingerprinted cache reuse."""
+    path = resolve_data_file(payload.file)
+    deleted_ids = deleted_row_ids_for(path)
+    search_term = payload.query.strip()
+    limit_value, _ = normalize_pagination(payload.limit, 0)
+
+    def _work(context: JobContext) -> dict[str, Any]:
+        cache_path = search_cache_path(path, query=search_term, limit=limit_value, deleted_ids=deleted_ids)
+        cached = load_cached_result(cache_path)
+        if cached is not None and cached.get("query") == search_term:
+            context.update(progress=1.0, message="Search loaded from cache")
+            return {**cached, "cached": True}
+        result = search_dataset(payload.file, path, query=search_term, limit=limit_value, control=context, deleted_ids=deleted_ids)
+        write_cached_result(cache_path, result)
+        return {**result, "cached": False}
+
+    return _job_store(request).submit("search", _work).to_response()
+
+
+@router.post("/api/jobs/query")
+def start_query_job(payload: QueryRequest, request: Request = REQUEST_DEFAULT) -> dict[str, Any]:
+    """Submit validated read-only SQL under query resource limits."""
+    path = resolve_data_file(payload.file)
+
+    def _work(context: JobContext) -> dict[str, Any]:
+        return execute_query_guarded(
+            file_name=payload.file,
+            path=path,
+            sql=payload.sql,
+            limit=payload.limit,
+            offset=payload.offset,
+            context=context,
+        )
+
+    return _job_store(request).submit("query", _work).to_response()
+
+
+@router.post("/api/jobs/stats")
+def start_stats_job(payload: StatsJobRequest, request: Request = REQUEST_DEFAULT) -> dict[str, Any]:
+    """Submit bounded column sampling with optional cache refresh."""
+    path = resolve_data_file(payload.file)
+
+    def _work(context: JobContext) -> dict[str, Any]:
+        context.update(progress=0.15, message="Sampling rows")
+        result = compute_cached_column_stats(payload.file, path, payload.sample, bool(payload.force))
+        context.update(progress=1.0, message="Stats ready")
+        return result
+
+    return _job_store(request).submit("stats", _work).to_response()
+
+
+@router.post("/api/jobs/eda")
+def start_eda_job(payload: EdaRequest, request: Request = REQUEST_DEFAULT) -> dict[str, Any]:
+    """Submit EDA generation for a bounded dataset sample."""
+    path = resolve_data_file(payload.file)
+    reports = eda_reports_service()
+
+    def _work(context: JobContext) -> dict[str, Any]:
+        return reports.generate_dataset_eda_report(
+            file_name=payload.file,
+            path=path,
+            sample=payload.sample,
+            mode=payload.mode,
+            force=payload.force,
+            context=context,
+        )
+
+    return _job_store(request).submit("eda", _work).to_response()
+
+
+@router.post("/api/jobs/eda_query")
+def start_eda_query_job(payload: EdaQueryRequest, request: Request = REQUEST_DEFAULT) -> dict[str, Any]:
+    """Submit EDA generation for validated SQL query results."""
+    path = resolve_data_file(payload.file)
+    reports = eda_reports_service()
+
+    def _work(context: JobContext) -> dict[str, Any]:
+        return reports.generate_query_eda_report(
+            file_name=payload.file,
+            path=path,
+            sql=payload.sql,
+            sample=payload.sample,
+            mode=payload.mode,
+            force=payload.force,
+            context=context,
+        )
+
+    return _job_store(request).submit("eda_query", _work).to_response()
+
+
+@router.post("/api/jobs/atlas")
+def start_atlas_job(payload: AtlasRequest, request: Request = REQUEST_DEFAULT) -> dict[str, Any]:
+    """Submit embedding and Atlas startup for a dataset column."""
+    path = resolve_data_file(payload.file)
+    atlas = atlas_service()
+
+    def _work(context: JobContext) -> dict[str, Any]:
+        return atlas.run_atlas_visualization(
+            file_name=payload.file,
+            path=path,
+            column=payload.column,
+            model=payload.model,
+            backend=payload.backend,
+            prompt=payload.prompt,
+            projection_method=payload.projection_method,
+            sql=None,
+            sample=payload.sample,
+            context=context,
+            runtime=_atlas_runtime(request),
+        )
+
+    return _job_store(request).submit("atlas", _work).to_response()
+
+
+@router.post("/api/jobs/atlas_query")
+def start_atlas_query_job(payload: AtlasQueryRequest, request: Request = REQUEST_DEFAULT) -> dict[str, Any]:
+    """Submit embedding and Atlas startup for validated SQL results."""
+    path = resolve_data_file(payload.file)
+    atlas = atlas_service()
+
+    def _work(context: JobContext) -> dict[str, Any]:
+        return atlas.run_atlas_visualization(
+            file_name=payload.file,
+            path=path,
+            column=payload.column,
+            model=payload.model,
+            backend=payload.backend,
+            prompt=payload.prompt,
+            projection_method=payload.projection_method,
+            sql=payload.sql,
+            sample=payload.sample,
+            context=context,
+            runtime=_atlas_runtime(request),
+        )
+
+    return _job_store(request).submit("atlas_query", _work).to_response()
+
+
+@router.get("/api/jobs/{job_id}")
+def get_job(job_id: str, request: Request = REQUEST_DEFAULT) -> dict[str, Any]:
+    """Return a detached snapshot of a job, or HTTP 404 when unknown."""
+    record = _job_store(request).get(job_id)
+    if record is None:
+        raise HTTPException(status_code=404, detail="job not found")
+    return record.to_response()
+
+
+@router.post("/api/jobs/{job_id}/cancel")
+def cancel_job(job_id: str, request: Request = REQUEST_DEFAULT) -> dict[str, Any]:
+    """Request cooperative cancellation, or return HTTP 404 when unknown."""
+    record = _job_store(request).cancel(job_id)
+    if record is None:
+        raise HTTPException(status_code=404, detail="job not found")
+    return record.to_response()

local_data_studio/server/api/mutations.py

@@ -0,0 +1,63 @@
+"""Dataset row and column mutation endpoints."""
+
+from pathlib import Path
+from typing import Any
+
+from fastapi import APIRouter, HTTPException
+
+from ..config import ALLOW_DELETE_DATA, HARD_DELETE_MAX_BYTES
+from ..db import count_relation_rows_raw
+from ..delete_ops import delete_column_from_file, delete_row_from_file
+from ..deleted_rows import add_deleted_row_id, clear_deleted_row_ids, deleted_row_ids_for
+from ..files import resolve_data_file
+from .schemas import DeleteColumnRequest, DeleteRowRequest
+
+router = APIRouter()
+
+
+def _reject_large_hard_delete(path: Path) -> None:
+    if path.stat().st_size > HARD_DELETE_MAX_BYTES:
+        raise HTTPException(
+            status_code=400,
+            detail="delete from file rewrites the dataset and is disabled for large files; use hide only",
+        )
+
+
+@router.post("/api/delete_row")
+def delete_row(payload: DeleteRowRequest) -> dict[str, Any]:
+    """Hide a row or rewrite a small dataset when persistent deletion is allowed.
+
+    Row IDs are one-based. Persistent deletion clears all soft-deleted row IDs.
+    """
+    path = resolve_data_file(payload.file)
+    row_id = int(payload.row_id)
+    if row_id < 1:
+        raise HTTPException(status_code=400, detail="row_id must be positive")
+    if payload.persist:
+        if not ALLOW_DELETE_DATA:
+            raise HTTPException(status_code=403, detail="delete from file is disabled")
+        _reject_large_hard_delete(path)
+        total_rows = count_relation_rows_raw(path)
+        if row_id > total_rows:
+            raise HTTPException(status_code=404, detail="row not found")
+        delete_row_from_file(path, row_id)
+        clear_deleted_row_ids(path)
+        return {"file": payload.file, "row_id": row_id, "persisted": True, "total_rows": max(0, total_rows - 1)}
+    add_deleted_row_id(path, row_id)
+    return {"file": payload.file, "row_id": row_id, "persisted": False, "deleted_count": len(deleted_row_ids_for(path))}
+
+
+@router.post("/api/delete_column")
+def delete_column(payload: DeleteColumnRequest) -> dict[str, Any]:
+    """Acknowledge a soft column hide or persistently rewrite a small dataset."""
+    path = resolve_data_file(payload.file)
+    column = payload.column.strip()
+    if not column:
+        raise HTTPException(status_code=400, detail="column is required")
+    if payload.persist:
+        if not ALLOW_DELETE_DATA:
+            raise HTTPException(status_code=403, detail="delete from file is disabled")
+        _reject_large_hard_delete(path)
+        delete_column_from_file(path, column)
+        return {"file": payload.file, "column": column, "persisted": True}
+    return {"file": payload.file, "column": column, "persisted": False}

local_data_studio/server/api/schemas.py

@@ -0,0 +1,117 @@
+"""Request schemas shared by Local Data Studio API routers."""
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class QueryRequest(BaseModel):
+    """Input for a guarded read-only SQL query."""
+
+    file: str = Field(min_length=1)
+    sql: str = Field(min_length=1)
+    limit: int | None = Field(default=None, ge=1)
+    offset: int | None = Field(default=None, ge=0)
+
+
+class RawRowRequest(BaseModel):
+    """Input selecting either a one-based dataset row or SQL result offset."""
+
+    file: str = Field(min_length=1)
+    row_id: int | None = Field(default=None, ge=1)
+    sql: str | None = None
+    offset: int | None = Field(default=None, ge=0)
+
+
+class EdaRequest(BaseModel):
+    """Input controlling bounded EDA generation and report cache reuse."""
+
+    file: str = Field(min_length=1)
+    sample: int | None = None
+    force: bool | None = None
+    mode: Literal["minimal", "maximal"] | None = None
+
+    @field_validator("sample")
+    @classmethod
+    def validate_sample(cls, value: int | None) -> int | None:
+        """Accept the unlimited marker or a positive row limit."""
+        if value is None or value == -1 or value >= 1:
+            return value
+        raise ValueError("sample must be -1 or an integer greater than or equal to 1")
+
+
+class EdaQueryRequest(EdaRequest):
+    """EDA input extended with the guarded SQL that supplies report rows."""
+
+    sql: str = Field(min_length=1)
+
+
+class AtlasRequest(BaseModel):
+    """Input selecting a dataset column and local model for Atlas embedding."""
+
+    file: str = Field(min_length=1)
+    column: str = Field(min_length=1)
+    model: str = Field(min_length=1)
+    sample: int | None = Field(default=None, ge=0)
+    backend: Literal["transformers", "sentence-transformers"] | None = None
+    prompt: str | None = Field(default=None, max_length=16_384)
+    projection_method: Literal["umap", "tsne", "pca"] = "umap"
+
+
+class AtlasQueryRequest(AtlasRequest):
+    """Atlas input extended with the guarded SQL that supplies embedding rows."""
+
+    sql: str = Field(min_length=1)
+
+
+class CountJobRequest(BaseModel):
+    """Input for a background row-count operation."""
+
+    file: str = Field(min_length=1)
+
+
+class IndexJobRequest(BaseModel):
+    """Input for incremental sparse-index construction."""
+
+    file: str = Field(min_length=1)
+
+
+class SearchJobRequest(BaseModel):
+    """Input for a bounded background dataset search."""
+
+    file: str = Field(min_length=1)
+    query: str = Field(min_length=1)
+    limit: int | None = Field(default=None, ge=1)
+
+
+class StatsJobRequest(BaseModel):
+    """Input controlling sampled statistics and cache refresh."""
+
+    file: str = Field(min_length=1)
+    sample: int | None = None
+    force: bool | None = None
+
+
+class DeleteRowRequest(BaseModel):
+    """Input for one-based soft or persistent row deletion."""
+
+    file: str = Field(min_length=1)
+    row_id: int = Field(ge=1)
+    persist: bool | None = None
+
+
+class DeleteColumnRequest(BaseModel):
+    """Input for soft or persistent column deletion."""
+
+    file: str = Field(min_length=1)
+    column: str = Field(min_length=1)
+    persist: bool | None = None
+
+
+class NLQueryRequest(BaseModel):
+    """Input for natural-language SQL generation with optional sample context."""
+
+    file: str = Field(min_length=1)
+    prompt: str = Field(min_length=1, max_length=16_384)
+    sample: dict[str, Any] | None = None
+    model: str | None = Field(default=None, max_length=64)

local_data_studio/server/api/services.py

@@ -0,0 +1,99 @@
+"""Small shared services used by API routers."""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from fastapi import HTTPException
+
+from ..cache import stats_cache_path
+from ..config import DEFAULT_SAMPLE
+from ..sql import is_large_dataset
+from ..stats import compute_column_stats
+
+
+def atlas_service() -> Any:
+    """Import the optional ML stack only when an Atlas job is requested."""
+    from .. import atlas  # noqa: PLC0415
+
+    return atlas
+
+
+def eda_reports_service() -> Any:
+    """Import profiling dependencies only when an EDA operation is requested."""
+    try:
+        from .. import eda_reports  # noqa: PLC0415
+    except ImportError as exc:
+        raise HTTPException(status_code=500, detail=f"EDA dependencies could not be loaded: {exc}") from exc
+    return eda_reports
+
+
+def reject_large_sync_operation(path: Path, operation: str) -> None:
+    """Reject potentially blocking full scans above the large-dataset threshold."""
+    if is_large_dataset(path):
+        raise HTTPException(
+            status_code=400,
+            detail=f"{operation} can scan the full dataset; use the background job endpoint for large files",
+        )
+
+
+def load_cached_result(cache_path: Path) -> dict[str, Any] | None:
+    """Load an object-shaped JSON cache, treating missing or invalid data as a miss."""
+    if not cache_path.exists():
+        return None
+    try:
+        payload = json.loads(cache_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    return payload if isinstance(payload, dict) else None
+
+
+def write_cached_result(cache_path: Path, result: dict[str, Any]) -> None:
+    """Atomically replace a JSON cache file with the supplied result.
+
+    The caller retains ownership of ``result``; this function does not mutate it.
+    """
+    cache_path.parent.mkdir(parents=True, exist_ok=True)
+    temporary_path: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="w",
+            encoding="utf-8",
+            dir=cache_path.parent,
+            prefix=f".{cache_path.name}.",
+            suffix=".tmp",
+            delete=False,
+        ) as temporary:
+            json.dump(result, temporary, ensure_ascii=False, indent=2)
+            temporary.flush()
+            os.fsync(temporary.fileno())
+            temporary_path = Path(temporary.name)
+        os.replace(temporary_path, cache_path)
+        temporary_path = None
+    finally:
+        if temporary_path is not None:
+            temporary_path.unlink(missing_ok=True)
+
+
+def _load_cached_stats(path: Path, sample: int) -> dict[str, Any] | None:
+    payload = load_cached_result(stats_cache_path(path))
+    if payload is None or payload.get("sample_request") != sample:
+        return None
+    result = payload.get("result")
+    return result if isinstance(result, dict) else None
+
+
+def compute_cached_column_stats(file_name: str, path: Path, sample: int | None, force: bool) -> dict[str, Any]:
+    """Compute or reuse statistics keyed by dataset fingerprint and sample size."""
+    sample_value = sample if sample is not None else DEFAULT_SAMPLE
+    if not force:
+        cached = _load_cached_stats(path, sample_value)
+        if cached is not None:
+            return {**cached, "cached": True}
+    result = compute_column_stats(file_name, path, sample_value)
+    write_cached_result(stats_cache_path(path), {"sample_request": sample_value, "result": result})
+    return {**result, "cached": False}