hyper-models 0.3.1__tar.gz → 0.3.3__tar.gz

{hyper_models-0.3.1 → hyper_models-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hyper-models
-Version: 0.3.1
+Version: 0.3.3
 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
@@ -87,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()
@@ -130,12 +130,17 @@ 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
 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.
+
 ### HyperView integration
 
 HyperView auto-detects `hyper-models` names and routes them to the `hyper-models` provider.
@@ -159,7 +164,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
 
@@ -173,7 +178,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.1 → hyper_models-0.3.3}/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,12 +89,17 @@ 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
 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.
+
 ### HyperView integration
 
 HyperView auto-detects `hyper-models` names and routes them to the `hyper-models` provider.
@@ -118,7 +123,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 +137,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.1 → hyper_models-0.3.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "hyper-models"
-version = "0.3.1"
+version = "0.3.3"
 description = "A model zoo for non-Euclidean embedding models (hyperbolic, spherical, product manifolds)"
 readme = "README.md"
 license = { text = "MIT" }

{hyper_models-0.3.1 → hyper_models-0.3.3}/src/hyper3_clip/models/encoders.py

@@ -10,6 +10,7 @@ from transformers import (
     CLIPTextConfig,
     CLIPTextModel,
     CLIPTextModelWithProjection,
+    CLIPTokenizerFast,
     CLIPVisionConfig,
     CLIPVisionModel,
     CLIPVisionModelWithProjection,
@@ -99,7 +100,14 @@ class VisionEncoder(nn.Module):
 
 
 class TextEncoder(nn.Module):
-    def __init__(self, model_name: str, pretrained: bool = True, pooling: str = "auto") -> None:
+    def __init__(
+        self,
+        model_name: str,
+        pretrained: bool = True,
+        pooling: str = "auto",
+        text_config: dict | None = None,
+        tokenizer_name_or_path: str | None = None,
+    ) -> None:
         super().__init__()
         if pooling not in {"auto", "pooler", "cls", "mean"}:
             raise ValueError(
@@ -107,10 +115,19 @@ class TextEncoder(nn.Module):
             )
         self.kind = "hf_text"
         self.pooling = pooling
-        tokenizer_name = model_name.removeprefix("hf_clip_projected:")
-        self.tokenizer = AutoTokenizer.from_pretrained(tokenizer_name)
+        tokenizer_name = tokenizer_name_or_path or model_name.removeprefix("hf_clip_projected:")
+        self.tokenizer = (
+            CLIPTokenizerFast.from_pretrained(tokenizer_name)
+            if text_config is not None
+            else AutoTokenizer.from_pretrained(tokenizer_name)
+        )
         model_name_lower = model_name.lower()
-        if model_name.startswith("hf_clip_projected:"):
+        if text_config is not None:
+            if pretrained or text_config.get("model_type") != "clip_text_model":
+                raise ValueError("Bundled text_config requires a non-pretrained CLIP text encoder")
+            self.backbone = CLIPTextModel(CLIPTextConfig.from_dict(text_config))
+            self.output_dim = self.backbone.config.hidden_size
+        elif model_name.startswith("hf_clip_projected:"):
             self.kind = "hf_clip_projected"
             projected_model_name = model_name.removeprefix("hf_clip_projected:")
             if pretrained:

{hyper_models-0.3.1 → hyper_models-0.3.3}/src/hyper3_clip/models/hyper3_clip.py

@@ -101,6 +101,8 @@ class Hyper3CLIP(ExperimentalObjectiveMixin, nn.Module):
         fuse_beta_query_encoder_forwards: bool = False,
         group_beta_query_pooling: bool = False,
         objective_autocast_dtype: str = "float32",
+        text_config: dict | None = None,
+        tokenizer_name_or_path: str | None = None,
     ) -> None:
         super().__init__()
         if objective not in {"hycoclip", "uncha", "proclip"}:
@@ -206,7 +208,11 @@ class Hyper3CLIP(ExperimentalObjectiveMixin, nn.Module):
             self.phyclip_num_factors = 0
         self.vision_encoder = VisionEncoder(vision_backbone, pretrained=vision_pretrained)
         self.text_encoder = TextEncoder(
-            text_model_name, pretrained=text_pretrained, pooling=text_pooling
+            text_model_name,
+            pretrained=text_pretrained,
+            pooling=text_pooling,
+            text_config=text_config,
+            tokenizer_name_or_path=tokenizer_name_or_path,
         )
         self.tokenizer = self.text_encoder.tokenizer
         self.embed_dim = embed_dim

{hyper_models-0.3.1 → hyper_models-0.3.3}/src/hyper_models/preprocessing.py

@@ -27,6 +27,7 @@ class ImageConfig:
     rescale: float = 1.0 / 255.0
     mean: tuple[float, float, float] | None = None
     std: tuple[float, float, float] | None = None
+    resize_mode: Literal["center_crop", "squash"] = "center_crop"
 
 
 def preprocess_images(images: list[Image.Image], config: ImageConfig | None = None) -> np.ndarray:
@@ -47,14 +48,18 @@ def preprocess_images(images: list[Image.Image], config: ImageConfig | None = No
         if img.mode != "RGB":
             img = img.convert("RGB")
 
-        # Resize shortest side, then center crop
-        w, h = img.size
-        scale = config.size / min(w, h)
-        img = img.resize((int(round(w * scale)), int(round(h * scale))), resample=resample)
-
-        w, h = img.size
-        left, top = (w - config.size) // 2, (h - config.size) // 2
-        img = img.crop((left, top, left + config.size, top + config.size))
+        if config.resize_mode == "squash":
+            img = img.resize((config.size, config.size), resample=resample)
+        elif config.resize_mode == "center_crop":
+            # Resize shortest side, then center crop.
+            w, h = img.size
+            scale = config.size / min(w, h)
+            img = img.resize((int(round(w * scale)), int(round(h * scale))), resample=resample)
+            w, h = img.size
+            left, top = (w - config.size) // 2, (h - config.size) // 2
+            img = img.crop((left, top, left + config.size, top + config.size))
+        else:
+            raise ValueError(f"Unknown resize mode: {config.resize_mode!r}")
 
         # To float32 CHW
         arr = np.asarray(img, dtype=np.float32) * config.rescale

{hyper_models-0.3.1 → hyper_models-0.3.3}/src/hyper_models/registry.py

@@ -100,21 +100,29 @@ _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",
+        hub_patterns=(
+            "config.json",
+            "model.safetensors",
+            "tokenizer.json",
+            "tokenizer_config.json",
+            "vocab.json",
+            "merges.txt",
+        ),
+        license="OpenMDW-1.0",
         loader="hyper3-clip-torch",
         optional_dependencies=("ml",),
         modalities=("image", "text"),
-        description="Hyper3-CLIP v0.5 ViT-B image+text encoder (HF safetensors, torch inference)",
+        description="Hyper3-CLIP v1 ViT-B image+text encoder (HF safetensors, torch inference)",
         image_config=ImageConfig(
             size=224,
             interpolation="bicubic",
+            resize_mode="squash",
             mean=(0.485, 0.456, 0.406),
             std=(0.229, 0.224, 0.225),
         ),
@@ -132,6 +140,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."""
@@ -142,6 +155,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.1 → hyper_models-0.3.3}/src/hyper_models/torch_models.py

@@ -6,6 +6,8 @@ They do not create a separate public provider surface.
 
 from __future__ import annotations
 
+import json
+from dataclasses import replace
 from pathlib import Path
 from typing import Any
 
@@ -257,7 +259,7 @@ def _align_text_tower_keys(state: dict[str, Any]) -> dict[str, Any]:
 
 
 class Hyper3ClipTorchModel:
-    """Hyper3-CLIP catalog entry runtime using torch for image inference."""
+    """Hyper3-CLIP image/text inference returning native Lorentz embeddings."""
 
     def __init__(
         self,
@@ -269,11 +271,14 @@ class Hyper3ClipTorchModel:
         device: str | None = None,
     ) -> None:
         self._checkpoint_path = checkpoint_path
-        self._config_path = checkpoint_path.with_name("config.yaml")
+        self._config_path = checkpoint_path.with_name("config.json")
+        if not self._config_path.is_file():
+            self._config_path = checkpoint_path.with_name("config.yaml")
         self.geometry = geometry
         self.dim = dim
         self._image_config = image_config or ImageConfig()
         self._device_override = device
+        self._max_text_length = 77
 
         self._torch = None
         self._device = None
@@ -316,11 +321,41 @@ class Hyper3ClipTorchModel:
         self._torch = torch
         self._device = self._resolve_device(torch)
 
-        config = yaml.safe_load(self._config_path.read_text(encoding="utf-8"))
-        model_config = dict(config["model"])
+        if self._config_path.suffix == ".json":
+            config = json.loads(self._config_path.read_text(encoding="utf-8"))
+            model_config = {
+                key: config[key]
+                for key in (
+                    "vision_backbone",
+                    "text_model_name",
+                    "embed_dim",
+                    "curv_init",
+                    "learn_curv",
+                )
+            }
+            # These constructor arguments affect training losses only.
+            model_config.update(
+                entail_weight=0.0, inter_aperture_scale=0.0, intra_aperture_scale=0.0
+            )
+            model_config["text_config"] = config["text_config"]
+            model_config["tokenizer_name_or_path"] = str(self._checkpoint_path.parent)
+        else:
+            config = yaml.safe_load(self._config_path.read_text(encoding="utf-8"))
+            model_config = dict(config["model"])
+        data_config = config.get("data", config)
+        self._image_config = replace(
+            self._image_config,
+            size=int(data_config.get("image_size", self._image_config.size)),
+            resize_mode="squash",
+        )
+        self._max_text_length = int(data_config.get("max_text_length", 77))
         model_config["vision_pretrained"] = False
         model_config["text_pretrained"] = False
         model = Hyper3CLIP(**model_config)
+        if model.embed_dim + 1 != self.dim:
+            raise ValueError("Hyper3-CLIP embedding dimension does not match the catalog entry")
+        model.curv_min = float(config.get("curvature_min", model.curv_min))
+        model.curv_max = float(config.get("curvature_max", model.curv_max))
         state = _align_text_tower_keys(load_file(self._checkpoint_path, device="cpu"))
         load_result = model.load_state_dict(state, strict=False)
         if load_result.missing_keys:
@@ -346,6 +381,7 @@ class Hyper3ClipTorchModel:
 
     def encode_images(self, images: list[Image.Image]) -> np.ndarray:
         """Encode PIL images to Hyper3-CLIP embeddings (B, D)."""
+        self._ensure_model()
         return self.encode(preprocess_images(images, self._image_config))
 
     def encode_texts(self, texts: list[str]) -> np.ndarray:
@@ -357,7 +393,11 @@ class Hyper3ClipTorchModel:
         assert self._device is not None
 
         encoded = self._model.tokenizer(
-            list(texts), padding=True, truncation=True, return_tensors="pt"
+            list(texts),
+            padding=True,
+            truncation=True,
+            max_length=self._max_text_length,
+            return_tensors="pt",
         )
         input_ids = encoded["input_ids"].to(self._device)
         attention_mask = encoded["attention_mask"].to(self._device)