> 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/working-with-data/add-text-vs-vectors.md).

# Text vs vectors

Decide between the text ingest/search path (needs an embedder) and the raw-vector path (bring your own precomputed float32 vectors) in Telys.

Every Telys collection stores vectors. The only choice is who computes them: Telys, from your text through an attached embedder, or you, precomputed from any model. Both paths write to the same collection and query it the same way.

| Use the text path                              | Use the vector path                               |
| ---------------------------------------------- | ------------------------------------------------- |
| `add_texts` / `upsert_texts` / `search_text`   | `add` / `upsert` / `search`                       |
| Collection has an embedder attached            | Collection needs no embedder                      |
| You pass `str` documents and queries           | You pass `float32` arrays of shape `(n, dim)`     |
| Telys embeds with the collection's embedder    | You embed with OpenAI, BGE, or any model you like |
| Simplest for on-device lexical/semantic memory | Best when you already run a model elsewhere       |

{% hint style="warning" %}
The `*_texts` and `search_text` methods need an embedder; on a collection created with `embedder=None` they raise `RuntimeError`. Raw `add` / `upsert` / `search` never embed and work on any collection.
{% endhint %}

## The text path

Attach an embedder at creation and pass strings. You never touch a vector.

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

telys = Telys("telys-store")
embedder = AlgentaMultigramEmbedder()

notes = telys.create_collection(
    "notes",
    dim=embedder.profile.dimension,
    partition_by="scope",
    embedder=embedder,
)

notes.add_texts(
    ["kubernetes rollout stuck on readiness probe"],
    ids=["note-1"],
    metadata=[{"scope": "ops"}],
)
notes.save()
```

## The vector path (bring your own)

If you already produce embeddings, create the collection with `dim` set to your model's output width and add raw vectors. No embedder is required.

```python
import numpy as np
from telys import Telys

DIM = 1536                       # your model's output dimension

telys = Telys("telys-store")
docs = telys.create_collection("docs", dim=DIM, partition_by="scope")

texts = ["invoice overdue reminder", "welcome email copy"]
vectors = np.asarray(my_model.encode(texts), dtype="float32")   # your model
assert vectors.shape == (len(texts), DIM)                       # (n, dim) float32

docs.add(
    vectors,
    ids=["doc-1", "doc-2"],
    metadata=[{"scope": "billing"}, {"scope": "marketing"}],
)
docs.save()
```

Two rules keep the vector path safe:

* **Shape.** Vectors must be `(n, dim)` with `n == len(ids) == len(metadata)`.
* **Dtype.** Vectors must be `float32`; call `.astype("float32")` if your model returns `float64`.

{% hint style="info" %}
Vector width is fixed at creation. A `dim=1536` collection accepts only 1536-wide vectors, and `search` raises on a wrong-length query. To switch embedding models, create a new collection. See [Dimensions & space IDs](https://docs.telys.ai/embeddings/dimensions-and-space-id.md).
{% endhint %}

## Expected result

Both paths return the external ids they wrote and grow the collection identically:

```python
>>> notes.add_texts(["disk pressure eviction"], ids=["note-2"], metadata=[{"scope": "ops"}])
['note-2']
>>> docs.add(vectors, ids=["doc-3", "doc-4"], metadata=[{"scope": "billing"}, {"scope": "billing"}])
['doc-3', 'doc-4']
```

At query time the two collections are indistinguishable: `notes` answers `search_text`, `docs` answers `search`, both over the same kind of vectors.

## Next steps

* [Search by text](https://docs.telys.ai/working-with-data/search-by-text.md) — query the text path with a string.
* [Search by vector](https://docs.telys.ai/working-with-data/search-by-vector.md) — query the vector path with a precomputed query.
* [CallableEmbedder (bring your own)](https://docs.telys.ai/embeddings/callable-byo.md) — wrap any model as an embedder to use `search_text` with BYO vectors.
