telys 0.1.0b1__tar.gz

telys-0.1.0b1/.gitignore

@@ -0,0 +1,64 @@
+# Mojo build output
+mojo_build/
+*.o
+*.so
+*.dylib
+*.a
+
+# Pixi / conda env
+.pixi/
+mojo_env/.pixi/
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+.venv-bench/
+bench/.venv-bench/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+
+# Secrets — NEVER commit (local Algenta key, env, certs, signing PRIVATE keys)
+*.key
+.algenta_key
+**/.algenta_key
+.env
+.env.*
+*.pem
+dist-keys/        # signing PRIVATE keys (issuer custody) — NEVER committed
+# Exception: the embedded Telys PUBLIC verification keys are public by design and MUST ship in the SDK wheel.
+!packages/telys-sdk/telys/_keys/*_pub.pem
+
+# Python build/wheel artifacts (incl. internal full-engine wheel — NEVER commit a bundled-kernel wheel)
+dist/
+dist-public/
+dist-internal/
+build/
+*.whl
+*.tar.gz
+
+# Node / TS SDK
+node_modules/
+packages/memengine-ts/dist/
+
+# Benchmark artifacts (raw results are committed selectively; large datasets are not)
+bench/datasets/*
+!bench/datasets/.gitkeep
+bench/results/raw/
+*.parquet
+*.faiss
+*.npy
+*.ame
+*.vidx
+*.sidx
+*.tidx
+
+# OS / editor
+.DS_Store
+*.swp
+.idea/
+.vscode/
+
+# local agent/session artifacts
+.claude/

telys-0.1.0b1/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: telys
+Version: 0.1.0b1
+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://telys.ai
+Project-URL: Repository, https://github.com/thyn-ai/telys
+Project-URL: Issues, https://github.com/thyn-ai/telys/issues
+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 :: 4 - Beta
+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
+
+**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](../../docs/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")
+col.add(vectors, ids=ids, metadata=metadata)          # bring your own vectors (embedding-agnostic)
+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
+```

telys-0.1.0b1/README.md

@@ -0,0 +1,49 @@
+# 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](../../docs/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")
+col.add(vectors, ids=ids, metadata=metadata)          # bring your own vectors (embedding-agnostic)
+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
+```

telys-0.1.0b1/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "telys"
+version = "0.1.0b1"
+description = "Telys — public, thin SDK for embedded on-device memory & retrieval (in-process, zero cloud roundtrips)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+# Telys is a product of Thyn (thyn.ai), the parent company.
+authors = [{ name = "Thyn", email = "eng@thyn.ai" }]
+maintainers = [{ name = "Thyn", email = "eng@thyn.ai" }]
+keywords = ["memory", "retrieval", "vector-search", "embeddings", "rag", "on-device", "sdk", "telys"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+# Thin SDK: facades, types, provider/tuner interfaces, runtime loader, CLI. The engine is a separate, closed,
+# on-device runtime fetched by `telys runtime install` (D-30) — NOT a dependency of this package.
+dependencies = [
+  "numpy>=1.24",          # the facade marshals float32 arrays to/from the runtime
+  "cryptography>=42",     # offline verification of the signed runtime manifest + RS256 license (D-31 #3/#5)
+]
+
+[project.optional-dependencies]
+# Local development: pull the runtime as an editable/local package instead of `telys runtime install`.
+runtime = ["telys-runtime"]
+
+[project.scripts]
+telys = "telys.cli:main"
+
+[project.urls]
+Homepage = "https://telys.ai"
+Documentation = "https://telys.ai"
+Repository = "https://github.com/thyn-ai/telys"
+Issues = "https://github.com/thyn-ai/telys/issues"
+Company = "https://thyn.ai"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["telys"]   # PUBLIC SDK only — no engine modules (enforced by scripts/check_public_wheel.py)
+# Force-include the embedded PUBLIC verification keys: they match the global `*.pem` gitignore (so the wheel
+# would otherwise drop them), but they are public trust anchors that MUST ship. ONLY *_pub.pem — never private.
+artifacts = ["telys/_keys/*_pub.pem"]

telys-0.1.0b1/telys/__init__.py

@@ -0,0 +1,55 @@
+"""Telys — embedded, on-device memory & retrieval SDK (public, thin).
+
+    from telys import Telys, Eq, scope_key
+    eng = Telys(path, embedding_providers={...})
+    eng.create_collection(name, dim, partition_by, embedder=, dtype=, filter_columns=)
+    eng.open_collection(name, embedder=) · eng.collections()
+    col.add_texts / add / upsert_texts / upsert
+    col.search_text / search (where=, top_k=, explain=, target_recall=, with_metadata=)
+    col.ids(where=)   # live external ids in a scope (or off-key column)
+    col.delete / update_texts / compact / build_ivf / save / stats / snapshot
+
+This is the public SDK: facades, types, and provider/tuner interfaces only — no engine implementation. The
+engine is a separate, closed, on-device runtime loaded on first use (`telys runtime install`; see D-30).
+`telys turns filtered vector search into a contiguous memory operation.`
+"""
+def _activate_installed_runtime() -> None:
+    """Zero-config runtime: after a VERIFIED `telys runtime install`, add the installed runtime's Python package
+    dir (pysite, from the signed bundle's slim telys-runtime-native wheel) to sys.path — so the native engine and
+    kernel-backed embedders import with NO env vars. Only ever prepends a telys-managed, verified path; a silent
+    no-op when nothing is installed (dev/editable installs are unaffected)."""
+    try:
+        import json
+        import os
+        import sys
+
+        import telys.paths as _paths
+
+        record = os.path.join(_paths.install_dir(), _paths.INSTALL_RECORD_NAME)
+        with open(record, encoding="utf-8") as fh:
+            if not json.load(fh).get("verified"):
+                return
+        site = _paths.installed_pysite()
+        if site and site not in sys.path:
+            sys.path.insert(0, site)
+    except Exception:  # noqa: BLE001 — never let runtime activation break `import telys`
+        return
+
+
+_activate_installed_runtime()
+
+from telys.engine import AME, Telys, FORMAT_VERSION, __version__, scope_key  # noqa: F401,E402
+from telys.filters import Eq  # noqa: F401,E402
+from telys.tuning import Tuner, TuningPlan  # noqa: F401,E402  (HeuristicTuner is lazy — see __getattr__)
+
+__all__ = ["Telys", "AME", "Eq", "scope_key", "Tuner", "HeuristicTuner", "TuningPlan",
+           "__version__", "FORMAT_VERSION"]
+
+
+def __getattr__(name):
+    # HeuristicTuner is a closed-runtime implementation; expose it lazily so `import telys` never loads the
+    # engine, while `from telys import HeuristicTuner` keeps working when the runtime is installed.
+    if name == "HeuristicTuner":
+        from telys.tuning import HeuristicTuner
+        return HeuristicTuner
+    raise AttributeError(f"module 'telys' has no attribute {name!r}")

telys-0.1.0b1/telys/_keys/README.md

@@ -0,0 +1,36 @@
+# Embedded Telys verification keys (PUBLIC only)
+
+These are the **public** halves of the Telys signing keys, embedded as the default offline trust anchors
+(D-31 #3/#5). `telys.verify` loads them when no `TELYS_RELEASE_PUBKEY[_FILE]` / `TELYS_LICENSE_PUBKEY[_FILE]`
+override is set, so `telys runtime install --file …` verifies with **zero configuration**.
+
+| File | Verifies | Signed by (private key, NOT in repo) |
+|---|---|---|
+| `telys_release_pub.pem` | the runtime **manifest** (artifact SHA-256s) | **Telys release key** (Telys-owned, local) |
+| `telys_license_pub.pem` | the offline **RS256 license** token (ver:2 entitlement) | the **SHARED platform license key** (decision-engine `license-signer` Worker — the SOLE license key for Telys/Algenta/Codna) |
+
+**Two different authorities (post platform-convergence):**
+- **RELEASE** key is Telys-owned and signs runtime manifests (`scripts/telys_issuer.py bundle`). Production-real here.
+- **LICENSE** key is NOT Telys-owned — Telys *rides the shared signer*. Real licenses are issued by the
+  decision-engine control plane (`api.codna.ai` → the Cloudflare `license-signer` Worker), which alone holds
+  the license private key across all products. `telys_license_pub.pem` must therefore be the **decision-engine
+  license public key** (export from its JWKS `GET /.well-known/jwks.json` or the operator). `telys.verify`
+  checks the engine's ver:2 token (iss `https://license.algenta.ai`, aud `telys-runtime`) against it, offline.
+
+**Override:** `TELYS_LICENSE_PUBKEY[_FILE]`, `TELYS_RELEASE_PUBKEY[_FILE]`, and `TELYS_LICENSE_ISSUER` /
+`TELYS_LICENSE_AUDIENCE` env vars override the embedded defaults (rotation / self-hosted / air-gapped).
+
+> ⚠️ **`telys_license_pub.pem` is a BOOTSTRAP platform keypair** (generated locally for dev/staging continuity
+> so the offline-license path is exercisable end-to-end before the control plane is live). Its **private half is
+> at `dist-keys/platform_license_priv.pem`** (gitignored, issuer custody — NEVER committed). To make real
+> licenses verify, do ONE of:
+> 1. **Adopt this bootstrap pair (dev/staging):** load `dist-keys/platform_license_priv.pem` into the
+>    decision-engine `license-signer` (its `license_signing_private_key` / Cloudflare Worker secret) so the
+>    signer mints with the private half of the key embedded here.
+> 2. **Production:** generate a **KMS-born** RS256 key in the control plane, then replace `telys_license_pub.pem`
+>    with that signer's public half (export from its JWKS `GET /.well-known/jwks.json`) and delete the bootstrap
+>    private from `dist-keys/`.
+>
+> Either way, **one signer authority** holds the license private key across Telys/Algenta/Codna — never mint
+> Telys licenses with a separate Telys-local key (the parallel-signer mistake the convergence removed). The
+> RELEASE key remains Telys-owned and production-real.

telys-0.1.0b1/telys/_supervisor.py

@@ -0,0 +1,61 @@
+"""Supervisor for the Telys self-host server — run it as a child process and relaunch on abnormal exit.
+
+The engine runs in-process, so an (already-rare, after the FFI guards in P0/P1) uncatchable native crash takes
+the daemon down. The supervisor restarts it from the last on-disk snapshot (collections persist and are lazily
+reopened), bounding downtime; periodic save (`telys serve --save-interval`) bounds the data-loss window. A
+clean exit (code 0, e.g. a SIGTERM-drained shutdown) is NOT restarted. A crash loop is capped so the
+supervisor gives up instead of spinning forever.
+"""
+from __future__ import annotations
+
+import logging
+import os
+import signal
+import subprocess
+import sys
+import time
+
+_log = logging.getLogger("telys.supervisor")
+
+
+def supervise(child_argv: list[str], *, env: dict | None = None,
+              max_restarts: int = 20, window_s: float = 60.0, backoff_s: float = 1.0) -> int:
+    """Run `python -m telys.cli <child_argv>` as a child, relaunching on abnormal exit.
+
+    Returns the child's last exit code (0 on a clean drain). Restarts are capped at ``max_restarts`` within
+    ``window_s`` to avoid a tight crash loop. SIGTERM/SIGINT are forwarded to the child for a graceful drain.
+    """
+    cmd = [sys.executable, "-m", "telys.cli", *child_argv]
+    child_env = dict(os.environ if env is None else env)
+    proc: subprocess.Popen | None = None
+    restarts: list[float] = []
+
+    def _forward(signum, _frame):
+        if proc is not None and proc.poll() is None:
+            proc.send_signal(signum)
+    for sig in (signal.SIGTERM, signal.SIGINT):
+        try:
+            signal.signal(sig, _forward)
+        except (ValueError, OSError):
+            pass
+
+    while True:
+        _log.info("supervisor: starting child: telys %s", " ".join(child_argv))
+        proc = subprocess.Popen(cmd, env=child_env)
+        try:
+            rc = proc.wait()
+        except KeyboardInterrupt:
+            proc.send_signal(signal.SIGINT)
+            return proc.wait()
+        if rc == 0:
+            _log.info("supervisor: child exited cleanly (0) — done")
+            return 0
+        now = time.monotonic()
+        restarts = [t for t in restarts if now - t < window_s]
+        restarts.append(now)
+        if len(restarts) > max_restarts:
+            _log.error("supervisor: child crash-looping (%d restarts in %.0fs) — giving up (rc=%d)",
+                       len(restarts), window_s, rc)
+            return rc
+        _log.warning("supervisor: child died (rc=%d) — restarting from last snapshot in %.1fs", rc, backoff_s)
+        time.sleep(backoff_s)

telys-0.1.0b1/telys/_wire.py

@@ -0,0 +1,38 @@
+"""Tiny length-prefixed JSON wire protocol shared by the Telys self-host server + client.
+
+Frame = 4-byte big-endian unsigned length, then that many bytes of UTF-8 JSON. A request is
+``{"op": str, "collection": str|null, "args": {...}}``; a reply is ``{"ok": true, "result": ...}`` or
+``{"ok": false, "error": str}``. Vectors travel as plain JSON number lists (MVP; a binary frame is a later
+optimization). The 4-byte length is bounded to fail closed on a hostile/oversized frame (anti-OOM).
+"""
+from __future__ import annotations
+
+import json
+import socket
+import struct
+
+MAX_FRAME = 256 * 1024 * 1024  # 256 MiB hard ceiling per message (anti-OOM on a bad/hostile length prefix)
+
+
+def send_msg(sock: socket.socket, obj) -> None:
+    data = json.dumps(obj).encode("utf-8")
+    if len(data) > MAX_FRAME:
+        raise ValueError(f"frame too large: {len(data)} > {MAX_FRAME}")
+    sock.sendall(struct.pack(">I", len(data)) + data)
+
+
+def _recv_exact(sock: socket.socket, n: int) -> bytes:
+    buf = bytearray()
+    while len(buf) < n:
+        chunk = sock.recv(n - len(buf))
+        if not chunk:
+            raise ConnectionError("peer closed the connection mid-frame")
+        buf += chunk
+    return bytes(buf)
+
+
+def recv_msg(sock: socket.socket):
+    (n,) = struct.unpack(">I", _recv_exact(sock, 4))
+    if n > MAX_FRAME:
+        raise ValueError(f"declared frame too large: {n} > {MAX_FRAME}")
+    return json.loads(_recv_exact(sock, n).decode("utf-8"))