RetrievalHit#

class scikitplot.corpus.RetrievalHit(doc, score, match_mode, backend=None, index_generation=None, native_score=None, native_metric=None, contributions=(), rank=None)[source]#

A single search result.

Parameters:
docCorpusDocument

The matched document.

scorefloat

Relevance score (higher is better). Scale depends on match mode:

  • STRICT: 1.0 if match, 0.0 otherwise

  • KEYWORD: Jaccard similarity [0, 1] or BM25 score

  • SEMANTIC: cosine similarity [-1, 1]

  • HYBRID: reciprocal rank fusion score

match_modestr

The mode that produced this result.

backendstr or None

Name of the dense ANN backend that produced this result (SEMANTIC/HYBRID), or None for STRICT/KEYWORD. Provenance only: excluded from equality and hashing.

index_generationIndexGeneration or None

The RetrievalIndex build generation that produced this result. Increments on every RetrievalIndex.build, so a caller can detect results computed against a since-rebuilt index. Provenance only: excluded from equality and hashing.

Parameters:

  • doc (Any)

  • score (float)

  • match_mode (str)

  • backend (str | None)

  • index_generation (IndexGeneration | None)

  • native_score (float | None)

  • native_metric (str | None)

  • contributions (tuple)

  • rank (int | None)

Notes

Developer note: backend and index_generation describe how the result was produced, not what it is, so they use compare=False — two results for the same document/score/mode remain equal regardless of provenance. Embedding-model identity is out of scope here (it travels with the document embeddings; see the embedding-cache identity contract).

backend: str | None = None#
contributions: tuple = ()#

Per-leg provenance for a fused hit, empty for a single-leg hit.

Each entry records which leg found this document, at what rank, and with what native score and metric. A hit that ranked #1 in both legs and one that ranked #1 and #40 used to be indistinguishable – very different confidence signals collapsed into one fused float (finding F-R09-02).

doc: Any[source]#
index_generation: IndexGeneration | None = None#
match_mode: str[source]#
native_metric: str | None = None#

Scale of native_score, e.g. "cosine_similarity".

§19 forbids comparing cosine, Euclidean, inner-product and backend-specific relevance scores as though they shared one scale. A hit that records its own scale lets a consumer verify no such comparison happened.

native_score: float | None = None#

The score the backend actually returned, before any fusion.

score is the value this hit was ranked by, which for a fused result is not any backend’s output. Keeping them separate is what makes a fused score explainable rather than merely a number (finding F-R07-03).

rank: int | None = None#

Zero-based position within the leg that produced this hit.

§19 names rank as the fallback ordering when no validated normalization exists – which, per R06, is the case for every non-cosine metric today.

score: float[source]#