> For the complete documentation index, see [llms.txt](https://docs.telys.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.telys.ai/embeddings/pooled.md).

# Pooled embedder

Reference for AlgentaPooledEmbedder — a runtime-only embedder that resolves lazily from the closed native runtime and is absent in a runtime-free install.

`AlgentaPooledEmbedder` is named in `telys.embedding.__all__` but is **not implemented in the public SDK**. The symbol is a lazy proxy: it resolves from the signed native runtime the first time you reference it. Without the runtime installed, that resolution raises `ImportError`.

For an embedder that works in a plain `pip install telys` environment, use [`AlgentaBigramEmbedder`](https://docs.telys.ai/embeddings/bigram.md) or [`AlgentaMultigramEmbedder`](https://docs.telys.ai/embeddings/multigram.md) (on-device lexical, native kernel), or [`CallableEmbedder`](https://docs.telys.ai/embeddings/callable-byo.md) (bring your own dense model).

## Availability

{% hint style="danger" %}
`AlgentaPooledEmbedder` is **runtime-only** — available only when the signed runtime is installed and verified. In a runtime-free install, importing or constructing it raises `ImportError`. Do not build a collection around it unless `telys runtime status` reports the runtime is ready.
{% endhint %}

Confirm the runtime before you reach for it:

```bash
telys runtime status     # exit 0 = ready, 1 = not installed
telys runtime verify
```

## Import behavior

The name is exported so `from telys.embedding import AlgentaPooledEmbedder` matches `__all__`, but the class body is supplied by the signed runtime at resolution time:

```python
from telys.embedding import AlgentaPooledEmbedder

# Without the native runtime installed:
emb = AlgentaPooledEmbedder()
# Traceback (most recent call last):
#   ...
# ImportError: the native runtime is not installed
```

With the verified runtime present, the symbol resolves to the runtime's implementation and constructs normally.

## Interface (when the runtime is present)

Like every Telys embedder, the resolved class implements the `EmbeddingProvider` protocol:

| Member                   | Returns                   | Notes                                              |
| ------------------------ | ------------------------- | -------------------------------------------------- |
| `profile`                | `EmbeddingProfile`        | The frozen space descriptor for this pooled space. |
| `embed_documents(texts)` | `ndarray[N, D]` `float32` | Embeds documents for ingestion.                    |
| `embed_queries(texts)`   | `ndarray[N, D]` `float32` | Embeds queries; defaults to `embed_documents`.     |

The concrete `model_id`, `dimension`, `pooling`, and other profile fields are defined by the runtime build, not the SDK. Read them from the constructed instance rather than assuming values:

```python
emb = AlgentaPooledEmbedder()      # requires the native runtime
emb.profile.as_dict()              # exact profile for your runtime build
emb.profile.dimension              # dimension exposed by the runtime
emb.profile.space_id()             # "sha256:<16 hex>" space identity
```

{% hint style="info" %}
Because the profile is runtime-defined, always create collections with `dim=emb.profile.dimension`. As with the other Algenta embedders, space identity comes from the profile — the constructor takes no `space_id` or `model_id` argument. See [EmbeddingProfile & space compatibility](https://docs.telys.ai/embeddings/embedding-profile.md).
{% endhint %}

## Portability note

A collection built on the pooled space can only be reopened where the same runtime build is available, since the space identity is defined by the runtime. For a space that works in any environment — including runtime-free SDK installs — prefer a [`CallableEmbedder`](https://docs.telys.ai/embeddings/callable-byo.md), whose profile and function you control end to end.

## See also

* [CallableEmbedder (bring your own)](https://docs.telys.ai/embeddings/callable-byo.md) — the portable, SDK-only embedding path.
* [Choosing an embedder](https://docs.telys.ai/embeddings/choosing-an-embedder.md) — the decision matrix.
* [AlgentaMultigramEmbedder](https://docs.telys.ai/embeddings/multigram.md) — the on-device lexical default.
* [The signed runtime & trust model](https://docs.telys.ai/understand-telys/signed-runtime-trust.md) — what the native runtime is and how it is verified.
* [Embedders API](https://docs.telys.ai/reference/embedders-api.md) — the full embedding surface.
