hyper-models
A model zoo for non-Euclidean embedding models
Hyperbolic · Spherical · Product Manifolds
Why?
- Standardized access to non-Euclidean embedding models
- One catalog surface: model names map to internal loaders such as ONNX or optional torch-backed runtimes
- Simple API —
load() and encode_images()
Installation
uv pip install hyper-models
This base install is the simple path: it stays torch-free and is enough for
ONNX-backed catalog entries such as HyCoCLIP and MERU.
For torch-backed checkpoints (for example UNCHA and Hyper3-CLIP):
uv pip install "hyper-models[ml]"
Usage
import hyper_models
from PIL import Image
# List available models
hyper_models.list_models()
# ['hycoclip-vit-s', 'hycoclip-vit-b', 'meru-vit-s', 'meru-vit-b', 'uncha-vit-s', 'uncha-vit-b', 'hyper3-clip-v1']
# Inspect supported internal loader kinds
hyper_models.list_loaders()
# ['hyper3-clip-torch', 'onnx', 'uncha-image-torch']
# Load model (auto-downloads from Hugging Face Hub)
model = hyper_models.load("hycoclip-vit-s")
model.geometry # 'hyperboloid'
model.dim # 513
# Encode PIL images
images = [Image.open("image.jpg")]
embeddings = model.encode_images(images) # (1, 513) ndarray
# Get model info
info = hyper_models.get_model_info("hycoclip-vit-s")
info.hub_id # 'mnm-matin/hyperbolic-clip'
info.loader # 'onnx'
info.license # 'CC-BY-NC'
# Low-level: preprocess images yourself
batch = hyper_models.preprocess_images(images) # (B, 3, 224, 224)
embeddings = model.encode(batch)
Architecture
hyper-models is intended to be a timm-like catalog for non-Euclidean models.
- The public abstraction is the catalog entry name, for example
hycoclip-vit-s.
- Each entry declares metadata such as geometry, dimensionality, artifact path,
and an internal loader kind.
- Internal loaders may differ by model family:
onnx for exported, torch-free runtimes
uncha-image-torch for raw checkpoints that need a PyTorch image runtime
hyper3-clip-torch for Hyper3-CLIP safetensors checkpoints
This keeps callers on one stable API:
model = hyper_models.load("hycoclip-vit-s")
model = hyper_models.load("uncha-vit-b")
model = hyper_models.load("hyper3-clip-v1")
Callers do not need to know which internal loader is used, except for optional
dependency installation when choosing entries that need hyper-models[ml].
For hyper3-clip-v1, encode_images(images) and encode_texts(texts) return
513-coordinate Lorentz embeddings in the same space. The loader downloads the
model's runtime configuration, weights, and tokenizer together. Complete the
model's Hugging Face access form and run hf auth login before the first download.
load() also accepts revision, token, local_files_only, and device as
keyword arguments. Pin revision when queries must use the same weights as an
existing image index. The Hyper3-CLIP runtime exposes warm_up() for explicit loading.
Haystack integration
Install the optional integration and the Transformers 5 model runtime:
pip install "hyper-models[ml,haystack]>=0.4.0"
from hyper_models.integrations.haystack import (
Hyper3DocumentImageEmbedder,
Hyper3TextEmbedder,
)
The components wrap the SDK's Hyper3-CLIP image and text encoders and return native
513-coordinate Lorentz embeddings. Both pin the released model revision by
default and share a loaded model when their configuration matches. Complete the
model's access form and authenticate with hf auth login, HF_TOKEN, or
HF_API_TOKEN before first use.
For retrieval, store the native image embeddings unchanged. Use Haystack's
OutputAdapter to negate only the first query coordinate before passing it to
an InMemoryEmbeddingRetriever backed by a dot-product document store:
from haystack.components.converters import OutputAdapter
lorentz_query = OutputAdapter(
template="{{ [-embedding[0]] + embedding[1:] }}",
output_type=list[float],
)
This computes the Lorentz inner product, -q0*x0 + qs·xs. Higher scores rank
nearer points first; use scale_score=False to retain the raw scores. See the
complete indexing and retrieval example.
Query and image embeddings must use the same model revision. Normalizing vectors
changes the scoring; approximate indexes need separate recall validation.
The optional module is not imported by the base SDK.
These components accept the hyper3-clip-v1 catalog name or its Hub ID and load
Hub snapshots, including cached offline snapshots. For arbitrary local checkpoint
files, use the SDK's load(..., local_path=...) API directly.
When loading a trusted saved pipeline, allow the module explicitly:
Pipeline.loads(yaml_text, allowed_modules=["hyper_models.integrations.haystack"]).
Run the SDK tests with pytest -m "not integration". After caching the pinned
model, run pytest -m integration tests/test_haystack_live.py for the real image,
text, and Lorentz retrieval check.
HyperView integration
HyperView auto-detects hyper-models names and routes them to the hyper-models provider.
import hyperview as hv
dataset = hv.Dataset.from_huggingface(
name="demo",
hf_dataset="uoft-cs/cifar10",
split="train",
image_key="img",
)
# Uses provider='hyper-models' automatically.
space_key = dataset.compute_embeddings(model="uncha-vit-b")
layout_key = dataset.compute_visualization(space_key=space_key, layout="poincare")
HyperView's simple path remains torch-free. If you use the default ONNX-backed
hyper-models entries or the default embed-anything provider, HyperView does
not need PyTorch. PyTorch is only needed when you explicitly select a
torch-backed catalog entry such as uncha-vit-s, uncha-vit-b, or
hyper3-clip-v1.
Models
Hyperbolic
Hyperspherical
Product Manifolds
Export Tooling
This repo also contains tooling to export PyTorch models to ONNX:
cd export/hycoclip
uv run python export_onnx.py --checkpoint model.pth --onnx model.onnx
See export/hycoclip/README.md for details.
References
License
The SDK uses the MIT license. The optional Haystack integration retains its
Apache-2.0 license; see NOTICE. Model weights retain their own licenses.