Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

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 and Local vs remote execution.

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 and Data residency & privacy.

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.

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 and Verify the runtime signature.

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.

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.

See The signed runtime & trust model.

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.

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 and Choosing an embedder.

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.

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 and Dimensions & space IDs.

Next steps

Last updated

Was this helpful?