soev_retrieval.ports
Implement a vector store: the protocol that every store implements, its errors, and its filter rule.
The engine and the stock adapters call a store only through VectorStore. A store raises only the errors of this
package, or subtypes of them.
Stores
A store searches and reads the chunks of one or more targets.
VectorStore
protocolVectorStoreSearch-side access to one or more targets of chunks.
A target is a name that only the store reads, for example a collection, a collection plus a tenant, or a
filtered view. Every search returns at most limit Hits best first. fetch returns Chunks with
no score. where restricts candidates before scoring. None restricts nothing, and NOTHING (or anything
simplify folds to it) is answered empty. A store checks every predicate in where against fields(target) and
refuses what it cannot serve rather than ignoring it.
Every method raises InvalidQueryError for an unknown target or a filter it will not serve, StoreUnavailable when
the backend gave no answer, and Unconfigured when the store as built cannot serve the call at all.
To write a store, implement these five methods, and test it with VectorStoreContract.
methodhybridasync (target, *, query, vector=None, limit, where=None, alpha=None) -> Sequence[Hit]Combine a vector match with a keyword match on query.
paramtargetTargetThe target to search.
paramquerystrThe query text for the keyword match, and for the vector match when vector is None.
paramvectorSequence[float] | None= NoneThe query embedding. None leaves embedding to the store.
paramlimitintThe maximum number of hits.
paramwhereFilter | None= NoneThe filter that restricts the candidates, or None to restrict nothing.
paramalphafloat | None= NoneThe weight of the vector side: 1.0 is pure vector, 0.0 pure keyword. None means the store's own
default.
Returns
Sequence[Hit]At most limit hits, best first.
Raises:
InvalidQueryError: The target is unknown, the store will not servewhere, or the store cannot honour the givenalpha.StoreUnavailable: The backend gave no answer.Unconfigured:vectorisNoneand the store has no way to embed the query.
methodnear_vectorasync (target, *, vector, limit, where=None) -> Sequence[Hit]Rank by similarity to vector alone.
paramtargetTargetThe target to search.
paramvectorSequence[float]The query embedding.
paramlimitintThe maximum number of hits.
paramwhereFilter | None= NoneThe filter that restricts the candidates, or None to restrict nothing.
Returns
Sequence[Hit]At most limit hits, most similar first.
Raises:
InvalidQueryError: The target is unknown, or the store will not servewhere.StoreUnavailable: The backend gave no answer.Unconfigured: The store as built cannot serve the call.
methodbm25async (target, *, query, limit, where=None) -> Sequence[Hit]Rank by keyword match on query alone.
Chunks matching no term are not returned.
paramtargetTargetThe target to search.
paramquerystrThe query text.
paramlimitintThe maximum number of hits.
paramwhereFilter | None= NoneThe filter that restricts the candidates, or None to restrict nothing.
Returns
Sequence[Hit]At most limit hits, best keyword match first.
Raises:
InvalidQueryError: The target is unknown, or the store will not servewhere.StoreUnavailable: The backend gave no answer.Unconfigured: The store as built cannot serve the call.
methodfetchasync (target, *, where=None, limit, order_by=None, descending=False) -> Sequence[Chunk]Return chunks matching where with nothing searched for.
paramtargetTargetThe target to read.
paramwhereFilter | None= NoneThe filter that the chunks match, or None for every chunk.
paramlimitintThe maximum number of chunks.
paramorder_bystr | None= NoneA stored field to sort on. A field not in fields(target) is refused. Without it, the order is
the store's own.
paramdescendingbool= FalseWhether to sort on order_by in descending order. The default is ascending.
Returns
Sequence[Chunk]At most limit chunks.
Raises:
InvalidQueryError: The target is unknown, the store will not servewhere, ororder_byis not a stored field.StoreUnavailable: The backend gave no answer.Unconfigured: The store as built cannot serve the call.
methodfieldsasync (target) -> FieldSpecReturn the stored fields of target and which of them a filter may name.
paramtargetTargetThe target to describe.
Returns
FieldSpecThe field spec of the target.
Raises:
InvalidQueryError: The target is unknown.StoreUnavailable: The backend gave no answer.
InvalidQueryError
errorInvalidQueryError(message, *, field=None)The store answered and rejected the call: an unknown target, or a filter it will not serve.
The fault is in the arguments of the call, so change the call. A store that refuses a target for a reason of its own raises a subtype of this, so the engine handles it as it handles any rejected call and learns nothing more.
Each VectorStore method raises it, and so does validate. Retrying raises it at once and does not
call the store again.
parammessagestrWhat is wrong with the call.
paramfieldstr | None= NoneThe name of the offending filter field, or None when there is none.
StoreUnavailable
errorStoreUnavailableThe store gave no answer this time: it is down, slow or unreachable.
The same call can succeed later.
Each VectorStore method raises it when the backend gave no answer. Retrying calls the store again
while the store raises it.
Unconfigured
errorUnconfiguredThe store cannot serve this call as built: nothing is configured to embed, or no backend is set.
A VectorStore method raises it. For example, VectorStore.hybrid raises it when it gets no vector and
the store cannot embed the query. Retrying raises it at once and does not call the store again.
Filter rule
A store checks each filter against the fields of its target before it calls its backend, and folds what matches everything or nothing out of the filter.
validate
functionvalidate(where, spec) -> NoneRefuse the first predicate anywhere in where that the fields of spec cannot serve.
A predicate is refused when it names an unknown or unfilterable field, an unknown operator, or an operand the
operator does not take: the wrong shape, a field type it is not defined on, or a value of the wrong type for the
field. Every such refusal names the field. Anything that is not a Filter is refused too. validate also
checks the branches that simplify removes.
A store calls it before it builds a query for its backend.
paramwhereFilter | NoneThe filter to check. None passes.
paramspecFieldSpecThe stored fields of the target that the filter is for.
Raises:
InvalidQueryError: A predicate cannot be served. Itsfieldnames the field of the predicate, except whenwhereis not aFilter.
simplify
functionsimplify(where) -> Filter | NoneReturn where with what matches everything or nothing folded out.
An AllOf or AnyOf left with one term becomes that term.
A store calls it after validate, and answers NOTHING with an empty sequence.
paramwhereFilter | NoneThe filter to fold.
Returns
Filter | NoneThe folded filter: None when it matches everything, NOTHING when it matches nothing.
OPERATORS
constantOPERATORS: Mapping[str, Operator]The operators that a DeclaredFilter can name, each with the operand that it takes.
eq,gt,gte,ltandltecompare a field with one scalar.inholds when the field equals one of the listed scalars.contains_anyholds when a list field contains at least one of the listed scalars. On a field with one value, it holds likein.underis a prefix scope on akeywordfield. Each store decides whether it servesunder.
validate refuses an operator that is not in this mapping.
Operator
dataclassOperator(many=False, on=None)The operand an operator takes: one scalar or many, on any field type or only some.
parammanybool= FalseWhether the operand is a sequence of scalars. False means one scalar.
paramonfrozenset[FieldType] | None= NoneThe field types that the operator is defined on, or None for every field type.