> 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/embedding-profile.md).

# Embedding profiles

Reference for EmbeddingProfile — the frozen record that names a vector space and, via space\_id(), gates which embedder can reopen or attach to a collection.

An `EmbeddingProfile` is the identity card of a vector space. Every embedder carries one, every saved collection stores one, and Telys uses its `space_id()` to decide whether an embedder may attach to a collection. Vectors from two different spaces are never comparable, so this record keeps a collection honest across reopen and re-attach.

```python
from telys.embedding import EmbeddingProfile
```

## Signature

```python
EmbeddingProfile(
    provider,
    model_id,
    model_version,
    dimension,
    dtype="float32",
    normalization="l2",
    distance="ip",
    pooling="none",
    tokenizer_hash="",
    projection_version="",
    created="",
)
```

A **frozen** dataclass — instances are immutable. Construct a new one to describe a new space.

## Fields

| Field                | Type  | Default     | Purpose                                                                                          |
| -------------------- | ----- | ----------- | ------------------------------------------------------------------------------------------------ |
| `provider`           | `str` | (required)  | Who produces the vectors, e.g. `"openai"`, `"algenta"`, `"local"`.                               |
| `model_id`           | `str` | (required)  | Model name, e.g. `"text-embedding-3-small"`, `"bigram"`.                                         |
| `model_version`      | `str` | (required)  | Version tag; bump it when the model's weights or behavior change.                                |
| `dimension`          | `int` | (required)  | Vector width `D`. Must equal the collection `dim` and what the embedder returns.                 |
| `dtype`              | `str` | `"float32"` | Element type of the emitted vectors.                                                             |
| `normalization`      | `str` | `"l2"`      | Norm your vectors carry (`"l2"` = unit length, `"none"` = raw).                                  |
| `distance`           | `str` | `"ip"`      | Similarity used at search time (`"ip"` = inner product; equals cosine on L2-normalized vectors). |
| `pooling`            | `str` | `"none"`    | How tokens are pooled, e.g. `"bigram-hash"`, `"multigram-hash"`, `"none"`.                       |
| `tokenizer_hash`     | `str` | `""`        | Optional tokenizer digest, for models where tokenization defines the space.                      |
| `projection_version` | `str` | `""`        | Optional tag for a post-embedding projection/reduction.                                          |
| `created`            | `str` | `""`        | Provenance timestamp. Bookkeeping only — see below.                                              |

## Methods

| Method                   | Returns | Description                                                                        |
| ------------------------ | ------- | ---------------------------------------------------------------------------------- |
| `space_id()`             | `str`   | `"sha256:"` plus 16 hex characters — a stable digest of the space-defining fields. |
| `compatible_with(other)` | `bool`  | `True` when `self.space_id() == other.space_id()`.                                 |
| `as_dict()`              | `dict`  | The field values. A saved collection stores this as `embedder_profile`.            |

## What defines space identity

`space_id()` digests the fields that determine whether vectors are comparable — provider/model identity, `dimension`, `dtype`, `normalization`, `distance`, `pooling`, and the tokenizer/projection tags. Change any of them and you have declared a new space:

```python
from telys.embedding import EmbeddingProfile

a = EmbeddingProfile("openai", "text-embedding-3-small", "1", 1536)
b = EmbeddingProfile("openai", "text-embedding-3-small", "1", 1536, created="2026-01-01T00:00:00Z")
c = EmbeddingProfile("openai", "text-embedding-3-small", "1", 512)   # shortened dimension

a.compatible_with(b)   # True  — created is provenance, not identity
a.compatible_with(c)   # False — a different dimension is a different space
a.space_id()           # e.g. "sha256:9c1f4a2b7e0d5163"
```

Because `created` stays out of the digest, a collection saved yesterday still matches a freshly built provider you register today — reopen keeps working across time.

## How identity gates reopen and attach

The profile is the contract enforced when an embedder meets a collection:

{% stepper %}
{% step %}

#### Create

`create_collection(..., embedder=e)` records `e.profile` and requires `dim == e.profile.dimension`.
{% endstep %}

{% step %}

#### Save

`col.save()` persists `embedder_profile` (the `as_dict()` form) into `collection.json`.
{% endstep %}

{% step %}

#### Reopen

`open_collection(name)` auto-attaches an embedder from the provider registry by matching `model_id` and `space_id()`. A provider whose `space_id()` differs will not attach — register one that describes the same space.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
To reopen a collection built with a custom embedder, register a matching provider first: `ame.register_provider(my_embedder.profile.model_id, my_embedder)` before `open_collection`. The registration key must equal the stored profile's `model_id` (or its `space_id()`) — auto-attach looks up by `model_id`, then `space_id()`. An arbitrary label will not match.
{% endhint %}

## Inspect a stored profile

```python
from telys import Telys
from telys.embedding import AlgentaMultigramEmbedder

ame = Telys("./telys-store")
emb = AlgentaMultigramEmbedder()
ame.register_provider(emb.profile.model_id, emb)   # so open_collection can re-attach it
col = ame.open_collection("docs")
print(col.stats())                       # runtime stats + name/key_name/external_ids
print(col.embedder.profile.as_dict())    # the exact space the vectors live in
print(col.embedder.profile.space_id())
```

## See also

* [Embeddings & vector spaces](https://docs.telys.ai/understand-telys/embeddings-and-spaces.md) — the concept behind spaces.
* [Dimensions & space IDs](https://docs.telys.ai/embeddings/dimensions-and-space-id.md) — dimension rules and how to migrate a space.
* [CallableEmbedder (bring your own)](https://docs.telys.ai/embeddings/callable-byo.md) — build a profile for your own model.
* [Embedders API](https://docs.telys.ai/reference/embedders-api.md) — the full `telys.embedding` surface.
