Metadata-Version: 2.5
Name: telys
Version: 0.1.2
Summary: Telys — public, thin SDK for embedded on-device memory & retrieval (in-process, zero cloud roundtrips)
Project-URL: Homepage, https://telys.ai
Project-URL: Documentation, https://docs.telys.ai
Project-URL: Changelog, https://docs.telys.ai/changelog
Project-URL: Company, https://thyn.ai
Author-email: Thyn <eng@thyn.ai>
Maintainer-email: Thyn <eng@thyn.ai>
License: Apache-2.0
Keywords: embeddings,memory,on-device,rag,retrieval,sdk,telys,vector-search
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: cryptography>=42
Requires-Dist: numpy>=1.24
Provides-Extra: runtime
Requires-Dist: telys-runtime; extra == 'runtime'
Description-Content-Type: text/markdown

# telys

<!-- mcp-name: io.github.thyn-ai/telys -->

**Public, thin SDK** for **Telys** — embedded, on-device memory & retrieval. In-process, **zero cloud
roundtrips** at query time.

This package contains only the developer-facing surface: the `Telys`/`Collection` facades, query/filter
types, the `EmbeddingProvider` interface, the `Tuner`/`TuningPlan` interfaces, a runtime loader, and the
`telys` CLI. **It contains no engine implementation** — the engine is a separate, closed, signed, on-device
runtime fetched by `telys runtime install` (see [DECISIONS D-30](../../internal/DECISIONS.md)).

## Install

**As a CLI** (recommended — isolated env, on your PATH, not pinned to one Python):

```bash
pipx install telys
# …or the one-liner (installs via pipx):
curl -fsSL https://telys.ai/install.sh | sh

telys login          # sign in → free device license + signed runtime; fully offline thereafter
```

**As a library** (to `import telys` in your own project):

```bash
python -m venv .venv && . .venv/bin/activate
pip install telys
```

> Plain `pip install --user telys` works too, but pip may warn that its user-scripts dir isn't on your
> PATH (a macOS `--user` quirk) — `pipx` avoids that entirely. Runtime platforms: **macOS arm64, Linux
> x86_64/arm64** (Windows: run under **WSL2**).
```python
from telys import Telys
db = Telys("./memory")
col = db.create_collection("docs", dim=768, partition_by="tenant_id")   # dim is arbitrary — 384/768/1024/1536/3072…
col.add(vectors, ids=ids, metadata=metadata)          # bring your own vectors (embedding-agnostic, any dimension)
hits = col.search(qvec, where={"tenant_id": "acme"}, top_k=10, explain=True)
```

The **runtime is required for execution**; the **embedder is optional** — `col.add(vectors, …)` and
`col.add_texts(…)` both need the runtime, but only `*_texts` needs an embedder (bring your own via
`telys.embedding.CallableEmbedder`, or use the on-device bigram embedder).

For local development, install the runtime as a package instead of via the CLI:

```bash
pip install "telys[runtime]"   # or: pip install telys-runtime
```

## Documentation

Full documentation lives at **[docs.telys.ai](https://docs.telys.ai)**:

- [Quickstart: your first collection](https://docs.telys.ai/quickstart-first-collection)
- [Working with data](https://docs.telys.ai/guides/create-a-collection) — add, upsert, search, filter, snapshot
- [Embeddings](https://docs.telys.ai/embeddings/choosing-an-embedder) — built-in lexical + bring-your-own via `CallableEmbedder`
- [CLI reference](https://docs.telys.ai/cli/overview) · [MCP integration](https://docs.telys.ai/mcp/overview) · [Self-hosting](https://docs.telys.ai/serve/overview)
- [SDK API index](https://docs.telys.ai/reference/sdk-api-index)

## Links

- Website: [telys.ai](https://telys.ai) · Pricing: [telys.ai/pricing](https://telys.ai/pricing)
- Account & billing: [accounts.thyn.ai](https://accounts.thyn.ai)
- Docs: [docs.telys.ai](https://docs.telys.ai) · PyPI: [pypi.org/project/telys](https://pypi.org/project/telys)
