Merge branch 'main' into pr-24-pca

# Conflicts:
#	src/hyperview/core/dataset.py
#	src/hyperview/embeddings/pipelines.py
#	src/hyperview/embeddings/projection.py
#	tests/test_pca_projection.py

Author: mnm-matin

.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

CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## 0.3.1 - 2026-03-22
+
+### Fixes
+- Switch the frontend `hyper-scatter` dependency to the published npm package so clean installs and GitHub release builds resolve it without a local checkout.
+
+### Notes
+- This release supersedes the failed `0.3.0` PyPI publish and carries forward the user-facing changes documented below.
+
+## 0.3.0 - 2026-03-22
+
+### Features
+- Add PCA projection support for Euclidean, Poincare, and spherical visualization layouts.
+- Add 3D layout support for visualizations, including spherical views and 3D lasso selection.
+- Add Hugging Face ingestion controls for subset configs, streaming, and configurable shuffle buffers.
+
+### Improvements
+- Preserve stable source indices and requested sample tracking during Hugging Face ingestion.
+- Expand the demo workflow with ready-made Euclidean, Poincare, spherical, and PCA layouts.
+
+### Breaking Changes
+- Replace CLI `--geometry` with repeatable `--layout` flags such as `--layout euclidean`, `--layout poincare`, and `--layout spherical`.
+- Replace `Dataset.compute_visualization(geometry=...)` with `Dataset.compute_visualization(layout=...)`; bare `spherical` layouts now resolve to 3D.

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

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

docs/datasets.md

@@ -31,6 +31,28 @@ dataset.add_from_huggingface(
 )
 ```
 
+To target a named Hugging Face subset/configuration, pass `config="default"`
+or another config name alongside `split=`.
+
+To avoid materializing the full split before sampling, use `streaming=True`.
+This keeps ingestion on Hugging Face's iterable dataset path and stops after the
+requested rows:
+
+```python
+dataset.add_from_huggingface(
+    "uoft-cs/cifar100",
+    split="train",
+    image_key="img",
+    label_key="fine_label",
+    max_samples=500,
+    streaming=True,
+)
+```
+
+When `streaming=True` and `shuffle=True`, sampling becomes approximate and
+buffer-based. Tune `shuffle_buffer_size=` if you need more mixing and can afford
+additional read-ahead.
+
 ### From Directory
 ```python
 dataset.add_images_dir("/path/to/images", label_from_folder=True)
@@ -66,8 +88,8 @@ Samples are **never implicitly deleted**. Use `hv.Dataset.delete("name")` for ex
 # High-dimensional embeddings (CLIP)
 dataset.compute_embeddings(model="openai/clip-vit-base-patch32", show_progress=True)
 
-# 2D projections for visualization
-dataset.compute_visualization()  # UMAP to Euclidean + Hyperbolic
+# 2D projection for visualization
+dataset.compute_visualization()  # Defaults to euclidean:2d
 ```
 
 Embeddings are stored per-sample. If a sample already has embeddings, it's skipped.

frontend/package-lock.json

@@ -25,7 +25,7 @@
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
     "dockview": "^4.13.1",
-    "hyper-scatter": "^0.1.0",
+    "hyper-scatter": "0.2.0",
     "justified-layout": "^4.1.0",
     "lucide-react": "^0.562.0",
     "next": "^16.1.6",

frontend/package.json

@@ -6,6 +6,7 @@ import { DockviewWorkspace, DockviewProvider } from "@/components/DockviewWorksp
 import { useStore } from "@/store/useStore";
 import type { Sample } from "@/types";
 import {
+  ApiError,
   fetchDataset,
   fetchSamples,
   fetchSamplesBatch,
@@ -35,12 +36,22 @@ export default function Home() {
     lassoTotal,
     lassoIsLoading,
     setLassoResults,
+    clearLassoSelection,
     labelFilter,
   } = useStore();
 
   const [loadingMore, setLoadingMore] = useState(false);
   const labelFilterRef = useRef<string | null>(labelFilter ?? null);
 
+  const refreshDatasetMetadata = useCallback(async () => {
+    try {
+      const dataset = await fetchDataset();
+      setDatasetInfo(dataset);
+    } catch (refreshErr) {
+      console.error("Failed to refresh dataset metadata:", refreshErr);
+    }
+  }, [setDatasetInfo]);
+
   // Initial data load - runs once on mount
   // Store setters are stable and don't need to be in deps
   useEffect(() => {
@@ -74,7 +85,6 @@ export default function Home() {
     const fetchSelectedSamples = async () => {
       if (isLassoSelection) return;
       if (selectedIds.size === 0) return;
-      if (selectionSource === "label") return;
 
       // Find IDs that are selected but not in our samples array
       const loadedIds = new Set(samples.map((s) => s.id));
@@ -131,6 +141,10 @@ export default function Home() {
         const res = await fetchLassoSelection({
           layoutKey: lassoQuery.layoutKey,
           polygon: lassoQuery.polygon,
+          labelFilter: lassoQuery.labelFilter ?? undefined,
+          view3d: lassoQuery.view3d,
+          viewportWidth: lassoQuery.viewportWidth,
+          viewportHeight: lassoQuery.viewportHeight,
           offset: 0,
           limit: SAMPLES_PER_PAGE,
           signal: abort.signal,
@@ -139,6 +153,18 @@ export default function Home() {
         setLassoResults(res.samples, res.total, false);
       } catch (err) {
         if (err instanceof DOMException && err.name === "AbortError") return;
+
+        if (
+          err instanceof ApiError &&
+          err.status === 404 &&
+          typeof err.detail === "string" &&
+          err.detail.includes("Layout not found")
+        ) {
+          clearLassoSelection();
+          void refreshDatasetMetadata();
+          return;
+        }
+
         console.error("Failed to fetch lasso selection:", err);
         setLassoResults([], 0, false);
       }
@@ -147,7 +173,14 @@ export default function Home() {
     run();
 
     return () => abort.abort();
-  }, [isLassoSelection, lassoIsLoading, lassoQuery, setLassoResults]);
+  }, [
+    clearLassoSelection,
+    isLassoSelection,
+    lassoIsLoading,
+    lassoQuery,
+    refreshDatasetMetadata,
+    setLassoResults,
+  ]);
 
   // Load more samples
   const loadMore = useCallback(async () => {
@@ -163,11 +196,26 @@ export default function Home() {
         const res = await fetchLassoSelection({
           layoutKey: lassoQuery.layoutKey,
           polygon: lassoQuery.polygon,
+          labelFilter: lassoQuery.labelFilter ?? undefined,
+          view3d: lassoQuery.view3d,
+          viewportWidth: lassoQuery.viewportWidth,
+          viewportHeight: lassoQuery.viewportHeight,
           offset: lassoSamples.length,
           limit: SAMPLES_PER_PAGE,
         });
         setLassoResults(res.samples, res.total, true);
       } catch (err) {
+        if (
+          err instanceof ApiError &&
+          err.status === 404 &&
+          typeof err.detail === "string" &&
+          err.detail.includes("Layout not found")
+        ) {
+          clearLassoSelection();
+          void refreshDatasetMetadata();
+          return;
+        }
+
         console.error("Failed to load more lasso samples:", err);
       } finally {
         setLoadingMore(false);
@@ -194,8 +242,10 @@ export default function Home() {
     lassoQuery,
     lassoSamples.length,
     lassoTotal,
+    clearLassoSelection,
     samplesLoaded,
     totalSamples,
+    refreshDatasetMetadata,
     setLassoResults,
     labelFilter,
   ]);