hyperview 0.1.0__tar.gz

hyperview-0.1.0/.gitignore

@@ -0,0 +1,76 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+env/
+venv/
+.venv/
+/uv.lock
+*.egg-info/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Jupyter Notebooks
+.ipynb_checkpoints
+
+# macOS
+.DS_Store
+
+# VS Code
+.vscode/
+
+# Generated assets
+assets/demo_animation_frames/
+*.gif
+
+# Frontend
+frontend/node_modules/
+frontend/.next/
+frontend/out/
+
+# Bundled frontend in Python package (built in CI during release)
+src/hyperview/server/static/
+
+# Python package build
+dist/
+build/
+*.egg-info/
+
+# Data cache
+*.hf/
+.cache/
+
+# external repo (https://github.com/Hyper3Labs/hyper-scatter)
+hyper-scatter/
+
+# nohup
+nohup.out
+frontend/nohup.out
+
+# Local logs / tool artifacts
+.hyperview-*.log
+.hyperview-*.pid
+.playwright-mcp/
+frontend/tsconfig.tsbuildinfo
+
+# Hyperbolic model zoo (kept as a separate repo)
+hyper_model_zoo/
+hyper_models/
+scripts_ignored/
+
+# AI Context (Agent files)
+.claude/
+context/
+CLAUDE.md
+TASKS.md
+TESTS.md
+AGENTS.md
+**/AGENTS.md
+.github/agents/
+.specstory/
+
+# Generated version file (hatch-vcs)
+src/hyperview/_version.py

hyperview-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Matin Mahmood
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hyperview-0.1.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: hyperview
+Version: 0.1.0
+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
+Project-URL: Repository, https://github.com/Hyper3Labs/HyperView
+Project-URL: Issues, https://github.com/Hyper3Labs/HyperView/issues
+Author: hyper3labs
+License: MIT
+License-File: LICENSE
+Keywords: curation,dataset,embeddings,hyperbolic,machine-learning,visualization
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Requires-Dist: aiofiles>=25.1.0
+Requires-Dist: datasets>=4.5.0
+Requires-Dist: embed-anything>=0.7.0
+Requires-Dist: fastapi>=0.128.0
+Requires-Dist: hyper-models>=0.1.0
+Requires-Dist: lancedb>=0.26.1
+Requires-Dist: numpy<2.4,>=1.26.4
+Requires-Dist: pillow>=12.1.0
+Requires-Dist: pyarrow>=22.0.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: umap-learn>=0.5.11
+Requires-Dist: uvicorn[standard]>=0.40.0
+Provides-Extra: dev
+Requires-Dist: httpx>=0.28.1; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
+Requires-Dist: pytest>=9.0.2; extra == 'dev'
+Requires-Dist: ruff>=0.14.13; extra == 'dev'
+Provides-Extra: ml
+Requires-Dist: timm>=1.0.0; extra == 'ml'
+Requires-Dist: torch>=2.9.1; extra == 'ml'
+Requires-Dist: torchvision>=0.24.1; extra == 'ml'
+Description-Content-Type: text/markdown
+
+# 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)
+
+<p align="center">
+  <a href="https://youtu.be/XLaa8FHSQtc" target="_blank">
+    <img src="assets/screenshot.png" alt="HyperView Screenshot" width="100%">
+  </a>
+  <br>
+  <a href="https://youtu.be/XLaa8FHSQtc" target="_blank">Watch the Demo Video</a>
+</p>
+
+---
+
+## Features
+
+- **Dual-Panel UI**: Image grid + scatter plot with bidirectional selection
+- **Euclidean/Poincaré Toggle**: Switch between standard 2D UMAP and Poincaré disk visualization
+- **HuggingFace Integration**: Load datasets directly from HuggingFace Hub
+- **Fast Embeddings**: Uses EmbedAnything for CLIP-based image embeddings
+
+## 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
+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]"
+```
+
+### Run the Demo
+
+```bash
+hyperview demo --samples 500
+```
+
+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**
+
+### 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.
+
+### Save and Load Datasets
+
+```python
+# Save dataset with embeddings
+dataset.save("my_dataset.json")
+
+# Load later
+dataset = hv.Dataset.load("my_dataset.json")
+hv.launch(dataset)
+```
+
+## Why Hyperbolic?
+
+Traditional Euclidean embeddings struggle with hierarchical data. In Euclidean space, volume grows polynomially ($r^d$), causing **Representation Collapse** where minority classes get crushed together.
+
+**Hyperbolic space** (Poincaré disk) has exponential volume growth ($e^r$), naturally preserving hierarchical structure and keeping rare classes distinct.
+
+<p align="center">
+  <img src="assets/hyperview_infographic.png" alt="Euclidean vs Hyperbolic" width="100%">
+</p>
+
+## 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 (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)
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

hyperview-0.1.0/README.md

@@ -0,0 +1,119 @@
+# 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)
+
+<p align="center">
+  <a href="https://youtu.be/XLaa8FHSQtc" target="_blank">
+    <img src="assets/screenshot.png" alt="HyperView Screenshot" width="100%">
+  </a>
+  <br>
+  <a href="https://youtu.be/XLaa8FHSQtc" target="_blank">Watch the Demo Video</a>
+</p>
+
+---
+
+## Features
+
+- **Dual-Panel UI**: Image grid + scatter plot with bidirectional selection
+- **Euclidean/Poincaré Toggle**: Switch between standard 2D UMAP and Poincaré disk visualization
+- **HuggingFace Integration**: Load datasets directly from HuggingFace Hub
+- **Fast Embeddings**: Uses EmbedAnything for CLIP-based image embeddings
+
+## 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
+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]"
+```
+
+### Run the Demo
+
+```bash
+hyperview demo --samples 500
+```
+
+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**
+
+### 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.
+
+### Save and Load Datasets
+
+```python
+# Save dataset with embeddings
+dataset.save("my_dataset.json")
+
+# Load later
+dataset = hv.Dataset.load("my_dataset.json")
+hv.launch(dataset)
+```
+
+## Why Hyperbolic?
+
+Traditional Euclidean embeddings struggle with hierarchical data. In Euclidean space, volume grows polynomially ($r^d$), causing **Representation Collapse** where minority classes get crushed together.
+
+**Hyperbolic space** (Poincaré disk) has exponential volume growth ($e^r$), naturally preserving hierarchical structure and keeping rare classes distinct.
+
+<p align="center">
+  <img src="assets/hyperview_infographic.png" alt="Euclidean vs Hyperbolic" width="100%">
+</p>
+
+## 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 (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)
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

hyperview-0.1.0/pyproject.toml

@@ -0,0 +1,103 @@
+[project]
+name = "hyperview"
+dynamic = ["version"]
+description = "Open-source dataset curation with hyperbolic embeddings visualization"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [
+    { name = "hyper3labs" }
+]
+keywords = ["embeddings", "visualization", "hyperbolic", "dataset", "curation", "machine-learning"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Scientific/Engineering :: Visualization",
+]
+
+dependencies = [
+    "fastapi>=0.128.0",
+    "uvicorn[standard]>=0.40.0",
+    "embed-anything>=0.7.0",
+    "hyper-models>=0.1.0",  # PyPI package: https://pypi.org/project/hyper-models/
+    "numpy>=1.26.4,<2.4",
+    "umap-learn>=0.5.11",
+    "pillow>=12.1.0",
+    "pydantic>=2.12.5",
+    "aiofiles>=25.1.0",
+    "datasets>=4.5.0",
+    "lancedb>=0.26.1",
+    "pyarrow>=22.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
+    "httpx>=0.28.1",
+    "ruff>=0.14.13",
+]
+ml = [
+    "torch>=2.9.1",
+    "torchvision>=0.24.1",
+    "timm>=1.0.0",
+]
+
+[project.scripts]
+hyperview = "hyperview.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/Hyper3Labs/HyperView"
+Documentation = "https://github.com/Hyper3Labs/HyperView#readme"
+Repository = "https://github.com/Hyper3Labs/HyperView"
+Issues = "https://github.com/Hyper3Labs/HyperView/issues"
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/hyperview/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hyperview"]
+# Include frontend static assets (pre-built before packaging)
+artifacts = ["src/hyperview/server/static/**"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/README.md",
+    "/LICENSE",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]
+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.0/src/hyperview/__init__.py

@@ -0,0 +1,14 @@
+"""HyperView - Open-source dataset curation with hyperbolic embeddings visualization."""
+
+from . import _version as _version
+from . import api as _api
+
+Dataset = _api.Dataset
+launch = _api.launch
+__version__ = _version.__version__
+
+__all__ = [
+    "Dataset",
+    "launch",
+    "__version__",
+]

hyperview-0.1.0/src/hyperview/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None