hyperview 0.1.1__tar.gz → 0.3.1__tar.gz

{hyperview-0.1.1 → hyperview-0.3.1}/.gitignore

@@ -70,7 +70,16 @@ TESTS.md
 AGENTS.md
 **/AGENTS.md
 .github/agents/
+.github/instructions/
+.github/hooks/
+.github/skills/
+.agents/
 .specstory/
 
+# Deployment repo (managed as a separate nested git repository)
+hyper-models/
+hyperview-spaces/
+eval/
+
 # Generated version file (hatch-vcs)
 src/hyperview/_version.py

{hyperview-0.1.1 → hyperview-0.3.1}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Matin Mahmood
+Copyright (c) 2025 Hyper3Labs
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{hyperview-0.1.1 → hyperview-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperview
-Version: 0.1.1
+Version: 0.3.1
 Summary: Open-source dataset curation with hyperbolic embeddings visualization
 Project-URL: Homepage, https://github.com/Hyper3Labs/HyperView
 Project-URL: Documentation, https://github.com/Hyper3Labs/HyperView#readme
@@ -48,14 +48,14 @@ Description-Content-Type: text/markdown
 
 > **Open-source dataset curation + embedding visualization (Euclidean + Poincaré disk)**
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/Hyper3Labs/HyperView)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/Hyper3Labs/HyperView) [![Open in HF Spaces](https://huggingface.co/datasets/huggingface/badges/resolve/main/open-in-hf-spaces-sm.svg)](https://huggingface.co/spaces/hyper3labs/HyperView) [![Discord](https://img.shields.io/badge/Discord-hyper%C2%B3labs-5865F2?logo=discord&logoColor=white)](https://discord.gg/Za3rBkTPSf)
 
 <p align="center">
-  <a href="https://youtu.be/XLaa8FHSQtc" target="_blank">
-    <img src="assets/screenshot.png" alt="HyperView Screenshot" width="100%">
+  <a href="https://huggingface.co/spaces/hyper3labs/HyperView" target="_blank">
+    <img src="https://raw.githubusercontent.com/Hyper3Labs/HyperView/main/assets/screenshot.png" alt="HyperView Screenshot" width="100%">
   </a>
   <br>
-  <a href="https://youtu.be/XLaa8FHSQtc" target="_blank">Watch the Demo Video</a>
+  <a href="https://huggingface.co/spaces/hyper3labs/HyperView" target="_blank">Try the live demo on HuggingFace Spaces</a>
 </p>
 
 ---
@@ -63,10 +63,16 @@ Description-Content-Type: text/markdown
 ## Features
 
 - **Dual-Panel UI**: Image grid + scatter plot with bidirectional selection
-- **Euclidean/Poincaré Toggle**: Switch between standard 2D UMAP and Poincaré disk visualization
+- **Multi-Layout Visualizations**: Explore Euclidean, Poincare, and spherical layouts in 2D or 3D with UMAP or PCA projections
 - **HuggingFace Integration**: Load datasets directly from HuggingFace Hub
 - **Fast Embeddings**: Uses EmbedAnything for CLIP-based image embeddings
 
+## Updates
+
+- **01-02-26** — [The Geometry of Image Embeddings, Hands-on Coding Workshop](https://www.meetup.com/berlin-computer-vision-group/events/312927919/) (Berlin Computer Vision Group)
+- **17-01-26** — [The Geometry of Image Embeddings, Hands-on Coding Workshop, Part I](https://www.meetup.com/berlin-computer-vision-group/events/312636174/) (Berlin Computer Vision Group)
+- **11-12-25** — [Hacker Room Demo Day #2](https://youtu.be/KnOiaNXN3Q0?t=2483) (Merantix AI Campus Berlin) — First version of HyperView presented
+
 ## Quick Start
 
 **Docs:** [docs/datasets.md](docs/datasets.md) · [docs/colab.md](docs/colab.md) · [CONTRIBUTING.md](CONTRIBUTING.md) · [TESTS.md](TESTS.md)
@@ -74,26 +80,45 @@ Description-Content-Type: text/markdown
 ### Installation
 
 ```bash
-git clone https://github.com/Hyper3Labs/HyperView.git
-cd HyperView
-
-# Install with uv
-uv venv .venv
-source .venv/bin/activate
-uv pip install -e ".[dev]"
+uv pip install hyperview
 ```
 
-### Run the Demo
+### Run HyperView
 
 ```bash
-hyperview demo --samples 500
+hyperview \
+  --dataset cifar10_demo \
+  --hf-dataset uoft-cs/cifar10 \
+  --split train \
+  --image-key img \
+  --label-key label \
+  --samples 500 \
+  --model openai/clip-vit-base-patch32 \
+  --layout euclidean \
+  --layout poincare
 ```
 
 This will:
-1. Load 500 samples from CIFAR-100
-2. Compute CLIP embeddings
-3. Generate Euclidean and Poincaré visualizations
-4. Start the server at **http://127.0.0.1:6262**
+1. Use dataset `cifar10_demo`
+2. Load up to 500 samples from CIFAR-10
+3. Compute CLIP embeddings
+4. Generate Euclidean and Poincare visualizations
+5. Start the server at **http://127.0.0.1:6262**
+
+You can also launch with explicit dataset/model/projection args:
+
+```bash
+hyperview \
+  --dataset imagenette_clip \
+  --hf-dataset fastai/imagenette \
+  --split train \
+  --image-key image \
+  --label-key label \
+  --samples 1000 \
+  --model openai/clip-vit-base-patch32 \
+  --method umap \
+  --layout euclidean
+```
 
 ### Python API
 
@@ -125,26 +150,19 @@ hv.launch(dataset)  # Opens http://127.0.0.1:6262
 
 See [docs/colab.md](docs/colab.md) for a fast Colab smoke test and notebook-friendly launch behavior.
 
-### Save and Load Datasets
+## Why Hyperbolic?
 
-```python
-# Save dataset with embeddings
-dataset.save("my_dataset.json")
+Traditional Euclidean embeddings struggle with hierarchical data. In Euclidean space, volume grows polynomially ($r^d$), causing **[Representation Collapse](https://hyper3labs.github.io/collapse)** where minority classes get crushed together.
 
-# Load later
-dataset = hv.Dataset.load("my_dataset.json")
-hv.launch(dataset)
-```
+**[Hyperbolic space](https://hyper3labs.github.io/warp)** (Poincaré disk) has exponential volume growth ($e^r$), naturally preserving hierarchical structure and keeping rare classes distinct.
 
-## Why Hyperbolic?
+**[Try the live demo on HuggingFace Spaces→](https://huggingface.co/spaces/hyper3labs/HyperView)**
 
-Traditional Euclidean embeddings struggle with hierarchical data. In Euclidean space, volume grows polynomially ($r^d$), causing **Representation Collapse** where minority classes get crushed together.
+## Community
 
-**Hyperbolic space** (Poincaré disk) has exponential volume growth ($e^r$), naturally preserving hierarchical structure and keeping rare classes distinct.
+**Weekly Open Discussion** — Every Tuesday at 15:00 UTC on [Discord](https://discord.gg/Az7k4Ure?event=1469730571440885944)
 
-<p align="center">
-  <img src="assets/hyperview_infographic.png" alt="Euclidean vs Hyperbolic" width="100%">
-</p>
+Join us to see the latest features demoed live, walk through new code, and get help with local setup. Whether you're a core maintainer or looking for your first contribution, everyone is welcome.
 
 ## Contributing
 
@@ -153,12 +171,7 @@ Development setup, frontend hot-reload, and backend API notes live in [CONTRIBUT
 ## Related projects
 
 - **hyper-scatter**: High-performance WebGL scatterplot engine (Euclidean + Poincaré) used by the frontend: https://github.com/Hyper3Labs/hyper-scatter
-- **hyper-models**: Non-Euclidean model zoo + ONNX exports (e.g. for hyperbolic VLM experiments): https://github.com/Hyper3Labs/hyper-models
-
-## References
-
-- [Poincaré Embeddings for Learning Hierarchical Representations](https://arxiv.org/abs/1705.08039) (Nickel & Kiela, 2017)
-- [Hyperbolic Neural Networks](https://arxiv.org/abs/1805.09112) (Ganea et al., 2018)
+- **hyper-models**: Non-Euclidean model zoo + ONNX exports : https://github.com/Hyper3Labs/hyper-models
 
 ## License
 

hyperview-0.3.1/README.md

@@ -0,0 +1,132 @@
+# HyperView
+
+> **Open-source dataset curation + embedding visualization (Euclidean + Poincaré disk)**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/Hyper3Labs/HyperView) [![Open in HF Spaces](https://huggingface.co/datasets/huggingface/badges/resolve/main/open-in-hf-spaces-sm.svg)](https://huggingface.co/spaces/hyper3labs/HyperView) [![Discord](https://img.shields.io/badge/Discord-hyper%C2%B3labs-5865F2?logo=discord&logoColor=white)](https://discord.gg/Za3rBkTPSf)
+
+<p align="center">
+  <a href="https://huggingface.co/spaces/hyper3labs/HyperView" target="_blank">
+    <img src="https://raw.githubusercontent.com/Hyper3Labs/HyperView/main/assets/screenshot.png" alt="HyperView Screenshot" width="100%">
+  </a>
+  <br>
+  <a href="https://huggingface.co/spaces/hyper3labs/HyperView" target="_blank">Try the live demo on HuggingFace Spaces</a>
+</p>
+
+---
+
+## Features
+
+- **Dual-Panel UI**: Image grid + scatter plot with bidirectional selection
+- **Multi-Layout Visualizations**: Explore Euclidean, Poincare, and spherical layouts in 2D or 3D with UMAP or PCA projections
+- **HuggingFace Integration**: Load datasets directly from HuggingFace Hub
+- **Fast Embeddings**: Uses EmbedAnything for CLIP-based image embeddings
+
+## Updates
+
+- **01-02-26** — [The Geometry of Image Embeddings, Hands-on Coding Workshop](https://www.meetup.com/berlin-computer-vision-group/events/312927919/) (Berlin Computer Vision Group)
+- **17-01-26** — [The Geometry of Image Embeddings, Hands-on Coding Workshop, Part I](https://www.meetup.com/berlin-computer-vision-group/events/312636174/) (Berlin Computer Vision Group)
+- **11-12-25** — [Hacker Room Demo Day #2](https://youtu.be/KnOiaNXN3Q0?t=2483) (Merantix AI Campus Berlin) — First version of HyperView presented
+
+## Quick Start
+
+**Docs:** [docs/datasets.md](docs/datasets.md) · [docs/colab.md](docs/colab.md) · [CONTRIBUTING.md](CONTRIBUTING.md) · [TESTS.md](TESTS.md)
+
+### Installation
+
+```bash
+uv pip install hyperview
+```
+
+### Run HyperView
+
+```bash
+hyperview \
+  --dataset cifar10_demo \
+  --hf-dataset uoft-cs/cifar10 \
+  --split train \
+  --image-key img \
+  --label-key label \
+  --samples 500 \
+  --model openai/clip-vit-base-patch32 \
+  --layout euclidean \
+  --layout poincare
+```
+
+This will:
+1. Use dataset `cifar10_demo`
+2. Load up to 500 samples from CIFAR-10
+3. Compute CLIP embeddings
+4. Generate Euclidean and Poincare visualizations
+5. Start the server at **http://127.0.0.1:6262**
+
+You can also launch with explicit dataset/model/projection args:
+
+```bash
+hyperview \
+  --dataset imagenette_clip \
+  --hf-dataset fastai/imagenette \
+  --split train \
+  --image-key image \
+  --label-key label \
+  --samples 1000 \
+  --model openai/clip-vit-base-patch32 \
+  --method umap \
+  --layout euclidean
+```
+
+### Python API
+
+```python
+import hyperview as hv
+
+# Create dataset
+dataset = hv.Dataset("my_dataset")
+
+# Load from HuggingFace
+dataset.add_from_huggingface(
+    "uoft-cs/cifar100",
+    split="train",
+    max_samples=1000
+)
+
+# Or load from local directory
+# dataset.add_images_dir("/path/to/images", label_from_folder=True)
+
+# Compute embeddings and visualization
+dataset.compute_embeddings(model="openai/clip-vit-base-patch32")
+dataset.compute_visualization()
+
+# Launch the UI
+hv.launch(dataset)  # Opens http://127.0.0.1:6262
+```
+
+### Google Colab
+
+See [docs/colab.md](docs/colab.md) for a fast Colab smoke test and notebook-friendly launch behavior.
+
+## Why Hyperbolic?
+
+Traditional Euclidean embeddings struggle with hierarchical data. In Euclidean space, volume grows polynomially ($r^d$), causing **[Representation Collapse](https://hyper3labs.github.io/collapse)** where minority classes get crushed together.
+
+**[Hyperbolic space](https://hyper3labs.github.io/warp)** (Poincaré disk) has exponential volume growth ($e^r$), naturally preserving hierarchical structure and keeping rare classes distinct.
+
+**[Try the live demo on HuggingFace Spaces→](https://huggingface.co/spaces/hyper3labs/HyperView)**
+
+## Community
+
+**Weekly Open Discussion** — Every Tuesday at 15:00 UTC on [Discord](https://discord.gg/Az7k4Ure?event=1469730571440885944)
+
+Join us to see the latest features demoed live, walk through new code, and get help with local setup. Whether you're a core maintainer or looking for your first contribution, everyone is welcome.
+
+## Contributing
+
+Development setup, frontend hot-reload, and backend API notes live in [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Related projects
+
+- **hyper-scatter**: High-performance WebGL scatterplot engine (Euclidean + Poincaré) used by the frontend: https://github.com/Hyper3Labs/hyper-scatter
+- **hyper-models**: Non-Euclidean model zoo + ONNX exports : https://github.com/Hyper3Labs/hyper-models
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

{hyperview-0.1.1 → hyperview-0.3.1}/pyproject.toml

@@ -98,9 +98,3 @@ ignore = ["E501"]
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
 testpaths = ["tests"]
-
-[tool.uv.workspace]
-members = ["hyper_models"]
-
-[tool.uv.sources]
-hyper-models = { workspace = true }

{hyperview-0.1.1 → hyperview-0.3.1}/src/hyperview/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.1.1'
-__version_tuple__ = version_tuple = (0, 1, 1)
+__version__ = version = '0.3.1'
+__version_tuple__ = version_tuple = (0, 3, 1)
 
 __commit_id__ = commit_id = None

{hyperview-0.1.1 → hyperview-0.3.1}/src/hyperview/api.py

@@ -7,6 +7,7 @@ import threading
 import time
 import webbrowser
 from dataclasses import dataclass
+from importlib.util import find_spec
 from urllib.error import URLError
 from urllib.request import Request, urlopen
 from uuid import uuid4
@@ -55,6 +56,16 @@ def _read_health(url: str, timeout_s: float) -> _HealthResponse:
     )
 
 
+def _resolve_default_launch_layout(dataset: Dataset) -> str:
+    spaces = dataset.list_spaces()
+
+    if any(space.geometry not in ("hyperboloid", "hypersphere") for space in spaces):
+        return "euclidean:2d"
+    if any(space.geometry == "hypersphere" for space in spaces):
+        return "spherical:3d"
+    return "poincare:2d"
+
+
 class Session:
     """A session for the HyperView visualizer."""
 
@@ -228,9 +239,9 @@ def launch(
     """Launch the HyperView visualization server.
 
     Note:
-        HyperView's UI needs at least one 2D layout. If layouts are missing but
-        embedding spaces exist, this function will compute a default layout
-        automatically (Euclidean if any Euclidean space exists, otherwise Poincaré).
+        HyperView needs at least one visualization to display. If no layouts
+        exist yet but embedding spaces do, this function computes one default
+        layout automatically.
 
     Args:
         dataset: The dataset to visualize.
@@ -318,26 +329,26 @@ def launch(
             "port or stop the process listening on that port."
         )
 
-    # The frontend requires 2D coords from /api/embeddings.
-    # Ensure at least one layout exists; do not auto-generate optional geometries.
     layouts = dataset.list_layouts()
     spaces = dataset.list_spaces()
 
-    if not spaces:
+    if not layouts and not spaces:
         raise ValueError(
-            "HyperView launch requires 2D projections for the UI. "
-            "No projections or embedding spaces were found. "
+            "HyperView launch requires at least one visualization or embedding space. "
+            "No visualizations or embedding spaces were found. "
             "Call `dataset.compute_embeddings()` and `dataset.compute_visualization()` "
-            "before `hv.launch()`."
+            "or `dataset.set_coords()` before `hv.launch()`."
         )
 
     if not layouts:
-        has_euclidean_space = any(s.geometry != "hyperboloid" for s in spaces)
-        default_geometry = "euclidean" if has_euclidean_space else "poincare"
+        default_layout = _resolve_default_launch_layout(dataset)
 
-        print(f"No layouts found. Computing {default_geometry} visualization...")
+        print(f"No visualizations found. Computing {default_layout} visualization...")
         # Let compute_visualization pick the most appropriate default space.
-        dataset.compute_visualization(space_key=None, geometry=default_geometry)
+        dataset.compute_visualization(
+            space_key=None,
+            layout=default_layout,
+        )
 
     session = Session(dataset, host, port)
 
@@ -390,9 +401,6 @@ def _is_colab() -> bool:
     """Check if running inside a Google Colab notebook runtime."""
     if os.environ.get("COLAB_RELEASE_TAG"):
         return True
-    try:
-        import google.colab  # type: ignore[import-not-found]
-
+    if find_spec("google.colab") is not None:
         return True
-    except ImportError:
-        return False
+    return False