denselinkage.core.ports.SearchableIndex¶

class denselinkage.core.ports.SearchableIndex(*args, **kwargs)[source]¶

Bases: Protocol

Immutable fitted artifact produced by VectorIndex.build().

Holds the indexed vectors for one dataset and answers nearest-neighbour queries; it has no add — the vectors are fixed at build time. search raises DimensionMismatch if a query’s width differs from the indexed vectors.

v1 is batch-oriented and the artifact is immutable. Incremental update is out of scope for v1; extended() is the designed (not-yet-implemented) escape hatch — it returns a NEW artifact rather than mutating this one.

extended(vectors: Any, ids: Sequence[str]) → SearchableIndex[source]¶

Return a NEW artifact holding this index’s vectors plus vectors; this instance is left unchanged (the immutable-artifact guarantee). ids align positionally with vectors and must be disjoint from the ids already indexed; vectors must match the indexed width or DimensionMismatch is raised.

Incremental indexing is out of scope for v1, so the v1 reference artifacts raise NotImplementedError rather than returning None; the signature is fixed pre-freeze so the capability can land later without a breaking change.