> 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/understand-telys/how-telys-works.md).

# How it works

The architecture of Telys — a thin public Python SDK that orchestrates a signed, closed native runtime, entirely on your machine.

Telys is two parts with a clean seam: a thin, open Python SDK (the `telys` package you `pip install`) and a closed, signed native runtime the SDK loads on demand. You program against the SDK; the runtime does the vector math, indexing, and storage. Everything runs in your process, on your machine.

## Two parts, one process

The `telys` package is small. It defines the facade you import — `Telys`, the `Collection` it returns, the `Eq` filter, `scope_key`, `Tuner`/`TuningPlan`, and the embedders under `telys.embedding` — plus the CLI, the MCP server, and the verify API. It holds no vector math. Touch a collection and the SDK loads the runtime and delegates.

|                  | Public SDK (`telys`)                                             | Native runtime (closed)                                            |
| ---------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------ |
| Ships as         | PyPI wheel `telys` (pure Python, `py3-none-any`)                 | Signed platform bundle, installed separately                       |
| Loaded as        | Python package `telys`                                           | native libraries via `ctypes`                                      |
| Native libraries | none                                                             | `libty_runtime` (engine) + `libame_kernel` (vector + lexical math) |
| Role             | Orchestrates: API, external-id map, on-disk format, verification | Executes: storage, distance math, IVF index, lexical embedding     |
| Source           | Apache-2.0, open                                                 | Closed; verified offline against an embedded key                   |

{% hint style="info" %}
The runtime is an optional dependency. `pip install telys` gives you the SDK; install the engine with `telys runtime install` (or the `telys[runtime]` extra). Every collection operation needs it — see [Verify your install](https://docs.telys.ai/start-here/verify-install.md).
{% endhint %}

## What runs where

The SDK owns your program's view of the data — names, ids, metadata layout, persistence format, trust. The runtime owns the machine's view — bytes, vectors, indexes, math.

| Concern                                                 | Handled by       |
| ------------------------------------------------------- | ---------------- |
| `Telys` facade, `Collection` methods, `Eq`, `scope_key` | SDK (Python)     |
| External-id ↔ internal-id mapping (`id_map.npy`)        | SDK              |
| On-disk format & commit point (`collection.json`)       | SDK              |
| Signature & license verification (`telys.verify`)       | SDK              |
| Vector storage and memory slabs                         | Runtime          |
| Distance / similarity computation                       | Runtime kernel   |
| IVF index build and probing                             | Runtime          |
| Lexical embedding hashing (`Algenta*` embedders)        | Runtime kernel   |
| Bring-your-own embeddings (`CallableEmbedder`)          | Your Python `fn` |
| Heuristic tuning (`HeuristicTuner`)                     | Runtime          |

{% hint style="warning" %}
The `Algenta*` embedders (`AlgentaBigramEmbedder`, `AlgentaMultigramEmbedder`) compute vectors in the native kernel and raise `ImportError` without it. `AlgentaPooledEmbedder` and `HeuristicTuner` are runtime-only: they resolve lazily from the runtime and are absent in a runtime-free install. A `CallableEmbedder` runs your own function and needs no kernel.
{% endhint %}

## Loading the runtime

You never load the runtime yourself; the facade does it lazily the first time you touch a collection:

```python
from telys import Telys

db = Telys("./memory")                                               # runtime not loaded yet
col = db.create_collection("notes", dim=384, partition_by="scope")  # loads it now
```

The SDK calls `load_runtime()` internally. The `TELYS_RUNTIME` environment variable selects which runtime it loads:

{% tabs %}
{% tab title="native (default)" icon="microchip" %}
`TELYS_RUNTIME="native"` — or any verified install — loads the signed native runtime. Verified installs are native-only and **fail-closed**: if the bundle can't be verified, nothing loads. This is what you get after `telys runtime install`.
{% endtab %}

{% tab title="local" icon="flask" %}
`TELYS_RUNTIME="local"` selects a non-verified local build for development. Leave `TELYS_RUNTIME` unset for the default (auto → native/verified).
{% endtab %}
{% endtabs %}

If the runtime can't be imported, `load_runtime()` raises `RuntimeNotInstalled`. Probe first without raising:

```python
from telys.runtime import load_runtime, runtime_available

if not runtime_available():
    raise SystemExit("runtime not installed — run: telys runtime install")

rt = load_runtime()   # a RuntimeHandle backed by the closed engine
```

{% hint style="info" %}
Importing `telys` has one side effect: if a verified runtime is installed, it prepends that install's `pysite/` to `sys.path` so the runtime is importable (a silent no-op otherwise). Set `$TELYS_KERNEL` (then `$AME_KERNEL` as a legacy fallback) to point the kernel at a specific library.
{% endhint %}

## Signed bundles, verified offline

The runtime ships as a signed, per-platform bundle. `telys runtime install` downloads it once from `packages.telys.ai` and unpacks it under `$TELYS_HOME/runtime/<platform>/` (default `~/.telys`):

```
~/.telys/runtime/macos-arm64/
  libty_runtime.dylib      # the engine
  libame_kernel.dylib      # vector + lexical kernel
  telys_manifest.json      # what the bundle contains + SHA-256s
  telys_manifest.sig       # RS256 signature over the manifest
  license.jwt              # offline license token
  pysite/                  # importable runtime package
  installed.json
```

Trust is established offline with keys embedded in the wheel. `telys.verify` exposes the primitives: `verify_manifest(manifest_bytes, signature)` checks the RS256 signature against `release_public_key()`; `verify_artifact(path, expected_sha256)` does a constant-time per-file hash check; `verify_license(token, now=...)` validates the license strictly offline. Run the whole chain with `telys runtime verify`.

{% hint style="success" %}
There is no separate `telys verify` command and no phone-home. Verification is `telys runtime verify` plus the `telys.verify` API, fully offline. See [The signed runtime & trust model](https://docs.telys.ai/understand-telys/signed-runtime-trust.md).
{% endhint %}

## Data flow, end to end

Every path below stays on your machine. Telys reaches the network only for the initial `telys runtime install` download and `telys login`; collection operations never do.

```
your Python process
        │  create/add/search/save
        ▼
   telys SDK  (pure Python)                 -- facade · id map · on-disk format · verify
   Telys · Collection · Eq · embedders
        │  ctypes
        ▼
   signed native runtime                    -- loaded lazily, verified offline
   libty_runtime  ·  libame_kernel
        │  vectors · IVF · distance math
        ▼
   your disk:  ./memory/<name>/             -- collection.json · id_map.npy · vector slabs
```

A search, step by step: the SDK validates the query vector length against `dim`, translates any `Eq` filter and partition scope, and calls the runtime; the kernel scores candidates (walking the IVF index if one is built); the runtime returns internal ids; the SDK maps them back to your external ids and returns `{"ids": [...], "scores": [...]}`. Your text, vectors, and metadata stay in your process and are written only to the directory you named.

## Nothing leaves the machine

The engine is in-process and the trust check is offline, so Telys is offline-first by construction. No hosted index, no query proxy, no telemetry on the data path. The `Algenta*` embedders compute vectors locally in the kernel, so raw text is embedded on-device. With `CallableEmbedder`, whether your function calls out is your choice, not Telys's.

## Next steps

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>The signed runtime &#x26; trust model</strong></td><td>How the closed runtime is signed, licensed, and verified offline.</td><td><a href="https://docs.telys.ai/understand-telys/signed-runtime-trust.md">Signed runtime &amp; trust</a></td></tr><tr><td><strong>On-device &#x26; offline-first</strong></td><td>Exactly what runs locally and what (little) touches the network.</td><td><a href="https://docs.telys.ai/understand-telys/on-device-offline.md">On-device &amp; offline</a></td></tr><tr><td><strong>Verify your install</strong></td><td>Install the runtime and confirm the signature end to end.</td><td><a href="https://docs.telys.ai/start-here/verify-install.md">Verify install</a></td></tr><tr><td><strong>Runtime API</strong></td><td>Reference for load_runtime, RuntimeHandle, and TELYS_RUNTIME.</td><td><a href="https://docs.telys.ai/reference/runtime-api.md">Runtime</a></td></tr></tbody></table>
