> 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

The constraints that shape Telys — on-device first, private by default, signed and verifiable, a thin SDK over a closed runtime, deterministic lexical, one space per collection.

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](https://docs.telys.ai/understand-telys/on-device-offline.md) and [Local vs remote execution](https://docs.telys.ai/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](https://docs.telys.ai/security/what-leaves-the-machine.md) and [Data residency & privacy](https://docs.telys.ai/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](https://docs.telys.ai/security/trust-anchors.md) and [Verify the runtime signature](https://docs.telys.ai/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](https://docs.telys.ai/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](https://docs.telys.ai/understand-telys/lexical-vs-dense.md) and [Choosing an embedder](https://docs.telys.ai/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](https://docs.telys.ai/understand-telys/embeddings-and-spaces.md) and [Dimensions & space IDs](https://docs.telys.ai/embeddings/dimensions-and-space-id.md).

## Next steps

* [Security overview](https://docs.telys.ai/security/overview.md) — how the trust model is implemented.
* [How Telys works](https://docs.telys.ai/understand-telys/how-telys-works.md) — the same ideas end to end.
