hyper-models 0.3.0__tar.gz → 0.3.2__tar.gz

{hyper_models-0.3.0 → hyper_models-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: hyper-models
-Version: 0.3.0
+Version: 0.3.2
 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
@@ -22,11 +22,13 @@ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Requires-Python: >=3.10
 Requires-Dist: huggingface-hub>=1.0
 Requires-Dist: numpy>=1.26
-Requires-Dist: onnxruntime>=1.20
+Requires-Dist: onnxruntime<1.24,>=1.20; python_version < '3.11'
+Requires-Dist: onnxruntime>=1.20; python_version >= '3.11'
 Requires-Dist: pillow>=10.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == 'dev'
 Requires-Dist: ruff>=0.1; extra == 'dev'
+Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'dev'
 Provides-Extra: ml
 Requires-Dist: protobuf>=4.25.0; extra == 'ml'
 Requires-Dist: pyyaml>=6.0.0; extra == 'ml'
@@ -85,7 +87,7 @@ 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-v0.5']
+# ['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()
@@ -128,7 +130,7 @@ This keeps callers on one stable API:
 ```python
 model = hyper_models.load("hycoclip-vit-s")
 model = hyper_models.load("uncha-vit-b")
-model = hyper_models.load("hyper3-clip-v0.5")
+model = hyper_models.load("hyper3-clip-v1")
 ```
 
 Callers do not need to know which internal loader is used, except for optional
@@ -157,7 +159,7 @@ 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-v0.5`.
+`hyper3-clip-v1`.
 
 ## Models
 
@@ -171,7 +173,7 @@ torch-backed catalog entry such as `uncha-vit-s`, `uncha-vit-b`, or
 | `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) |
-| `hyper3-clip-v0.5` | [![HF](https://img.shields.io/badge/🤗-HuggingFace-yellow)](https://huggingface.co/hyper3labs/hyper3-clip-v0.5) | — | [Hyper3Labs/hyper3-clip](https://github.com/Hyper3Labs/hyper3-clip) |
+| `hyper3-clip-v1` | [![HF](https://img.shields.io/badge/🤗-HuggingFace-yellow)](https://huggingface.co/hyper3labs/hyper3-clip-v1) | — | [Hyper3Labs/hyper3-clip](https://github.com/Hyper3Labs/hyper3-clip) |
 | `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) |

{hyper_models-0.3.0 → hyper_models-0.3.2}/README.md

@@ -46,7 +46,7 @@ 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-v0.5']
+# ['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()
@@ -89,7 +89,7 @@ This keeps callers on one stable API:
 ```python
 model = hyper_models.load("hycoclip-vit-s")
 model = hyper_models.load("uncha-vit-b")
-model = hyper_models.load("hyper3-clip-v0.5")
+model = hyper_models.load("hyper3-clip-v1")
 ```
 
 Callers do not need to know which internal loader is used, except for optional
@@ -118,7 +118,7 @@ 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-v0.5`.
+`hyper3-clip-v1`.
 
 ## Models
 
@@ -132,7 +132,7 @@ torch-backed catalog entry such as `uncha-vit-s`, `uncha-vit-b`, or
 | `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) |
-| `hyper3-clip-v0.5` | [![HF](https://img.shields.io/badge/🤗-HuggingFace-yellow)](https://huggingface.co/hyper3labs/hyper3-clip-v0.5) | — | [Hyper3Labs/hyper3-clip](https://github.com/Hyper3Labs/hyper3-clip) |
+| `hyper3-clip-v1` | [![HF](https://img.shields.io/badge/🤗-HuggingFace-yellow)](https://huggingface.co/hyper3labs/hyper3-clip-v1) | — | [Hyper3Labs/hyper3-clip](https://github.com/Hyper3Labs/hyper3-clip) |
 | `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) |

{hyper_models-0.3.0 → hyper_models-0.3.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "hyper-models"
-version = "0.3.0"
+version = "0.3.2"
 description = "A model zoo for non-Euclidean embedding models (hyperbolic, spherical, product manifolds)"
 readme = "README.md"
 license = { text = "MIT" }
@@ -20,7 +20,11 @@ classifiers = [
 ]
 dependencies = [
     "numpy>=1.26",
-    "onnxruntime>=1.20",
+    # onnxruntime stopped publishing cp310 wheels after 1.23.x; without this
+    # split a universal resolution picks a release that cannot install on the
+    # 3.10 this package still supports.
+    "onnxruntime>=1.20,<1.24; python_version<'3.11'",
+    "onnxruntime>=1.20; python_version>='3.11'",
     "huggingface-hub>=1.0",
     "pillow>=10.0",
 ]
@@ -29,6 +33,8 @@ dependencies = [
 dev = [
     "pytest>=7.0",
     "ruff>=0.1",
+    # tomllib is stdlib from 3.11; the version test reads pyproject.toml on 3.10 too.
+    "tomli>=2.0; python_version<'3.11'",
 ]
 ml = [
     "torch>=2.9.1",

{hyper_models-0.3.0 → hyper_models-0.3.2}/src/hyper_models/__init__.py

@@ -11,6 +11,9 @@ Example:
     >>> model.dim       # 513
 """
 
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _installed_version
+
 from hyper_models.loader import load
 from hyper_models.loaders import list_loaders
 from hyper_models.models import ONNXModel
@@ -27,4 +30,10 @@ __all__ = [
     "ImageConfig",
     "preprocess_images",
 ]
-__version__ = "0.3.0"
+try:
+    # Read the installed distribution so this cannot drift from pyproject.toml:
+    # a hand-maintained literal here stayed at 0.3.0 through the 0.3.1 release,
+    # and the demo Dockerfiles print this value to confirm what they installed.
+    __version__ = _installed_version("hyper-models")
+except PackageNotFoundError:  # running from a source tree that was never installed
+    __version__ = "0.0.0.dev0"

{hyper_models-0.3.0 → hyper_models-0.3.2}/src/hyper_models/models.py

@@ -37,7 +37,9 @@ class ONNXModel:
         if self._session is None:
             import onnxruntime as ort
 
-            self._session = ort.InferenceSession(str(self._path), providers=["CPUExecutionProvider"])
+            self._session = ort.InferenceSession(
+                str(self._path), providers=["CPUExecutionProvider"]
+            )
 
     def encode(self, inputs: np.ndarray) -> np.ndarray:
         """Encode preprocessed inputs (B, C, H, W) to embeddings (B, D)."""

{hyper_models-0.3.0 → hyper_models-0.3.2}/src/hyper_models/registry.py

@@ -31,6 +31,7 @@ class ModelInfo:
     description: str = ""
     input_name: str = "image"
     output_name: str | None = None
+    modalities: tuple[str, ...] = ("image",)  # what the loaded model can encode
     image_config: ImageConfig = field(default_factory=ImageConfig)
 
 
@@ -99,17 +100,18 @@ _MODELS: dict[str, ModelInfo] = {
         optional_dependencies=("ml",),
         description="UNCHA ViT-B/16 checkpoint (HF .pth, torch inference)",
     ),
-    "hyper3-clip-v0.5": ModelInfo(
-        name="hyper3-clip-v0.5",
+    "hyper3-clip-v1": ModelInfo(
+        name="hyper3-clip-v1",
         geometry="hyperboloid",
         dim=513,
-        hub_id="hyper3labs/hyper3-clip-v0.5",
+        hub_id="hyper3labs/hyper3-clip-v1",
         hub_path="model.safetensors",
         hub_patterns=("config.yaml", "model.safetensors"),
         license="Unknown",
         loader="hyper3-clip-torch",
         optional_dependencies=("ml",),
-        description="Hyper3-CLIP v0.5 ViT-B image encoder (HF safetensors, torch inference)",
+        modalities=("image", "text"),
+        description="Hyper3-CLIP v1 ViT-B image+text encoder (HF safetensors, torch inference)",
         image_config=ImageConfig(
             size=224,
             interpolation="bicubic",
@@ -130,6 +132,11 @@ _MODELS: dict[str, ModelInfo] = {
     ),
 }
 
+_ALIASES = {
+    # Compatibility for callers that selected the model before its v1 rename.
+    "hyper3-clip-v0.5": "hyper3-clip-v1",
+}
+
 
 def list_models(geometry: str | None = None) -> list[str]:
     """List available model names, optionally filtered by geometry."""
@@ -140,6 +147,7 @@ def list_models(geometry: str | None = None) -> list[str]:
 
 def get_model_info(name: str) -> ModelInfo:
     """Get metadata for a model. Raises KeyError if not found."""
+    name = _ALIASES.get(name, name)
     if name not in _MODELS:
         raise KeyError(f"Model '{name}' not found. Available: {', '.join(_MODELS.keys())}")
     return _MODELS[name]

{hyper_models-0.3.0 → hyper_models-0.3.2}/src/hyper_models/torch_models.py

@@ -232,6 +232,30 @@ class UNCHATorchModel:
         return self.encode(preprocess_images(images, self._image_config))
 
 
+_CHECKPOINT_TEXT_PREFIX = "text_encoder.backbone.text_model."
+_MODEL_TEXT_PREFIX = "text_encoder.backbone."
+
+
+def _align_text_tower_keys(state: dict[str, Any]) -> dict[str, Any]:
+    """Match published Hyper3-CLIP text weights to the model's parameter names.
+
+    The checkpoint stores the text tower under the full Hugging Face
+    ``CLIPTextModel`` path, while :class:`Hyper3CLIP` binds its backbone one
+    level deeper, at ``CLIPTextModel.text_model``. Without this rename the text
+    tower silently loads no pretrained weights and every text embedding comes
+    from a randomly initialised encoder.
+    """
+
+    return {
+        (
+            _MODEL_TEXT_PREFIX + key[len(_CHECKPOINT_TEXT_PREFIX) :]
+            if key.startswith(_CHECKPOINT_TEXT_PREFIX)
+            else key
+        ): value
+        for key, value in state.items()
+    }
+
+
 class Hyper3ClipTorchModel:
     """Hyper3-CLIP catalog entry runtime using torch for image inference."""
 
@@ -297,14 +321,11 @@ class Hyper3ClipTorchModel:
         model_config["vision_pretrained"] = False
         model_config["text_pretrained"] = False
         model = Hyper3CLIP(**model_config)
-        state = load_file(self._checkpoint_path, device="cpu")
+        state = _align_text_tower_keys(load_file(self._checkpoint_path, device="cpu"))
         load_result = model.load_state_dict(state, strict=False)
-        missing_non_text = [
-            key for key in load_result.missing_keys if not key.startswith("text_encoder.")
-        ]
-        if missing_non_text:
-            missing = ", ".join(missing_non_text[:8])
-            raise RuntimeError(f"Hyper3-CLIP checkpoint missing required image keys: {missing}")
+        if load_result.missing_keys:
+            missing = ", ".join(load_result.missing_keys[:8])
+            raise RuntimeError(f"Hyper3-CLIP checkpoint missing required keys: {missing}")
         model.to(self._device)
         model.eval()
         self._model = model
@@ -326,3 +347,21 @@ class Hyper3ClipTorchModel:
     def encode_images(self, images: list[Image.Image]) -> np.ndarray:
         """Encode PIL images to Hyper3-CLIP embeddings (B, D)."""
         return self.encode(preprocess_images(images, self._image_config))
+
+    def encode_texts(self, texts: list[str]) -> np.ndarray:
+        """Encode text queries into the same hyperboloid as the images (B, D)."""
+        self._ensure_model()
+
+        assert self._model is not None
+        assert self._torch is not None
+        assert self._device is not None
+
+        encoded = self._model.tokenizer(
+            list(texts), padding=True, truncation=True, return_tensors="pt"
+        )
+        input_ids = encoded["input_ids"].to(self._device)
+        attention_mask = encoded["attention_mask"].to(self._device)
+        with self._torch.inference_mode():
+            emb = self._model.encode_text(input_ids, attention_mask)
+
+        return np.asarray(emb.detach().cpu().numpy(), dtype=np.float32)