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

# Bigram embedder

Reference for AlgentaBigramEmbedder — the compact on-device lexical bigram-hash embedder in telys.embedding.

A compact, on-device **lexical** embedder. It hashes character bigrams of each input into a fixed-width `float32` vector, L2-normalized so inner-product search behaves like cosine similarity. It runs entirely inside the native kernel — no model download, no network — and is the smallest shipped space, which suits short strings such as keys, tags, and symbol names.

```python
from telys.embedding import AlgentaBigramEmbedder

emb = AlgentaBigramEmbedder(max_bytes=1 << 20)
```

## Signature

```python
AlgentaBigramEmbedder(*, max_bytes: int = 1 << 20)
```

Keyword-only. Takes no `dimension`, `model_id`, or `space_id` argument — space identity comes from the profile, and the dimension is read from the native kernel at construction time.

| Parameter   | Type  | Default           | Meaning                                                                                           |
| ----------- | ----- | ----------------- | ------------------------------------------------------------------------------------------------- |
| `max_bytes` | `int` | `1 << 20` (1 MiB) | Upper bound on the UTF-8 bytes read per input string. Longer inputs are truncated before hashing. |

## Requirements

{% hint style="warning" %}
`AlgentaBigramEmbedder` requires the **native kernel**. Constructing it without the kernel raises `ImportError`. Install and confirm the runtime with `telys runtime install` and `telys runtime verify`. Override the kernel library path with `$TELYS_KERNEL` (highest priority), then `$AME_KERNEL`.
{% endhint %}

## Interface

`AlgentaBigramEmbedder` satisfies the `EmbeddingProvider` protocol:

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

```python
emb = AlgentaBigramEmbedder()

emb.profile.dimension            # e.g. 64 — read from the native kernel
vecs = emb.embed_documents(["hello world", "telys memory"])
vecs.shape                       # (2, D)   float32, L2-normalized rows
```

## Profile

The embedder exposes a frozen [`EmbeddingProfile`](https://docs.telys.ai/embeddings/embedding-profile.md) with fixed identity fields:

| Field           | Value                                                   |
| --------------- | ------------------------------------------------------- |
| `provider`      | `"algenta"`                                             |
| `model_id`      | `"bigram"`                                              |
| `dimension`     | read from the native kernel (hint: `64`)                |
| `dtype`         | `"float32"`                                             |
| `normalization` | `"l2"`                                                  |
| `distance`      | `"ip"` (inner product; with L2 rows this equals cosine) |
| `pooling`       | `"bigram-hash"`                                         |

`model_version` (`"0.1.15"`) and `tokenizer_hash` (`"utf8-bytes"`) are fixed constants; `projection_version` and `created` default to empty strings. Only `dimension` is read from the kernel. Inspect the exact values for your install:

```python
emb.profile.as_dict()
emb.profile.space_id()           # "sha256:<16 hex>" identity of the space
```

Two embedders address the same collection only when their `space_id()` values match — see [`compatible_with`](https://docs.telys.ai/embeddings/embedding-profile.md).

## Using it with a collection

Create the collection with the embedder's own dimension, never a hard-coded kernel hint:

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

engine = Telys("./memory")
emb = AlgentaBigramEmbedder()

col = engine.create_collection(
    "tags",
    dim=emb.profile.dimension,
    partition_by="scope",
    embedder=emb,
)
col.add_texts(
    ["invoice paid", "invoice overdue"],
    ids=["t1", "t2"],
    metadata=[{"scope": "billing"}, {"scope": "billing"}],
)
col.save()

hits = col.search_text("overdue invoice", top_k=5)
```

## See also

* [AlgentaMultigramEmbedder](https://docs.telys.ai/embeddings/multigram.md) — the richer lexical space and MCP default.
* [Choosing an embedder](https://docs.telys.ai/embeddings/choosing-an-embedder.md) — the decision matrix.
* [EmbeddingProfile & space compatibility](https://docs.telys.ai/embeddings/embedding-profile.md) — how space identity is computed.
* [Embedders API](https://docs.telys.ai/reference/embedders-api.md) — the full embedding surface.
* [Lexical vs dense embeddings](https://docs.telys.ai/understand-telys/lexical-vs-dense.md) — when lexical recall is the right tool.
