Model card: add Sentence Transformers usage section

README.md

@@ -3,6 +3,7 @@ license: cc-by-nc-4.0
 language:
   - en
 pipeline_tag: feature-extraction
+library_name: sentence-transformers
 tags:
   - embeddings
   - multimodal
@@ -209,7 +210,8 @@ default.
 <details>
   <summary>Requirements</summary>
 
-- `fusion_embedding` package: `pip install fusion-embedding[hf]`
+- `fusion_embedding` package: `pip install fusion-embedding[hf]` (the
+  Sentence Transformers section below uses the lighter `[sense]` extra)
 - `transformers>=4.46`, `torch` (CUDA), `torchvision`, `pillow`, `soundfile`, `librosa`
 - ~14 GB GPU memory at bf16
 
@@ -255,6 +257,110 @@ gallery = FusionEmbedder.center(gallery_embeddings)
 
 </details>
 
+## Sentence Transformers
+
+fusion-embedding-2 works directly with [Sentence Transformers](https://sbert.net) (v5.5.1+,
+multimodal `encode`). The custom module on this repository is a thin adapter over the
+`fusion-embedding` package, so embeddings are identical to the native
+`fusion_embedding.UnifiedEmbedder.from_pretrained` path.
+
+```bash
+pip install -U "sentence-transformers>=5.5.1" "fusion-embedding[sense]>=0.3.0" torchvision
+
+# only to embed a video by file path; torchcodec also needs FFmpeg installed
+pip install -U torchcodec
+```
+
+```python
+import numpy as np
+from sentence_transformers import SentenceTransformer
+
+model = SentenceTransformer(
+    "EximiusLabs/fusion-embedding-2-2b-preview",
+    trust_remote_code=True,
+)
+
+# Text
+text_embs = model.encode([
+    "a dog barks in the distance while rain falls on a tin roof",
+    "an orchestra tuning up before a performance",
+])
+
+# Images: local path, PIL image, or HxWxC uint8 array
+image_embs = model.encode(["photo_of_a_bicycle.jpg"])
+
+# Audio: local file path, or a waveform with its sampling rate
+waveform = np.sin(2 * np.pi * 440.0 * np.arange(44100) / 44100).astype(np.float32)
+audio_embs = model.encode([
+    "dog_bark.wav",
+    {"audio": {"array": waveform, "sampling_rate": 44100}},
+])
+
+# Video: local file path (requires torchcodec) or a [T, C, H, W] uint8 frame
+# tensor
+video_embs = model.encode(["clip.mp4"])
+
+# One shared space: rank any modality against any other
+scores = model.similarity(text_embs, audio_embs)
+```
+
+All vectors are L2-normalized at the full interoperability dimension (2048).
+
+### Queries, documents, and instructions
+
+The text side carries a retrieval instruction through the base model's chat template.
+`encode` uses the query instruction by default; `encode_query` / `encode_document`
+select the released query/document instructions, and a custom instruction can be
+passed as `prompt=` (it replaces the instruction inside the chat template rather than
+being prepended to the text):
+
+```python
+q = model.encode_query(["engine failure sounds"])
+d = model.encode_document(["The compressor stalls with a loud metallic bang."])
+custom = model.encode(["dog"], prompt="Retrieve audio by sound description.")
+```
+
+Image, video, and audio inputs use the model's fixed native formats; instructions and
+prompts only affect text.
+
+### Matryoshka dimensions
+
+The checkpoint was trained with Matryoshka rungs (2048, 1536, 1024, 512, 256, 128, 64).
+Truncate and renormalize to use a shorter rung (this matches the native MRL readout):
+
+```python
+vecs = model.encode(
+    ["a dog barks in the distance"],
+    truncate_dim=1024,
+    normalize_embeddings=True,
+)
+```
+
+### Notes
+
+- Revisions: the integration files are on `main`, which is what loads when no
+  `revision=` is given. The immutable release tags, `v0.3-preview` among them, predate
+  the integration and do not carry these files, so the `revision=` pin shown in the
+  `inference.py` example above does not apply here. `main` carries the same flagship
+  checkpoint as `v0.3-preview`. For a reproducible load, pin the commit hash of a
+  revision that carries the integration files.
+- Each input item is a single modality; embed each modality in its own `encode` call
+  (the shared space makes the vectors directly comparable). Fused multi-modality items
+  (for example `{"text": ..., "audio": ...}` in one dict) are not part of the released
+  model contract and raise an error.
+- Audio arrays must carry a sampling rate (`{"array": ..., "sampling_rate": ...}`);
+  any rate is accepted and resampled to 16 kHz exactly as the native path does.
+- Cross-modal ranking of a full gallery benefits from per-modality mean-centering, worth
+  a couple of points of R@1; see the "Cross-modal ranking tip" above. The package
+  equivalent of that section's `FusionEmbedder.center` is
+  `fusion_embedding.UnifiedEmbedder.center`.
+- The first load downloads the frozen base (`Qwen/Qwen3-VL-Embedding-2B`) and the
+  frozen audio tower (`Qwen/Qwen2.5-Omni-7B` audio encoder) plus this repository's
+  trained connector checkpoint, exactly like the native loader.
+- `model.save(...)` writes configuration only; the 2B weight stack always loads from
+  the Hugging Face repositories above, so saved directories stay small and reloads
+  fetch weights from the hub cache.
+
 ## Changelog
 
 - **v0.3-preview** (default): retrieval-tuned flagship. AudioCaps a2t R@10 0.785