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.

Users of the retired hyper3-haystack package should install the extra above and change the import to hyper_models.integrations.haystack. The component names and native embedding format are unchanged; saved pipelines must be recreated with the new import path. 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

Model	Available	Paper	Code
hycoclip-vit-s		ICLR 2025	PalAvik/hycoclip
hycoclip-vit-b		ICLR 2025	PalAvik/hycoclip
meru-vit-s		ICML 2023	facebookresearch/meru
meru-vit-b		ICML 2023	facebookresearch/meru
uncha-vit-s		CVPR 2026	jeeit17/UNCHA
uncha-vit-b		CVPR 2026	jeeit17/UNCHA
hyper3-clip-v1		—	Hyper3Labs/hyper3-clip
hyp-vit	—	CVPR 2022	htdt/hyp_metric
hie	—	CVPR 2020	leymir/hyperbolic-image-embeddings
hcnn	—	ICLR 2024	kschwethelm/HyperbolicCV

Hyperspherical

Model	Available	Paper	Code
megadescriptor (via timm)		WACV 2024	WildlifeDatasets/wildlife-datasets
sphereface	—	CVPR 2017	wy1iu/sphereface
arcface	—	CVPR 2019	deepinsight/insightface

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

• HyCoCLIP
• MERU
• geoopt

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.