ANNIndexArtifact#

class scikitplot.corpus.ANNIndexArtifact(path, manifest, generation, doc_ids, backend)[source]#

A persisted vector index together with its provenance.

Parameters:
pathpathlib.Path

Artifact directory.

manifestEmbeddingManifest

Which model produced the vectors.

generationIndexGeneration

Which content the index was built over.

doc_idstuple of str

The sidecar: doc_ids[i] is the document at row i.

backendstr

Name of the backend that wrote the native payload.

Parameters:

Notes

Developer. doc_ids is a tuple, so an artifact cannot have its mapping mutated after the correspondence has been validated.

backend: str[source]#
doc_id_for(ordinal)[source]#

Resolve a backend row offset to a stable document identity.

Parameters:
ordinalint

Row index as returned by VectorIndexBackend.query.

Returns:
str

The doc_id at that row.

Raises:
IndexError

If ordinal is negative or outside the sidecar. Out of range means the index and the sidecar disagree – a corrupt artifact rather than a bad query.

TypeError

If ordinal is not an integer. bool is rejected explicitly: it is an int subclass, so True would otherwise resolve to row 1.

Parameters:

ordinal (int)

Return type:

str

Notes

Developer. The domain comes from scikitplot._utils._indexing.require_index, so this boundary and the lexical index answer the same question the same way. Direct tuple indexing used to accept -1 and resolve it to the last row, which turned a caller’s off-by-one into a plausible wrong document.

doc_ids: tuple[str, ...][source]#
generation: IndexGeneration[source]#
classmethod generations(path)[source]#

Return the generation directories retained under path.

Parameters:
pathstr or pathlib.Path

Artifact root.

Returns:
list of pathlib.Path

Retained generations, sorted by name. A reader holding one of these keeps reading it until it is pruned.

Parameters:

path (str | Path)

Return type:

list[Path]

load_vectors()[source]#

Return the native payload, or None when none was written.

Return type:

Any

manifest: EmbeddingManifest[source]#
classmethod open(path)[source]#

Open the generation the artifact’s pointer currently names.

Parameters:
pathstr or pathlib.Path

Artifact root, or a generation directory, which is opened directly.

Returns:
ANNIndexArtifact
Raises:
ArtifactError

If the root has no readable pointer, or the generation it names is absent. A directory with no pointer is refused rather than guessed at: picking a generation by name would make the choice silently.

Parameters:

path (str | Path)

Return type:

ANNIndexArtifact

classmethod open_generation(path)[source]#

Load an artifact, validating its internal consistency.

Raises:
ArtifactError

If the artifact is missing a required file, declares an unreadable sidecar schema, or its sidecar disagrees with its manifest.

Parameters:

path (str | Path)

Return type:

ANNIndexArtifact

Notes

Developer. Loading validates before returning, so a caller cannot hold an artifact whose mapping has not been checked. A sidecar written by a future schema is refused rather than interpreted, for the same reason the document schema refuses an unknown major version: a mapping that might mean something else is worse than no mapping.

path: Path[source]#
require_compatible(manifest=None, *, documents=None)[source]#

Refuse to use this artifact with incompatible inputs.

Parameters:
manifestEmbeddingManifest or None, optional

Query-time embedding generation. Must match the artifact’s.

documentsiterable or None, optional

Documents the caller intends to serve from this index. Their identities must match the sidecar as a set.

Raises:
IncompatibleEmbeddingsError

If manifest describes a different embedding generation.

ArtifactError

If documents do not match the sidecar.

Parameters:
Return type:

None

Notes

Developer. The document check compares sets, not order. Order is exactly what the sidecar exists to record, so requiring the caller to reproduce it would defeat the purpose; what must hold is that the artifact describes these documents and no others.

resolve(hits)[source]#

Map (ordinal, score) pairs to (doc_id, score) pairs.

Parameters:

hits (Iterable[tuple[int, float]])

Return type:

list[tuple[str, float]]

property row_count: int#

Number of rows the sidecar describes.

classmethod write(path, *, documents, backend, manifest, vectors=None, generation=None)[source]#

Publish an artifact atomically.

Parameters:
pathstr or pathlib.Path

Destination directory. Replaced atomically if it exists.

documentssequence

Documents in row order. Their order defines the sidecar, which is the point: it is recorded rather than assumed.

backendstr

Name of the backend that produced the native payload.

manifestEmbeddingManifest

Embedding generation the vectors belong to.

vectorsarray-like or None, optional

Native payload. Written as .npy when NumPy is available.

generationIndexGeneration or None, optional

Defaults to deriving one from documents and backend.

Returns:
ANNIndexArtifact
Parameters:
Return type:

ANNIndexArtifact

Notes

Developer. Publication uses atomic_write_path, which R04 verified under ENOSPC, EACCES and KeyboardInterrupt: the target is left intact and no temporary files survive. A half-written artifact would be worse than none, because its sidecar could describe rows the native index does not have.