Metadata-Version: 2.4
Name: ltr-bert-sir-client
Version: 0.2.2
Summary: Python client for the ltr-bert-sir ELSIE API (sir-elsie Space)
Project-URL: Homepage, https://huggingface.co/s-m-quadri/ltr-bert-sir
Project-URL: Documentation, https://huggingface.co/spaces/s-m-quadri/sir-elsie
Project-URL: Repository, https://github.com/s-m-quadri/ltr-bert-sir-client-py
Project-URL: JavaScript client, https://www.npmjs.com/package/@s-m-quadri/ltr-bert-sir-client
Project-URL: Docker image, https://hub.docker.com/r/smquadri/ltr-bert-sir-elsie
Project-URL: Issues, https://github.com/s-m-quadri/ltr-bert-sir-client-py/issues
Author: Syed Minnatullah Quadri
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: elsie,hybrid-retrieval,information-retrieval,ltr-bert,ltr-bert-sir,ms-marco,reranker,semantic-search,sir
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest-httpx>=0.35; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# ltr-bert-sir-client

Python client for the **ELSIE** semantic information retrieval API. The API is served by the [sir-elsie](https://huggingface.co/spaces/s-m-quadri/sir-elsie) Hugging Face Space and implements the hybrid retrieval stack associated with the [ltr-bert-sir](https://huggingface.co/s-m-quadri/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

| Resource | Description | URL |
|----------|-------------|-----|
| Model | Weights, metrics, offline `LTRBertSIR` | [huggingface.co/s-m-quadri/ltr-bert-sir](https://huggingface.co/s-m-quadri/ltr-bert-sir) |
| Demo Space (ELSIE) | Interactive UI and REST API | [huggingface.co/spaces/s-m-quadri/sir-elsie](https://huggingface.co/spaces/s-m-quadri/sir-elsie) |
| JavaScript client (npm) | Companion package | [npmjs.com/package/@s-m-quadri/ltr-bert-sir-client](https://www.npmjs.com/package/@s-m-quadri/ltr-bert-sir-client) |
| Python client (PyPI) | This package | [pypi.org/project/ltr-bert-sir-client](https://pypi.org/project/ltr-bert-sir-client/) |
| Source (TypeScript) | Companion repository | [github.com/s-m-quadri/ltr-bert-sir-client-js](https://github.com/s-m-quadri/ltr-bert-sir-client-js) |
| Source (Python) | This repository | [github.com/s-m-quadri/ltr-bert-sir-client-py](https://github.com/s-m-quadri/ltr-bert-sir-client-py) |
| Docker image | Self-hosted ELSIE API | [hub.docker.com/r/smquadri/ltr-bert-sir-elsie](https://hub.docker.com/r/smquadri/ltr-bert-sir-elsie) |

## 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

```bash
pip install ltr-bert-sir-client
```

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

## Configuration

```python
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:

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

## Search modes

| API `mode` | UI label | First stage | Neural stage | Notes |
|------------|----------|-------------|--------------|-------|
| `bm25` | Fast | BM25 | none | No embedding index required |
| `blend` | Hybrid | BM25@`bm25_k` | LTR-BERT fusion | Default; needs encoded collection |
| `semantic` | Dense | semantic pool | LTR-BERT | Semantic-first variant |
| `ce_cascade` | Precise | Hybrid pool | LTR-BERT + MiniLM CE | Reranks top `ce_top_k` |
| `ce_only` | CE-only | CE on pool | MiniLM CE | Cross-encoder without blend shortcut |

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).

| Area | Methods |
|------|---------|
| Health and defaults | `health()`, `ranking_config()` |
| Collections | `list_collections()`, `get_collection()`, `create_collection()`, `import_collection()`, `delete_collection()`, `cancel_collection()` |
| Ingest and index | `ingest_file()`, `ingest_url()`, `encode()`, `progress()` |
| Search and documents | `search()`, `get_document()` |
| Statistics | `stats()`, `clear_stats()`, `stats_export_url()` |
| Seeds | `list_seeds()`, `get_seed()`, `load_seed()`, `index_seed()`, `seed_alice()` |
| Qrels and evaluation | `qrels_status()`, `upload_qrels()`, `delete_qrels()`, `export_qrels()`, `annotate_qrels()`, `evaluate()` |
| Library | `library_config()`, `set_library_config()`, `index_all()`, `library_status()`, `import_library()`, `export_library()`, `export_library_with_config()`, `library_export_url()` |
| Binary export | `export_url()`, `export_collection()`, `download()` |

Additional modules:

| Module | Role |
|--------|------|
| `ltr_bert_sir_client.format` | `bytes_fmt`, `mode_label`, `progress_label`, and related display helpers |
| `ltr_bert_sir_client.hints` | Tooltip strings aligned with ELSIE |
| `ltr_bert_sir_client.collections` | `dedupe_collections`, `duplicate_collections`, `collections_by_seed` |
| `ltr_bert_sir_client.ui` | `write_demo()`, `theme_css()` for a standalone HTML demo |

## Usage

```python
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:

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

Generate a minimal browser demo:

```python
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](https://huggingface.co/s-m-quadri/ltr-bert-sir#citation) 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.
