Metadata-Version: 2.4
Name: hyperview
Version: 0.6.2
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: <3.14,>=3.10
Requires-Dist: aiofiles>=25.1.0
Requires-Dist: datasets>=4.5.0
Requires-Dist: embed-anything>=0.7.0
Requires-Dist: esbuild-py>=0.1.6
Requires-Dist: fastapi>=0.128.0
Requires-Dist: huggingface-hub<2.0,>=1.11.0
Requires-Dist: hyper-models>=0.3.0
Requires-Dist: lancedb>=0.33.0
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: setuptools>=80.9.0
Requires-Dist: tomli>=2.0; python_version < '3.11'
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: hyper-models[ml]>=0.3.0; 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

> Interactive geometric workbench for embedding space analysis.

HyperView turns image datasets into live embedding workspaces. Load samples, compute embeddings, inspect Euclidean, hyperbolic, or spherical layouts, select clusters and outliers, and keep media, labels, layouts, selections, panels, and tools in one local workspace.

[![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 Hugging Face Spaces</a>
</p>

## Install

```bash
uv tool install --upgrade hyperview
hyperview skill install
```

For a project-local GitHub Copilot skill:

```bash
hyperview skill install --scope project --agent github-copilot --yes
```

## Python

```python
import hyperview as hv

dataset = hv.Dataset("cifar100")
dataset.add_from_huggingface("uoft-cs/cifar100", split="train", max_samples=1000)
dataset.compute_embeddings(model="openai/clip-vit-base-patch32")
dataset.compute_visualization()

hv.launch(dataset)
```

## CLI

```bash
hyperview workspace create imagenette-demo \
  --dataset imagenette_clip_20260411 \
  --activate

hyperview serve \
  --workspace imagenette-demo \
  --dataset imagenette_clip_20260411
```

Agents and scripts can control the running workspace:

```bash
hyperview ui layout set --workspace imagenette-demo --layout-key <layout-key>
hyperview ui selection set --workspace imagenette-demo --ids sample-1,sample-8
hyperview extension add .hyperview/extensions/selection-profile --workspace imagenette-demo
hyperview tools run selection_profile.summarize --workspace imagenette-demo
```

## What It Does

- Ingests image data from Hugging Face datasets or local folders.
- Computes embeddings with built-in or custom providers.
- Projects spaces into Euclidean, Poincare/hyperbolic, and spherical layouts.
- Links scatter points to thumbnails, labels, selections, and nearest neighbors.
- Adds dataset-specific Python tools and native frontend panels.
- Gives coding agents a CLI control plane for the same workspace humans inspect.

## Docs

- [Datasets](docs/datasets.md)
- [Google Colab](docs/colab.md)
- [Contributing](CONTRIBUTING.md)
- [Tests](TESTS.md)

## Why Geometry?

Embedding failures often hide in the shape of the space: collapsed classes, weak separation, hierarchy, long-tail samples, and boundary cases. HyperView lets you inspect those structures through multiple geometric views instead of a single fixed projection.

## Related Projects

- [hyper-scatter](https://github.com/Hyper3Labs/hyper-scatter): WebGL scatterplot engine for Euclidean and Poincare views.
- [hyper-models](https://github.com/Hyper3Labs/hyper-models): Non-Euclidean model zoo and ONNX exports.
- [hyper-lrp](https://github.com/Hyper3Labs/hyper-lrp): Attribution tools for inspecting model evidence.

## Community

Join the [Hyper3Labs Discord](https://discord.gg/Za3rBkTPSf) for demos, setup help, and project discussion.

## License

MIT License. See [LICENSE](LICENSE).

## Citation

If you use HyperView in research, please cite:

```bibtex
@software{hyperview2026,
  author  = {{Hyper3Labs}},
  title   = {HyperView: An Interactive Geometric Workbench for Embedding Space Analysis},
  year    = {2026},
  version = {0.6.2},
  url     = {https://github.com/Hyper3Labs/HyperView}
}
```
