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

TypeScript SDK

Reference for the TypeScript SDK (npm `telys-ai`) — the encapsulated in-process runtime, the Telys/Collection surface, Eq filters, persistence shared with Python, and the runtime ops.

Telys ships a TypeScript SDK alongside the Python one: npm install telys-ai (Node >= 22). It is the same engine with the same guarantees — embedded, on-device, zero cloud roundtrips at query time — loaded in-process inside your Node process. There is no sidecar process and nothing to manage.

npm install telys-ai
import { Telys, Eq } from "telys-ai";

const db = await Telys.open("./memory");
const col = db.createCollection("docs", {
  dim: 768,
  partitionBy: "tenant_id",
  filterColumns: ["lang"],
});

col.add(vectors, ids, metadata);                    // bring your own vectors (embedding-agnostic)
const hits = col.search(queryVec, {
  topK: 10,
  where: new Eq("tenant_id", "acme"),
  explain: true,
});

How the runtime gets there (encapsulated)

The closed Mojo runtime (libty_runtime) is loaded through a frozen C-ABI inside your process:

  1. A runtime already installed by the Python CLI (telys runtime install) is reused from $TELYS_HOME/runtime/<platform>/ (default ~/.telys) — both SDKs share one verified install.

  2. Otherwise, when a token is available (TELYS_TOKEN / TELYS_API_KEY), the SDK fetches the signed bundle itself from the download host and verifies it OFFLINE — RS256 manifest signature over the exact shipped bytes, SHA-256 artifact hashes, and the strict ver:2 license policy (alg pinned to RS256, no crit, issuer/audience/expiry/grace, products.telys with a tier + features). This is the same trust core as the Python SDK, ported to node:crypto.

Installing the runtime is the only networked step. Queries never touch the network.

The surface

Area
API

Engine

await Telys.open(path) · Telys.openSync(path) · createCollection · openCollection · collections() · scopeKey(...parts)

Collection

add (new ids only) · upsert · update (strict — unknown ids raise) · search · ids(where?) · fetch(ids) · delete · compact · snapshot · stats · save

Filters

new Eq(column, value) on the partition key or a declared filter column

Runtime ops

ensureRuntime() · installFromHost() · installFromFile() · verifyInstalled() · resolveRuntimeLib()

Trust core

verifyManifest() · verifyLicense() · verifyArtifact()

Semantics match the Python SDK exactly: add raises on existing ids, upsert adds-or-replaces (a new visible version, never a duplicate row), update replaces existing rows only and raises for unknown or deleted ids, deletes are tombstones reclaimed by compact.

Shared persistence

Collections persist in the same on-disk format as the Python SDK (ty_base.npy + ty_native.json + collection.json), so a store is portable across languages in either direction — a collection written by Python opens in TypeScript and vice versa.

Scope today

Vectors in, vectors out: filtered dense search over bring-your-own embeddings. Text embedders (the kernel-backed bigram/multigram) and the lexical code index are Python-side today and come to this SDK later — from TypeScript, embed with any model and pass the vectors.

Platforms: macOS arm64 and Linux x86_64 runtime targets (the signed-bundle P0 set). See Supported platforms.

Next

Task
What it covers
Guide

Install Telys

SDK + runtime install and verification.

First collection

Create, add, and search your first collection.

Filters (Eq)

The equality filter semantics shared by both SDKs.

Python SDK API index

The full Python surface this SDK mirrors.

Last updated

Was this helpful?