Embed
embed.EmbedBackend
A batch text-embedding backend producing an (n, dim) float32 matrix.
Usage
embed.EmbedBackend()embed.ApiBackend
An OpenAI-compatible /embeddings endpoint as an embedding backend.
Usage
embed.ApiBackend(base_url, model)Parameter Attributes
base_url: strmodel: str
Example
>>> await ApiBackend("http://127.0.0.1:8400/v1", "text-embedding-3-small").embed(["hi"])embed.LocalBackend
A local sentence-transformers model as an embedding backend (lazy import).
Usage
embed.LocalBackend(model="all-MiniLM-L6-v2")Parameter Attributes
model: str = "all-MiniLM-L6-v2"
Example
>>> await LocalBackend().embed(["hi"])embed.VoyageEmbedBackend
The Voyage AI /embeddings API as an embedding backend (lazy import, embed-voyage extra).
Usage
embed.VoyageEmbedBackend(settings, input_type="document", normalize=True)Packs texts into dual-budget batches — each capped by both settings.batch_texts items and settings.batch_chars characters — embeds the batches concurrently under settings.concurrency, and reassembles the vectors in the original input order. input_type and normalize are construction state: build one instance for documents and a separate one for queries.
Parameter Attributes
settings: VoyageSettingsinput_type: Literal["query", "document"] = "document"normalize: bool = True
Example
>>> await VoyageEmbedBackend.from_settings(input_type="query").embed(["hi"])Methods
| Name | Description |
|---|---|
| from_settings() | Build a backend from VoyageSettings, loaded from the config file and environment. |
from_settings()
Build a backend from VoyageSettings, loaded from the config file and environment.
Usage
from_settings(*, input_type="document", normalize=True)embed.EmbedIndex
A content-digest-keyed incremental embedding matrix persisted under cache_root.
Usage
embed.EmbedIndex(namespace, backend)upsert re-embeds only the ids whose text digest changed since the last pass; the matrix is persisted as an .npz blob through athome.cache.Cache atomic writes. Call upsert() or matrix() before mmr(), which reranks the loaded matrix.
Concurrency contract: upsert() serialises its read-modify-write per namespace with an in-process anyio.Lock, so concurrent upserts within one process never lose updates. That lock does not span processes, so the contract is a single writer per namespace across processes; a second writing process can still clobber an update. A cross-process file lock is intentionally out of scope — run one writer per namespace.
Parameter Attributes
namespace: strbackend: EmbedBackend
Example
>>> index = EmbedIndex("exemplars", LocalBackend())
>>> await index.upsert({"a": "first", "b": "second"})
>>> index.mmr(query_vec, k=8)Methods
| Name | Description |
|---|---|
| matrix() |
Load and return the full (n, dim) float32 embedding matrix.
|
| mmr() |
Rerank the loaded matrix against query_vec by maximal marginal relevance, returning ids.
|
| upsert() |
Insert or update id -> text entries, re-embedding only the changed digests.
|
matrix()
Load and return the full (n, dim) float32 embedding matrix.
Usage
matrix()mmr()
Rerank the loaded matrix against query_vec by maximal marginal relevance, returning ids.
Usage
mmr(query_vec, *, k, lambda_=0.5)Greedily picks the id maximizing lambda_ * sim(query, id) - (1 - lambda_) * max sim(id, picked): higher lambda_ favors relevance, lower favors diversity among the k returned ids.
upsert()
Insert or update id -> text entries, re-embedding only the changed digests.
Usage
upsert(items)The read-modify-write is serialised per namespace by an in-process anyio.Lock, so concurrent upserts within one process never lose updates. The lock does not span processes: keep a single writer per namespace across processes.
embed.EmbedSettings
The [embed] section: the bearer key for OpenAI-compatible embedding endpoints.
Usage
embed.EmbedSettings()embed.VoyageSettings
The [embed.voyage] section: the Voyage AI key, model, and batching budgets.
Usage
embed.VoyageSettings()Bound to ATHOME_EMBED_VOYAGE_*; api_key reads the canonical VOYAGE_API_KEY so a consumer’s existing convention works unchanged. batch_texts and batch_chars cap each request by item count and total characters, and concurrency bounds the in-flight requests per VoyageEmbedBackend.embed() call.
embed.EmbedError
An embedding backend or index operation failed.
Usage
embed.EmbedError()