telys 0.1.0a1__py3-none-any.whl

telys/__init__.py

@@ -0,0 +1,30 @@
+"""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.`
+"""
+from telys.engine import AME, Telys, FORMAT_VERSION, __version__, scope_key  # noqa: F401
+from telys.filters import Eq  # noqa: F401
+from telys.tuning import Tuner, TuningPlan  # noqa: F401  (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/_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/_keys/telys_license_pub.pem

@@ -0,0 +1,9 @@
+-----BEGIN PUBLIC KEY-----
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0J1XV/U6NyCYqdwUCES1
+TRXHH+ZimEwWPi7CeDXsOT1bNo57i+MAvM1ho2hUmIjVJsF8f8snEPHWycg29e72
+BYmxtHRgcT9ErswIqzuEv7g8MzL1e7WqJMtevxGAuD2GtzrncVh51XOhc9VbIlcA
+AifNamfk3uLcSm+HRDJxlRw+PCcDCQDEjyHC9/akbNDQSK82csR8DO+zleYMs5pB
+pLrJc++Lamqq0IknT6dHeF2/VwGmMkZ+lRQxSXMvWdTcLw4w9eopeRq8/Yj3mwqA
+BhG+bAlqjUzl6rq87WRszOiZjtDlYnMln8V4oDvJw/iy58VNlW6xvlj42lVXpay7
+tQIDAQAB
+-----END PUBLIC KEY-----

telys/_keys/telys_release_pub.pem

@@ -0,0 +1,9 @@
+-----BEGIN PUBLIC KEY-----
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzqOtDOYcDh0F3ImMt0kS
+sgefxYH11ULzOyAM8M5jlGidlpSreh/449fhyECJa998Qm7ouwPJWn8iF5cYvChY
+P5/aqlay8C3r7Q1jNkOrL3qnIYVVsORpNDHrQZCMwSBONUD8mkf+Qc219Jk8qjIj
+nCbo8SWiiG/Wqj2nuCS6Hq6xGKTw4GpSQ19PXEDBhFFk9rMVbw5TrdhbaAZczG2w
+pfvVnDaBu0iIBB6w+uzEkJQ5BN4Q+6gJb7JcBASENi1aXoklXm4nJMSF9FdHyAK/
+GZad3y1wO7htt1fHf+kgbfXpFwj/65ViTJ5qehqR+eTMAoSOYPyL1dQja56wdiOY
+iwIDAQAB
+-----END PUBLIC KEY-----

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/_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"))

telys/cli.py

@@ -0,0 +1,266 @@
+"""Telys CLI — `telys ...` (scaffold).
+
+Commands:
+  telys login                 authenticate for gated runtime downloads (Phase 1: real auth)
+  telys runtime status        show whether the on-device runtime is installed + where it resolves from
+  telys runtime install --file <bundle> --license <license.jwt>
+                              verify a signed runtime bundle + offline RS256 license LOCALLY and install it
+                              (offline-file install; hosted packages.telys.ai download lands later — D-31 #4)
+  telys runtime verify        re-verify the installed runtime offline (manifest signature + artifact SHA-256 + license)
+  telys runtime update        update to the latest runtime on the configured channel (Phase 1)
+  telys version               print SDK version + format version
+
+The SDK is thin: `runtime install` is the ONLY step that may touch the network (and offline-file install does
+not even do that). Verification + query execution are always local/offline (D-30/D-31): the runtime + license
+verify themselves against Telys public keys with no network, no OS-native signing.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+
+def _runtime_status() -> int:
+    from telys.runtime import runtime_available, load_runtime
+    from telys import __version__, FORMAT_VERSION
+    if not runtime_available():
+        print("runtime: NOT INSTALLED")
+        print("  install it:  telys runtime install   (or, for local dev:  pip install telys-runtime)")
+        return 1
+    # Ask the runtime where its kernel resolves from — the SDK never imports engine internals (D-30).
+    info = load_runtime().kernel_info()
+    ok = bool(info.get("found"))
+    if ok:
+        print(f"runtime: READY  (telys {__version__}, format v{FORMAT_VERSION}, impl={info.get('runtime')})")
+        print(f"  kernel: FOUND  [{info.get('source')}]  {info.get('path')}")
+        return 0
+    print(f"runtime: PACKAGE PRESENT, KERNEL NOT INSTALLED  (telys {__version__}, impl={info.get('runtime')})")
+    print(f"  kernel: MISSING  [{info.get('source')}]  {info.get('path')}")
+    print("  install it:  telys runtime install --file <bundle> --license <license.jwt>")
+    return 1
+
+
+def _not_implemented(what: str) -> int:
+    print(f"`telys {what}` is not implemented yet (Phase 1: gated download + signature verification).")
+    print("For local development, install the runtime package directly:  pip install telys-runtime")
+    return 2
+
+
+def _runtime_install(args) -> int:
+    # D-31 #4: --file = offline-file install (no network). Otherwise download the signed bundle from the host
+    # (the ONLY networked step) and verify it LOCALLY — same RS256/SHA-256 gate either way.
+    from telys.installer import install_from_file, install_from_host, InstallError
+    from telys.verify import VerificationError
+    try:
+        if getattr(args, "file", None):
+            rec = install_from_file(args.file, args.license)
+        else:
+            from telys.paths import packages_url
+            print(f"downloading runtime '{args.version}' from {packages_url()} …")
+            rec = install_from_host(version=args.version, license_path=getattr(args, "license", None))
+    except (InstallError, VerificationError) as e:
+        print(f"install FAILED: {e}")
+        return 1
+    lic = rec.get("license", {})
+    print(f"runtime INSTALLED + VERIFIED  [{rec['platform']}]  ({len(rec['artifacts'])} artifacts)")
+    print(f"  license: tier={lic.get('tier')} features={lic.get('features')} exp={lic.get('exp')}")
+    if rec.get("source"):
+        print(f"  source: {rec['source']}")
+    print("  query execution is now fully local/offline — no network.")
+    return 0
+
+
+def _login(args) -> int:
+    # One command: OAuth device-code -> create API key -> register device -> platform-signed license ->
+    # install + verify the signed runtime -> cache. After this, Telys runs fully offline. --token skips the
+    # browser step (headless/CI); --no-install provisions without downloading the runtime.
+    from telys.login import login, LoginError
+    try:
+        info = login(
+            plan=getattr(args, "plan", "telys_developer"),
+            access_token=getattr(args, "token", None) or os.environ.get("TELYS_TOKEN"),
+            install=not getattr(args, "no_install", False),
+            open_browser=not getattr(args, "no_browser", False),
+        )
+    except LoginError as e:
+        print(f"login FAILED: {e}")
+        return 1
+    runtime = "installed" if info["installed"] else "not installed (run `telys runtime install`)"
+    print(f"  api key: {info['api_key_prefix']}   device: {info['device_id'][:12]}…   "
+          f"tier: {info['tier']}   runtime: {runtime}")
+    return 0
+
+
+def _mem(args) -> int:
+    import json as _json
+
+    from telys.mcp import TelysMemory
+
+    m = TelysMemory(getattr(args, "path", None))
+    try:
+        if args.memcmd == "list":
+            out = m.list_collections()
+        elif args.memcmd == "create":
+            out = m.create_collection(args.name, partition_by=args.partition_by)
+        elif args.memcmd == "add":
+            out = m.add(args.collection, texts=args.text, ids=args.id or None)
+        elif args.memcmd == "search":
+            out = m.search(args.collection, args.query, top_k=args.top_k)
+        elif args.memcmd == "stats":
+            out = m.stats(args.collection)
+        else:
+            print("usage: telys mem {add,search,create,list,stats} …")
+            return 2
+    except Exception as e:  # noqa: BLE001
+        print(f"error: {e}")
+        return 1
+    print(_json.dumps(out, indent=2))
+    return 0
+
+
+def _runtime_verify() -> int:
+    from telys.installer import verify_installed, InstallError
+    from telys.verify import VerificationError
+    try:
+        rep = verify_installed()
+    except (InstallError, VerificationError) as e:
+        print(f"runtime verify FAILED: {e}")
+        return 1
+    print(f"runtime VERIFIED  [{rep['platform']}]  {rep['dir']}")
+    print(f"  artifacts: {', '.join(rep['artifacts_verified'])}")
+    print(f"  license: tier={rep.get('tier')} exp={rep.get('exp')}")
+    return 0
+
+
+def _serve(args) -> int:
+    import os
+    license_token = args.license or os.environ.get("TELYS_LICENSE")
+    access_token = args.access_token or os.environ.get("TELYS_ACCESS_TOKEN")
+    if not args.socket and not (args.host and args.port):
+        print("error: pass --socket <path> (Unix) or --host <h> --port <p> (TCP)")
+        return 2
+
+    if args.supervise:
+        # Re-run ourselves as a supervised child WITHOUT --supervise. Secrets go via env (inherited by the
+        # child), never on the child's argv, so they don't leak into the process list.
+        from telys._supervisor import supervise
+        if license_token:
+            os.environ["TELYS_LICENSE"] = license_token
+        if access_token:
+            os.environ["TELYS_ACCESS_TOKEN"] = access_token
+        child = ["serve", "--path", args.path]
+        if args.socket:
+            child += ["--socket", args.socket]
+        if args.host:
+            child += ["--host", args.host]
+        if args.port:
+            child += ["--port", str(args.port)]
+        if args.require_license:
+            child += ["--require-license"]
+        if args.save_interval:
+            child += ["--save-interval", str(args.save_interval)]
+        print(f"telys serve (supervised): {args.path}")
+        return supervise(child)
+
+    from telys.server import serve
+    where = args.socket if args.socket else f"{args.host}:{args.port}"
+    print(f"telys serve: shared memory at {args.path} on {where}"
+          + ("  [license-gated]" if args.require_license else "")
+          + ("  [token-auth]" if access_token else "")
+          + (f"  [save every {args.save_interval}s]" if args.save_interval else ""))
+    try:
+        serve(args.path, args.socket, host=args.host, port=args.port,
+              license_token=license_token, require_license=args.require_license,
+              access_token=access_token, save_interval_s=args.save_interval)
+    except KeyboardInterrupt:
+        print("\nshutting down")
+    except OSError as e:
+        print(f"error: cannot bind {where} ({e}); is another telys server already running there?")
+        return 2
+    except ValueError as e:
+        print(f"error: {e}")
+        return 2
+    return 0
+
+
+def main(argv=None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    p = argparse.ArgumentParser(prog="telys", description="Telys — on-device memory & retrieval SDK")
+    sub = p.add_subparsers(dest="cmd")
+    login = sub.add_parser("login", help="one command: OAuth -> API key -> device -> license -> runtime install")
+    login.add_argument("--token", help="use an existing OAuth token (headless/CI); else browser device-code login")
+    login.add_argument("--plan", default="telys_developer", help="tier to request (default: telys_developer, free)")
+    login.add_argument("--no-install", action="store_true", help="provision only; skip downloading the runtime")
+    login.add_argument("--no-browser", action="store_true", help="don't auto-open the browser (print the code)")
+    sub.add_parser("version", help="print SDK + format version")
+    rt = sub.add_parser("runtime", help="manage the on-device runtime").add_subparsers(dest="rtcmd")
+    rt.add_parser("status", help="is the runtime installed?")
+    rt_install = rt.add_parser("install", help="install + verify the signed runtime (online host, or --file offline)")
+    rt_install.add_argument("--file", help="path to a signed runtime bundle (.bundle/.tar.gz) for offline install")
+    rt_install.add_argument("--license", help="path to the signed offline license (license.jwt)")
+    rt_install.add_argument("--version", default="latest", help="runtime version to fetch from the host (default: latest)")
+    rt.add_parser("verify", help="re-verify the installed runtime's signature/integrity + license (offline)")
+    rt.add_parser("update", help="update to the latest runtime on the channel")
+    srv = sub.add_parser("serve", help="self-host a shared Telys memory (Team tier) over a Unix socket or TCP")
+    srv.add_argument("--path", required=True, help="engine data directory (the shared memory store)")
+    srv.add_argument("--socket", help="Unix-domain socket to listen on (trusted host; no token needed)")
+    srv.add_argument("--host", help="TCP bind host (e.g. 0.0.0.0 for a container); requires --access-token")
+    srv.add_argument("--port", type=int, help="TCP bind port (with --host)")
+    srv.add_argument("--access-token", help="shared bearer token for TCP clients; or set TELYS_ACCESS_TOKEN")
+    srv.add_argument("--license", help="Telys license token (Team tier); or set TELYS_LICENSE")
+    srv.add_argument("--require-license", action="store_true",
+                     help="refuse to serve without a valid Telys (products.telys) license")
+    srv.add_argument("--save-interval", type=float, default=0.0, metavar="SECONDS",
+                     help="background periodic save every N seconds (bounds data loss on a crash; 0=off)")
+    srv.add_argument("--supervise", action="store_true",
+                     help="run under a supervisor that auto-restarts the server from the last snapshot on crash")
+
+    mcp = sub.add_parser("mcp", help="run the Telys MCP stdio server (plugin for Claude/Cursor/OpenAI; no port)")
+    mcp.add_argument("--path", help="memory directory (default: ~/.telys/memory or $TELYS_MEMORY_PATH)")
+
+    mem = sub.add_parser("mem", help="use Telys memory from the terminal (advanced)").add_subparsers(dest="memcmd")
+    for _name in ("add", "search", "create", "list", "stats"):
+        mp = mem.add_parser(_name)
+        mp.add_argument("--path", help="memory directory (default: ~/.telys/memory)")
+        if _name in ("add", "search", "stats"):
+            mp.add_argument("-c", "--collection", required=True)
+        if _name == "create":
+            mp.add_argument("--name", required=True)
+            mp.add_argument("--partition-by", default="scope")
+        if _name == "add":
+            mp.add_argument("-t", "--text", action="append", required=True, help="document text (repeatable)")
+            mp.add_argument("--id", action="append", help="document id (repeatable; matches --text order)")
+        if _name == "search":
+            mp.add_argument("-q", "--query", required=True)
+            mp.add_argument("--top-k", type=int, default=5)
+
+    args = p.parse_args(argv)
+    if args.cmd == "serve":
+        return _serve(args)
+    if args.cmd == "version":
+        from telys import __version__, FORMAT_VERSION
+        print(f"telys {__version__} (format v{FORMAT_VERSION})")
+        return 0
+    if args.cmd == "login":
+        return _login(args)
+    if args.cmd == "mcp":
+        from telys.mcp import MCPServer, TelysMemory
+        return MCPServer(TelysMemory(getattr(args, "path", None))).serve()
+    if args.cmd == "mem":
+        return _mem(args)
+    if args.cmd == "runtime":
+        if args.rtcmd == "status":
+            return _runtime_status()
+        if args.rtcmd == "install":
+            return _runtime_install(args)
+        if args.rtcmd == "verify":
+            return _runtime_verify()
+        if args.rtcmd == "update":
+            return _not_implemented("runtime update")
+    p.print_help()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

telys/client.py

@@ -0,0 +1,173 @@
+"""Telys self-host client — the thin remote half of the Team deployment.
+
+``connect()`` returns a ``RemoteTelys`` whose facade mirrors the in-process ``Telys``/``Collection`` API, so
+application code is unchanged: it just talks to a shared self-hosted engine over a Unix socket instead of an
+in-process dylib. Every client of the same server shares one memory.
+
+    from telys.client import connect
+    eng = connect("/tmp/telys.sock")
+    col = eng.create_collection("mem", dim=768, partition_by="tenant_id", filter_columns=["tenant_id"])
+    col.add(vectors, ids=ids, metadata=metadata)
+    hits = col.search(qvec, where={"tenant_id": "acme"}, top_k=10)
+
+The client holds no engine code and needs no numpy — vectors may be numpy arrays or plain lists.
+"""
+from __future__ import annotations
+
+import socket
+import threading
+
+from telys._wire import recv_msg, send_msg
+
+
+class RemoteError(RuntimeError):
+    """An error raised by the server while handling a request (carries the server-side type + message)."""
+
+
+def _listify(v):
+    """Deep-coerce to plain JSON-able values, without importing numpy: numpy arrays AND scalars (np.float32,
+    np.int64, …) both expose .tolist(); dict values (e.g. metadata pulled from a dataframe) are coerced too,
+    since json.dumps rejects numpy scalars."""
+    if hasattr(v, "tolist"):          # numpy ndarray OR scalar -> python list/number
+        return v.tolist()
+    if isinstance(v, dict):
+        return {k: _listify(x) for k, x in v.items()}
+    if isinstance(v, (list, tuple)):
+        return [_listify(x) for x in v]
+    return v
+
+
+def _parse_addr(address: str):
+    """Resolve an address to ('unix', path) or ('tcp', (host, port)). Accepts:
+    'unix:///run/telys.sock', '/abs/path.sock', './rel.sock', 'tcp://host:port', 'host:port'."""
+    if address.startswith("unix://"):
+        return "unix", address[len("unix://"):]
+    if address.startswith("tcp://"):
+        address = address[len("tcp://"):]
+    elif "/" in address or address.startswith("."):     # looks like a filesystem path
+        return "unix", address
+    if ":" in address:
+        host, _, port = address.rpartition(":")
+        return "tcp", (host or "127.0.0.1", int(port))
+    return "unix", address
+
+
+class RemoteTelys:
+    """Client handle to a self-hosted Telys server (one shared engine). ``address`` is a Unix socket path or
+    a 'host:port' / 'tcp://host:port'; ``token`` is the shared access token for a TCP server."""
+
+    def __init__(self, address: str, token: str | None = None, *, connect_timeout: float = 30.0) -> None:
+        self._addr = address
+        kind, target = _parse_addr(address)
+        fam = socket.AF_UNIX if kind == "unix" else socket.AF_INET
+        self._sock = socket.socket(fam, socket.SOCK_STREAM)
+        # Bound connect + handshake so a dead/hostile server can't hang the client forever; then go blocking
+        # for data ops (which may legitimately take a while).
+        self._sock.settimeout(connect_timeout)
+        self._sock.connect(target)
+        self._lock = threading.Lock()  # one in-flight request/response per connection
+        if token is not None:          # auth handshake (TCP); must precede any other op
+            try:
+                with self._lock:
+                    send_msg(self._sock, {"op": "auth", "collection": None, "args": {"token": token}})
+                    reply = recv_msg(self._sock)
+            except (OSError, socket.timeout) as exc:
+                self._sock.close()
+                raise RemoteError(f"auth handshake failed: {exc}") from exc
+            if not reply.get("ok"):
+                self._sock.close()
+                raise RemoteError(reply.get("error", "authentication failed"))
+        self._sock.settimeout(None)
+
+    def _call(self, op: str, collection: str | None = None, **args):
+        with self._lock:
+            send_msg(self._sock, {"op": op, "collection": collection, "args": args})
+            reply = recv_msg(self._sock)
+        if not reply.get("ok"):
+            raise RemoteError(reply.get("error", "unknown server error"))
+        return reply.get("result")
+
+    # ── engine surface ───────────────────────────────────────────────────────────────────────────────
+    def ping(self) -> bool:
+        return bool(self._call("ping").get("pong"))
+
+    def create_collection(self, name: str, dim: int, partition_by, *, filter_columns=(),
+                          dtype: str = "f32", embedder: str | None = None) -> "RemoteCollection":
+        self._call("create_collection", name, dim=dim, partition_by=partition_by,
+                   filter_columns=list(filter_columns), dtype=dtype, embedder=embedder)
+        return RemoteCollection(self, name)
+
+    def open_collection(self, name: str) -> "RemoteCollection":
+        self._call("open_collection", name)
+        return RemoteCollection(self, name)
+
+    def collections(self) -> list:
+        return self._call("collections")
+
+    def __getitem__(self, name: str) -> "RemoteCollection":
+        return RemoteCollection(self, name)
+
+    def close(self) -> None:
+        try:
+            self._sock.close()
+        except OSError:
+            pass
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()
+
+
+class RemoteCollection:
+    """Mirrors telys.engine.Collection — forwards each op to the shared server."""
+
+    def __init__(self, engine: RemoteTelys, name: str) -> None:
+        self._engine = engine
+        self.name = name
+
+    def add(self, vectors, ids, metadata):
+        return self._engine._call("add", self.name, vectors=_listify(vectors),
+                                  ids=_listify(ids), metadata=_listify(metadata))
+
+    def upsert(self, vectors, ids, metadata):
+        return self._engine._call("upsert", self.name, vectors=_listify(vectors),
+                                  ids=_listify(ids), metadata=_listify(metadata))
+
+    def add_texts(self, texts, ids, metadata):
+        return self._engine._call("add_texts", self.name, texts=list(texts),
+                                  ids=_listify(ids), metadata=_listify(metadata))
+
+    def upsert_texts(self, texts, ids, metadata):
+        return self._engine._call("upsert_texts", self.name, texts=list(texts),
+                                  ids=_listify(ids), metadata=_listify(metadata))
+
+    def search(self, vector, top_k: int = 10, where=None, explain: bool = False, with_metadata: bool = False):
+        return self._engine._call("search", self.name, vector=_listify(vector), top_k=top_k,
+                                  where=_listify(where), explain=explain, with_metadata=with_metadata)
+
+    def search_text(self, text, top_k: int = 10, where=None, explain: bool = False, with_metadata: bool = False):
+        return self._engine._call("search_text", self.name, text=text, top_k=top_k,
+                                  where=_listify(where), explain=explain, with_metadata=with_metadata)
+
+    def ids(self, where=None) -> list:
+        return self._engine._call("ids", self.name, where=_listify(where))
+
+    def delete(self, ids):
+        return self._engine._call("delete", self.name, ids=_listify(ids))
+
+    def compact(self):
+        return self._engine._call("compact", self.name)
+
+    def save(self):
+        return self._engine._call("save", self.name)
+
+    def stats(self) -> dict:
+        return self._engine._call("stats", self.name)
+
+
+def connect(address: str, token: str | None = None) -> RemoteTelys:
+    """Connect to a self-hosted Telys server. ``address`` is a Unix-socket path or 'host:port'/'tcp://host:port';
+    pass ``token`` for a TCP server that requires a shared access token."""
+    return RemoteTelys(address, token)