> 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 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](/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//` (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](/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// -- 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
The signed runtime & trust modelHow the closed runtime is signed, licensed, and verified offline./pages/VmHkD0an28Ww8yTFnwpS
On-device & offline-firstExactly what runs locally and what (little) touches the network./pages/8qFzJkRN9mhP0vZqJwZv
Verify your installInstall the runtime and confirm the signature end to end./pages/h4z9ZPSmvEnW3qsGotXt
Runtime APIReference for load_runtime, RuntimeHandle, and TELYS_RUNTIME./pages/UWvIgdnHL2WmqDcv9fMO
--- # 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/understand-telys/how-telys-works.md?ask=&goal= ``` `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.