rat-embed 0.1.1

Relative Anchor Translation: zero-shot embedding space translation via similarity profiles

RAT — Relative Anchor Translation

Zero-shot embedding space translation using relative distances to shared anchors. No additional training required.

Install

pip install rat-embed            # core (numpy only)
pip install "rat-embed[models]"  # + sentence-transformers for fit()
pip install "rat-embed[dev]"     # + pytest, ruff

Quick Start

import numpy as np
from rat import RATranslator

# 1. Prepare anchor embeddings from both models (K anchors, L2-normalized)
anchor_a = ...  # (K, D_a) from model A
anchor_b = ...  # (K, D_b) from model B

# 2. Fit the translator
translator = RATranslator(kernel="poly").fit_embeddings(anchor_a, anchor_b)

# 3. Transform & retrieve
query_emb = ...  # (N, D_a) from model A
db_emb = ...     # (M, D_b) from model B
results = translator.retrieve(query_emb, db_emb, top_k=10)
# results["indices"]  → (N, 10) nearest neighbor indices
# results["scores"]   → (N, 10) cosine similarity scores

Or transform individually for more control:

q_rel = translator.transform(query_emb, "a")              # query side (no z-score)
d_rel = translator.transform(db_emb, "b")                 # db side (z-score applied)
d_rel = translator.transform(db_emb, "b", role="query")   # override: skip z-score

Note: For cross-family model pairs (e.g., MiniLM → BGE), use normalize="always" when constructing the translator. The default "auto" mode may skip z-score normalization for some models where it would actually help in cross-model scenarios.

Advanced: RATHub (multi-model)

from rat import RATHub

hub = RATHub(kernel="poly")
hub.set_anchors("minilm", anchor_minilm)      # (K, 384)
hub.set_anchors("e5", anchor_e5)              # (K, 1024)
hub.set_anchors("bge", anchor_bge)            # (K, 384)

# Transform from any model
q = hub.transform("minilm", query_emb, role="query")
d = hub.transform("e5", db_emb, role="db")

# Or use retrieve directly
results = hub.retrieve(query_emb, db_emb, "minilm", "e5", top_k=10)

Paper

See the Zenodo record for the full experiment report.

Experiment reproduction code is in experiments/ (unchanged from the original research).

License

MIT