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.jsonNo 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, andverify_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 pinsalgto RS256, rejects unknowncritheaders, 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__.pyexports exactlyTelys,Eq,scope_key,Tuner,TuningPlan,HeuristicTuner,__version__, andFORMAT_VERSION. Embedders live intelys.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
ImportErrorwithout it installed —HeuristicTunerandAlgentaPooledEmbedderare runtime-only, not part of the runtime-free SDK.
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
Security overview — how the trust model is implemented.
How Telys works — the same ideas end to end.
Last updated
Was this helpful?