README.md

---
title: README
emoji: 🏆
colorFrom: indigo
colorTo: blue
sdk: static
pinned: false
license: mit
---
<!--
QuerynAi — Hugging Face organization card.
Local draft (git-ignored). Paste into the org card at
https://huggingface.co/organizations/QuerynAi/settings  →  or the QuerynAi/README repo.
Fill the <…> placeholders before publishing.
-->

# Queryn — Embedding Translation

**Move a corpus between embedding models without re-embedding it.** Given a text
chunk's embedding in Model A's space, a Queryn adapter returns the equivalent
vector in Model B's space — so a vector index built with one model can be served
against another after a lightweight transform instead of a full, expensive
backfill.

## What's in this org

The **[Queryn Embedding Adapters](https://huggingface.co/QuerynAi)** collection —
one small ONNX model per directed model pair (`queryn-adapter-<source>_to_<target>`).
Each repo contains:

- `model.onnx` — the adapter, opset 17, dynamic batch axis. Runs anywhere
  `onnxruntime` runs; no PyTorch needed.
- `model.safetensors` — the same weights, for retraining / inspection.
- `config.json` — dimensions, the I/O contract, and provenance.
- a model card with per-pair metrics and training plots.

Every adapter L2-normalizes its input and output internally, so you feed raw
embeddings straight in and get unit vectors back.

## Using an adapter

```python
import numpy as np, onnxruntime as ort
from huggingface_hub import hf_hub_download

repo = "QuerynAi/queryn-adapter-ada-002_to_bge-m3"
sess = ort.InferenceSession(hf_hub_download(repo, "model.onnx"),
                            providers=["CPUExecutionProvider"])

src = np.random.rand(8, 1536).astype(np.float32)          # your ada-002 embeddings
tgt = sess.run(["target_embedding"], {"source_embedding": src})[0]
#  tgt: (8, 1024) unit vectors in bge-m3 space
```

## How the adapters are built

- One **linear** projection and one **1-hidden-layer GELU MLP** (with a
  compressed latent below both dimensions) are trained per pair; whichever scores
  higher on held-out cosine similarity is published, ties to linear. Each pair's
  card reports both, so the linear-vs-nonlinear trade-off is visible.
- Trained on a unified **~349,674-row, five-domain corpus** (arXiv abstracts,
  Australian case law, SQuAD passages, PubMed RCT abstracts, financial/markets
  news), optimizing `1 − mean cosine similarity` with Adam and LR scheduling.
- Some embedding spaces are near-isomorphic and align well with a single matrix;
  others need the nonlinear map and still lose accuracy. Check the card metrics
  for your pair before relying on it — translation is an approximation, not a
  substitute for re-embedding when fidelity is critical.

## Model coverage

| Model | Dim | Role in v1 |
|---|---|---|
| `ada-002` | 1536 | source only (deprecated as a target) |
| `te3-small` | 1536 | source + target |
| `qwen3-emb-8b` | 4096 | source + target |
| `bge-m3` | 1024 | source + target |
| `me5-large` | 1024 | source + target |
| `pplx-embed-1` | 1024 | source + target |
| `nemotron-1b-free` | 2048 | source + target |
| `fastembed-bge-small` | 384 | source + target |

49 directed pairs in the current (v1) generation.

## Links

- **Code & pipeline:** <GitHub repo URL>
- **Training corpus + paired embeddings:** <Kaggle dataset URL>
- **Papers behind the approach:** Vec2Vec ([arXiv:2306.12689](https://arxiv.org/abs/2306.12689)),
  mini-vec2vec ([arXiv:2510.02348](https://arxiv.org/abs/2510.02348))

## License

Adapter models: **MIT**. The Queryn codebase: **Apache-2.0**. Training data keeps
each source corpus's own license — see the dataset's `LICENSE` manifest.

## Status

An independent research project on practical embedding-space alignment. Issues and
findings welcome via the repo; the adapters are provided as-is.