CorpusAnnoyRetriever#

class scikitplot.mcp.CorpusAnnoyRetriever(embedder, index, doc_lookup, *, strict=False)[source]#

Docs dense retriever backed by an embedder + a vector index + a document lookup.

Parameters:

embedderEmbedder: Query embedder (the same model used to embed the corpus).
indexVectorIndex: Vector index returning (doc_id, score) for a query vector.
doc_lookupcallable: doc_id -> mapping returning at least text and source_uri, optionally title / anchor. In production this reads the CorpusDocument from corpus storage.

Parameters:

embedder (Embedder)
index (VectorIndex)
doc_lookup (Callable[[str], dict[str, Any]])
strict (bool)

Notes

Read-only. Retrieved text is untrusted and is sanitised downstream by build_search_docs_result.

classmethod from_corpus_annoy(docs_path, *, metric='angular', n_trees=10, embedding_model='all-MiniLM-L6-v2', embedder=None, backend='annoy', strict=False, mode='semantic')[source]#

Build the real retriever from a docs directory (import-guarded).

Wires scikitplot.corpus end to end. A single CorpusBuilder pass ingests, embeds, and builds an Annoy-backed RetrievalIndex (selected through index_kwargs), and this retriever consumes that index’s vector-level query seam directly. There is no second, ad-hoc Annoy index and no bespoke distance-to-score arithmetic — the corpus owns both the vector backend and the cosine score contract.

Parameters:

docs_pathstr: Directory of documentation sources (RST / MyST / Markdown / HTML).
metricstr, optional: Annoy metric ('angular' for cosine-like on normalised vectors).
n_treesint, optional: Annoy tree count (accuracy/size trade-off).
embedding_modelstr, optional: Sentence-embedding model used when embedder is None. The query embedder uses the same model so query and corpus vectors share one space.
embeddercallable or object with embed(list[str]), optional: Explicit local batch embedder. When provided, the corpus is ingested without model embeddings, this callable supplies document vectors, and the same callable embeds queries. This is suitable for deterministic/offline helpers such as scikitplot.corpus.HashEmbedder.
backendstr, optional: Dense ANN backend for the corpus index. 'annoy' (default) or 'auto' (Annoy first, then FAISS / Voyager / brute-force).
strictbool, optional: False.
mode{‘semantic’, ‘hybrid’, ‘keyword’}, optional: 'semantic' (default) returns a CorpusAnnoyRetriever over the vector seam, as before. 'hybrid' and 'keyword' return a CorpusIndexRetriever over the same index, which already holds a BM25 leg: hybrid fuses BM25 and dense by rank inside the corpus (finding CX-04).

Returns:

CorpusAnnoyRetriever or CorpusIndexRetriever

Raises:

RuntimeError: If scikitplot.corpus is unavailable, or the build produced no queryable semantic index (e.g. embeddings were unavailable).
ValueError: If mode is not one of the accepted values (checked before any build), or propagated from CorpusBuilder when docs_path contains no valid input sources.

Parameters: