hyperview 0.2.0__tar.gz → 0.3.1__tar.gz

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

@@ -77,7 +77,9 @@ AGENTS.md
 .specstory/
 
 # Deployment repo (managed as a separate nested git repository)
-deploy/
+hyper-models/
+hyperview-spaces/
+eval/
 
 # Generated version file (hatch-vcs)
 src/hyperview/_version.py

{hyperview-0.2.0 → 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.2.0 → hyperview-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperview
-Version: 0.2.0
+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,7 +48,7 @@ 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) [![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/Az7k4Ure)
+[![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">
@@ -63,7 +63,7 @@ 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
 
@@ -94,14 +94,15 @@ hyperview \
   --label-key label \
   --samples 500 \
   --model openai/clip-vit-base-patch32 \
-  --geometry both
+  --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 Poincaré visualizations
+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:
@@ -116,7 +117,7 @@ hyperview \
   --samples 1000 \
   --model openai/clip-vit-base-patch32 \
   --method umap \
-  --geometry euclidean
+  --layout euclidean
 ```
 
 ### Python API

{hyperview-0.2.0 → hyperview-0.3.1}/README.md

@@ -2,7 +2,7 @@
 
 > **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/Az7k4Ure)
+[![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">
@@ -17,7 +17,7 @@
 ## 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
 
@@ -48,14 +48,15 @@ hyperview \
   --label-key label \
   --samples 500 \
   --model openai/clip-vit-base-patch32 \
-  --geometry both
+  --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 Poincaré visualizations
+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:
@@ -70,7 +71,7 @@ hyperview \
   --samples 1000 \
   --model openai/clip-vit-base-patch32 \
   --method umap \
-  --geometry euclidean
+  --layout euclidean
 ```
 
 ### Python API

{hyperview-0.2.0 → 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.2.0'
-__version_tuple__ = version_tuple = (0, 2, 0)
+__version__ = version = '0.3.1'
+__version_tuple__ = version_tuple = (0, 3, 1)
 
 __commit_id__ = commit_id = None

{hyperview-0.2.0 → 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

{hyperview-0.2.0 → hyperview-0.3.1}/src/hyperview/cli.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import argparse
 
 from hyperview import Dataset, launch
+from hyperview.core.dataset import parse_visualization_layout
 
 
 def _build_parser() -> argparse.ArgumentParser:
@@ -38,6 +39,12 @@ def _build_parser() -> argparse.ArgumentParser:
         default=None,
         help="HuggingFace split to use (required with --hf-dataset)",
     )
+    parser.add_argument(
+        "--hf-config",
+        type=str,
+        default=None,
+        help="Optional HuggingFace subset/configuration to use",
+    )
     parser.add_argument(
         "--image-key",
         type=str,
@@ -72,6 +79,14 @@ def _build_parser() -> argparse.ArgumentParser:
         default=None,
         help="Maximum number of ingested samples (omit to load all)",
     )
+    parser.add_argument(
+        "--hf-streaming",
+        action="store_true",
+        help=(
+            "Stream HuggingFace rows instead of materializing the full split first. "
+            "Useful for loading subsets without eager full-split downloads."
+        ),
+    )
     parser.add_argument(
         "--shuffle",
         action="store_true",
@@ -83,6 +98,15 @@ def _build_parser() -> argparse.ArgumentParser:
         default=42,
         help="Random seed used when --shuffle is enabled (default: 42)",
     )
+    parser.add_argument(
+        "--hf-shuffle-buffer-size",
+        type=int,
+        default=1000,
+        help=(
+            "Shuffle buffer size used with --hf-streaming and --shuffle. "
+            "Streaming shuffle is approximate and trades larger buffers for more read-ahead."
+        ),
+    )
 
     parser.add_argument(
         "--model",
@@ -95,17 +119,20 @@ def _build_parser() -> argparse.ArgumentParser:
     )
     parser.add_argument(
         "--method",
-        choices=["umap"],
+        choices=["umap", "pca"],
         default="umap",
-        help="Projection method (currently only 'umap')",
+        help="Projection method: 'umap' (default) or 'pca'",
     )
     parser.add_argument(
-        "--geometry",
-        choices=["auto", "euclidean", "poincare", "both"],
-        default="both",
+        "--layout",
+        action="append",
+        dest="layouts",
+        metavar="GEOMETRY[:2d|3d]",
         help=(
-            "Layout geometry to compute when embeddings are computed. "
-            "auto chooses based on embedding geometry; both computes both layouts."
+            "Visualization layout to compute. Repeat this flag to request multiple layouts, "
+            "for example '--layout euclidean --layout spherical'. "
+            "Omitting the suffix defaults to 2D for euclidean/poincare and 3D for spherical. "
+            "If omitted, HyperView picks one sensible default layout for the selected embedding space."
         ),
     )
     parser.add_argument(
@@ -162,6 +189,23 @@ def _build_parser() -> argparse.ArgumentParser:
 
 
 def _validate_args(parser: argparse.ArgumentParser, args: argparse.Namespace) -> None:
+    if args.layouts:
+        canonical_layouts: list[str] = []
+        seen_layouts: set[str] = set()
+        for layout_spec in args.layouts:
+            try:
+                geometry, layout_dimension = parse_visualization_layout(layout_spec)
+            except ValueError as exc:
+                parser.error(str(exc))
+
+            canonical_layout = f"{geometry}:{layout_dimension}d"
+            if canonical_layout in seen_layouts:
+                continue
+            seen_layouts.add(canonical_layout)
+            canonical_layouts.append(canonical_layout)
+
+        args.layouts = canonical_layouts
+
     if args.hf_dataset and args.images_dir:
         parser.error("Use either --hf-dataset or --images-dir, not both.")
 
@@ -181,6 +225,8 @@ def _validate_args(parser: argparse.ArgumentParser, args: argparse.Namespace) ->
             parser.error("--split is required when using --hf-dataset.")
         if not args.image_key:
             parser.error("--image-key is required when using --hf-dataset.")
+        if args.hf_shuffle_buffer_size < 1:
+            parser.error("--hf-shuffle-buffer-size must be at least 1.")
 
 
 def _print_ingestion_result(added: int, skipped: int) -> None:
@@ -191,9 +237,11 @@ def _print_ingestion_result(added: int, skipped: int) -> None:
 
 
 def _ingest_huggingface(dataset: Dataset, args: argparse.Namespace, dataset_name: str) -> None:
-    print(f"Loading HuggingFace dataset {dataset_name}...")
+    config_suffix = f" [{args.hf_config}]" if args.hf_config else ""
+    print(f"Loading HuggingFace dataset {dataset_name}{config_suffix}...")
     added, skipped = dataset.add_from_huggingface(
         dataset_name,
+        config=args.hf_config,
         split=args.split,
         image_key=args.image_key,
         label_key=args.label_key,
@@ -201,6 +249,8 @@ def _ingest_huggingface(dataset: Dataset, args: argparse.Namespace, dataset_name
         max_samples=args.samples,
         shuffle=args.shuffle,
         seed=args.seed,
+        streaming=args.hf_streaming,
+        shuffle_buffer_size=args.hf_shuffle_buffer_size,
     )
     _print_ingestion_result(added, skipped)
 
@@ -228,37 +278,35 @@ def _prepare_dataset(args: argparse.Namespace) -> Dataset:
     return dataset
 
 
-def _resolve_geometry_targets(
+def _resolve_default_layouts(
     dataset: Dataset,
-    geometry: str,
     space_key: str | None,
 ) -> list[str]:
-    if geometry == "both":
-        return ["euclidean", "poincare"]
-
-    if geometry in ("euclidean", "poincare"):
-        return [geometry]
-
-    if space_key is None:
-        return ["euclidean"]
-
     spaces = dataset.list_spaces()
     selected = next((space for space in spaces if space.space_key == space_key), None)
-    if selected is not None and selected.geometry == "hyperboloid":
-        return ["poincare"]
 
-    return ["euclidean"]
+    if selected is not None:
+        if selected.geometry == "hyperboloid":
+            return ["poincare:2d"]
+        if selected.geometry == "hypersphere":
+            return ["spherical:3d"]
+        return ["euclidean:2d"]
 
+    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"]
 
 def _compute_layouts(dataset: Dataset, args: argparse.Namespace, space_key: str | None) -> None:
-    targets = _resolve_geometry_targets(dataset, args.geometry, space_key)
+    target_layouts = args.layouts or _resolve_default_layouts(dataset, space_key)
 
     print("Computing visualizations...")
-    for target_geometry in targets:
+    for target_layout in target_layouts:
         dataset.compute_visualization(
             space_key=space_key,
             method=args.method,
-            geometry=target_geometry,
+            layout=target_layout,
             n_neighbors=args.n_neighbors,
             min_dist=args.min_dist,
             metric=args.metric,