SimilarityIndex#

class scikitplot.corpus.SimilarityIndex(config=None)[source]#

Multi-mode similarity index over CorpusDocument collections.

Parameters:
configSearchConfig or None, optional

Default search configuration. Can be overridden per query.

Parameters:

config (SearchConfig | None)

See also

scikitplot.corpus._schema.MatchMode

Enum of match modes.

scikitplot.corpus._adapters

Convert results to LangChain / MCP format.

Notes

User note: Build the index once, query many times:

index = SimilarityIndex()
index.build(documents)
results = index.search("What did Hamlet say about death?")

Developer note: The index stores references to the original documents. If documents are mutated after building, results are undefined.

Examples

>>> index = SimilarityIndex()
>>> # index.build(corpus_documents)
>>> # results = index.search("quantum computing")
property backend_name: str | None#

Name of the active dense ANN backend, or None if unbuilt.

build(documents)[source]#

Build the index from CorpusDocument instances.

Parameters:
documentsSequence[CorpusDocument]

Documents to index. Must have text (and optionally embedding, tokens, normalized_text).

Raises:
ValueError

If documents is empty.

Parameters:

documents (Sequence[Any])

Return type:

None

property has_embeddings: bool#

Whether dense embeddings are indexed.

property index_generation: int#

Build generation, incremented on every build.

Zero before the first build. Every SearchResult produced by search carries the generation active at query time, so a caller can detect results computed against a since-rebuilt index.

property n_documents: int#

Number of indexed documents.

query(vector, k=None)[source]#

Vector-level ANN query returning (doc_id, score) pairs.

This is the vector-index seam consumed by scikitplot.mcp (the VectorIndex protocol): it takes a query vector (already embedded) rather than a query string, and returns stable document identities instead of SearchResult objects.

Parameters:
vectorarray-like

Query embedding of the same dimension as the indexed vectors.

kint or None, optional

Number of neighbours to return. Defaults to config.top_k.

Returns:
list of (str, float)

(doc_id, cosine_score) pairs, best first. doc_id is the document’s doc_id attribute when present, else its stringified index. Empty if no dense index was built or the query is zero-norm.

Raises:
ValueError

If vector dimension mismatches the index or is non-finite.

Parameters:
Return type:

list[tuple[str, float]]

search(query, *, config=None, query_embedding=None)[source]#

Search the index.

Parameters:
querystr

Query text.

configSearchConfig or None, optional

Override default config for this query.

query_embeddingarray-like or None, optional

Pre-computed query embedding. Required for SEMANTIC mode if no embedding engine is attached.

Returns:
list[SearchResult]

Results sorted by descending score.

Parameters:
Return type:

list[SearchResult]