refactor: unify embedding providers via LanceDB registry

- Replace BaseEmbeddingProvider/ModelSpec with LanceDB registry-based EmbeddingSpec
- Add embed-anything and hyper-models as @register'd LanceDB embedding functions
- Make model parameter required in compute_embeddings() with auto-detection
- Add list_embedding_providers() and get_provider_info() to public API
- Use uv workspace for hyper-models dependency (local development)
- Add CONTRIBUTING.md with development setup guide
- Update docs to use full HuggingFace model IDs
- Smarter default geometry selection in launch() auto-layout

Author: mnm-matin

CONTRIBUTING.md

@@ -0,0 +1,82 @@
+# Contributing to HyperView
+
+We welcome contributions! This guide will help you set up your development environment and submit high-quality pull requests.
+
+## Development Setup
+
+### Requirements
+- **Python 3.10+**
+- **uv** (Package manager)
+- **Node.js** (For frontend development)
+
+### One-time Setup
+Clone the repo and install dependencies:
+
+```bash
+git clone https://github.com/Hyper3Labs/HyperView.git
+cd HyperView
+
+# Create virtual environment and install dev dependencies
+uv venv .venv
+source .venv/bin/activate
+uv pip install -e ".[dev]"
+
+# Install frontend dependencies
+cd frontend
+npm install
+cd ..
+```
+
+## Running Locally
+
+For the best development experience, run the backend and frontend in separate terminals.
+
+### 1. Start the Backend
+Runs the Python API server at `http://127.0.0.1:6262`.
+
+```bash
+uv run hyperview demo --samples 200 --no-browser
+```
+
+_Tip: Use `HF_DATASETS_OFFLINE=1` if you have cached datasets and want to work offline._
+
+### 2. Start the Frontend
+Runs the Next.js dev server at `http://127.0.0.1:3000` with hot reloading.
+
+```bash
+cd frontend
+npm run dev
+```
+
+The frontend automatically proxies API requests (`/api/*`) to the backend.
+
+## Common Tasks
+
+### Testing & Linting
+Please ensure all checks pass before submitting a PR.
+
+```bash
+# Python
+uv run pytest             # Run unit tests
+uv run ruff format .      # formatting
+uv run ruff check . --fix # Linting
+
+# Frontend
+cd frontend
+npm run lint
+```
+
+### Exporting the Frontend
+The Python package bundles the compiled frontend. If you modify the frontend, you must regenerate the static assets so they can be served by the Python backend in production/demos.
+
+```bash
+bash scripts/export_frontend.sh
+```
+_This compiles the frontend and places artifacts into `src/hyperview/server/static/`. Do not edit files in that directory manually._
+
+## Pull Request Guidelines
+
+1.  **Scope**: Keep changes focused. Open an issue first for major refactors or new features.
+2.  **Tests**: Add tests for new logic where practical.
+3.  **Visuals**: If changing the UI, please attach a screenshot or GIF to your PR.
+4.  **Format**: Ensure code is formatted with `ruff` (Python) and `prettier` (JS/TS implicit in `npm run lint`).

README.md

@@ -68,7 +68,7 @@ dataset.add_from_huggingface(
 # dataset.add_images_dir("/path/to/images", label_from_folder=True)
 
 # Compute embeddings and visualization
-dataset.compute_embeddings()
+dataset.compute_embeddings(model="openai/clip-vit-base-patch32")
 dataset.compute_visualization()
 
 # Launch the UI

docs/datasets.md

@@ -63,8 +63,8 @@ Samples are **never implicitly deleted**. Use `hv.Dataset.delete("name")` for ex
 ## Computing Embeddings
 
 ```python
-# High-dimensional embeddings (CLIP/ResNet)
-dataset.compute_embeddings(model="clip", show_progress=True)
+# 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

notebooks/demo.ipynb

@@ -26,7 +26,7 @@ dependencies = [
     "fastapi>=0.128.0",
     "uvicorn[standard]>=0.40.0",
     "embed-anything>=0.7.0",
-    "hyper-models @ git+https://github.com/Hyper3Labs/hyper-models.git@7489595f4f665802671136872b2bf61794995e1b",
+    "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",
@@ -88,3 +88,9 @@ ignore = ["E501"]
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
 testpaths = ["tests"]
+
+[tool.uv.workspace]
+members = ["hyper_models"]
+
+[tool.uv.sources]
+hyper-models = { workspace = true }

pyproject.toml

@@ -68,11 +68,11 @@ def main():
         max_samples=args.samples,
     )
 
-    dataset.compute_embeddings(model=args.model, show_progress=True)
+    space_key = dataset.compute_embeddings(model=args.model, show_progress=True)
 
-    # Compute both euclidean and poincare layouts
-    dataset.compute_visualization(geometry="euclidean")
-    dataset.compute_visualization(geometry="poincare")
+    # Compute a single layout for the UI to display by default.
+    # Switch to geometry="euclidean" for standard 2D UMAP.
+    dataset.compute_visualization(space_key=space_key, geometry="poincare")
 
     if args.no_server:
         return

scripts/demo.py

@@ -1,18 +1,16 @@
 #!/usr/bin/env python
-"""Demo: CLIP (Euclidean) + HyCoCLIP (Poincaré) on CIFAR-100."""
+"""Demo: CLIP (Euclidean) + hyper-models (Poincaré) on CIFAR-100."""
 
 import hyperview as hv
-import hyperview.embeddings.providers.hycoclip  # noqa: F401
-from hyperview.embeddings.providers import ModelSpec
 
-DATASET_NAME = "cifar100_clip_hycoclip"
+DATASET_NAME = "cifar100_clip_hyper_models"
 HF_DATASET = "uoft-cs/cifar100"
 HF_SPLIT = "test"
 HF_IMAGE_KEY = "img"
 HF_LABEL_KEY = "fine_label"
 NUM_SAMPLES = 200
 CLIP_MODEL_ID = "openai/clip-vit-base-patch32"
-HYCOCLIP_MODEL_ID = "hycoclip_vit_s"
+HYPER_MODELS_MODEL_ID = "hycoclip-vit-s"
 
 
 def main() -> None:
@@ -29,9 +27,8 @@ def main() -> None:
 
     clip_space = dataset.compute_embeddings(CLIP_MODEL_ID)
     dataset.compute_visualization(space_key=clip_space, geometry="euclidean")
-    hycoclip_spec = ModelSpec(provider="hycoclip", model_id=HYCOCLIP_MODEL_ID)
-    hycoclip_space = dataset.compute_embeddings(hycoclip_spec)
-    dataset.compute_visualization(space_key=hycoclip_space, geometry="poincare")
+    hyper_space = dataset.compute_embeddings(model=HYPER_MODELS_MODEL_ID)
+    dataset.compute_visualization(space_key=hyper_space, geometry="poincare")
 
     print("Launching at http://127.0.0.1:6262")
 

scripts/demo_hyperbolic_clip.py

@@ -1,6 +1,18 @@
 """HyperView - Open-source dataset curation with hyperbolic embeddings visualization."""
 
 from hyperview.api import Dataset, launch
+from hyperview.embeddings.engine import (
+    EmbeddingSpec,
+    get_provider_info,
+    list_embedding_providers,
+)
 
 __version__ = "0.1.0"
-__all__ = ["Dataset", "launch", "__version__"]
+__all__ = [
+    "Dataset",
+    "EmbeddingSpec",
+    "get_provider_info",
+    "launch",
+    "list_embedding_providers",
+    "__version__",
+]