hyper-models 0.1.0__tar.gz → 0.2.0__tar.gz

{hyper_models-0.1.0 → hyper_models-0.2.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: hyper-models
-Version: 0.1.0
+Version: 0.2.0
 Summary: A model zoo for non-Euclidean embedding models (hyperbolic, spherical, product manifolds)
 Project-URL: Homepage, https://github.com/Hyper3Labs/hyper-models
 Project-URL: Repository, https://github.com/Hyper3Labs/hyper-models
 Project-URL: Documentation, https://github.com/Hyper3Labs/hyper-models#readme
 Project-URL: Issues, https://github.com/Hyper3Labs/hyper-models/issues
-Author: Hyper3Labs
+Author: hyper3labs
 License: MIT
 License-File: LICENSE
 Keywords: clip,embeddings,hyperbolic,model-zoo,non-euclidean,onnx
@@ -27,6 +27,9 @@ Requires-Dist: pillow>=10.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == 'dev'
 Requires-Dist: ruff>=0.1; extra == 'dev'
+Provides-Extra: ml
+Requires-Dist: timm>=1.0.0; extra == 'ml'
+Requires-Dist: torch>=2.9.1; extra == 'ml'
 Description-Content-Type: text/markdown
 
 # hyper-models
@@ -51,13 +54,22 @@ Description-Content-Type: text/markdown
 ## Why?
 
 - **Standardized access** to non-Euclidean embedding models
-- **Torch-free runtime** via ONNX (models published to Hugging Face Hub)
+- **One catalog surface**: model names map to internal loaders such as ONNX or optional torch-backed runtimes
 - **Simple API** — `load()` and `encode_images()`
 
 ## Installation
 
 ```bash
-pip install hyper-models
+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):
+
+```bash
+uv pip install "hyper-models[ml]"
 ```
 
 ## Usage
@@ -68,7 +80,11 @@ from PIL import Image
 
 # List available models
 hyper_models.list_models()
-# ['hycoclip-vit-s', 'hycoclip-vit-b', 'meru-vit-s', 'meru-vit-b']
+# ['hycoclip-vit-s', 'hycoclip-vit-b', 'meru-vit-s', 'meru-vit-b', 'uncha-vit-s', 'uncha-vit-b']
+
+# Inspect supported internal loader kinds
+hyper_models.list_loaders()
+# ['onnx', 'uncha-image-torch']
 
 # Load model (auto-downloads from Hugging Face Hub)
 model = hyper_models.load("hycoclip-vit-s")
@@ -82,6 +98,7 @@ 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
@@ -89,6 +106,51 @@ 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
+
+This keeps callers on one stable API:
+
+```python
+model = hyper_models.load("hycoclip-vit-s")
+model = hyper_models.load("uncha-vit-b")
+```
+
+Callers do not need to know which internal loader is used, except for optional
+dependency installation when choosing entries that need `hyper-models[ml]`.
+
+### HyperView integration
+
+HyperView auto-detects `hyper-models` names and routes them to the `hyper-models` provider.
+
+```python
+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` or `uncha-vit-b`.
+
 ## Models
 
 ### Hyperbolic
@@ -99,16 +161,20 @@ embeddings = model.encode(batch)
 | `hycoclip-vit-b` | [![HF](https://img.shields.io/badge/🤗-HuggingFace-yellow)](https://huggingface.co/mnm-matin/hyperbolic-clip/tree/main/hycoclip-vit-b) | [ICLR 2025](https://arxiv.org/abs/2410.06912) | [PalAvik/hycoclip](https://github.com/PalAvik/hycoclip) |
 | `meru-vit-s` | [![HF](https://img.shields.io/badge/🤗-HuggingFace-yellow)](https://huggingface.co/mnm-matin/hyperbolic-clip/tree/main/meru-vit-s) | [ICML 2023](https://arxiv.org/abs/2304.09172) | [facebookresearch/meru](https://github.com/facebookresearch/meru) |
 | `meru-vit-b` | [![HF](https://img.shields.io/badge/🤗-HuggingFace-yellow)](https://huggingface.co/mnm-matin/hyperbolic-clip/tree/main/meru-vit-b) | [ICML 2023](https://arxiv.org/abs/2304.09172) | [facebookresearch/meru](https://github.com/facebookresearch/meru) |
+| `uncha-vit-s` | [![HF](https://img.shields.io/badge/🤗-HuggingFace-yellow)](https://huggingface.co/hayeonkim/uncha/blob/main/uncha_vit_s.pth) | [CVPR 2026](https://arxiv.org/abs/2603.22042) | [jeeit17/UNCHA](https://github.com/jeeit17/UNCHA) |
+| `uncha-vit-b` | [![HF](https://img.shields.io/badge/🤗-HuggingFace-yellow)](https://huggingface.co/hayeonkim/uncha/blob/main/uncha_vit_b.pth) | [CVPR 2026](https://arxiv.org/abs/2603.22042) | [jeeit17/UNCHA](https://github.com/jeeit17/UNCHA) |
 | `hyp-vit` | — | [CVPR 2022](https://arxiv.org/abs/2203.10833) | [htdt/hyp_metric](https://github.com/htdt/hyp_metric) |
 | `hie` | — | [CVPR 2020](https://arxiv.org/abs/1904.02239) | [leymir/hyperbolic-image-embeddings](https://github.com/leymir/hyperbolic-image-embeddings) |
 | `hcnn` | — | [ICLR 2024](https://openreview.net/forum?id=ekz1hN5QNh) | [kschwethelm/HyperbolicCV](https://github.com/kschwethelm/HyperbolicCV) |
 
-### Spherical
+### Hyperspherical
+
+| Model            | Available | Paper | Code |
+|------------------|:---------:|-------|------|
+| `megadescriptor` (via timm) | [![HF](https://img.shields.io/badge/🤗-HuggingFace-yellow)](https://huggingface.co/BVRA/MegaDescriptor-L-384) | [WACV 2024](https://openaccess.thecvf.com/content/WACV2024/papers/Cermak_WildlifeDatasets_An_Open-Source_Toolkit_for_Animal_Re-Identification_WACV_2024_paper.pdf) | [WildlifeDatasets/wildlife-datasets](https://github.com/WildlifeDatasets/wildlife-datasets) |
+| `sphereface`     | — | [CVPR 2017](https://arxiv.org/abs/1704.08063) | [wy1iu/sphereface](https://github.com/wy1iu/sphereface) |
+| `arcface`       | — | [CVPR 2019](https://arxiv.org/abs/1801.07698) | [deepinsight/insightface](https://github.com/deepinsight/insightface) |
 
-| Model | Available | Paper | Code |
-|-------|:---------:|-------|------|
-| `sphereface` | — | [CVPR 2017](https://arxiv.org/abs/1704.08063) | [wy1iu/sphereface](https://github.com/wy1iu/sphereface) |
-| `arcface` | — | [CVPR 2019](https://arxiv.org/abs/1801.07698) | [deepinsight/insightface](https://github.com/deepinsight/insightface) |
 
 ### Product Manifolds
 

{hyper_models-0.1.0 → hyper_models-0.2.0}/README.md

@@ -20,13 +20,22 @@
 ## Why?
 
 - **Standardized access** to non-Euclidean embedding models
-- **Torch-free runtime** via ONNX (models published to Hugging Face Hub)
+- **One catalog surface**: model names map to internal loaders such as ONNX or optional torch-backed runtimes
 - **Simple API** — `load()` and `encode_images()`
 
 ## Installation
 
 ```bash
-pip install hyper-models
+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):
+
+```bash
+uv pip install "hyper-models[ml]"
 ```
 
 ## Usage
@@ -37,7 +46,11 @@ from PIL import Image
 
 # List available models
 hyper_models.list_models()
-# ['hycoclip-vit-s', 'hycoclip-vit-b', 'meru-vit-s', 'meru-vit-b']
+# ['hycoclip-vit-s', 'hycoclip-vit-b', 'meru-vit-s', 'meru-vit-b', 'uncha-vit-s', 'uncha-vit-b']
+
+# Inspect supported internal loader kinds
+hyper_models.list_loaders()
+# ['onnx', 'uncha-image-torch']
 
 # Load model (auto-downloads from Hugging Face Hub)
 model = hyper_models.load("hycoclip-vit-s")
@@ -51,6 +64,7 @@ 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
@@ -58,6 +72,51 @@ 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
+
+This keeps callers on one stable API:
+
+```python
+model = hyper_models.load("hycoclip-vit-s")
+model = hyper_models.load("uncha-vit-b")
+```
+
+Callers do not need to know which internal loader is used, except for optional
+dependency installation when choosing entries that need `hyper-models[ml]`.
+
+### HyperView integration
+
+HyperView auto-detects `hyper-models` names and routes them to the `hyper-models` provider.
+
+```python
+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` or `uncha-vit-b`.
+
 ## Models
 
 ### Hyperbolic
@@ -68,16 +127,20 @@ embeddings = model.encode(batch)
 | `hycoclip-vit-b` | [![HF](https://img.shields.io/badge/🤗-HuggingFace-yellow)](https://huggingface.co/mnm-matin/hyperbolic-clip/tree/main/hycoclip-vit-b) | [ICLR 2025](https://arxiv.org/abs/2410.06912) | [PalAvik/hycoclip](https://github.com/PalAvik/hycoclip) |
 | `meru-vit-s` | [![HF](https://img.shields.io/badge/🤗-HuggingFace-yellow)](https://huggingface.co/mnm-matin/hyperbolic-clip/tree/main/meru-vit-s) | [ICML 2023](https://arxiv.org/abs/2304.09172) | [facebookresearch/meru](https://github.com/facebookresearch/meru) |
 | `meru-vit-b` | [![HF](https://img.shields.io/badge/🤗-HuggingFace-yellow)](https://huggingface.co/mnm-matin/hyperbolic-clip/tree/main/meru-vit-b) | [ICML 2023](https://arxiv.org/abs/2304.09172) | [facebookresearch/meru](https://github.com/facebookresearch/meru) |
+| `uncha-vit-s` | [![HF](https://img.shields.io/badge/🤗-HuggingFace-yellow)](https://huggingface.co/hayeonkim/uncha/blob/main/uncha_vit_s.pth) | [CVPR 2026](https://arxiv.org/abs/2603.22042) | [jeeit17/UNCHA](https://github.com/jeeit17/UNCHA) |
+| `uncha-vit-b` | [![HF](https://img.shields.io/badge/🤗-HuggingFace-yellow)](https://huggingface.co/hayeonkim/uncha/blob/main/uncha_vit_b.pth) | [CVPR 2026](https://arxiv.org/abs/2603.22042) | [jeeit17/UNCHA](https://github.com/jeeit17/UNCHA) |
 | `hyp-vit` | — | [CVPR 2022](https://arxiv.org/abs/2203.10833) | [htdt/hyp_metric](https://github.com/htdt/hyp_metric) |
 | `hie` | — | [CVPR 2020](https://arxiv.org/abs/1904.02239) | [leymir/hyperbolic-image-embeddings](https://github.com/leymir/hyperbolic-image-embeddings) |
 | `hcnn` | — | [ICLR 2024](https://openreview.net/forum?id=ekz1hN5QNh) | [kschwethelm/HyperbolicCV](https://github.com/kschwethelm/HyperbolicCV) |
 
-### Spherical
+### Hyperspherical
+
+| Model            | Available | Paper | Code |
+|------------------|:---------:|-------|------|
+| `megadescriptor` (via timm) | [![HF](https://img.shields.io/badge/🤗-HuggingFace-yellow)](https://huggingface.co/BVRA/MegaDescriptor-L-384) | [WACV 2024](https://openaccess.thecvf.com/content/WACV2024/papers/Cermak_WildlifeDatasets_An_Open-Source_Toolkit_for_Animal_Re-Identification_WACV_2024_paper.pdf) | [WildlifeDatasets/wildlife-datasets](https://github.com/WildlifeDatasets/wildlife-datasets) |
+| `sphereface`     | — | [CVPR 2017](https://arxiv.org/abs/1704.08063) | [wy1iu/sphereface](https://github.com/wy1iu/sphereface) |
+| `arcface`       | — | [CVPR 2019](https://arxiv.org/abs/1801.07698) | [deepinsight/insightface](https://github.com/deepinsight/insightface) |
 
-| Model | Available | Paper | Code |
-|-------|:---------:|-------|------|
-| `sphereface` | — | [CVPR 2017](https://arxiv.org/abs/1704.08063) | [wy1iu/sphereface](https://github.com/wy1iu/sphereface) |
-| `arcface` | — | [CVPR 2019](https://arxiv.org/abs/1801.07698) | [deepinsight/insightface](https://github.com/deepinsight/insightface) |
 
 ### Product Manifolds
 

{hyper_models-0.1.0 → hyper_models-0.2.0}/pyproject.toml

@@ -1,11 +1,11 @@
 [project]
 name = "hyper-models"
-version = "0.1.0"
+version = "0.2.0"
 description = "A model zoo for non-Euclidean embedding models (hyperbolic, spherical, product manifolds)"
 readme = "README.md"
 license = { text = "MIT" }
 requires-python = ">=3.10"
-authors = [{ name = "Hyper3Labs" }]
+authors = [{ name = "hyper3labs" }]
 keywords = ["embeddings", "hyperbolic", "onnx", "clip", "model-zoo", "non-euclidean"]
 classifiers = [
     "Development Status :: 3 - Alpha",
@@ -30,6 +30,10 @@ dev = [
     "pytest>=7.0",
     "ruff>=0.1",
 ]
+ml = [
+    "torch>=2.9.1",
+    "timm>=1.0.0",
+]
 
 [project.urls]
 Homepage = "https://github.com/Hyper3Labs/hyper-models"

{hyper_models-0.1.0 → hyper_models-0.2.0}/src/hyper_models/__init__.py

@@ -1,6 +1,7 @@
 """hyper-models: A model zoo for non-Euclidean embedding models.
 
-Hyperbolic, spherical, and product manifold models with torch-free ONNX inference.
+Hyperbolic, spherical, and product manifold models exposed through one catalog
+surface, with internal loaders such as ONNX and optional torch-backed runtimes.
 
 Example:
     >>> import hyper_models
@@ -11,12 +12,14 @@ Example:
 """
 
 from hyper_models.loader import load
+from hyper_models.loaders import list_loaders
 from hyper_models.registry import ModelInfo, get_model_info, list_models
 from hyper_models.models import ONNXModel
 from hyper_models.preprocessing import ImageConfig, preprocess_images
 
 __all__ = [
     "load",
+    "list_loaders",
     "list_models",
     "get_model_info",
     "ModelInfo",
@@ -24,5 +27,5 @@ __all__ = [
     "ImageConfig",
     "preprocess_images",
 ]
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 

{hyper_models-0.1.0 → hyper_models-0.2.0}/src/hyper_models/loader.py

@@ -1,23 +1,24 @@
-"""Model loading - download from Hub and instantiate."""
+"""Public catalog loading entrypoint for hyper-models."""
 
 from __future__ import annotations
 
 from pathlib import Path
+from typing import Any
 
 from huggingface_hub import snapshot_download
 
-from hyper_models.models import ONNXModel
+from hyper_models.loaders import load_model
 from hyper_models.registry import get_model_info
 
 __all__ = ["load"]
 
 
-def load(name: str, *, local_path: str | Path | None = None) -> ONNXModel:
+def load(name: str, *, local_path: str | Path | None = None) -> Any:
     """Load a model by name.
 
     Args:
-        name: Model name (e.g., 'hycoclip-vit-s').
-        local_path: Optional local ONNX path (skips Hub download).
+        name: Catalog model name (e.g., 'hycoclip-vit-s').
+        local_path: Optional local artifact path (skips Hub download).
 
     Returns:
         Model instance ready for inference.
@@ -28,18 +29,14 @@ def load(name: str, *, local_path: str | Path | None = None) -> ONNXModel:
     """
     info = get_model_info(name)
 
+    # Route-only entries (e.g. timm-image) raise immediately without downloading.
+    if info.loader == "timm-image":
+        return load_model(info, Path())
+
     if local_path is None:
-        hub_path = f"{info.name}/model.onnx"
-        local_dir = snapshot_download(info.hub_id, allow_patterns=[f"{hub_path}*"])
-        local_path = Path(local_dir) / hub_path
+        local_dir = snapshot_download(info.hub_id, allow_patterns=[f"{info.hub_path}*"])
+        artifact_path = Path(local_dir) / info.hub_path
     else:
-        local_path = Path(local_path)
-
-    return ONNXModel(
-        path=Path(local_path),
-        geometry=info.geometry,
-        dim=info.dim,
-        input_name=info.input_name,
-        output_name=info.output_name,
-        image_config=info.image_config,
-    )
+        artifact_path = Path(local_path)
+
+    return load_model(info, artifact_path)

hyper_models-0.2.0/src/hyper_models/loaders.py

@@ -0,0 +1,72 @@
+"""Internal loader implementations for hyper-models catalog entries."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Callable
+
+from hyper_models.models import ONNXModel
+from hyper_models.registry import ModelInfo
+
+__all__ = ["list_loaders", "load_model"]
+
+LoaderFn = Callable[[ModelInfo, Path], Any]
+
+
+def _load_onnx_model(info: ModelInfo, artifact_path: Path) -> ONNXModel:
+    return ONNXModel(
+        path=artifact_path,
+        geometry=info.geometry,
+        dim=info.dim,
+        input_name=info.input_name,
+        output_name=info.output_name,
+        image_config=info.image_config,
+    )
+
+
+def _load_uncha_image_torch_model(info: ModelInfo, artifact_path: Path) -> Any:
+    if info.variant is None:
+        raise ValueError(f"UNCHA model '{info.name}' is missing a registry variant")
+
+    from hyper_models.torch_models import UNCHATorchModel
+
+    return UNCHATorchModel(
+        checkpoint_path=artifact_path,
+        geometry=info.geometry,
+        dim=info.dim,
+        variant=info.variant,
+        image_config=info.image_config,
+    )
+
+
+def _load_timm_image_route(info: ModelInfo, artifact_path: Path) -> Any:
+    raise ValueError(
+        f"Model '{info.name}' is a timm model. "
+        f"Use HyperView provider='timm-image' with model='hf-hub:{info.hub_id}' instead.\n"
+        f"  dataset.compute_embeddings(model='hf-hub:{info.hub_id}', provider='timm-image')"
+    )
+
+
+_LOADERS: dict[str, LoaderFn] = {
+    "onnx": _load_onnx_model,
+    "uncha-image-torch": _load_uncha_image_torch_model,
+    "timm-image": _load_timm_image_route,
+}
+
+
+def list_loaders() -> list[str]:
+    """List supported internal loader kinds for catalog entries."""
+    return sorted(_LOADERS)
+
+
+def load_model(info: ModelInfo, artifact_path: Path) -> Any:
+    """Instantiate a catalog entry using the loader declared in ``ModelInfo``."""
+    try:
+        loader = _LOADERS[info.loader]
+    except KeyError:
+        available = ", ".join(sorted(_LOADERS))
+        raise ValueError(
+            f"Unsupported loader '{info.loader}' for model '{info.name}'. Available: {available}"
+        ) from None
+
+    return loader(info, artifact_path)

{hyper_models-0.1.0 → hyper_models-0.2.0}/src/hyper_models/registry.py

@@ -1,4 +1,4 @@
-"""Model registry - maps model names to hub locations and metadata."""
+"""Catalog registry for hyper-models entries and their loader metadata."""
 
 from __future__ import annotations
 
@@ -11,13 +11,22 @@ __all__ = ["ModelInfo", "list_models", "get_model_info"]
 
 @dataclass
 class ModelInfo:
-    """Metadata for a registered model."""
+    """Metadata for a registered catalog model.
+
+    `loader` describes how the catalog entry is instantiated internally.
+    This is intentionally separate from the public catalog surface so callers
+    can always use ``hyper_models.load(name)`` regardless of runtime backend.
+    """
 
     name: str
     geometry: str  # 'hyperboloid', 'poincare', 'sphere', 'euclidean'
     dim: int
     hub_id: str
+    hub_path: str
     license: str
+    loader: str = "onnx"  # e.g. 'onnx', 'uncha-image-torch'
+    variant: str | None = None  # optional loader hint (e.g., 'vit_s', 'vit_b')
+    optional_dependencies: tuple[str, ...] = ()
     description: str = ""
     input_name: str = "image"
     output_name: str | None = None
@@ -30,6 +39,7 @@ _MODELS: dict[str, ModelInfo] = {
         geometry="hyperboloid",
         dim=513,
         hub_id="mnm-matin/hyperbolic-clip",
+        hub_path="hycoclip-vit-s/model.onnx",
         license="CC-BY-NC",
         description="HyCoCLIP ViT-Small (512D hyperboloid)",
         output_name="embedding_hyperboloid",
@@ -39,6 +49,7 @@ _MODELS: dict[str, ModelInfo] = {
         geometry="hyperboloid",
         dim=513,
         hub_id="mnm-matin/hyperbolic-clip",
+        hub_path="hycoclip-vit-b/model.onnx",
         license="CC-BY-NC",
         description="HyCoCLIP ViT-Base (512D hyperboloid)",
         output_name="embedding_hyperboloid",
@@ -48,6 +59,7 @@ _MODELS: dict[str, ModelInfo] = {
         geometry="hyperboloid",
         dim=513,
         hub_id="mnm-matin/hyperbolic-clip",
+        hub_path="meru-vit-s/model.onnx",
         license="CC-BY-NC",
         description="MERU ViT-Small (512D hyperboloid)",
         output_name="embedding_hyperboloid",
@@ -57,10 +69,46 @@ _MODELS: dict[str, ModelInfo] = {
         geometry="hyperboloid",
         dim=513,
         hub_id="mnm-matin/hyperbolic-clip",
+        hub_path="meru-vit-b/model.onnx",
         license="CC-BY-NC",
         description="MERU ViT-Base (512D hyperboloid)",
         output_name="embedding_hyperboloid",
     ),
+    "uncha-vit-s": ModelInfo(
+        name="uncha-vit-s",
+        geometry="hyperboloid",
+        dim=513,
+        hub_id="hayeonkim/uncha",
+        hub_path="uncha_vit_s.pth",
+        license="Unknown",
+        loader="uncha-image-torch",
+        variant="vit_s",
+        optional_dependencies=("ml",),
+        description="UNCHA ViT-S/16 checkpoint (HF .pth, torch inference)",
+    ),
+    "uncha-vit-b": ModelInfo(
+        name="uncha-vit-b",
+        geometry="hyperboloid",
+        dim=513,
+        hub_id="hayeonkim/uncha",
+        hub_path="uncha_vit_b.pth",
+        license="Unknown",
+        loader="uncha-image-torch",
+        variant="vit_b",
+        optional_dependencies=("ml",),
+        description="UNCHA ViT-B/16 checkpoint (HF .pth, torch inference)",
+    ),
+    "megadescriptor": ModelInfo(
+        name="megadescriptor",
+        geometry="sphere",
+        dim=1024,
+        hub_id="BVRA/MegaDescriptor-L-384",
+        hub_path="",
+        license="MIT",
+        loader="timm-image",
+        description="MegaDescriptor-L-384 (via timm, use provider='timm-image')",
+        image_config=ImageConfig(size=384),
+    ),
 }
 
 

hyper_models-0.2.0/src/hyper_models/torch_models.py

@@ -0,0 +1,230 @@
+"""Torch-backed catalog model implementations.
+
+These are internal loader targets used by selected hyper-models catalog entries.
+They do not create a separate public provider surface.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+from PIL import Image
+
+from hyper_models.preprocessing import ImageConfig, preprocess_images
+
+__all__ = ["UNCHATorchModel"]
+
+
+class _UNCHAImageEncoder:
+    """Minimal UNCHA image encoder graph for inference-only embeddings."""
+
+    def __init__(self, torch: Any, timm: Any, nn: Any, *, variant: str) -> None:
+        self._torch = torch
+        self._timm = timm
+        self._nn = nn
+        self._variant = variant
+
+        self._register_custom_variants()
+        self.visual = self._build_visual()
+        self.visual_proj = nn.Linear(self.visual.width, 512, bias=False)
+
+        self.visual_alpha = nn.Parameter(torch.tensor(512**-0.5).log())
+        self.curv = nn.Parameter(torch.tensor(1.0).log())
+
+        self.pixel_mean = torch.tensor((0.485, 0.456, 0.406)).view(1, 3, 1, 1)
+        self.pixel_std = torch.tensor((0.229, 0.224, 0.225)).view(1, 3, 1, 1)
+
+    def _register_custom_variants(self) -> None:
+        if self._timm.models.is_model("vit_small_mocov3_patch16_224"):
+            return
+
+        @self._timm.models.register_model
+        def vit_small_mocov3_patch16_224(**kwargs: Any):
+            return self._timm.models.vision_transformer._create_vision_transformer(
+                "vit_small_patch16_224",
+                patch_size=16,
+                embed_dim=384,
+                depth=12,
+                num_heads=12,
+                **kwargs,
+            )
+
+    def _build_visual(self) -> Any:
+        arch = {
+            "vit_s": "vit_small_mocov3_patch16_224",
+            "vit_b": "vit_base_patch16_224",
+        }[self._variant]
+
+        visual = self._timm.create_model(
+            arch,
+            num_classes=0,
+            global_pool="token",
+            class_token=True,
+            norm_layer=self._nn.LayerNorm,
+            pretrained=False,
+        )
+
+        # Match upstream UNCHA image encoder API expected by projection layers.
+        visual.width = int(getattr(visual, "embed_dim", getattr(visual, "num_features", 0)))
+        if visual.width <= 0:
+            raise RuntimeError("Unable to infer visual width for UNCHA image encoder")
+        return visual
+
+    def _exp_map0(self, tangent: Any, curvature: Any) -> Any:
+        torch = self._torch
+        sqrt_curvature = torch.sqrt(curvature)
+        norm = torch.linalg.norm(tangent, dim=-1, keepdim=True).clamp_min(1e-12)
+        scale = torch.sinh(sqrt_curvature * norm) / (sqrt_curvature * norm)
+        return tangent * scale
+
+    def _lift_hyperboloid(self, space: Any, curvature: Any) -> Any:
+        torch = self._torch
+        time = torch.sqrt((1.0 / curvature) + torch.sum(space * space, dim=-1, keepdim=True))
+        return torch.cat([time, space], dim=-1)
+
+    def encode(self, images_bchw: Any) -> Any:
+        torch = self._torch
+
+        images = (images_bchw - self.pixel_mean) / self.pixel_std
+        image_feats = self.visual(images)
+        image_feats = self.visual_proj(image_feats)
+
+        visual_scale = torch.exp(torch.clamp(self.visual_alpha, max=0.0))
+        tangent = image_feats * visual_scale
+
+        curvature = torch.exp(self.curv).clamp(min=1e-8)
+        space = self._exp_map0(tangent, curvature)
+        return self._lift_hyperboloid(space, curvature)
+
+
+class UNCHATorchModel:
+    """UNCHA catalog entry runtime using torch+timm for image inference."""
+
+    def __init__(
+        self,
+        checkpoint_path: Path,
+        *,
+        geometry: str,
+        dim: int,
+        variant: str,
+        image_config: ImageConfig | None = None,
+        device: str | None = None,
+    ) -> None:
+        self._checkpoint_path = checkpoint_path
+        self.geometry = geometry
+        self.dim = dim
+        self._variant = variant
+        self._image_config = image_config or ImageConfig()
+        self._device_override = device
+
+        self._torch = None
+        self._device = None
+        self._encoder = None
+
+    def _import_ml_stack(self) -> tuple[Any, Any, Any]:
+        try:
+            import timm
+            import torch
+            from torch import nn
+        except ImportError as e:
+            raise ImportError(
+                "This catalog entry requires the optional 'ml' dependencies. "
+                "Install with: uv sync --extra ml or uv pip install 'hyper-models[ml]'"
+            ) from e
+
+        return torch, timm, nn
+
+    def _resolve_device(self, torch: Any) -> Any:
+        if self._device_override:
+            return torch.device(self._device_override)
+        if torch.cuda.is_available():
+            return torch.device("cuda")
+        if hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
+            return torch.device("mps")
+        return torch.device("cpu")
+
+    def _load_state_dict(self) -> dict[str, Any]:
+        assert self._torch is not None
+
+        checkpoint_obj = self._torch.load(
+            self._checkpoint_path,
+            map_location="cpu",
+            weights_only=False,
+        )
+
+        if isinstance(checkpoint_obj, dict) and "model" in checkpoint_obj:
+            model_state = checkpoint_obj["model"]
+            if isinstance(model_state, dict):
+                return model_state
+
+        if isinstance(checkpoint_obj, dict):
+            return checkpoint_obj
+
+        raise TypeError("Unexpected UNCHA checkpoint format; expected dict or {'model': state_dict}")
+
+    def _ensure_encoder(self) -> None:
+        if self._encoder is not None:
+            return
+
+        torch, timm, nn = self._import_ml_stack()
+        self._torch = torch
+        self._device = self._resolve_device(torch)
+
+        encoder = _UNCHAImageEncoder(torch, timm, nn, variant=self._variant)
+        state_dict = self._load_state_dict()
+
+        own_state: dict[str, Any] = {}
+        for key, value in state_dict.items():
+            if key.startswith("module."):
+                key = key[len("module.") :]
+            if key.startswith("model."):
+                key = key[len("model.") :]
+
+            if key.startswith("visual.") or key.startswith("visual_proj."):
+                own_state[key] = value
+            elif key in {"visual_alpha", "curv"}:
+                own_state[key] = value
+
+        module = torch.nn.Module()
+        module.visual = encoder.visual
+        module.visual_proj = encoder.visual_proj
+        module.visual_alpha = encoder.visual_alpha
+        module.curv = encoder.curv
+
+        load_result = module.load_state_dict(own_state, strict=False)
+        if len(own_state) == 0:
+            raise RuntimeError("UNCHA checkpoint did not contain visual encoder weights")
+        if "visual_proj.weight" in load_result.missing_keys:
+            raise RuntimeError("UNCHA checkpoint missing required key: visual_proj.weight")
+
+        encoder.visual = module.visual.to(self._device)
+        encoder.visual_proj = module.visual_proj.to(self._device)
+        encoder.visual_alpha = torch.nn.Parameter(module.visual_alpha.to(self._device))
+        encoder.curv = torch.nn.Parameter(module.curv.to(self._device))
+        encoder.pixel_mean = encoder.pixel_mean.to(self._device)
+        encoder.pixel_std = encoder.pixel_std.to(self._device)
+
+        encoder.visual.eval()
+        encoder.visual_proj.eval()
+
+        self._encoder = encoder
+
+    def encode(self, inputs: np.ndarray) -> np.ndarray:
+        """Encode preprocessed inputs (B, C, H, W) to embeddings (B, D)."""
+        self._ensure_encoder()
+
+        assert self._encoder is not None
+        assert self._torch is not None
+        assert self._device is not None
+
+        images = self._torch.from_numpy(inputs).to(device=self._device, dtype=self._torch.float32)
+        with self._torch.inference_mode():
+            emb = self._encoder.encode(images)
+
+        return np.asarray(emb.detach().cpu().numpy(), dtype=np.float32)
+
+    def encode_images(self, images: list[Image.Image]) -> np.ndarray:
+        """Encode PIL images to embeddings (B, D)."""
+        return self.encode(preprocess_images(images, self._image_config))