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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hyper-models
-Version: 0.3.2
+Version: 0.3.4
 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
@@ -96,7 +96,7 @@ hyper_models.list_loaders()
 # Load model (auto-downloads from Hugging Face Hub)
 model = hyper_models.load("hycoclip-vit-s")
 model.geometry  # 'hyperboloid'
-model.dim       # 513
+model.dim  # 513
 
 # Encode PIL images
 images = [Image.open("image.jpg")]
@@ -104,9 +104,9 @@ 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'
+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)
@@ -136,6 +136,11 @@ 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.
@@ -144,10 +149,10 @@ HyperView auto-detects `hyper-models` names and routes them to the `hyper-models
 import hyperview as hv
 
 dataset = hv.Dataset.from_huggingface(
-  name="demo",
-  hf_dataset="uoft-cs/cifar10",
-  split="train",
-  image_key="img",
+    name="demo",
+    hf_dataset="uoft-cs/cifar10",
+    split="train",
+    image_key="img",
 )
 
 # Uses provider='hyper-models' automatically.

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

@@ -55,7 +55,7 @@ hyper_models.list_loaders()
 # Load model (auto-downloads from Hugging Face Hub)
 model = hyper_models.load("hycoclip-vit-s")
 model.geometry  # 'hyperboloid'
-model.dim       # 513
+model.dim  # 513
 
 # Encode PIL images
 images = [Image.open("image.jpg")]
@@ -63,9 +63,9 @@ 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'
+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)
@@ -95,6 +95,11 @@ 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.
@@ -103,10 +108,10 @@ HyperView auto-detects `hyper-models` names and routes them to the `hyper-models
 import hyperview as hv
 
 dataset = hv.Dataset.from_huggingface(
-  name="demo",
-  hf_dataset="uoft-cs/cifar10",
-  split="train",
-  image_key="img",
+    name="demo",
+    hf_dataset="uoft-cs/cifar10",
+    split="train",
+    image_key="img",
 )
 
 # Uses provider='hyper-models' automatically.

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

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

{hyper_models-0.3.2 → hyper_models-0.3.4}/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.2 → hyper_models-0.3.4}/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.2 → hyper_models-0.3.4}/src/hyper_models/models.py

@@ -3,6 +3,8 @@
 from __future__ import annotations
 
 from pathlib import Path
+from shutil import copyfile
+from tempfile import TemporaryDirectory
 
 import numpy as np
 from PIL import Image
@@ -32,14 +34,26 @@ class ONNXModel:
         self._output_name = output_name
         self._image_config = image_config or ImageConfig()
         self._session = None
+        self._artifact_directory = None
 
     def _ensure_session(self) -> None:
         if self._session is None:
             import onnxruntime as ort
 
-            self._session = ort.InferenceSession(
-                str(self._path), providers=["CPUExecutionProvider"]
-            )
+            path = self._path
+            # Hub snapshots link the graph and external weights to different
+            # blob directories. New ONNX Runtime versions correctly reject
+            # external data outside the resolved graph directory. Materialize
+            # our catalog's graph and sidecars together, keeping validation on.
+            artifacts = [path, *path.parent.glob(f"{path.name}.*")]
+            if any(artifact.is_symlink() for artifact in artifacts):
+                self._artifact_directory = TemporaryDirectory(prefix="hyper-models-onnx-")
+                directory = Path(self._artifact_directory.name)
+                for artifact in artifacts:
+                    if artifact.is_file():
+                        copyfile(artifact, directory / artifact.name)
+                path = directory / path.name
+            self._session = ort.InferenceSession(str(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.2 → hyper_models-0.3.4}/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.2 → hyper_models-0.3.4}/src/hyper_models/registry.py

@@ -106,8 +106,15 @@ _MODELS: dict[str, ModelInfo] = {
         dim=513,
         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"),
@@ -115,6 +122,7 @@ _MODELS: dict[str, ModelInfo] = {
         image_config=ImageConfig(
             size=224,
             interpolation="bicubic",
+            resize_mode="squash",
             mean=(0.485, 0.456, 0.406),
             std=(0.229, 0.224, 0.225),
         ),

{hyper_models-0.3.2 → hyper_models-0.3.4}/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)