sie-server 0.3.0__tar.gz → 0.3.1__tar.gz

{sie_server-0.3.0 → sie_server-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sie-server
-Version: 0.3.0
+Version: 0.3.1
 Summary: Search Inference Engine - GPU inference server for search workloads
 License: Apache-2.0
 License-File: LICENSE
@@ -19,6 +19,7 @@ Requires-Dist: msgpack<2,>=1.1
 Requires-Dist: msgspec>=0.20.0
 Requires-Dist: nats-py<3,>=2.9
 Requires-Dist: numpy<3,>=2
+Requires-Dist: open-clip-torch>=2.24
 Requires-Dist: opentelemetry-api<2,>=1.28
 Requires-Dist: opentelemetry-exporter-otlp<2,>=1.28
 Requires-Dist: opentelemetry-instrumentation-fastapi<1,>=0.49b0

{sie_server-0.3.0 → sie_server-0.3.1}/bundles/default.yaml

@@ -71,6 +71,8 @@ deps:
   loguru: '>=0.7,<1'
   # donut, florence2
   timm: '>=0.9.0,<1.0'
+  # siglip (Marqo/marqo-ecommerce-embeddings-B uses open_clip native loader)
+  open-clip-torch: '>=2.24'
   # docling — composite-document parser (PDF/DOCX/HTML)
   docling: '>=2,<3'
   # Flash Attention 2 — CUDA only, prebuilt wheel

{sie_server-0.3.0 → sie_server-0.3.1}/models/BAAI__bge-m3.yaml

@@ -13,7 +13,7 @@ tasks:
       dim: 250002
     multivector:
       dim: 1024
-  score: null
+  score: {}
   extract: null
 max_sequence_length: 8192
 profiles:

sie_server-0.3.1/models/Marqo__marqo-ecommerce-embeddings-B.yaml

@@ -0,0 +1,28 @@
+sie_id: Marqo/marqo-ecommerce-embeddings-B
+hf_id: Marqo/marqo-ecommerce-embeddings-B
+inputs:
+  text: true
+  image: true
+  audio: false
+  video: false
+tasks:
+  encode:
+    dense:
+      dim: 768
+    sparse: null
+    multivector: null
+  score: null
+  extract: null
+max_sequence_length: 64
+profiles:
+  default:
+    max_batch_tokens: 16384
+    compute_precision: float16
+    adapter_path: sie_server.adapters.siglip:SiglipAdapter
+    adapter_options:
+      loadtime:
+        backend: open_clip
+        open_clip_model_id: hf-hub:Marqo/marqo-ecommerce-embeddings-B
+        dense_dim: 768
+      runtime:
+        normalize: true

sie_server-0.3.1/models/google__embeddinggemma-300m.yaml

@@ -0,0 +1,49 @@
+# NOTE: ``google/embeddinggemma-300m`` is a *gated* HuggingFace repo. The
+# server requires ``HF_TOKEN`` (with the model license accepted on the
+# HF account) to load this model. Without it, the registry records a
+# terminal ``GATED`` failure and the API returns ``MODEL_LOAD_FAILED``
+# (502, no Retry-After) so the SDK does not loop.
+#
+# Architecture support: needs ``transformers>=4.56`` for
+# ``Gemma3TextModel``. Older versions raise an unsupported-model error
+# which the registry classifies as ``DEPENDENCY``.
+sie_id: google/embeddinggemma-300m
+hf_id: google/embeddinggemma-300m
+# Track the default branch. Note: ``main`` is mutable on the Hub, so
+# this does NOT guarantee bit-for-bit reproducibility — it merely names
+# the branch we expect HuggingFace to resolve. For a true pin, replace
+# this with an immutable commit SHA after verifying the new revision
+# against ``test_google_embeddinggemma_300m_dense``.
+hf_revision: main
+inputs:
+  text: true
+  image: false
+  audio: false
+  video: false
+tasks:
+  encode:
+    dense:
+      dim: 768
+    sparse: null
+    multivector: null
+  score: null
+  extract: null
+max_sequence_length: 2048
+profiles:
+  default:
+    max_batch_tokens: 16384
+    # bfloat16 on CUDA matches the captured reference embedding in
+    # ``test_all_models.py``. On CPU the adapter falls back to fp32
+    # automatically (see pytorch_embedding adapter); the loaded model
+    # still works, but numerical-equivalence tests should be gated on
+    # CUDA availability if drift becomes an issue.
+    compute_precision: bfloat16
+    adapter_path: sie_server.adapters.pytorch_embedding:PyTorchEmbeddingAdapter
+    adapter_options:
+      loadtime:
+        attn_implementation: sdpa
+      runtime:
+        pooling: mean
+        normalize: true
+        query_template: 'task: search result | query: {text}'
+        doc_template: 'title: none | text: {text}'

{sie_server-0.3.0 → sie_server-0.3.1}/openapi.json

@@ -3,7 +3,7 @@
   "info": {
     "title": "SIE Server",
     "description": "Search Inference Engine - GPU inference server for search workloads",
-    "version": "0.3.0"
+    "version": "0.3.1"
   },
   "paths": {
     "/": {
@@ -134,6 +134,9 @@
           "404": {
             "description": "Model not found"
           },
+          "502": {
+            "description": "Terminal model-load failure (MODEL_LOAD_FAILED). Carried in the ``detail`` envelope: ``{code, message, error_class, permanent, attempts}``. No ``Retry-After`` header \u2014 clients MUST NOT auto-retry. See sie-test#85."
+          },
           "503": {
             "description": "Model not loaded or service unavailable"
           },
@@ -234,6 +237,9 @@
           "404": {
             "description": "Model not found"
           },
+          "502": {
+            "description": "Terminal model-load failure (MODEL_LOAD_FAILED). Carried in the ``detail`` envelope: ``{code, message, error_class, permanent, attempts}``. No ``Retry-After`` header \u2014 clients MUST NOT auto-retry. See sie-test#85."
+          },
           "503": {
             "description": "Model not loaded or service unavailable"
           },
@@ -334,6 +340,9 @@
           "404": {
             "description": "Model not found"
           },
+          "502": {
+            "description": "Terminal model-load failure (MODEL_LOAD_FAILED). Carried in the ``detail`` envelope: ``{code, message, error_class, permanent, attempts}``. No ``Retry-After`` header \u2014 clients MUST NOT auto-retry. See sie-test#85."
+          },
           "503": {
             "description": "Model not loaded or service unavailable"
           },
@@ -504,6 +513,9 @@
           "404": {
             "description": "Model not found"
           },
+          "502": {
+            "description": "Terminal model-load failure (MODEL_LOAD_FAILED). Carried in the ``detail`` envelope: ``{code, message, error_class, permanent, attempts}``. No ``Retry-After`` header \u2014 clients MUST NOT auto-retry. See sie-test#85."
+          },
           "503": {
             "description": "Service unavailable"
           },
@@ -847,6 +859,28 @@
             "type": "boolean",
             "title": "Loaded"
           },
+          "state": {
+            "type": "string",
+            "enum": [
+              "available",
+              "loading",
+              "loaded",
+              "unloading",
+              "failed"
+            ],
+            "title": "State",
+            "default": "available"
+          },
+          "last_error": {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/ModelLoadError"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
           "max_sequence_length": {
             "anyOf": [
               {
@@ -878,6 +912,35 @@
         "title": "ModelInfo",
         "description": "Information about a model."
       },
+      "ModelLoadError": {
+        "properties": {
+          "code": {
+            "type": "string",
+            "title": "Code"
+          },
+          "message": {
+            "type": "string",
+            "title": "Message"
+          },
+          "attempts": {
+            "type": "integer",
+            "title": "Attempts"
+          },
+          "permanent": {
+            "type": "boolean",
+            "title": "Permanent"
+          }
+        },
+        "type": "object",
+        "required": [
+          "code",
+          "message",
+          "attempts",
+          "permanent"
+        ],
+        "title": "ModelLoadError",
+        "description": "Diagnostic detail for a recorded load failure.\n\nSurfaced in :class:`ModelInfo` when the registry has a sticky\nfailure for the model. Attributes mirror the server-side\n:class:`sie_server.core.load_errors.LoadFailure`."
+      },
       "ModelsListResponse": {
         "properties": {
           "models": {

{sie_server-0.3.0 → sie_server-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sie-server"
-version = "0.3.0"
+version = "0.3.1"
 description = "Search Inference Engine - GPU inference server for search workloads"
 requires-python = ">=3.12,<3.13"
 license = { text = "Apache-2.0" }
@@ -29,6 +29,8 @@ dependencies = [
     # Docling — composite-document parser (PDF/DOCX/HTML) for extract()
     "docling>=2,<3",
     "loguru>=0.7,<1",
+    # SigLIP (Marqo/marqo-ecommerce-embeddings-B native open_clip loader)
+    "open-clip-torch>=2.24",
     # Image processing
     "pillow>=11,<12",
     "numpy>=2,<3",

{sie_server-0.3.0 → sie_server-0.3.1}/src/sie_server/adapters/bge_m3/__init__.py

@@ -26,6 +26,7 @@ from torch.nn import functional
 from sie_server.adapters._base_adapter import BaseAdapter
 from sie_server.adapters._spec import AdapterSpec
 from sie_server.adapters._types import ERR_NOT_LOADED, ERR_REQUIRES_TEXT, ComputePrecision
+from sie_server.adapters.bge_m3_score_mixin import BGEM3ScoreMixin
 from sie_server.core.inference_output import EncodeOutput, SparseVector
 from sie_server.types.inputs import Item
 
@@ -35,16 +36,19 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
-class BGEM3Adapter(BaseAdapter):
+class BGEM3Adapter(BGEM3ScoreMixin, BaseAdapter):
     """Adapter for BAAI/bge-m3 model.
 
     This adapter uses direct PyTorch inference with Flash Attention 2
     for optimal performance (dense, sparse, and multi-vector outputs).
+
+    Scoring (`/v1/score`) is supported via :class:`BGEM3ScoreMixin`, which
+    composes scores from the encoder outputs (dense / sparse / multivector).
     """
 
     spec = AdapterSpec(
         inputs=("text",),
-        outputs=("dense", "sparse", "multivector"),
+        outputs=("dense", "sparse", "multivector", "score"),
         dense_dim=1024,
         sparse_dim=250002,
         multivector_dim=1024,

{sie_server-0.3.0 → sie_server-0.3.1}/src/sie_server/adapters/bge_m3_flag/__init__.py

@@ -23,6 +23,7 @@ import torch
 from sie_server.adapters._base_adapter import BaseAdapter
 from sie_server.adapters._spec import AdapterSpec
 from sie_server.adapters._types import ERR_NOT_LOADED, ERR_REQUIRES_TEXT, ComputePrecision
+from sie_server.adapters.bge_m3_score_mixin import BGEM3ScoreMixin
 from sie_server.core.inference_output import EncodeOutput, SparseVector
 
 if TYPE_CHECKING:
@@ -35,16 +36,19 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
-class BGEM3FlagAdapter(BaseAdapter):
+class BGEM3FlagAdapter(BGEM3ScoreMixin, BaseAdapter):
     """Adapter for BAAI/bge-m3 using FlagEmbedding library.
 
     This adapter uses the FlagEmbedding library's BGEM3FlagModel.
     For better performance, use BGEM3Adapter which uses Flash Attention 2.
+
+    Scoring (`/v1/score`) is supported via :class:`BGEM3ScoreMixin`, which
+    composes scores from the encoder outputs (dense / sparse / multivector).
     """
 
     spec = AdapterSpec(
         inputs=("text",),
-        outputs=("dense", "sparse", "multivector"),
+        outputs=("dense", "sparse", "multivector", "score"),
         dense_dim=1024,
         sparse_dim=250002,
         multivector_dim=1024,

{sie_server-0.3.0 → sie_server-0.3.1}/src/sie_server/adapters/bge_m3_flash/__init__.py

@@ -14,6 +14,7 @@ from sie_server.adapters._flash_base import FlashBaseAdapter
 from sie_server.adapters._spec import AdapterSpec
 from sie_server.adapters._types import ERR_NOT_LOADED, ComputePrecision
 from sie_server.adapters._utils import validate_output_types
+from sie_server.adapters.bge_m3_score_mixin import BGEM3ScoreMixin
 from sie_server.adapters.peft_lora_mixin import PEFTLoRAMixin
 from sie_server.core.inference_output import EncodeOutput, SparseVector
 from sie_server.types.inputs import Item
@@ -26,7 +27,7 @@ logger = logging.getLogger(__name__)
 _ERR_CPU_NOT_SUPPORTED = "BGEM3FlashAdapter requires CUDA. Use bge_m3 adapter for CPU."
 
 
-class BGEM3FlashAdapter(PEFTLoRAMixin, FlashBaseAdapter):
+class BGEM3FlashAdapter(BGEM3ScoreMixin, PEFTLoRAMixin, FlashBaseAdapter):
     """BGE-M3 adapter using Flash Attention 2 with variable-length sequences.
 
     This adapter eliminates padding waste by packing sequences and using
@@ -41,7 +42,7 @@ class BGEM3FlashAdapter(PEFTLoRAMixin, FlashBaseAdapter):
 
     spec = AdapterSpec(
         inputs=("text",),
-        outputs=("dense", "sparse", "multivector"),
+        outputs=("dense", "sparse", "multivector", "score"),
         dense_dim=1024,
         sparse_dim=250002,
         multivector_dim=1024,
@@ -232,6 +233,8 @@ class BGEM3FlashAdapter(PEFTLoRAMixin, FlashBaseAdapter):
 
         return self._to_inference_output(results, output_types, len(items), is_query)
 
+    # score() and score_pairs() are provided by BGEM3ScoreMixin.
+
     def _build_position_ids(self, cu_seqlens: torch.Tensor, num_seqs: int) -> torch.Tensor:
         """Build XLMRoberta-style position IDs for packed sequences.
 

sie_server-0.3.1/src/sie_server/adapters/bge_m3_score_mixin.py

@@ -0,0 +1,283 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, ClassVar
+
+import numpy as np
+
+from sie_server.core.inference_output import ScoreOutput
+
+if TYPE_CHECKING:
+    from sie_server.core.inference_output import EncodeOutput
+    from sie_server.types.inputs import Item
+
+
+class BGEM3ScoreMixin:
+    """Adds BGE-M3 score()/score_pairs() to any adapter implementing encode().
+
+    BGE-M3 supports four scoring modes composable from any of its encode
+    outputs (dense / sparse / multivector). This mixin implements the modes
+    once and is consumed by every BGE-M3 adapter (``bge_m3_flash``,
+    ``bge_m3``, ``bge_m3_flag``) so they all expose the same ``/v1/score``
+    semantics.
+
+    Modes:
+      - ``dense``  : cosine similarity between CLS-pooled, L2-normalized vectors.
+      - ``sparse`` : ``Σ q_w * d_w`` over shared token ids (BGE-M3 paper /
+        FlagEmbedding's ``compute_lexical_matching_score``).
+      - ``colbert``: ColBERT-style MaxSim over the multi-vector projection,
+        normalized by query length (matches FlagEmbedding's ``colbert_score``).
+      - ``hybrid`` : weighted sum (default ``{dense: 0.4, sparse: 0.2, colbert: 0.4}``,
+        override via ``options["score_weights"]``).
+
+    Runtime-side companion to ``"score"`` being declared in
+    :class:`AdapterSpec.outputs`; the class-level validator at
+    :mod:`sie_server.adapters._base_adapter` only checks that ``score`` /
+    ``score_pairs`` are overridden on the class — both come from this mixin.
+
+    Subclasses must provide ``encode()`` and ``_check_loaded()`` (the latter
+    is supplied by the standard adapter base classes). The TYPE_CHECKING
+    stubs below let the type checker resolve ``self.encode`` / ``self._check_loaded``
+    inside this module without affecting Python's runtime MRO — they only
+    exist for the type checker, never as live attributes.
+    """
+
+    if TYPE_CHECKING:
+
+        def encode(
+            self,
+            items: list[Item],
+            output_types: list[str],
+            *,
+            instruction: str | None = ...,
+            is_query: bool = ...,
+            prepared_items: Any = ...,
+            options: dict[str, Any] | None = ...,
+        ) -> EncodeOutput: ...
+
+        def _check_loaded(self) -> None: ...
+
+    # Default hybrid weights from the BGE-M3 paper (Chen et al., 2024).
+    _DEFAULT_HYBRID_WEIGHTS: ClassVar[dict[str, float]] = {"dense": 0.4, "sparse": 0.2, "colbert": 0.4}
+    _VALID_SCORE_MODES: ClassVar[frozenset[str]] = frozenset({"dense", "sparse", "colbert", "hybrid"})
+    _MODE_TO_OUTPUT: ClassVar[dict[str, str]] = {
+        "dense": "dense",
+        "sparse": "sparse",
+        "colbert": "multivector",
+    }
+
+    # ------------------------------------------------------------------ public
+
+    def score(
+        self,
+        query: Item,
+        items: list[Item],
+        *,
+        instruction: str | None = None,
+        options: dict[str, Any] | None = None,
+    ) -> list[float]:
+        """Score items against a query using bi-encoder similarity.
+
+        Args:
+            query: Query item.
+            items: Document items to score.
+            instruction: Optional instruction prepended to query and items.
+            options: Runtime options. Recognized keys:
+                ``score_mode``: one of
+                    ``"dense" | "sparse" | "colbert" | "hybrid"`` (default ``"dense"``).
+                ``score_weights``: mapping
+                    ``{dense, sparse, colbert} -> float`` for hybrid mode.
+
+        Returns:
+            List of scores parallel to ``items``.
+        """
+        self._check_loaded()
+        if not items:
+            return []
+
+        score_mode, weights = self._resolve_score_mode(options)
+        output_types = self._output_types_for_mode(score_mode, weights)
+
+        query_out = self.encode(
+            [query],
+            output_types=output_types,
+            instruction=instruction,
+            is_query=True,
+            options=options,
+        )
+        items_out = self.encode(
+            items,
+            output_types=output_types,
+            instruction=instruction,
+            is_query=False,
+            options=options,
+        )
+
+        return [self._compute_pair_score(query_out, 0, items_out, i, score_mode, weights) for i in range(len(items))]
+
+    def score_pairs(
+        self,
+        queries: list[Item],
+        docs: list[Item],
+        *,
+        instruction: str | None = None,
+        options: dict[str, Any] | None = None,
+    ) -> ScoreOutput:
+        """Score parallel (query, doc) pairs in a single batched encode."""
+        self._check_loaded()
+        if len(queries) != len(docs):
+            msg = f"score_pairs requires equal-length queries and docs, got {len(queries)} queries and {len(docs)} docs"
+            raise ValueError(msg)
+        if not queries:
+            return ScoreOutput(scores=np.empty(0, dtype=np.float32))
+
+        score_mode, weights = self._resolve_score_mode(options)
+        output_types = self._output_types_for_mode(score_mode, weights)
+
+        queries_out = self.encode(
+            queries,
+            output_types=output_types,
+            instruction=instruction,
+            is_query=True,
+            options=options,
+        )
+        docs_out = self.encode(
+            docs,
+            output_types=output_types,
+            instruction=instruction,
+            is_query=False,
+            options=options,
+        )
+
+        scores = np.asarray(
+            [self._compute_pair_score(queries_out, i, docs_out, i, score_mode, weights) for i in range(len(queries))],
+            dtype=np.float32,
+        )
+        return ScoreOutput(scores=scores)
+
+    # ------------------------------------------------------------ option resolve
+
+    def _resolve_score_mode(self, options: dict[str, Any] | None) -> tuple[str, dict[str, float]]:
+        """Validate and resolve ``score_mode`` and ``score_weights`` from options."""
+        opts = options or {}
+        score_mode = opts.get("score_mode", "dense")
+        # Validate type before membership (frozenset.__contains__ would raise
+        # TypeError on unhashable inputs like list/dict, leaking a 500).
+        if not isinstance(score_mode, str) or score_mode not in self._VALID_SCORE_MODES:
+            msg = f"Invalid score_mode '{score_mode}'. Expected one of {sorted(self._VALID_SCORE_MODES)}."
+            raise ValueError(msg)
+
+        weights = dict(self._DEFAULT_HYBRID_WEIGHTS)
+        override = opts.get("score_weights")
+        if override is not None:
+            if not isinstance(override, dict):
+                msg = "score_weights must be a mapping of {dense, sparse, colbert} -> float"
+                raise ValueError(msg)
+            unknown = set(override) - set(self._DEFAULT_HYBRID_WEIGHTS)
+            if unknown:
+                msg = f"Unknown score_weights keys: {sorted(unknown)}. Allowed: dense, sparse, colbert"
+                raise ValueError(msg)
+            for key, value in override.items():
+                # bool is a subclass of int — reject it explicitly to avoid silently
+                # treating True/False as 1.0/0.0 weights.
+                if isinstance(value, bool) or not isinstance(value, (int, float)) or value < 0:
+                    msg = f"score_weights['{key}'] must be a non-negative number, got {value!r}"
+                    raise ValueError(msg)
+                weights[key] = float(value)
+
+        if score_mode == "hybrid":
+            total = sum(weights.values())
+            if total <= 0:
+                msg = "score_weights for hybrid mode must contain at least one positive weight"
+                raise ValueError(msg)
+
+        return score_mode, weights
+
+    def _output_types_for_mode(self, score_mode: str, weights: dict[str, float]) -> list[str]:
+        """Resolve which encode outputs are needed for the requested score mode."""
+        if score_mode == "hybrid":
+            # Skip outputs whose weight is zero to save compute.
+            return [self._MODE_TO_OUTPUT[mode] for mode in ("dense", "sparse", "colbert") if weights.get(mode, 0.0) > 0]
+        return [self._MODE_TO_OUTPUT[score_mode]]
+
+    # ------------------------------------------------------------------ similarity
+
+    def _compute_pair_score(
+        self,
+        q_out: EncodeOutput,
+        q_idx: int,
+        d_out: EncodeOutput,
+        d_idx: int,
+        score_mode: str,
+        weights: dict[str, float],
+    ) -> float:
+        """Compute a single (query, doc) score under the resolved mode."""
+        if score_mode == "dense":
+            return self._dense_sim(q_out, q_idx, d_out, d_idx)
+        if score_mode == "sparse":
+            return self._sparse_sim(q_out, q_idx, d_out, d_idx)
+        if score_mode == "colbert":
+            return self._colbert_sim(q_out, q_idx, d_out, d_idx)
+        # hybrid
+        score = 0.0
+        if weights.get("dense", 0.0) > 0:
+            score += weights["dense"] * self._dense_sim(q_out, q_idx, d_out, d_idx)
+        if weights.get("sparse", 0.0) > 0:
+            score += weights["sparse"] * self._sparse_sim(q_out, q_idx, d_out, d_idx)
+        if weights.get("colbert", 0.0) > 0:
+            score += weights["colbert"] * self._colbert_sim(q_out, q_idx, d_out, d_idx)
+        return float(score)
+
+    @staticmethod
+    def _dense_sim(q_out: EncodeOutput, q_idx: int, d_out: EncodeOutput, d_idx: int) -> float:
+        """Cosine similarity between dense vectors (normalized inside encode)."""
+        if q_out.dense is None or d_out.dense is None:
+            msg = "Dense vectors required for dense scoring but missing from encode output"
+            raise RuntimeError(msg)
+        q = q_out.dense[q_idx]
+        d = d_out.dense[d_idx]
+        # Defensive normalization in case caller disabled normalize at runtime.
+        q_norm = float(np.linalg.norm(q))
+        d_norm = float(np.linalg.norm(d))
+        if q_norm == 0.0 or d_norm == 0.0:
+            return 0.0
+        return float(np.dot(q, d) / (q_norm * d_norm))
+
+    @staticmethod
+    def _sparse_sim(q_out: EncodeOutput, q_idx: int, d_out: EncodeOutput, d_idx: int) -> float:
+        """BGE-M3 lexical-match score: sum of q_w * d_w over shared token ids."""
+        if q_out.sparse is None or d_out.sparse is None:
+            msg = "Sparse vectors required for sparse scoring but missing from encode output"
+            raise RuntimeError(msg)
+        q_vec = q_out.sparse[q_idx]
+        d_vec = d_out.sparse[d_idx]
+        if len(q_vec.indices) == 0 or len(d_vec.indices) == 0:
+            return 0.0
+        d_lookup = dict(zip(d_vec.indices.tolist(), d_vec.values.tolist(), strict=True))
+        total = 0.0
+        for tid, q_w in zip(q_vec.indices.tolist(), q_vec.values.tolist(), strict=True):
+            d_w = d_lookup.get(tid)
+            if d_w is not None:
+                total += float(q_w) * float(d_w)
+        return float(total)
+
+    @staticmethod
+    def _colbert_sim(q_out: EncodeOutput, q_idx: int, d_out: EncodeOutput, d_idx: int) -> float:
+        """ColBERT MaxSim: sum over query tokens of max-dot against doc tokens, normalized by query length.
+
+        Matches FlagEmbedding's ``BGEM3FlagModel.colbert_score`` exactly.
+        """
+        if q_out.multivector is None or d_out.multivector is None:
+            msg = "Multivector outputs required for colbert scoring but missing from encode output"
+            raise RuntimeError(msg)
+        q_mv = q_out.multivector[q_idx]
+        d_mv = d_out.multivector[d_idx]
+        if q_mv.size == 0 or d_mv.size == 0:
+            return 0.0
+        # Defensive normalization (multivector is normalized inside encode by default).
+        q_norms = np.linalg.norm(q_mv, axis=-1, keepdims=True)
+        d_norms = np.linalg.norm(d_mv, axis=-1, keepdims=True)
+        q_normed = np.divide(q_mv, q_norms, out=np.zeros_like(q_mv), where=q_norms > 0)
+        d_normed = np.divide(d_mv, d_norms, out=np.zeros_like(d_mv), where=d_norms > 0)
+        sim = q_normed @ d_normed.T  # [q_len, d_len]
+        max_per_query_token = sim.max(axis=-1)
+        return float(max_per_query_token.sum() / q_mv.shape[0])