Initialize jaguar HyperView multigeometry Space

.dockerignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+*.so
+.venv/
+dataset_build/

.gitignore

@@ -0,0 +1,7 @@
+assets/*
+!assets/.gitkeep
+dataset_build/
+dataset_build_smoke/
+assets_runtime_smoke/
+__pycache__/
+scripts/__pycache__/

Dockerfile

@@ -0,0 +1,38 @@
+FROM python:3.11-slim
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    curl \
+    git \
+    libssl-dev \
+    pkg-config \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN useradd -m -u 1000 user
+USER user
+
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH \
+    HF_HOME=/home/user/.cache/huggingface \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    HYPERVIEW_DATASETS_DIR=/home/user/app/demo_data/datasets \
+    HYPERVIEW_MEDIA_DIR=/home/user/app/demo_data/media
+
+WORKDIR $HOME/app
+
+RUN pip install --upgrade pip
+
+ARG HYPERVIEW_VERSION=0.3.1
+RUN pip install "hyperview[ml]==${HYPERVIEW_VERSION}" "datasets>=3.0.0" "numpy>=1.26.0" "pillow>=10.0.0" \
+    && python -c "import hyperview; print('hyperview', hyperview.__version__)"
+
+COPY --chown=user demo.py ./demo.py
+COPY --chown=user assets ./assets
+
+EXPOSE 7860
+
+HEALTHCHECK --interval=30s --timeout=10s --start-period=600s --retries=3 \
+    CMD curl -f http://localhost:7860/__hyperview__/health || exit 1
+
+CMD ["python", "demo.py"]

README.md

@@ -1,10 +1,112 @@
 ---
-title: Jaguar Hyperview Multigeometry
-emoji: 📊
-colorFrom: blue
-colorTo: indigo
+title: "HyperView: Jaguar Embedding Geometry Comparison"
+emoji: 🐆
+colorFrom: green
+colorTo: yellow
 sdk: docker
+app_port: 7860
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# HyperView Jaguar Core Claims Demo
+
+This Space compares the top core-claims-set families in three geometric panels:
+
+1. Euclidean: `triplet:T0:msv3` (seed 43)
+2. Hyperspherical view: `arcface:O0:msv3` (seed 44)
+3. Hyperbolic (Poincare) view: `lorentz:O1:msv3` (seed 44)
+
+The app loads train + validation-tagged samples from a resized Hugging Face dataset and injects precomputed embedding assets generated offline on GPU.
+
+## Contracts
+
+Runtime environment variables:
+
+- `HF_DATASET_REPO` (default: `hyper3labs/jaguar-hyperview-demo`)
+- `HF_DATASET_CONFIG` (default: `default`)
+- `HF_DATASET_SPLIT` (default: `train`)
+- `EMBEDDING_ASSET_DIR` (default: `./assets`)
+- `EMBEDDING_ASSET_MANIFEST` (default: `${EMBEDDING_ASSET_DIR}/manifest.json`)
+- `HYPERVIEW_DEFAULT_PANEL` (default: `spherical3d`; enables Sphere 3D as initial scatter panel)
+- `HYPERVIEW_LAYOUT_CACHE_VERSION` (default: `v6`; bumps dock layout localStorage key to invalidate stale cached panel state)
+- `HYPERVIEW_BIND_HOST` (preferred bind host; optional)
+- `SPACE_HOST` (compat input only; used for bind only if local: `0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`)
+- `SPACE_PORT` (primary port source)
+- `PORT` (fallback port source when `SPACE_PORT` is unset)
+
+Port precedence: `SPACE_PORT` > `PORT` > `7860`.
+
+On Hugging Face Spaces, `SPACE_HOST` may be injected as `<space-subdomain>.hf.space`. That domain must not be used as a local bind socket, so the runtime falls back to `0.0.0.0` unless `HYPERVIEW_BIND_HOST` is explicitly set.
+
+The runtime also patches HyperView's dock-layout cache key from legacy `hyperview:dockview-layout:v5` to `hyperview:dockview-layout:${HYPERVIEW_LAYOUT_CACHE_VERSION}` to force migration away from stale panel layouts after UI/layout changes. For future migrations, increment `HYPERVIEW_LAYOUT_CACHE_VERSION` (for example, `v7`) without changing code.
+
+## Important Note
+
+HyperView similarity search currently uses cosine distance in storage backends. The Lorentz panel in this Space is intended for embedding-space visualization and geometry-aware comparison rather than canonical Lorentz-distance retrieval scoring.
+
+## Reproducibility Commands
+
+Run from this folder (`HyperViewDemoHuggingFaceSpace/`).
+
+### 1) Build embedding assets (GPU required)
+
+```bash
+source .venv/bin/activate
+python3 scripts/build_hyperview_demo_assets.py \
+  --model_manifest config/model_manifest.json \
+  --dataset_root ../kaggle_jaguar_dataset_v2 \
+  --coreset_csv ../data/validation_coreset.csv \
+  --output_dir ./assets \
+  --device cuda \
+  --batch_size 64 \
+  --num_workers 4
+```
+
+### 2) Publish resized demo dataset
+
+```bash
+source .venv/bin/activate
+python3 scripts/publish_hyperview_demo_dataset.py \
+  --dataset_root ../kaggle_jaguar_dataset_v2 \
+  --coreset_csv ../data/validation_coreset.csv \
+  --output_dir ./dataset_build \
+  --repo_id hyper3labs/jaguar-hyperview-demo \
+  --config_name default
+```
+
+Use `--no_push` for local dry-runs.
+
+### 3) Local Docker smoke run
+
+```bash
+docker build -t jaguar-hyperview .
+docker run --rm -p 7860:7860 \
+  -e HF_DATASET_REPO=hyper3labs/jaguar-hyperview-demo \
+  -e EMBEDDING_ASSET_DIR=/home/user/app/assets \
+  jaguar-hyperview
+```
+
+Open `http://127.0.0.1:7860`.
+
+### 4) Optional H100 batch export on HPI
+
+```bash
+sbatch remote_setup/build_hyperview_demo_assets_h100.slurm
+```
+
+Override defaults at submit time if needed:
+
+```bash
+MODEL_MANIFEST=config/model_manifest.json \
+OUTPUT_DIR=./assets \
+sbatch remote_setup/build_hyperview_demo_assets_h100.slurm
+```
+
+## Provenance
+
+Model manifest: `config/model_manifest.json`
+
+Ranking and source-of-truth anchors:
+
+- `reports/summaries_of_findings/core_claims_axis12_paper_facing_tables_2026_03_16_102311/axis1_primary_ranking.csv`
+- `paper_draft/second_draft/sources_of_truth.md`

assets/.gitkeep

@@ -0,0 +1,2 @@
+# Generated assets are written here by scripts/build_hyperview_demo_assets.py.
+# Keep this directory in git even when empty.

config/model_manifest.json

@@ -0,0 +1,45 @@
+{
+  "description": "Core-claims top families for HyperView demo (TEST-best single-seed checkpoints)",
+  "source_of_truth": {
+    "ranking_csv": "reports/summaries_of_findings/core_claims_axis12_paper_facing_tables_2026_03_16_102311/axis1_primary_ranking.csv",
+    "registry": "paper_draft/second_draft/sources_of_truth.md"
+  },
+  "models": [
+    {
+      "model_key": "triplet_t0_msv3_seed43",
+      "comparison_key": "triplet:T0:msv3",
+      "family": "euclidean",
+      "loader": "triplet_benchmark",
+      "space_key": "triplet_t0_testbest",
+      "geometry": "euclidean",
+      "layout": "euclidean:2d",
+      "checkpoint_name": "triplet_miewid_msv3_T0_seed43_best.pth",
+      "checkpoint_path": "checkpoints/triplet_miewid_msv3_T0_seed43_best.pth",
+      "notes": "TEST-best seed in selected plan"
+    },
+    {
+      "model_key": "arcface_o0_msv3_seed44",
+      "comparison_key": "arcface:O0:msv3",
+      "family": "hyperspherical",
+      "loader": "arcface_benchmark",
+      "space_key": "arcface_o0_testbest",
+      "geometry": "euclidean",
+      "layout": "spherical:3d",
+      "checkpoint_name": "arcface_miewid_msv3_O0_seed44_best.pth",
+      "checkpoint_path": "checkpoints/arcface_miewid_msv3_O0_seed44_best.pth",
+      "notes": "TEST-best seed in selected plan"
+    },
+    {
+      "model_key": "lorentz_o1_msv3_seed44",
+      "comparison_key": "lorentz:O1:msv3",
+      "family": "hyperbolic_lorentz",
+      "loader": "lorentz",
+      "space_key": "lorentz_o1_testbest",
+      "geometry": "hyperboloid",
+      "layout": "poincare:2d",
+      "checkpoint_name": "lorentz_miewid_msv3_O1_seed44_best.pth",
+      "checkpoint_path": "checkpoints/lorentz_miewid_msv3_O1_seed44_best.pth",
+      "notes": "TEST-best seed in selected plan"
+    }
+  ]
+}

demo.py

@@ -0,0 +1,326 @@
+#!/usr/bin/env python3
+"""HyperView Space runtime for core-claims top jaguar ReID models."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+from datasets import Dataset as HFDataset
+from datasets import DatasetDict as HFDatasetDict
+from datasets import load_dataset, load_from_disk
+import hyperview as hv
+from hyperview.core.sample import Sample
+
+SPACE_HOST = os.environ.get("SPACE_HOST", "0.0.0.0")
+LOCAL_BIND_HOSTS = {"0.0.0.0", "127.0.0.1", "localhost", "::", "::1"}
+
+DATASET_NAME = os.environ.get("HYPERVIEW_DATASET_NAME", "jaguar_core_claims_demo")
+HF_DATASET_REPO = os.environ.get("HF_DATASET_REPO", "hyper3labs/jaguar-hyperview-demo")
+HF_DATASET_CONFIG = os.environ.get("HF_DATASET_CONFIG", "default")
+HF_DATASET_SPLIT = os.environ.get("HF_DATASET_SPLIT", "train")
+
+EMBEDDING_ASSET_DIR = Path(
+    os.environ.get(
+        "EMBEDDING_ASSET_DIR",
+        str((Path(__file__).resolve().parent / "assets").resolve()),
+    )
+)
+ASSET_MANIFEST_PATH = Path(
+    os.environ.get("EMBEDDING_ASSET_MANIFEST", str((EMBEDDING_ASSET_DIR / "manifest.json").resolve()))
+)
+
+
+def _patch_hyperview_default_panel() -> None:
+    """Patch HyperView 0.3.1 frontend for default panel and dock cache-key migration.
+
+    HyperView currently has no public API for these behaviors. This runtime patch is
+    intentionally narrow and idempotent, targeting the known bundled chunk for v0.3.1.
+    """
+    default_panel = os.environ.get("HYPERVIEW_DEFAULT_PANEL", "spherical3d").strip().lower()
+    apply_default_panel_patch = default_panel in {"spherical3d", "sphere3d"}
+    if not apply_default_panel_patch:
+        print(f"Skipping frontend default-panel patch (HYPERVIEW_DEFAULT_PANEL={default_panel!r}).")
+
+    cache_version = os.environ.get("HYPERVIEW_LAYOUT_CACHE_VERSION", "v6").strip() or "v6"
+    target_layout_key = f"hyperview:dockview-layout:{cache_version}"
+    legacy_layout_key = "hyperview:dockview-layout:v5"
+    layout_key_pattern = r"hyperview:dockview-layout:v\d+"
+
+    chunk_path = (
+        Path(hv.__file__).resolve().parent
+        / "server"
+        / "static"
+        / "_next"
+        / "static"
+        / "chunks"
+        / "077b38561d6ea80d.js"
+    )
+    if not chunk_path.exists():
+        print(f"Default-panel patch skipped: chunk not found at {chunk_path}")
+        return
+
+    marker_before = 'v||(v=n)};if(f&&l&&w({id:dr,title:"Euclidean"'
+    marker_after = 'v||(v=n),t.id===dd&&n.api.setActive()};if(f&&l&&w({id:dr,title:"Euclidean"'
+
+    try:
+        payload = chunk_path.read_text(encoding="utf-8")
+    except OSError as exc:
+        print(f"Default-panel patch skipped: failed reading chunk ({exc})")
+        return
+
+    patched = payload
+    changed = False
+
+    if apply_default_panel_patch:
+        if marker_after in patched:
+            print("HyperView frontend already patched for Sphere 3D default panel.")
+        elif marker_before in patched:
+            patched = patched.replace(marker_before, marker_after, 1)
+            changed = True
+            print("Patched HyperView frontend: Sphere 3D will open as default scatter panel.")
+        else:
+            print("Default-panel patch skipped: expected marker not found in HyperView chunk.")
+
+    if target_layout_key in patched:
+        print(f"HyperView frontend already uses dock cache key '{target_layout_key}'.")
+    elif legacy_layout_key in patched:
+        patched = patched.replace(legacy_layout_key, target_layout_key, 1)
+        changed = True
+        print(f"Patched HyperView frontend: dock cache key {legacy_layout_key} -> {target_layout_key}.")
+    else:
+        discovered = re.search(layout_key_pattern, patched)
+        if discovered:
+            source_key = discovered.group(0)
+            if source_key == target_layout_key:
+                print(f"HyperView frontend already uses dock cache key '{target_layout_key}'.")
+            else:
+                print(
+                    f"Dock cache patch notice: expected legacy key '{legacy_layout_key}' not found; "
+                    f"migrating detected key '{source_key}' -> '{target_layout_key}'."
+                )
+                patched = patched.replace(source_key, target_layout_key, 1)
+                changed = True
+        else:
+            print(
+                "Dock cache patch warning: expected layout cache key marker "
+                f"'{legacy_layout_key}' not found in HyperView chunk."
+            )
+
+    if not changed:
+        return
+
+    try:
+        chunk_path.write_text(patched, encoding="utf-8")
+    except OSError as exc:
+        print(f"Frontend patch skipped: failed writing chunk ({exc})")
+
+
+def _resolve_bind_host() -> tuple[str, str | None]:
+    explicit_bind = os.environ.get("HYPERVIEW_BIND_HOST")
+    if explicit_bind:
+        return explicit_bind, None
+
+    if SPACE_HOST in LOCAL_BIND_HOSTS:
+        return SPACE_HOST, None
+
+    return "0.0.0.0", f"SPACE_HOST='{SPACE_HOST}' is non-local; falling back to 0.0.0.0"
+
+
+def _resolve_port() -> int:
+    for key in ("SPACE_PORT", "PORT"):
+        value = os.environ.get(key)
+        if value:
+            try:
+                return int(value)
+            except ValueError as exc:
+                raise ValueError(f"Invalid integer value for {key}: {value}") from exc
+    return 7860
+
+
+def load_asset_manifest(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        raise FileNotFoundError(
+            f"Embedding asset manifest not found: {path}. "
+            "Run scripts/build_hyperview_demo_assets.py first."
+        )
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    if "models" not in payload or not isinstance(payload["models"], list):
+        raise ValueError(f"Invalid asset manifest format: {path}")
+    return payload
+
+
+def _load_hf_rows() -> HFDataset:
+    repo_path = Path(HF_DATASET_REPO)
+    if repo_path.exists():
+        loaded = load_from_disk(str(repo_path))
+        if isinstance(loaded, HFDatasetDict):
+            if HF_DATASET_SPLIT in loaded:
+                return loaded[HF_DATASET_SPLIT]
+            if "train" in loaded:
+                return loaded["train"]
+            first_split = next(iter(loaded.keys()))
+            return loaded[first_split]
+        return loaded
+    return load_dataset(HF_DATASET_REPO, name=HF_DATASET_CONFIG, split=HF_DATASET_SPLIT)
+
+
+def ingest_hf_dataset_samples(dataset: hv.Dataset) -> None:
+    rows = _load_hf_rows()
+    media_root = Path(os.environ.get("HYPERVIEW_MEDIA_DIR", "./demo_data/media")) / DATASET_NAME
+    media_root.mkdir(parents=True, exist_ok=True)
+
+    added = 0
+    for index, row in enumerate(rows):
+        filename = str(row.get("filename", f"sample_{index:06d}.jpg"))
+        sample_id = str(row.get("sample_id", filename))
+        if dataset._storage.get_sample(sample_id) is not None:
+            continue
+
+        image_obj = row["image"]
+        image_path = media_root / f"{Path(sample_id).stem}.jpg"
+        if not image_path.exists():
+            image_obj.convert("RGB").save(image_path, format="JPEG", quality=90, optimize=True)
+
+        label = str(row.get("label", ""))
+        metadata = {
+            "filename": filename,
+            "sample_id": sample_id,
+            "split_tag": str(row.get("split_tag", "unknown")),
+            "identity": label,
+            "source_repo": HF_DATASET_REPO,
+            "source_config": HF_DATASET_CONFIG,
+            "source_split": HF_DATASET_SPLIT,
+        }
+
+        dataset.add_sample(
+            Sample(
+                id=sample_id,
+                filepath=str(image_path),
+                label=label,
+                metadata=metadata,
+            )
+        )
+        added += 1
+
+    print(f"Ingested {added} HF samples into HyperView dataset '{DATASET_NAME}'.")
+
+
+def ensure_embedding_spaces(dataset: hv.Dataset, asset_manifest: dict[str, Any], asset_dir: Path) -> None:
+    known_sample_ids = {sample.id for sample in dataset.samples}
+
+    for model in asset_manifest["models"]:
+        model_key = str(model["model_key"])
+        space_key = str(model["space_key"])
+        embeddings_rel = model.get("embeddings_path")
+        if not embeddings_rel:
+            raise ValueError(f"Missing embeddings_path in asset manifest for model {model_key}")
+
+        embeddings_path = asset_dir / str(embeddings_rel)
+        if not embeddings_path.exists():
+            raise FileNotFoundError(
+                f"Missing embeddings file for model {model_key}: {embeddings_path}"
+            )
+
+        payload = np.load(embeddings_path, allow_pickle=False)
+        ids = [str(x) for x in payload["ids"].tolist()]
+        vectors = np.asarray(payload["vectors"], dtype=np.float32)
+
+        if vectors.ndim != 2:
+            raise ValueError(f"Embeddings for {model_key} must be 2D; got {vectors.shape}")
+        if len(ids) != vectors.shape[0]:
+            raise ValueError(
+                f"Embeddings/ID mismatch for {model_key}: {len(ids)} ids vs {vectors.shape[0]} vectors"
+            )
+
+        missing_ids = sorted(set(ids) - known_sample_ids)
+        if missing_ids:
+            preview = ", ".join(missing_ids[:5])
+            raise RuntimeError(
+                f"Embedding IDs missing from loaded dataset for {model_key}. "
+                f"First missing IDs: {preview}"
+            )
+
+        config = {
+            "provider": "precomputed-checkpoint",
+            "geometry": str(model["geometry"]),
+            "comparison_key": model.get("comparison_key"),
+            "family": model.get("family"),
+            "checkpoint_path": model.get("checkpoint_path"),
+        }
+
+        dataset._storage.ensure_space(
+            model_id=model_key,
+            dim=int(vectors.shape[1]),
+            space_key=space_key,
+            config=config,
+        )
+        dataset._storage.add_embeddings(space_key, ids, vectors)
+
+        print(f"Ensured space {space_key} ({vectors.shape[0]} x {vectors.shape[1]})")
+
+
+def ensure_layouts(dataset: hv.Dataset, asset_manifest: dict[str, Any]) -> list[str]:
+    layout_keys: list[str] = []
+    for model in asset_manifest["models"]:
+        space_key = str(model["space_key"])
+        layout_spec = str(model.get("layout", "euclidean:2d"))
+        layout_key = dataset.compute_visualization(
+            space_key=space_key,
+            layout=layout_spec,
+            method="umap",
+            force=False,
+        )
+        layout_keys.append(layout_key)
+        print(f"Ensured layout {layout_key} for space={space_key}")
+    return layout_keys
+
+
+def build_dataset() -> hv.Dataset:
+    asset_manifest = load_asset_manifest(ASSET_MANIFEST_PATH)
+
+    dataset = hv.Dataset(DATASET_NAME)
+    if len(dataset) == 0:
+        print(
+            f"Loading HF dataset rows from {HF_DATASET_REPO}[{HF_DATASET_CONFIG}] split={HF_DATASET_SPLIT}"
+        )
+        ingest_hf_dataset_samples(dataset)
+
+    ensure_embedding_spaces(dataset, asset_manifest=asset_manifest, asset_dir=EMBEDDING_ASSET_DIR)
+    layout_keys = ensure_layouts(dataset, asset_manifest=asset_manifest)
+
+    print(f"Dataset '{DATASET_NAME}' has {len(dataset)} samples")
+    print(f"Spaces: {[space.space_key for space in dataset.list_spaces()]}")
+    print(f"Layouts: {layout_keys}")
+
+    return dataset
+
+
+def main() -> None:
+    _patch_hyperview_default_panel()
+    dataset = build_dataset()
+
+    if os.environ.get("HYPERVIEW_DEMO_PREP_ONLY") == "1":
+        print("Preparation-only mode enabled; skipping server launch.")
+        return
+
+    bind_host, bind_warning = _resolve_bind_host()
+    bind_port = _resolve_port()
+
+    if bind_warning:
+        print(f"Bind host notice: {bind_warning}")
+    print(
+        "Starting HyperView with "
+        f"bind_host={bind_host} bind_port={bind_port} "
+        f"(SPACE_HOST={SPACE_HOST!r}, SPACE_PORT={os.environ.get('SPACE_PORT')!r}, "
+        f"PORT={os.environ.get('PORT')!r})"
+    )
+    hv.launch(dataset, host=bind_host, port=bind_port, open_browser=False)
+
+
+if __name__ == "__main__":
+    main()

scripts/build_hyperview_demo_assets.py

@@ -0,0 +1,532 @@
+#!/usr/bin/env python3
+"""Build precomputed HyperView embedding assets for the jaguar Space."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+import sys
+from typing import Any
+from urllib.parse import urlparse
+
+import numpy as np
+import pandas as pd
+import torch
+from PIL import Image
+from torch.utils.data import DataLoader, Dataset
+from tqdm import tqdm
+
+PROJECT_ROOT = Path(__file__).resolve().parents[2]
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.append(str(PROJECT_ROOT))
+
+from experiment_scripts.evaluate_inpainted_bgfg import (  # noqa: E402
+    _load_arcface_benchmark,
+    _load_lorentz,
+    _load_triplet_benchmark,
+)
+from experiment_scripts.train_lorentz_reid import build_transforms  # noqa: E402
+
+DEFAULT_MANIFEST_PATH = PROJECT_ROOT / "HyperViewDemoHuggingFaceSpace/config/model_manifest.json"
+DEFAULT_DATASET_ROOT = PROJECT_ROOT / "kaggle_jaguar_dataset_v2"
+DEFAULT_CORESET_CSV = PROJECT_ROOT / "data/validation_coreset.csv"
+DEFAULT_OUTPUT_DIR = PROJECT_ROOT / "HyperViewDemoHuggingFaceSpace/assets"
+
+
+@dataclass
+class LoadedModel:
+    model: Any
+    val_transform: Any
+    image_size: int
+
+
+class JaguarEmbeddingDataset(Dataset):
+    def __init__(
+        self,
+        rows: list[dict[str, str]],
+        images_dir: Path,
+        transform: Any,
+        image_variant: str,
+    ):
+        self.rows = rows
+        self.images_dir = images_dir
+        self.transform = transform
+        self.image_variant = image_variant
+
+    def __len__(self) -> int:
+        return len(self.rows)
+
+    @staticmethod
+    def _is_albumentations_transform(transform: Any) -> bool:
+        return transform.__class__.__module__.startswith("albumentations")
+
+    def _load_image(self, filename: str) -> Image.Image:
+        image_path = self.images_dir / filename
+        if self.image_variant == "foreground_only":
+            rgba = Image.open(image_path).convert("RGBA")
+            rgba_np = np.array(rgba, dtype=np.uint8)
+            rgb = rgba_np[:, :, :3]
+            alpha = rgba_np[:, :, 3]
+            mask = (alpha > 0).astype(np.uint8)
+            cutout_rgb = (rgb * mask[:, :, np.newaxis]).astype(np.uint8)
+            return Image.fromarray(cutout_rgb, mode="RGB")
+        return Image.open(image_path).convert("RGB")
+
+    def __getitem__(self, idx: int):
+        row = self.rows[idx]
+        image = self._load_image(row["filename"])
+
+        if self.transform is None:
+            raise ValueError("Validation transform is required for embedding extraction.")
+
+        if self._is_albumentations_transform(self.transform):
+            image_tensor = self.transform(image=np.array(image, dtype=np.uint8))["image"]
+        else:
+            image_tensor = self.transform(image)
+
+        return (
+            image_tensor,
+            row["sample_id"],
+            row["label"],
+            row["filename"],
+            row["split_tag"],
+        )
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Build precomputed embedding artifacts for HyperView Space runtime."
+    )
+    parser.add_argument(
+        "--model_manifest",
+        type=Path,
+        default=DEFAULT_MANIFEST_PATH,
+        help="Model manifest JSON defining the three demo models.",
+    )
+    parser.add_argument(
+        "--dataset_root",
+        type=Path,
+        default=DEFAULT_DATASET_ROOT,
+        help="Dataset root containing train.csv and train/ images.",
+    )
+    parser.add_argument(
+        "--coreset_csv",
+        type=Path,
+        default=DEFAULT_CORESET_CSV,
+        help="Validation coreset CSV used to tag split_tag=train/validation.",
+    )
+    parser.add_argument(
+        "--output_dir",
+        type=Path,
+        default=DEFAULT_OUTPUT_DIR,
+        help="Output directory for per-model embeddings and manifest JSON.",
+    )
+    parser.add_argument(
+        "--device",
+        type=str,
+        default="cuda",
+        choices=["cuda"],
+        help="Runtime device. CUDA-only by contract.",
+    )
+    parser.add_argument("--batch_size", type=int, default=64)
+    parser.add_argument("--num_workers", type=int, default=4)
+    parser.add_argument(
+        "--image_variant",
+        type=str,
+        default="foreground_only",
+        choices=["foreground_only", "full_rgb"],
+    )
+    parser.add_argument(
+        "--max_samples",
+        type=int,
+        default=None,
+        help="Optional smoke-mode sample cap for quick checks.",
+    )
+    return parser.parse_args()
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def resolve_device(device_name: str) -> torch.device:
+    if device_name != "cuda":
+        raise SystemExit("GPU unavailable: CUDA requested but not available.")
+    if not torch.cuda.is_available():
+        raise SystemExit("GPU unavailable: CUDA requested but not available.")
+    return torch.device("cuda")
+
+
+def load_model_manifest(manifest_path: Path) -> dict[str, Any]:
+    payload = json.loads(manifest_path.read_text(encoding="utf-8"))
+    if "models" not in payload or not isinstance(payload["models"], list):
+        raise ValueError(f"Invalid model manifest: {manifest_path}")
+    return payload
+
+
+def parse_run_url(run_url: str) -> tuple[str, str, str]:
+    parsed = urlparse(run_url)
+    parts = [p for p in parsed.path.split("/") if p]
+    if len(parts) >= 4 and parts[2] == "runs":
+        return parts[0], parts[1], parts[3]
+    raise ValueError(f"Unsupported W&B run URL format: {run_url}")
+
+
+def pick_checkpoint_file(root: Path, checkpoint_name: str | None) -> Path:
+    if checkpoint_name:
+        exact = sorted(root.rglob(checkpoint_name))
+        if exact:
+            return exact[0]
+
+    candidates = sorted(root.rglob("*.pth"))
+    if not candidates:
+        raise FileNotFoundError(f"No .pth checkpoints found under downloaded artifact: {root}")
+    return candidates[0]
+
+
+def download_checkpoint_from_wandb(
+    run_url: str,
+    model_key: str,
+    checkpoint_name: str | None,
+    output_dir: Path,
+) -> tuple[Path, str]:
+    try:
+        import wandb
+    except ImportError as exc:
+        raise ImportError(
+            "wandb is required to download missing checkpoints. Install with `uv pip install wandb`."
+        ) from exc
+
+    entity, project, run_id = parse_run_url(run_url)
+    api = wandb.Api()
+    run = api.run(f"{entity}/{project}/{run_id}")
+
+    artifacts = [artifact for artifact in run.logged_artifacts() if artifact.type == "model"]
+    if not artifacts:
+        raise FileNotFoundError(
+            f"No model artifacts found for run {entity}/{project}/{run_id}."
+        )
+
+    artifact = artifacts[-1]
+    safe_name = artifact.name.replace("/", "_").replace(":", "_")
+    download_root = output_dir / "downloaded_checkpoints" / model_key / safe_name
+    download_root.mkdir(parents=True, exist_ok=True)
+    downloaded_dir = Path(artifact.download(root=str(download_root)))
+
+    checkpoint_path = pick_checkpoint_file(downloaded_dir, checkpoint_name)
+    return checkpoint_path, f"wandb_artifact:{artifact.name}"
+
+
+def resolve_checkpoint_path(model_cfg: dict[str, Any], output_dir: Path) -> tuple[Path, str]:
+    checkpoint_path = Path(model_cfg.get("checkpoint_path", ""))
+    if not checkpoint_path.is_absolute():
+        checkpoint_path = (PROJECT_ROOT / checkpoint_path).resolve()
+
+    if checkpoint_path.exists():
+        return checkpoint_path, "local_path"
+
+    run_url = model_cfg.get("run_url")
+    if not run_url:
+        raise FileNotFoundError(
+            f"Checkpoint not found at {checkpoint_path} and no run_url provided for fallback download."
+        )
+
+    return download_checkpoint_from_wandb(
+        run_url=run_url,
+        model_key=str(model_cfg["model_key"]),
+        checkpoint_name=model_cfg.get("checkpoint_name"),
+        output_dir=output_dir,
+    )
+
+
+def read_augmentation_profile(checkpoint_path: Path) -> str:
+    checkpoint = torch.load(checkpoint_path, map_location="cpu", weights_only=False)
+    return str(checkpoint.get("augmentation_profile", "lorentz_default"))
+
+
+def load_model(model_cfg: dict[str, Any], checkpoint_path: Path, device: str) -> LoadedModel:
+    loader = str(model_cfg["loader"])
+    if loader == "arcface_benchmark":
+        model, image_size, _metric = _load_arcface_benchmark(str(checkpoint_path), device)
+        augmentation_profile = read_augmentation_profile(checkpoint_path)
+        _train_tf, val_tf, _resolved = build_transforms(image_size, augmentation_profile=augmentation_profile)
+        return LoadedModel(model=model, val_transform=val_tf, image_size=int(image_size))
+
+    if loader == "triplet_benchmark":
+        model, image_size, _metric = _load_triplet_benchmark(str(checkpoint_path), device)
+        augmentation_profile = read_augmentation_profile(checkpoint_path)
+        _train_tf, val_tf, _resolved = build_transforms(image_size, augmentation_profile=augmentation_profile)
+        return LoadedModel(model=model, val_transform=val_tf, image_size=int(image_size))
+
+    if loader == "lorentz":
+        model, image_size, _metric, val_tf = _load_lorentz(str(checkpoint_path), device)
+        return LoadedModel(model=model, val_transform=val_tf, image_size=int(image_size))
+
+    raise ValueError(f"Unsupported loader='{loader}' in model manifest.")
+
+
+def build_sample_rows(
+    dataset_root: Path,
+    coreset_csv: Path,
+    max_samples: int | None,
+) -> list[dict[str, str]]:
+    train_csv = dataset_root / "train.csv"
+    images_dir = dataset_root / "train"
+    if not train_csv.exists():
+        raise FileNotFoundError(f"Missing train.csv at {train_csv}")
+    if not images_dir.exists():
+        raise FileNotFoundError(f"Missing train images directory at {images_dir}")
+
+    train_df = pd.read_csv(train_csv)
+    coreset_df = pd.read_csv(coreset_csv)
+    coreset_filenames = set(coreset_df["filename"].astype(str).tolist())
+
+    train_df = train_df.copy()
+    train_df["filename"] = train_df["filename"].astype(str)
+    train_df["ground_truth"] = train_df["ground_truth"].astype(str)
+    train_df["sample_id"] = train_df["filename"]
+    train_df["split_tag"] = np.where(train_df["filename"].isin(coreset_filenames), "validation", "train")
+
+    if max_samples is not None:
+        train_df = train_df.iloc[: int(max_samples)].copy()
+
+    rows: list[dict[str, str]] = []
+    for _, row in train_df.iterrows():
+        rows.append(
+            {
+                "sample_id": str(row["sample_id"]),
+                "filename": str(row["filename"]),
+                "label": str(row["ground_truth"]),
+                "split_tag": str(row["split_tag"]),
+            }
+        )
+
+    return rows
+
+
+def extract_embeddings(
+    loaded_model: LoadedModel,
+    rows: list[dict[str, str]],
+    images_dir: Path,
+    image_variant: str,
+    device: torch.device,
+    batch_size: int,
+    num_workers: int,
+    progress_label: str,
+) -> tuple[list[str], np.ndarray, list[str], list[str], list[str]]:
+    dataset = JaguarEmbeddingDataset(
+        rows=rows,
+        images_dir=images_dir,
+        transform=loaded_model.val_transform,
+        image_variant=image_variant,
+    )
+    loader = DataLoader(
+        dataset,
+        batch_size=batch_size,
+        shuffle=False,
+        num_workers=num_workers,
+        pin_memory=True,
+    )
+
+    all_vectors: list[np.ndarray] = []
+    all_ids: list[str] = []
+    all_labels: list[str] = []
+    all_filenames: list[str] = []
+    all_split_tags: list[str] = []
+
+    loaded_model.model.eval()
+    with torch.no_grad():
+        for images, sample_ids, labels, filenames, split_tags in tqdm(loader, desc=progress_label):
+            images = images.to(device, non_blocking=True)
+            vectors = loaded_model.model(images)
+            if isinstance(vectors, (tuple, list)):
+                vectors = vectors[0]
+            vectors_np = vectors.detach().cpu().numpy().astype(np.float32)
+
+            all_vectors.append(vectors_np)
+            all_ids.extend([str(x) for x in sample_ids])
+            all_labels.extend([str(x) for x in labels])
+            all_filenames.extend([str(x) for x in filenames])
+            all_split_tags.extend([str(x) for x in split_tags])
+
+    if not all_vectors:
+        raise RuntimeError("No embeddings were generated.")
+
+    stacked = np.vstack(all_vectors).astype(np.float32)
+    return all_ids, stacked, all_labels, all_filenames, all_split_tags
+
+
+def save_model_artifacts(
+    output_dir: Path,
+    model_cfg: dict[str, Any],
+    checkpoint_path: Path,
+    checkpoint_source: str,
+    sample_ids: list[str],
+    vectors: np.ndarray,
+    labels: list[str],
+    filenames: list[str],
+    split_tags: list[str],
+    image_variant: str,
+    image_size: int,
+    batch_size: int,
+    num_workers: int,
+) -> dict[str, Any]:
+    model_key = str(model_cfg["model_key"])
+    model_dir = output_dir / "models" / model_key
+    model_dir.mkdir(parents=True, exist_ok=True)
+
+    embeddings_path = model_dir / "embeddings.npz"
+    metadata_path = model_dir / "metadata.json"
+
+    np.savez_compressed(
+        embeddings_path,
+        ids=np.asarray(sample_ids),
+        vectors=vectors,
+        labels=np.asarray(labels),
+        filenames=np.asarray(filenames),
+        split_tags=np.asarray(split_tags),
+    )
+
+    metadata = {
+        "generated_at_utc": utc_now(),
+        "model_key": model_key,
+        "comparison_key": model_cfg.get("comparison_key"),
+        "family": model_cfg.get("family"),
+        "loader": model_cfg.get("loader"),
+        "space_key": model_cfg.get("space_key"),
+        "geometry": model_cfg.get("geometry"),
+        "layout": model_cfg.get("layout"),
+        "num_samples": int(vectors.shape[0]),
+        "embedding_dim": int(vectors.shape[1]),
+        "checkpoint_path": str(checkpoint_path),
+        "checkpoint_source": checkpoint_source,
+        "run_url": model_cfg.get("run_url"),
+        "image_variant": image_variant,
+        "image_size": int(image_size),
+        "batch_size": int(batch_size),
+        "num_workers": int(num_workers),
+    }
+    metadata_path.write_text(json.dumps(metadata, indent=2), encoding="utf-8")
+
+    return {
+        "model_key": model_key,
+        "comparison_key": model_cfg.get("comparison_key"),
+        "family": model_cfg.get("family"),
+        "loader": model_cfg.get("loader"),
+        "space_key": model_cfg.get("space_key"),
+        "geometry": model_cfg.get("geometry"),
+        "layout": model_cfg.get("layout"),
+        "checkpoint_path": str(checkpoint_path),
+        "checkpoint_source": checkpoint_source,
+        "run_url": model_cfg.get("run_url"),
+        "embeddings_path": str(embeddings_path.relative_to(output_dir)),
+        "metadata_path": str(metadata_path.relative_to(output_dir)),
+        "num_samples": int(vectors.shape[0]),
+        "embedding_dim": int(vectors.shape[1]),
+    }
+
+
+def write_sample_index(output_dir: Path, rows: list[dict[str, str]]) -> Path:
+    sample_index_path = output_dir / "sample_index.csv"
+    sample_df = pd.DataFrame(rows)
+    sample_df.to_csv(sample_index_path, index=False)
+    return sample_index_path
+
+
+def main() -> int:
+    args = parse_args()
+    device = resolve_device(args.device)
+
+    model_manifest = load_model_manifest(args.model_manifest)
+    output_dir = args.output_dir.resolve()
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    dataset_root = args.dataset_root.resolve()
+    images_dir = dataset_root / "train"
+    rows = build_sample_rows(
+        dataset_root=dataset_root,
+        coreset_csv=args.coreset_csv,
+        max_samples=args.max_samples,
+    )
+    if not rows:
+        raise RuntimeError("No rows found in train.csv after applying filters.")
+
+    expected_ids = [row["sample_id"] for row in rows]
+    sample_index_path = write_sample_index(output_dir, rows)
+
+    emitted_models: list[dict[str, Any]] = []
+    for model_cfg in model_manifest["models"]:
+        model_key = str(model_cfg["model_key"])
+        print(f"\n=== Building embeddings for {model_key} ===")
+
+        checkpoint_path, checkpoint_source = resolve_checkpoint_path(model_cfg=model_cfg, output_dir=output_dir)
+        print(f"Checkpoint: {checkpoint_path} ({checkpoint_source})")
+
+        loaded_model = load_model(model_cfg=model_cfg, checkpoint_path=checkpoint_path, device=args.device)
+        ids, vectors, labels, filenames, split_tags = extract_embeddings(
+            loaded_model=loaded_model,
+            rows=rows,
+            images_dir=images_dir,
+            image_variant=args.image_variant,
+            device=device,
+            batch_size=int(args.batch_size),
+            num_workers=int(args.num_workers),
+            progress_label=f"extract:{model_key}",
+        )
+
+        if ids != expected_ids:
+            raise RuntimeError(
+                f"Sample ID alignment failed for {model_key}: extracted order does not match expected sample index."
+            )
+
+        emitted = save_model_artifacts(
+            output_dir=output_dir,
+            model_cfg=model_cfg,
+            checkpoint_path=checkpoint_path,
+            checkpoint_source=checkpoint_source,
+            sample_ids=ids,
+            vectors=vectors,
+            labels=labels,
+            filenames=filenames,
+            split_tags=split_tags,
+            image_variant=args.image_variant,
+            image_size=loaded_model.image_size,
+            batch_size=int(args.batch_size),
+            num_workers=int(args.num_workers),
+        )
+        emitted_models.append(emitted)
+
+    manifest_out = {
+        "generated_at_utc": utc_now(),
+        "source_model_manifest": str(args.model_manifest.resolve()),
+        "dataset": {
+            "dataset_root": str(dataset_root),
+            "images_dir": str(images_dir),
+            "coreset_csv": str(args.coreset_csv.resolve()),
+            "num_samples": len(rows),
+            "image_variant": args.image_variant,
+            "sample_index_csv": str(sample_index_path.relative_to(output_dir)),
+        },
+        "models": emitted_models,
+    }
+
+    manifest_path = output_dir / "manifest.json"
+    manifest_path.write_text(json.dumps(manifest_out, indent=2), encoding="utf-8")
+
+    print("\n=== HyperView asset build complete ===")
+    print(f"Sample count: {len(rows)}")
+    print(f"Manifest: {manifest_path}")
+    for emitted in emitted_models:
+        print(
+            f"- {emitted['model_key']}: {emitted['num_samples']} x {emitted['embedding_dim']} "
+            f"({emitted['embeddings_path']})"
+        )
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/publish_hyperview_demo_dataset.py

@@ -0,0 +1,229 @@
+#!/usr/bin/env python3
+"""Create and optionally publish a resized HF dataset for the HyperView Space."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+from PIL import Image
+from datasets import Dataset, Image as HFImage
+
+PROJECT_ROOT = Path(__file__).resolve().parents[2]
+DEFAULT_DATASET_ROOT = PROJECT_ROOT / "kaggle_jaguar_dataset_v2"
+DEFAULT_CORESET_CSV = PROJECT_ROOT / "data/validation_coreset.csv"
+DEFAULT_OUTPUT_DIR = PROJECT_ROOT / "HyperViewDemoHuggingFaceSpace/dataset_build"
+DEFAULT_REPO_ID = os.environ.get("HF_DATASET_REPO", "hyper3labs/jaguar-hyperview-demo")
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Build resized train+validation demo dataset with split tags for HyperView."
+    )
+    parser.add_argument("--dataset_root", type=Path, default=DEFAULT_DATASET_ROOT)
+    parser.add_argument("--coreset_csv", type=Path, default=DEFAULT_CORESET_CSV)
+    parser.add_argument("--output_dir", type=Path, default=DEFAULT_OUTPUT_DIR)
+    parser.add_argument("--repo_id", type=str, default=DEFAULT_REPO_ID)
+    parser.add_argument("--config_name", type=str, default="default")
+    parser.add_argument("--image_size", type=int, default=384)
+    parser.add_argument("--jpeg_quality", type=int, default=90)
+    parser.add_argument(
+        "--image_variant",
+        type=str,
+        default="foreground_only",
+        choices=["foreground_only", "full_rgb"],
+    )
+    parser.add_argument("--max_samples", type=int, default=None)
+    parser.add_argument("--private", action="store_true")
+    parser.add_argument("--hf_token_env", type=str, default="HF_TOKEN")
+    parser.add_argument("--no_push", action="store_true")
+    return parser.parse_args()
+
+
+def load_rows(dataset_root: Path, coreset_csv: Path, max_samples: int | None) -> pd.DataFrame:
+    train_csv = dataset_root / "train.csv"
+    if not train_csv.exists():
+        raise FileNotFoundError(f"Missing train.csv at {train_csv}")
+
+    train_df = pd.read_csv(train_csv)
+    coreset_df = pd.read_csv(coreset_csv)
+    coreset_filenames = set(coreset_df["filename"].astype(str).tolist())
+
+    train_df = train_df.copy()
+    train_df["filename"] = train_df["filename"].astype(str)
+    train_df["label"] = train_df["ground_truth"].astype(str)
+    train_df["split_tag"] = np.where(train_df["filename"].isin(coreset_filenames), "validation", "train")
+    train_df["sample_id"] = train_df["filename"]
+
+    if max_samples is not None:
+        train_df = train_df.iloc[: int(max_samples)].copy()
+
+    return train_df[["filename", "label", "split_tag", "sample_id"]]
+
+
+def load_variant_image(image_path: Path, image_variant: str) -> Image.Image:
+    if image_variant == "foreground_only":
+        rgba = Image.open(image_path).convert("RGBA")
+        rgba_np = np.array(rgba, dtype=np.uint8)
+        rgb = rgba_np[:, :, :3]
+        alpha = rgba_np[:, :, 3]
+        mask = (alpha > 0).astype(np.uint8)
+        cutout_rgb = (rgb * mask[:, :, np.newaxis]).astype(np.uint8)
+        return Image.fromarray(cutout_rgb, mode="RGB")
+    return Image.open(image_path).convert("RGB")
+
+
+def build_resized_images(
+    rows_df: pd.DataFrame,
+    dataset_root: Path,
+    output_images_dir: Path,
+    image_size: int,
+    jpeg_quality: int,
+    image_variant: str,
+) -> pd.DataFrame:
+    source_images_dir = dataset_root / "train"
+    if not source_images_dir.exists():
+        raise FileNotFoundError(f"Missing image directory: {source_images_dir}")
+
+    output_images_dir.mkdir(parents=True, exist_ok=True)
+
+    records: list[dict[str, str]] = []
+    for _, row in rows_df.iterrows():
+        filename = str(row["filename"])
+        src = source_images_dir / filename
+        if not src.exists():
+            raise FileNotFoundError(f"Missing source image: {src}")
+
+        image = load_variant_image(src, image_variant=image_variant)
+        image = image.resize((int(image_size), int(image_size)), Image.Resampling.BICUBIC)
+
+        dst_name = f"{Path(filename).stem}.jpg"
+        dst = output_images_dir / dst_name
+        image.save(dst, format="JPEG", quality=int(jpeg_quality), optimize=True)
+
+        records.append(
+            {
+                "image": str(dst),
+                "label": str(row["label"]),
+                "filename": filename,
+                "split_tag": str(row["split_tag"]),
+                "sample_id": str(row["sample_id"]),
+            }
+        )
+
+    return pd.DataFrame(records)
+
+
+def build_hf_dataset(records_df: pd.DataFrame) -> Dataset:
+    payload = {
+        "image": records_df["image"].tolist(),
+        "label": records_df["label"].tolist(),
+        "filename": records_df["filename"].tolist(),
+        "split_tag": records_df["split_tag"].tolist(),
+        "sample_id": records_df["sample_id"].tolist(),
+    }
+    dataset = Dataset.from_dict(payload)
+    dataset = dataset.cast_column("image", HFImage())
+    return dataset
+
+
+def maybe_push_to_hub(
+    dataset: Dataset,
+    repo_id: str,
+    config_name: str,
+    private: bool,
+    hf_token_env: str,
+    no_push: bool,
+) -> str:
+    if no_push:
+        return "skipped (--no_push)"
+
+    token = os.environ.get(hf_token_env)
+    if not token:
+        raise RuntimeError(
+            f"Missing Hugging Face token in environment variable {hf_token_env}."
+        )
+
+    dataset.push_to_hub(
+        repo_id=repo_id,
+        config_name=config_name,
+        token=token,
+        private=bool(private),
+    )
+    return f"pushed:{repo_id}:{config_name}"
+
+
+def main() -> int:
+    args = parse_args()
+
+    output_dir = args.output_dir.resolve()
+    images_out = output_dir / "images"
+    dataset_out = output_dir / "hf_dataset"
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    rows_df = load_rows(
+        dataset_root=args.dataset_root.resolve(),
+        coreset_csv=args.coreset_csv.resolve(),
+        max_samples=args.max_samples,
+    )
+    if rows_df.empty:
+        raise RuntimeError("No dataset rows found for publish pipeline.")
+
+    records_df = build_resized_images(
+        rows_df=rows_df,
+        dataset_root=args.dataset_root.resolve(),
+        output_images_dir=images_out,
+        image_size=int(args.image_size),
+        jpeg_quality=int(args.jpeg_quality),
+        image_variant=args.image_variant,
+    )
+
+    dataset = build_hf_dataset(records_df)
+    dataset.save_to_disk(str(dataset_out))
+
+    publish_status = maybe_push_to_hub(
+        dataset=dataset,
+        repo_id=args.repo_id,
+        config_name=args.config_name,
+        private=args.private,
+        hf_token_env=args.hf_token_env,
+        no_push=args.no_push,
+    )
+
+    metadata = {
+        "generated_at_utc": utc_now(),
+        "dataset_root": str(args.dataset_root.resolve()),
+        "coreset_csv": str(args.coreset_csv.resolve()),
+        "output_dir": str(output_dir),
+        "repo_id": args.repo_id,
+        "config_name": args.config_name,
+        "image_size": int(args.image_size),
+        "jpeg_quality": int(args.jpeg_quality),
+        "image_variant": args.image_variant,
+        "num_rows": int(len(records_df)),
+        "split_counts": records_df["split_tag"].value_counts().to_dict(),
+        "push_status": publish_status,
+    }
+
+    metadata_path = output_dir / "publish_metadata.json"
+    metadata_path.write_text(json.dumps(metadata, indent=2), encoding="utf-8")
+
+    print("=== HyperView demo dataset pipeline complete ===")
+    print(f"Rows: {len(records_df)}")
+    print(f"HF dataset saved to: {dataset_out}")
+    print(f"Push status: {publish_status}")
+    print(f"Metadata: {metadata_path}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())