## Embed
## embed.EmbedBackend
A batch text-embedding backend producing an `(n, dim)` float32 matrix.
Usage
``` python
embed.EmbedBackend()
```
## embed.ApiBackend
An OpenAI-compatible `/embeddings` endpoint as an embedding backend.
Usage
``` python
embed.ApiBackend(base_url, model)
```
#### Parameter Attributes
`base_url: str`
`model: str`
#### Example
``` python
>>> 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
``` python
embed.LocalBackend(model="all-MiniLM-L6-v2")
```
#### Parameter Attributes
`model: str = ``"all-MiniLM-L6-v2"`
#### Example
``` python
>>> await LocalBackend().embed(["hi"])
```
## embed.VoyageEmbedBackend
The Voyage AI `/embeddings` API as an embedding backend (lazy import, `embed-voyage` extra).
Usage
``` python
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: `VoyageSettings
`input_type: Literal[``"query", ``"document"``]`` = ``"document"`
`normalize: bool = ``True`
#### Example
``` python
>>> await VoyageEmbedBackend.from_settings(input_type="query").embed(["hi"])
```
#### Methods
| Name | Description |
|----|----|
| [from_settings()](#athome.embed.VoyageEmbedBackend.from_settings) | Build a backend from [VoyageSettings](embed.md#athome.embed.VoyageSettings), loaded from the config file and environment. |
##### from_settings()
Build a backend from [VoyageSettings](embed.md#athome.embed.VoyageSettings), loaded from the config file and environment.
Usage
``` python
from_settings(*, input_type="document", normalize=True)
```
## embed.EmbedIndex
A content-digest-keyed incremental embedding matrix persisted under `cache_root`.
Usage
``` python
embed.EmbedIndex(namespace, backend)
```
[upsert](embed.md#athome.embed.EmbedIndex.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](cache.md#athome.cache.Cache) atomic writes. Call [upsert()](embed.md#athome.embed.EmbedIndex.upsert) or [matrix()](embed.md#athome.embed.EmbedIndex.matrix) before [mmr()](embed.md#athome.embed.EmbedIndex.mmr), which reranks the loaded matrix.
Concurrency contract: [upsert()](embed.md#athome.embed.EmbedIndex.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: str`
`backend: `EmbedBackend
#### Example
``` python
>>> index = EmbedIndex("exemplars", LocalBackend())
>>> await index.upsert({"a": "first", "b": "second"})
>>> index.mmr(query_vec, k=8)
```
#### Methods
| Name | Description |
|----|----|
| [matrix()](#athome.embed.EmbedIndex.matrix) | Load and return the full `(n, dim)` float32 embedding matrix. |
| [mmr()](#athome.embed.EmbedIndex.mmr) | Rerank the loaded matrix against `query_vec` by maximal marginal relevance, returning ids. |
| [upsert()](#athome.embed.EmbedIndex.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
``` python
matrix()
```
##### mmr()
Rerank the loaded matrix against `query_vec` by maximal marginal relevance, returning ids.
Usage
``` python
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
``` python
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
``` python
embed.EmbedSettings()
```
## embed.VoyageSettings
The `[embed.voyage]` section: the Voyage AI key, model, and batching budgets.
Usage
``` python
embed.VoyageSettings()
```
Bound to `ATHOME_EMBED_VOYAGE_*`; [api_key](serve.md#athome.serve.ManagedServer.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
``` python
embed.EmbedError()
```