ltr-bert-sir-client

Python client for the ELSIE semantic information retrieval API. The API is served by the sir-elsie Hugging Face Space and implements the hybrid retrieval stack associated with the ltr-bert-sir bi-encoder checkpoint: BM25 first stage, pool-restricted LTR-BERT scoring, optional cross-encoder reranking, and library management for long-text corpora.

Authors: Syed Minnatullah Quadri, Vrishali A. Chakkarwar
License: Apache-2.0

Related resources

1. Bi-encoder weights, metrics, and offline LTRBertSIR inference at s-m-quadri/ltr-bert-sir on Hugging Face
2. Interactive ELSIE demo and REST API at s-m-quadri/sir-elsie on Hugging Face Spaces
3. JavaScript and TypeScript client at @s-m-quadri/ltr-bert-sir-client on npm
4. Python client (this package) at ltr-bert-sir-client on PyPI
5. TypeScript source at ltr-bert-sir-client-js on GitHub
6. Python source at ltr-bert-sir-client-py on GitHub
7. Self-hosted ELSIE API at smquadri/ltr-bert-sir-elsie on Docker Hub

Background

Long-document ad hoc retrieval on MS MARCO is typically staged: a lexical first stage (here BM25@100) defines a candidate pool; a bi-encoder scores only within that pool; scores are fused (linear blend with alpha = 0.85 by default) or passed to a cross-encoder on a short shortlist. The Hub model repository documents the fine-tuned LTR-BERT bi-encoder and offline scoring. This package targets the live HTTP API exposed by the ELSIE Space: search, collection ingest, seed libraries, qrels upload, batch evaluation, and library export.

Default base URL (DEFAULT_SIR_API_URL):

https://huggingface.co/spaces/s-m-quadri/sir-elsie

Pass a different origin to SirClient(...) when the FastAPI app runs locally, via Docker, or elsewhere.

Installation

pip install ltr-bert-sir-client

Requirements: Python 3.10 or newer. Depends on httpx for HTTP.

Configuration

from ltr_bert_sir_client import SirClient, DEFAULT_SIR_API_URL

sir = SirClient(DEFAULT_SIR_API_URL, timeout=120.0)

Use the context manager to close the underlying HTTP client:

with SirClient() as sir:
    print(sir.health())

Search modes

Search bodies accept query, optional collection_id, mode, k, bm25_k, ce_top_k, and alpha. Responses include hits, ms, optional trace, and optional eval when qrels are loaded.

API overview

The SirClient class mirrors the Space REST surface (parity with the JavaScript client).

Additional modules:

Usage

from ltr_bert_sir_client import SirClient

with SirClient() as sir:
    health = sir.health()
    cols = sir.list_collections()
    cid = cols["collections"][0]["id"]
    result = sir.search(
        {
            "query": "alice rabbit hole curious dream",
            "collection_id": cid,
            "mode": "blend",
            "k": 10,
        }
    )
    for hit in result["hits"]:
        print(hit["title"], hit["score"])

Batch evaluation when qrels are present:

metrics = sir.evaluate(
    cid,
    mode="blend",
    k=100,
    bm25_k=100,
    ce_top_k=32,
)

Generate a minimal browser demo:

from ltr_bert_sir_client.ui import write_demo

write_demo("./demo", "https://huggingface.co/spaces/s-m-quadri/sir-elsie")

Citation

Bibliographies and publication details are on the ltr-bert-sir model card on Hugging Face. Cite MS MARCO when using bundled evaluation qrels or MS MARCO-derived training described there.

License

Apache-2.0. MS MARCO remains under Microsoft research terms when used through the API or bundled seeds.