Embeddings

The embedding port, a callable embedder and its cache. Concepts: Embeddings.

Embeddings: the EmbeddingPort, CallableEmbedder for any host function, and its cache.

CallableEmbedder

Wraps fn(texts) with batching, an optional per-text cache, a ledger entry and events.

A sync fn runs in a worker thread with the caller's contextvars. timeout_s bounds each fn call; a timed-out thread is abandoned, not stopped.

Raises:

Type	Description
ConfigError	a bad model, provider, batch_size or timeout_s.
ToolUsageError	fn is not callable.

embed(texts, *, ctx=None) async

Vectors for texts, in order; repeated texts are embedded once.

Raises:

Type	Description
ToolUsageError	texts is not a sequence of strings.
ModelTimeout	one fn call took longer than timeout_s.
ModelOutputInvalid	fn returned no valid vectors, the wrong count, or mixed sizes.
ModelError	fn raised a non-adapter error (it is the __cause__).

EmbeddingCache

Stores vectors under embed_key; backend failures and bad entries are misses.

get_many(texts, *, provider, model) async

The cached vector of each text that has one.

set_many(vectors, *, provider, model) async

Store each vector; returns how many were stored.

EmbeddingPort

Bases: Protocol

Turns texts into vectors; raises ModelError subclasses.

EmbeddingResult

Bases: BaseModel

Vectors in input order, the model that made them, its usage and the cache hits.

embed_key(namespace, text, *, provider, model)

Key for one text's vector; the text appears only as a digest.