> 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/reference/sdk-api-index.md). # SDK API index Every symbol the `telys` package exports. The SDK is thin and pure-Python; the signed native runtime executes every collection operation and loads lazily on first use. Version **0.1.0b2**, `FORMAT_VERSION = 1`, `requires-python >=3.10`. ```python from telys import Telys, Eq, scope_key, Tuner, TuningPlan, __version__, FORMAT_VERSION ``` ## Top-level exports Import these directly from `telys`. Embedders, the remote client, the server, the runtime loader, and the verify API live in submodules (second table). | Name | Kind | Import | Notes | | ---------------- | ------------ | ---------------------------------- | ------------------------------------------------------------------------------------- | | `Telys` | class | `from telys import Telys` | The engine facade. | | `Eq` | class | `from telys import Eq` | The only filter. See [Filters (Eq)](/reference/filters.md). | | `scope_key` | function | `from telys import scope_key` | Compose one partition key. | | `Tuner` | class | `from telys import Tuner` | Base tuner. See [Tuner & TuningPlan API](/reference/tuner-api.md). | | `TuningPlan` | dataclass | `from telys import TuningPlan` | Result of `Collection.tune()`. | | `HeuristicTuner` | class (lazy) | `from telys import HeuristicTuner` | In `__all__`, but resolves from the signed runtime — raises `ImportError` without it. | | `__version__` | str | `from telys import __version__` | Installed distribution version. | | `FORMAT_VERSION` | int | `from telys import FORMAT_VERSION` | On-disk format contract (`1`). | Not top-level (import from a submodule): | Symbol | Module | Detail page | | ----------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | --------------------------------------------------------------- | | `EmbeddingProvider`, `EmbeddingProfile`, `CallableEmbedder`, `AlgentaBigramEmbedder`, `AlgentaMultigramEmbedder`, `AlgentaPooledEmbedder` | `telys.embedding` | [Embedders API](/reference/embedders-api.md) | | `connect`, `RemoteTelys` | `telys.client` | [Remote API](/reference/remote-api.md) | | `serve` | `telys.server` | [Remote API](/reference/remote-api.md) | | `load_runtime`, `runtime_available`, `RuntimeHandle`, `RuntimeNotInstalled` | `telys.runtime` | [Runtime API](/reference/runtime-api.md) | | `verify_manifest`, `verify_artifact`, `verify_license`, … | `telys.verify` | [Exceptions & error codes](/reference/exceptions-and-errors.md) | {% hint style="info" %} `import telys` has one side effect: if a **verified** runtime is installed, it prepends that runtime's `pysite/` to `sys.path`. Otherwise it is a silent no-op. {% endhint %} ## The Telys facade ### Constructor ```python Telys(path: str, embedding_providers: dict | None = None, runtime=None) ``` Creates `path` as the engine-root directory; the runtime loads lazily on first use. Pass `embedding_providers` as a `{key: provider}` map to pre-register embedders, or add them later with `register_provider`. ### Methods | Signature | Returns | Description | | ------------------------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------- | | `register_provider(key, provider)` | `None` | Register an embedder under a key so `open_collection` can re-attach it. | | `create_collection(name, dim, partition_by, embedder=None, dtype="f32", filter_columns=(), tuner=None)` | `Collection` | Build and cache a collection. Does **not** write disk until `col.save()`. | | `open_collection(name, embedder=None)` | `Collection` | Open a saved collection; auto-attaches an embedder from the registry by `model_id`/`space_id`. | | `collections()` | `list[str]` | Sorted names of directories containing a `collection.json` (i.e. already saved). | | `__getitem__(name)` | `Collection` | `ame[name]` — return the cached collection or open it. | | `scope_key(*parts)` | `str` | Join `str(parts)` with the `\x1f` separator into one partition key. | `__version__` and `FORMAT_VERSION` are module-level (`from telys import …`), not attributes of the `Telys` class. ```python from telys import Telys from telys.embedding import AlgentaMultigramEmbedder ame = Telys("./memory") emb = AlgentaMultigramEmbedder() col = ame.create_collection( "notes", dim=emb.profile.dimension, partition_by="scope", embedder=emb, filter_columns=("tenant_id",), ) col.add_texts(["hello world"], ids=["n1"], metadata=[{"scope": "u:42", "tenant_id": "acme"}]) col.save() ``` {% hint style="warning" %} `partition_by` is **not composite**. If you pass a list or tuple, only element `[0]` becomes the physical partition key. To key by several fields, compose one string with [`scope_key`](#scope-key). {% endhint %} ## Collection Returned by `create_collection` and `open_collection`. Every method requires the runtime; the `*_texts` variants also require an attached embedder (otherwise `RuntimeError`). ### Ingest All ingest methods return the list of external ids they wrote. | Signature | Returns | Description | | ------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------ | | `add_texts(texts, ids, metadata)` | `list` | Embed and insert **new** rows only. `KeyError` if an id already exists; `RuntimeError` if no embedder. | | `add(vectors, ids, metadata)` | `list` | Insert raw `(n, dim)` float32 vectors, **new** rows only. | | `upsert_texts(texts, ids, metadata)` | `list` | Embed and insert-or-replace. Needs an embedder. | | `upsert(vectors, ids, metadata)` | `list` | Insert-or-replace raw vectors. | | `update_texts(texts, ids, metadata)` | `list` | Replace **existing** rows only. Needs an embedder. | ### Query | Signature | Returns | Description | | ------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------ | | `search(vector, top_k=10, where=None, explain=False, target_recall=None, with_metadata=False)` | `dict` | Nearest neighbours by vector. Validates `len(vector) == dim`. | | `search_text(text, top_k=10, where=None, explain=False, target_recall=None, with_metadata=False)` | `dict` | Embed `text`, then search. Needs an embedder. | | `ids(where=None)` | `list` | Live external ids, optionally scoped by a single-key dict or `Eq`. | Both `search` variants return `{"ids": [...], "scores": [...]}`, plus `"explain"` when `explain=True` and `"metadata"` when `with_metadata=True`. `where` takes a single-key dict or an [`Eq`](/reference/filters.md) instance. ```python from telys import Eq hits = col.search_text( "release checklist", top_k=5, where=Eq("tenant_id", "acme"), with_metadata=True, ) for rid, score in zip(hits["ids"], hits["scores"]): print(rid, round(score, 4)) ``` ### Tuning | Signature | Returns | Description | | ---------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------ | | `tune(workload=None, objectives=None, dry_run=None)` | `TuningPlan` | Produce a plan. `dry_run=True` never applies; `False` always applies; `None` applies only when `tuner.mode == "suggest_then_apply"`. | | `apply_tuning(plan)` | `stats` | Set `default_target_recall` and exact-crossover, build/use per-partition IVF, set `nprobe`. | ### Maintenance | Signature | Description | | ----------------------------------------------- | ----------------------------------------------- | | `delete(ids)` | Delete only the ids that are present. | | `compact()` | Reclaim space from deleted and replaced rows. | | `build_ivf(min_rows=20000, target_recall=0.98)` | Build the IVF index (skipped below `min_rows`). | | `snapshot()` | Take an on-disk snapshot. | ### Persistence & introspection | Signature | Returns | Description | | --------- | ------- | ------------------------------------------------------------------------------------------------ | | `stats()` | `dict` | Runtime stats plus `name`, `key_name`, `external_ids`. | | `save()` | `dir` | Commit to disk. Writes the `id_map.npy` sidecar, then `collection.json` last (the commit point). | `save()` persists: `name`, `dim`, `dtype`, `key_name`, `filter_columns`, `id_map_sidecar`, `telys_version`, `default_target_recall`, `applied_tuner`, and `embedder_profile`. ### Container protocol | Expression | Result | | ------------ | ---------------------------------- | | `len(col)` | Number of external ids. | | `ext in col` | Whether external id `ext` is live. | ## scope\_key ```python scope_key(*parts) -> str ``` Joins each `str(part)` with the `\x1f` (unit separator) into one partition key. Available top-level (`from telys import scope_key`) and as a method (`ame.scope_key(...)`). Use it because `partition_by` keys on one physical column. ```python from telys import scope_key key = scope_key("acme", "user", 42) # "acme\x1fuser\x1f42" col.add_texts(["…"], ids=["m1"], metadata=[{"scope": key}]) ``` ## Version & format constants | Constant | Value | Meaning | | ---------------------- | ----------- | ------------------------------------------------------------------------- | | `telys.__version__` | `"0.1.0b2"` | Installed distribution version (`"0.0.0+source"` from a source checkout). | | `telys.FORMAT_VERSION` | `1` | On-disk format contract for saved collections. | ## See also
Filters (Eq)The single filter used by search, search_text, and ids./pages/Gecj6sBExuNdfnjm5iOB
Embedders APIEverything under telys.embedding./pages/XX1QfZrdFzsjJ9XKpN80
CollectionsThe concept behind create_collection and save./pages/ZBd4ROKi3CD4dcp51PD4
QuickstartBuild and query your first collection./pages/3P7KO0CUnD1NfTy6KAyk
--- # 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/reference/sdk-api-index.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.