Deploy hyper3labs/HyperView from Hyper3Labs/hyperview-spaces@13b0870

Dockerfile

@@ -21,7 +21,7 @@ WORKDIR $HOME/app
 
 RUN pip install --upgrade pip
 
-ARG HYPERVIEW_VERSION=0.2.0
+ARG HYPERVIEW_VERSION=0.3.1
 ARG HYPER_MODELS_VERSION=0.1.0
 
 # Pin package versions so Docker cache cannot silently hold an older PyPI release.
@@ -30,17 +30,11 @@ RUN pip install "hyper-models==${HYPER_MODELS_VERSION}" && python -c "import hyp
 
 COPY --chown=user demo.py ./demo.py
 
-ARG DEMO_SAMPLES=300
-
 ENV HYPERVIEW_DATASETS_DIR=/home/user/app/demo_data/datasets \
-    HYPERVIEW_MEDIA_DIR=/home/user/app/demo_data/media \
-    DEMO_SAMPLES=${DEMO_SAMPLES}
+    HYPERVIEW_MEDIA_DIR=/home/user/app/demo_data/media
 
 # Precompute at build time so the Space starts fast.
-RUN python demo.py --precompute
-
-ENV HOST=0.0.0.0 \
-    PORT=7860
+RUN python -c "from demo import build_dataset; build_dataset()"
 
 EXPOSE 7860
 

README.md

@@ -10,25 +10,52 @@ pinned: false
 
 # HyperView — Imagenette (CLIP + HyCoCLIP)
 
-This Hugging Face Space runs HyperView with:
+This folder is the simplest copyable HyperView Space example in this repo.
+It keeps all dataset-specific settings in the constants block at the top of
+[demo.py](demo.py), so a coding agent can usually adapt it by editing one file.
+
+This example runs HyperView with:
 
 - CLIP embeddings (`openai/clip-vit-base-patch32`) for Euclidean layout
 - HyCoCLIP embeddings (`hycoclip-vit-s`) for Poincaré layout
 
-The Docker image installs the **latest HyperView from PyPI** and precomputes
-embeddings/layouts during build for fast runtime startup.
+The Docker image installs released HyperView packages from PyPI and precomputes
+the dataset, embeddings, and layouts during build for fast runtime startup.
+
+## Reuse This Template
+
+When you copy this folder for your own dataset, change these parts first:
+
+1. Edit the constants block in [demo.py](demo.py).
+2. Rename the copied Space from `HyperView` to your own project name such as `yourproject-HyperView` or `HyperView-yourproject`.
+3. Update this README frontmatter, title, and H1.
+4. Point a deploy workflow at your new folder.
+
+This starter currently installs `hyperview==0.3.1` and `hyper-models==0.1.0`.
+
+The defaults in [demo.py](demo.py) are:
+
+- Hugging Face dataset: `Multimodal-Fatima/Imagenette_validation`
+- Split: `validation`
+- Image field: `image`
+- Label field: `label`
+- Sample count: `300`
+- Layouts: CLIP + Euclidean, HyCoCLIP + Poincaré
+
+If you only want one model in your own Space, keep a single entry in
+`EMBEDDING_LAYOUTS` and delete the rest.
+
+When contributing your own Space back to this repository, add a row to the
+community table in the root `README.md` and include your Hugging Face Space ID
+in the pull request description.
 
-## Configuration
+## Build Model
 
-Environment variables:
+The Dockerfile runs `build_dataset()` during image build. That means:
 
-- `DEMO_HF_DATASET` (default: `Multimodal-Fatima/Imagenette_validation`)
-- `DEMO_HF_SPLIT` (default: `validation`)
-- `DEMO_HF_IMAGE_KEY` (default: `image`)
-- `DEMO_HF_LABEL_KEY` (default: `label`)
-- `DEMO_SAMPLES` (default: `300`)
-- `DEMO_CLIP_MODEL` (default: `openai/clip-vit-base-patch32`)
-- `DEMO_HYPER_MODEL` (default: `hycoclip-vit-s`)
+- the first expensive download/embedding pass happens at build time
+- the runtime container mostly just launches HyperView
+- there is no extra runtime configuration path to keep in sync
 
 ## Deploy source
 

demo.py

@@ -1,147 +1,75 @@
 #!/usr/bin/env python
-"""HyperView Hugging Face Space demo: CLIP + HyCoCLIP on Imagenette.
+"""HyperView Hugging Face Space template example.
 
-Usage:
-  python demo.py --precompute   # run during Docker build
-  python demo.py                # run as app entrypoint
+Copy this folder, then edit the constants below for your dataset.
 """
 
 from __future__ import annotations
 
-import os
-import sys
-
 import hyperview as hv
 
-HOST = os.environ.get("HOST", "0.0.0.0")
-PORT = int(os.environ.get("PORT", "7860"))
-
-DATASET_NAME = os.environ.get("DEMO_DATASET", "imagenette_clip_hycoclip")
-HF_DATASET = os.environ.get("DEMO_HF_DATASET", "Multimodal-Fatima/Imagenette_validation")
-HF_SPLIT = os.environ.get("DEMO_HF_SPLIT", "validation")
-HF_IMAGE_KEY = os.environ.get("DEMO_HF_IMAGE_KEY", "image")
-HF_LABEL_KEY = os.environ.get("DEMO_HF_LABEL_KEY", "label")
-NUM_SAMPLES = int(os.environ.get("DEMO_SAMPLES", "300"))
-SAMPLE_SEED = int(os.environ.get("DEMO_SEED", "42"))
-
-CLIP_MODEL_ID = os.environ.get("DEMO_CLIP_MODEL", "openai/clip-vit-base-patch32")
-HYPER_MODEL_ID = os.environ.get("DEMO_HYPER_MODEL", "hycoclip-vit-s")
-
-
-def _truthy_env(name: str, default: bool = True) -> bool:
-    value = os.environ.get(name)
-    if value is None:
-        return default
-    return value.strip().lower() not in {"0", "false", "no", "off", ""}
-
+# Edit this block when you reuse the template for another Space.
+SPACE_HOST = "0.0.0.0"
+SPACE_PORT = 7860
+
+DATASET_NAME = "imagenette_clip_hycoclip"
+HF_DATASET = "Multimodal-Fatima/Imagenette_validation"
+HF_SPLIT = "validation"
+HF_IMAGE_KEY = "image"
+HF_LABEL_KEY = "label"
+SAMPLE_COUNT = 300
+SAMPLE_SEED = 42
+
+# Keep one or more entries here. Most reuses only need one model/layout pair.
+EMBEDDING_LAYOUTS = [
+    {
+        "name": "CLIP",
+        "provider": "embed-anything",
+        "model": "openai/clip-vit-base-patch32",
+        "layout": "euclidean",
+    },
+    {
+        "name": "HyCoCLIP",
+        "provider": "hyper-models",
+        "model": "hycoclip-vit-s",
+        "layout": "poincare",
+    },
+]
+
+
+def build_dataset() -> hv.Dataset:
+    dataset = hv.Dataset(DATASET_NAME)
 
-def _ensure_demo_ready(dataset: hv.Dataset) -> None:
     if len(dataset) == 0:
-        print(f"Loading samples from {HF_DATASET} ({HF_SPLIT})...")
+        print(f"Loading {SAMPLE_COUNT} samples from {HF_DATASET} ({HF_SPLIT})...")
         dataset.add_from_huggingface(
             HF_DATASET,
             split=HF_SPLIT,
             image_key=HF_IMAGE_KEY,
             label_key=HF_LABEL_KEY,
-            max_samples=NUM_SAMPLES,
+            max_samples=SAMPLE_COUNT,
             shuffle=True,
             seed=SAMPLE_SEED,
         )
 
-    spaces = dataset.list_spaces()
-
-    clip_space = next(
-        (
-            space
-            for space in spaces
-            if getattr(space, "provider", None) == "embed-anything"
-            and getattr(space, "model_id", None) == CLIP_MODEL_ID
-        ),
-        None,
-    )
-
-    if clip_space is None:
-        print(f"Computing CLIP embeddings ({CLIP_MODEL_ID})...")
-        dataset.compute_embeddings(model=CLIP_MODEL_ID, provider="embed-anything", show_progress=True)
-        spaces = dataset.list_spaces()
-        clip_space = next(
-            (
-                space
-                for space in spaces
-                if getattr(space, "provider", None) == "embed-anything"
-                and getattr(space, "model_id", None) == CLIP_MODEL_ID
-            ),
-            None,
+    for embedding in EMBEDDING_LAYOUTS:
+        print(f"Ensuring {embedding['name']} embeddings ({embedding['model']})...")
+        space_key = dataset.compute_embeddings(
+            model=embedding["model"],
+            provider=embedding["provider"],
+            show_progress=True,
         )
 
-    if clip_space is None:
-        raise RuntimeError("Failed to create CLIP embedding space")
-
-    compute_hyperbolic = _truthy_env("DEMO_COMPUTE_HYPERBOLIC", default=True)
-    hyper_space = next(
-        (
-            space
-            for space in spaces
-            if getattr(space, "provider", None) == "hyper-models"
-            and getattr(space, "model_id", None) == HYPER_MODEL_ID
-        ),
-        None,
-    )
-
-    if compute_hyperbolic and hyper_space is None:
-        try:
-            print(f"Computing hyperbolic embeddings ({HYPER_MODEL_ID})...")
-            dataset.compute_embeddings(model=HYPER_MODEL_ID, provider="hyper-models", show_progress=True)
-            spaces = dataset.list_spaces()
-            hyper_space = next(
-                (
-                    space
-                    for space in spaces
-                    if getattr(space, "provider", None) == "hyper-models"
-                    and getattr(space, "model_id", None) == HYPER_MODEL_ID
-                ),
-                None,
-            )
-        except Exception as exc:
-            print(f"WARNING: hyperbolic embeddings failed ({type(exc).__name__}: {exc})")
-
-    layouts = dataset.list_layouts()
-    geometries = {getattr(layout, "geometry", None) for layout in layouts}
-
-    if "euclidean" not in geometries:
-        print("Computing euclidean layout...")
-        dataset.compute_visualization(space_key=clip_space.space_key, geometry="euclidean")
-
-    if "poincare" not in geometries:
-        print("Computing poincaré layout...")
-        poincare_space_key = hyper_space.space_key if hyper_space is not None else clip_space.space_key
-        dataset.compute_visualization(space_key=poincare_space_key, geometry="poincare")
+        print(f"Ensuring {embedding['layout']} layout...")
+        dataset.compute_visualization(space_key=space_key, layout=embedding["layout"])
 
+    return dataset
 
-def main() -> None:
-    dataset = hv.Dataset(DATASET_NAME)
-
-    if len(dataset) == 0 or not dataset.list_layouts():
-        print("Preparing demo dataset...")
-        try:
-            _ensure_demo_ready(dataset)
-        except Exception as exc:
-            import traceback
-            traceback.print_exc()
-            print(f"\nFATAL: demo setup failed: {type(exc).__name__}: {exc}", file=sys.stderr)
-            sys.exit(1)
-    else:
-        print(
-            f"Loaded cached dataset '{DATASET_NAME}' with "
-            f"{len(dataset.list_spaces())} spaces and {len(dataset.list_layouts())} layouts"
-        )
-
-    if "--precompute" in sys.argv:
-        print("Precompute complete")
-        return
 
-    print(f"Starting HyperView on {HOST}:{PORT}")
-    hv.launch(dataset, host=HOST, port=PORT, open_browser=False)
+def main() -> None:
+    dataset = build_dataset()
+    print(f"Starting HyperView on {SPACE_HOST}:{SPACE_PORT}")
+    hv.launch(dataset, host=SPACE_HOST, port=SPACE_PORT, open_browser=False)
 
 
 if __name__ == "__main__":