> 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/resources/design-principles.md).

# Design principles

Telys is a set of deliberate constraints as much as a feature list. These six principles explain *why* the SDK looks the way it does — why embedders are lexical by default, why the runtime is a separate signed download, why a collection binds exactly one embedding space. Read this when a design choice surprises you.

## On-device first

Every collection lives on your machine. `Telys(path)` makes a directory; a collection commits when `Collection.save()` writes `id_map.npy` and then `collection.json` last as the commit point. Ingestion, embedding, indexing, and search all run locally against that directory through the native runtime.

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

engine = Telys("./memory")                 # a local directory, nothing remote
emb = AlgentaMultigramEmbedder()           # lexical; needs the native kernel
col = engine.create_collection(
    "notes", dim=emb.profile.dimension, partition_by="scope", embedder=emb,
)
col.add_texts(["hello world"], ids=["n1"], metadata=[{"scope": "demo"}])
col.save()                                  # ./memory/notes/collection.json
```

No hosted vector database to provision, no per-query network hop. For a shared endpoint, run one yourself with `telys serve` and reach it over a socket with `RemoteTelys` — still your infrastructure, still your data. See [On-device & offline-first](/understand-telys/on-device-offline.md) and [Local vs remote execution](/understand-telys/local-vs-remote.md).

## Privacy by default

Because collections are local, your documents, vectors, and metadata do not leave the machine as a side effect of using Telys. `telys serve` makes **no outbound network connections** and, over TCP, refuses anonymous clients — it requires an access token compared in constant time. A Unix domain socket is created `0o600` and treated as trusted.

The only network traffic Telys initiates is control-plane and install: device-code sign-in against `accounts.thyn.ai`, license and key exchange against `api.telys.ai`, and the signed runtime download from `packages.telys.ai`. Your memory contents are never part of it. See [What leaves the machine](/security/what-leaves-the-machine.md) and [Data residency & privacy](/security/data-residency-privacy.md).

## Signed and verifiable

Trust is anchored in cryptography, not a promise. The runtime you download is verified offline before it is trusted, and licenses are verified offline too.

* The **release key** signs the runtime manifest; `verify_manifest(...)` checks an RS256/PKCS#1 v1.5 + SHA-256 signature, and `verify_artifact(path, expected_sha256)` checks each file with a constant-time compare.
* The **license key** signs your license; `verify_license(token, *, now, ...)` is strict and offline — it pins `alg` to RS256, rejects unknown `crit` headers, and checks issuer, audience, `ver == 2`, and expiry with grace.
* A **verified install is native-only and fail-closed**: `load_runtime()` will only activate a runtime whose signature checks out.

```bash
telys runtime verify        # re-checks the installed runtime's signatures offline
```

The public keys ship embedded in the wheel (`telys/_keys/telys_release_pub.pem`, `telys/_keys/telys_license_pub.pem`), and both can be overridden by env var for your own trust root. See [Three trust anchors](/security/trust-anchors.md) and [Verify the runtime signature](/security/runtime-signature-verification.md).

## A thin public SDK over a closed runtime

The `telys` package you install from PyPI is small and pure-Python. The engine is a separate, closed, signed native runtime loaded lazily via `ctypes`; it is not bundled in the wheel.

This seam is intentional:

* The **public surface stays stable and auditable**. `telys/__init__.py` exports exactly `Telys`, `Eq`, `scope_key`, `Tuner`, `TuningPlan`, `HeuristicTuner`, `__version__`, and `FORMAT_VERSION`. Embedders live in `telys.embedding`; remote, serve, runtime, and verify APIs live in their own submodules.
* The **engine can evolve independently** and ship signed updates without changing the API you code against.
* Some names resolve **lazily from the runtime** and raise `ImportError` without it installed — `HeuristicTuner` and `AlgentaPooledEmbedder` are runtime-only, not part of the runtime-free SDK.

{% hint style="info" %}
`import telys` is a no-op unless a verified runtime is installed, in which case it prepends that runtime's `pysite/` to `sys.path`. Any collection operation needs the runtime; the lexical embedders additionally need the native kernel.
{% endhint %}

See [The signed runtime & trust model](/understand-telys/signed-runtime-trust.md).

## A deterministic lexical option

Most vector databases assume a GPU and a downloaded model. Telys ships a deterministic **lexical** embedding family, so you can build useful memory with no model weights and no accelerator.

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

engine = Telys("./memory")
emb = AlgentaMultigramEmbedder()
col = engine.create_collection(
    "docs", dim=emb.profile.dimension, partition_by="scope",
    embedder=emb,                          # lexical multigram hash, dim from the kernel
)
```

`AlgentaBigramEmbedder` and `AlgentaMultigramEmbedder` hash character n-grams into an L2-normalized vector with inner-product distance. They are reproducible — the same text always yields the same vector — so results are stable across machines and easy to test. They need the native kernel, but no GPU and no model download. For semantic density instead, bring your own model through `CallableEmbedder`; the two coexist because a collection records its embedding space. See [Lexical vs dense embeddings](/understand-telys/lexical-vs-dense.md) and [Choosing an embedder](/embeddings/choosing-an-embedder.md).

## One embedding space per collection

A collection binds to exactly one embedding space, and Telys enforces that identity rather than trusting a model name. Every embedder exposes an `EmbeddingProfile`; the space is identified by `profile.space_id()` — a SHA-256-derived fingerprint of provider, model id, version, dimension, dtype, normalization, distance, pooling, tokenizer hash, and projection version.

```python
from telys.embedding import AlgentaMultigramEmbedder

profile = AlgentaMultigramEmbedder().profile
profile.space_id()                 # stable fingerprint of the space
profile.compatible_with(profile)   # True only when space_ids match
```

Mixing vectors from two spaces in one collection is meaningless, so Telys forbids it: `open_collection` re-attaches the embedder registered for the collection's space, and a dimension or space mismatch is rejected rather than silently returning garbage. That keeps results trustworthy across ingestion runs. See [Embeddings & vector spaces](/understand-telys/embeddings-and-spaces.md) and [Dimensions & space IDs](/embeddings/dimensions-and-space-id.md).

## Next steps

* [Roadmap](/resources/roadmap.md) — where these principles are taking Telys next.
* [Security overview](/security/overview.md) — how the trust model is implemented.
* [How Telys works](/understand-telys/how-telys-works.md) — the same ideas end to end.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.telys.ai/resources/design-principles.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.