IMRNNs

Interpretable Modular Retrieval Neural Networks
Efficient, interpretable dense retrieval through dynamic embedding modulation.

        

Paper · Documentation · PyPI · Project website · Author portfolio

---

Given a query and candidate documents, IMRNNs dynamically modulates both sides of their dense embeddings before ranking the documents by cosine similarity. A Query Adapter conditions each document representation on the query, while a Document Adapter uses feedback from the candidate set to adapt the query representation. The MiniLM base encoder stays frozen.

This repository contains the ready-to-use MiniLM–SciFact adapter. Browse the checkpoint files or load the adapter automatically with the imrnns package.

Installation

python -m pip install imrnns

Rank SciFact documents

This executable example uses claim 130 and three genuine document titles from the BEIR SciFact corpus.

from imrnns import IMRNNAdapter

CLAIM = (
    "Articles published in open access format are more likely to be cited "
    "than traditional journals."
)

DOCUMENTS = {
    "27768226": "Open Access Increases Citation Rate",
    "38180456": "Short-term medical service trips: a systematic review of the evidence.",
    "16979690": (
        "Effect on the quality of peer review of blinding reviewers and asking "
        "them to sign their reports: a randomized controlled trial."
    ),
}

adapter = IMRNNAdapter.from_pretrained(
    encoder="minilm",
    dataset="scifact",
    repo_id="yashsaxena21/IMRNNs",
    device="cpu",
)

ranked_documents = adapter.rank(
    query=CLAIM,
    documents=list(DOCUMENTS.values()),
    document_ids=list(DOCUMENTS),
    top_k=3,
)

for item in ranked_documents:
    print(
        item.rank,
        item.document_id,
        item.base_score,
        item.adapted_score,
        item.score_delta,
    )

Each returned item contains its new rank, original input position, optional document ID and text, frozen-encoder score, modulated score, and score change.

Explain a retrieval decision

Use the same claim and document to inspect vocabulary-level concepts and the query/document modulation vectors:

from pathlib import Path

explanation = adapter.explain(
    query=CLAIM,
    document=DOCUMENTS["27768226"],
    top_tokens=5,
)

print(explanation.top_query_tokens)
print(explanation.top_document_tokens)
print(explanation.query_modulation)
print(explanation.document_modulation)

Path("imrnns-explanation.html").write_text(
    explanation.to_html(),
    encoding="utf-8",
)

Vocabulary concepts are inspection aids derived through a Moore–Penrose back-projection. They can contain WordPiece fragments and should not be treated as causal natural-language rationales.

Rank existing embeddings

Use vectors produced by the checkpoint's pinned MiniLM encoder:

from sentence_transformers import SentenceTransformer

encoder = SentenceTransformer(
    "sentence-transformers/all-MiniLM-L6-v2",
    revision="c9745ed1d9f207416be6d2e6f8de32d1f16199bf",
    device="cpu",
)
query_embedding = encoder.encode(CLAIM, convert_to_numpy=True)
document_embeddings = encoder.encode(
    list(DOCUMENTS.values()),
    convert_to_numpy=True,
)

embedding_adapter = IMRNNAdapter.from_pretrained(
    encoder="minilm",
    dataset="scifact",
    load_encoder=False,
    device="cpu",
)

ranked_documents = embedding_adapter.rank_embeddings(
    query_embedding=query_embedding,
    document_embeddings=document_embeddings,
    document_ids=list(DOCUMENTS),
    top_k=3,
)

NumPy arrays, PyTorch tensors, and numeric Python sequences are accepted. The embedding dimension and base encoder must match the adapter checkpoint.

Model details

Field	Value
Base encoder	sentence-transformers/all-MiniLM-L6-v2
Base revision	c9745ed1d9f207416be6d2e6f8de32d1f16199bf
Dataset	SciFact
Embedding dimension	384
Framework	PyTorch
Python package	imrnns
License	CC BY 4.0

For checkpoint downloading, offline loading, vector-store integration, training, custom datasets, custom encoders, CLI commands, and the complete Python API, see the project documentation.

Intended use and limitations

The adapter is intended for research and development involving dense retrieval, embedding analysis, and retrieval-decision interpretability. It is specialized for the documented base encoder and domain. Behavior can change with corpus composition, candidate-set size, query style, input truncation, or encoder version. Review retrieved evidence before using it in high-impact or safety-critical systems.

Citation

@inproceedings{saxena-etal-2026-imrnns,
  title = "{IMRNN}s: An Efficient Method for Interpretable Dense Retrieval via Embedding Modulation",
  author = "Saxena, Yash and Padia, Ankur and Gunaratna, Kalpa and Gaur, Manas",
  booktitle = "Findings of the Association for Computational Linguistics: EACL 2026",
  year = "2026",
  pages = "6324--6337",
  doi = "10.18653/v1/2026.findings-eacl.333",
  url = "https://aclanthology.org/2026.findings-eacl.333/"
}

License

The code, scripts, documentation, and checkpoints are licensed under Creative Commons Attribution 4.0 International. Please preserve the attribution and citation information when redistributing this work.