kymoscope 0.1.0__tar.gz

kymoscope-0.1.0/.gitignore

@@ -0,0 +1,85 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+# Local env overrides — never commit
+.env.local
+.env.*.local
+.env.production
+
+# Brainstorming visual-companion scratch (mockups, server state)
+.superpowers/
+
+# Downloaded Kymoscope sender config — contains an API key, never commit
+kymoscope-stream.json
+**/kymoscope-stream.json
+# Native plugin config — holds the stream password
+**/kymoscope-plugin.json
+# Pre-rename (Prism) names of the same local files
+**/prism-stream.json
+**/prism-plugin.json
+**/prism-lmu-sender.zip
+**/.prism_live_state.json
+
+# Python caches
+__pycache__/
+*.pyc
+.pytest_cache/
+
+# Built client sender bundle (artifact of examples/build_sender_bundle.py)
+kymoscope-lmu-sender.zip
+**/kymoscope-lmu-sender.zip
+
+# PyInstaller scratch
+examples/build/
+examples/*.spec
+
+# Sender resume state (stream id+salt per name; local, non-secret)
+.kymoscope_live_state.json
+**/.kymoscope_live_state.json
+
+# Playwright MCP scratch (screenshots / snapshots from agent runs)
+.playwright-mcp/
+
+# Large local benchmark dataset — keep out of git (use LFS or external storage)
+public/big-telemetry.csv
+.vercel
+.env.local
+
+# Supabase CLI local state (linked project, CLI version cache)
+supabase/.temp/
+
+# QA run output (screenshots, sender configs with the run's throwaway keys) and reports
+tests/e2e-prod/out/
+tests/e2e-prod/reports/
+
+# Import bench files (generated on demand: tests/fixtures/import/gen_bench.py)
+tests/fixtures/import/bench/
+
+# Local state of wrangler dev and the Supabase CLI
+.wrangler/
+supabase/.branches/
+
+# Python packaging
+.venv/

kymoscope-0.1.0/LICENSE.md

@@ -0,0 +1,69 @@
+# Kymoscope SDK License Agreement
+
+Copyright © 2026 Kymoscope. All rights reserved.
+
+This is proprietary software. It is licensed, not sold. By installing, copying
+or using the Kymoscope SDK (the "Software") you agree to these terms. If you do not
+agree, do not use the Software.
+
+> Template notice for the owner: this agreement was drafted as a starting point.
+> Have it reviewed by a lawyer for your jurisdiction and fill in the legal
+> entity, governing law and contact details before relying on it.
+
+## 1. Licenses
+
+**1.1 Evaluation.** You may use the Software without a license key to evaluate
+it and to develop your integration. Unlicensed use displays a "Powered by
+Kymoscope" attribution in the workspace.
+
+**1.2 Production.** Using the Software in a product, service or internal tool
+made available to anyone other than your own developers ("Production Use")
+requires a valid license key issued by Kymoscope for each domain the Software is
+served from, under an order or agreement with Kymoscope.
+
+**1.3 Scope.** A license key is personal to the licensee named in it, for the
+domains listed in it and until its expiry date.
+
+## 2. Restrictions
+
+You must not, and must not allow others to:
+
+1. make the Software available in Production Use without a valid license key
+   for that domain;
+2. remove, hide, obscure or alter the attribution shown by unlicensed use, or
+   the copyright notices in the Software;
+3. circumvent, disable or modify the license check, or create, alter or share
+   license keys;
+4. copy, sell, sublicense, distribute or publish the Software, or offer it as a
+   standalone component library or SDK, except as embedded in your own product
+   as permitted above;
+5. reverse engineer, decompile or disassemble the Software, except to the
+   extent applicable law expressly permits it despite this restriction;
+6. use the Software to build a competing embeddable analytics or charting
+   product.
+
+## 3. Kymoscope services
+
+Live-stream relaying, watch tickets and other hosted services are provided
+under your Kymoscope account terms and may be rate limited or suspended for abuse.
+
+## 4. Ownership
+
+Kymoscope and its licensors own all rights in the Software. No rights are granted
+except those expressly stated here.
+
+## 5. Termination
+
+This license ends automatically if you breach it. On termination you must stop
+using the Software and delete all copies.
+
+## 6. No warranty and limitation of liability
+
+The Software is provided "as is", without warranties of any kind. To the
+maximum extent permitted by law, Kymoscope is not liable for any indirect,
+incidental or consequential damages, and its total liability is limited to the
+fees you paid for the Software in the twelve months before the claim.
+
+## 7. Contact
+
+For license keys and commercial terms, contact Kymoscope.

kymoscope-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.5
+Name: kymoscope
+Version: 0.1.0
+Summary: Stream live, end-to-end encrypted telemetry to Kymoscope
+Project-URL: Homepage, https://kymoscope.com
+Project-URL: Documentation, https://kymoscope.com/docs/live
+License: # Kymoscope SDK License Agreement
+        
+        Copyright © 2026 Kymoscope. All rights reserved.
+        
+        This is proprietary software. It is licensed, not sold. By installing, copying
+        or using the Kymoscope SDK (the "Software") you agree to these terms. If you do not
+        agree, do not use the Software.
+        
+        > Template notice for the owner: this agreement was drafted as a starting point.
+        > Have it reviewed by a lawyer for your jurisdiction and fill in the legal
+        > entity, governing law and contact details before relying on it.
+        
+        ## 1. Licenses
+        
+        **1.1 Evaluation.** You may use the Software without a license key to evaluate
+        it and to develop your integration. Unlicensed use displays a "Powered by
+        Kymoscope" attribution in the workspace.
+        
+        **1.2 Production.** Using the Software in a product, service or internal tool
+        made available to anyone other than your own developers ("Production Use")
+        requires a valid license key issued by Kymoscope for each domain the Software is
+        served from, under an order or agreement with Kymoscope.
+        
+        **1.3 Scope.** A license key is personal to the licensee named in it, for the
+        domains listed in it and until its expiry date.
+        
+        ## 2. Restrictions
+        
+        You must not, and must not allow others to:
+        
+        1. make the Software available in Production Use without a valid license key
+           for that domain;
+        2. remove, hide, obscure or alter the attribution shown by unlicensed use, or
+           the copyright notices in the Software;
+        3. circumvent, disable or modify the license check, or create, alter or share
+           license keys;
+        4. copy, sell, sublicense, distribute or publish the Software, or offer it as a
+           standalone component library or SDK, except as embedded in your own product
+           as permitted above;
+        5. reverse engineer, decompile or disassemble the Software, except to the
+           extent applicable law expressly permits it despite this restriction;
+        6. use the Software to build a competing embeddable analytics or charting
+           product.
+        
+        ## 3. Kymoscope services
+        
+        Live-stream relaying, watch tickets and other hosted services are provided
+        under your Kymoscope account terms and may be rate limited or suspended for abuse.
+        
+        ## 4. Ownership
+        
+        Kymoscope and its licensors own all rights in the Software. No rights are granted
+        except those expressly stated here.
+        
+        ## 5. Termination
+        
+        This license ends automatically if you breach it. On termination you must stop
+        using the Software and delete all copies.
+        
+        ## 6. No warranty and limitation of liability
+        
+        The Software is provided "as is", without warranties of any kind. To the
+        maximum extent permitted by law, Kymoscope is not liable for any indirect,
+        incidental or consequential damages, and its total liability is limited to the
+        fees you paid for the Software in the twelve months before the claim.
+        
+        ## 7. Contact
+        
+        For license keys and commercial terms, contact Kymoscope.
+License-File: LICENSE.md
+Requires-Python: >=3.9
+Requires-Dist: cryptography>=41
+Requires-Dist: requests>=2.28
+Requires-Dist: websocket-client>=1.6
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Provides-Extra: viewer
+Requires-Dist: msgpack>=1.0; extra == 'viewer'
+Description-Content-Type: text/markdown
+
+# kymoscope
+
+Stream live, end-to-end encrypted telemetry to [Kymoscope](https://kymoscope.com) from Python.
+
+Requires Python 3.9 or later.
+
+```bash
+pip install kymoscope
+```
+
+## Example
+
+```python
+import math, time
+from kymoscope import LiveStream
+
+API_KEY = "kymoscope_..."   # Account -> API & real-time streaming, or a project's API key
+start = time.time()
+
+# state_path keeps this sender's identity, so a restart needs no new approval
+with LiveStream(API_KEY, "Rig A", state_path="kymoscope-state.json") as stream:
+    print("stream id:", stream.stream_id)
+    while True:
+        t = time.time() - start
+        stream.send([{"t": t, "signals": [
+            {"name": "speed", "unit": "m/s", "value": 50 + 10 * math.sin(t)},
+        ]}])
+        time.sleep(1 / 60)
+```
+
+In an end-to-end encrypted project, the first run waits until a project member's browser
+approves the sender; after that it publishes on its own.
+
+The headless viewer (`kymoscope.viewer`) needs msgpack: `pip install 'kymoscope[viewer]'`.
+
+Full documentation: https://kymoscope.com/docs/live

kymoscope-0.1.0/README.md

@@ -0,0 +1,36 @@
+# kymoscope
+
+Stream live, end-to-end encrypted telemetry to [Kymoscope](https://kymoscope.com) from Python.
+
+Requires Python 3.9 or later.
+
+```bash
+pip install kymoscope
+```
+
+## Example
+
+```python
+import math, time
+from kymoscope import LiveStream
+
+API_KEY = "kymoscope_..."   # Account -> API & real-time streaming, or a project's API key
+start = time.time()
+
+# state_path keeps this sender's identity, so a restart needs no new approval
+with LiveStream(API_KEY, "Rig A", state_path="kymoscope-state.json") as stream:
+    print("stream id:", stream.stream_id)
+    while True:
+        t = time.time() - start
+        stream.send([{"t": t, "signals": [
+            {"name": "speed", "unit": "m/s", "value": 50 + 10 * math.sin(t)},
+        ]}])
+        time.sleep(1 / 60)
+```
+
+In an end-to-end encrypted project, the first run waits until a project member's browser
+approves the sender; after that it publishes on its own.
+
+The headless viewer (`kymoscope.viewer`) needs msgpack: `pip install 'kymoscope[viewer]'`.
+
+Full documentation: https://kymoscope.com/docs/live

kymoscope-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kymoscope"
+version = "0.1.0"
+description = "Stream live, end-to-end encrypted telemetry to Kymoscope"
+readme = "README.md"
+license = { file = "LICENSE.md" }
+requires-python = ">=3.9"
+dependencies = ["requests>=2.28", "cryptography>=41", "websocket-client>=1.6"]
+
+[project.optional-dependencies]
+viewer = ["msgpack>=1.0"]
+test = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://kymoscope.com"
+Documentation = "https://kymoscope.com/docs/live"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kymoscope"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/kymoscope", "tests", "README.md", "LICENSE.md"]

kymoscope-0.1.0/src/kymoscope/__init__.py

@@ -0,0 +1,18 @@
+"""Shared Kymoscope Live Streams sender client.
+
+A small client for streaming end-to-end-encrypted signals into Kymoscope: load a
+downloaded config, derive an AES key from a password, register a stream, and
+publish frames over a WebSocket to the Kymoscope live relay.
+"""
+
+from .config import KymoscopeConfig, ConfigError, load_config
+from .crypto import derive_key, generate_salt, make_key_check, KEY_CHECK_PLAINTEXT
+from .client import KymoscopeClient, RegistrationError
+from .stream import LiveStream, ANON_KEY, SUPABASE_URL
+
+__all__ = [
+    "KymoscopeConfig", "ConfigError", "load_config",
+    "derive_key", "generate_salt", "make_key_check", "KEY_CHECK_PLAINTEXT",
+    "KymoscopeClient", "RegistrationError",
+    "LiveStream", "ANON_KEY", "SUPABASE_URL",
+]

kymoscope-0.1.0/src/kymoscope/broadcast.py

@@ -0,0 +1,42 @@
+"""Broadcast cadence: decide when a sender should flush its pending frame batch.
+
+Senders sample at full resolution but should not emit one Realtime message per
+sample — that is what blows past the plan's message quota. Instead they hold
+frames in a `pending` batch and flush it on a *broadcast* cadence: every
+`period` seconds, or as soon as the batch reaches `max_frames` (to bound the
+message payload). This keeps all samples (nothing is dropped) while cutting the
+message count by roughly `sample_rate / broadcast_rate`.
+
+`should_flush` is a pure predicate so the loop timing stays trivially testable.
+"""
+
+# Frames handed to one LiveStream.send, which splits them into messages by
+# bytes (the relay's limit): a cap only on how much a backlog holds before a
+# flush. Mirrors the C++ plugin (constants.h MAX_FRAMES_PER_SEND).
+MAX_FRAMES_PER_MESSAGE = 256
+
+
+def should_flush(pending_count, now, last_flush, period, max_frames=MAX_FRAMES_PER_MESSAGE):
+    """Whether to flush the pending batch now.
+
+    Flush when there is at least one pending frame AND either the batch has
+    reached `max_frames` (bound payload size, ignoring the timer) or at least
+    `period` seconds have elapsed since the last flush. An empty batch never
+    flushes.
+    """
+    if pending_count <= 0:
+        return False
+    if pending_count >= max_frames:
+        return True
+    return (now - last_flush) >= period
+
+
+def effective_broadcast_rate(configured, cap):
+    """Clamp a configured broadcast rate to the plan cap.
+
+    A falsy/zero/None cap means "no cap" (e.g. an older stream-token response
+    without maxRateHz), so the configured rate wins.
+    """
+    if cap and cap > 0 and cap < configured:
+        return cap
+    return configured

kymoscope-0.1.0/src/kymoscope/client.py

@@ -0,0 +1,155 @@
+"""Talk to Kymoscope's backend as a stream sender.
+
+  1. mint_token: API key -> short-lived `pt.` publisher token (stream-token).
+     It is NOT a Supabase JWT: it only works against the stream-publisher
+     function, so a leaked token/API key cannot read or write account data.
+  2. register / heartbeat / delete / resolve_org: the `stream-publisher` edge
+     function, authenticated with that token. register and heartbeat return a
+     `pp.` publish ticket bound to the stream: the only credential the relay
+     accepts on the publish socket.
+  3. watch_ticket: API key -> `wt.` watch ticket + join material for one stream
+     (stream-watch-ticket), for headless viewers/checkers.
+"""
+
+import uuid
+
+
+class RegistrationError(Exception):
+    """A registry call (register/heartbeat/delete/resolve_org) failed; `status` is the HTTP status when there is one."""
+
+    def __init__(self, message, status=None):
+        super().__init__(message)
+        self.status = status
+
+
+class KymoscopeClient:
+    def __init__(self, base: str, anon_key: str, http):
+        self.base = base.rstrip("/")
+        self.anon_key = anon_key  # kept for callers; the publisher path needs no anon key
+        self.http = http  # a requests.Session-like object
+        # The account's live limits from the last stream-token (see mint_token).
+        self.limits = {}
+
+    def mint_token(self, api_key: str):
+        r = self.http.post(
+            f"{self.base}/functions/v1/stream-token",
+            headers={"x-api-key": api_key},
+            timeout=10,
+        )
+        if r.status_code != 200:
+            raise RegistrationError(f"stream-token failed: {r.status_code} {r.text}")
+        body = r.json()
+        # maxBytesPerSec / maxViewers: what the account negotiated (the relay enforces
+        # them); maxMessageBytes: the relay's message size limit. Absent from older servers.
+        self.limits = {k: body[k] for k in ("maxBytesPerSec", "maxViewers", "maxMessageBytes") if body.get(k)}
+        # The key's id and, for a project key, its project: {id, e2ee} (e2ee: encrypted project).
+        self.publisher = {"api_key_id": body.get("apiKeyId"), "project": body.get("project")}
+        # maxRateHz caps the sender's broadcast cadence (0/absent = no cap);
+        # relayUrl is the live relay the sender publishes to.
+        return body["token"], body["userId"], body.get("maxRateHz", 0) or 0, body.get("relayUrl")
+
+    def _publisher(self, token, body, what):
+        r = self.http.post(
+            f"{self.base}/functions/v1/stream-publisher",
+            headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
+            json=body,
+            timeout=10,
+        )
+        if r.status_code != 200:
+            # Refusals carry {error, message}: show the server's sentence, not raw JSON.
+            try:
+                err = r.json()
+                detail = f"{err['message']} ({err.get('error')})"
+            except (ValueError, KeyError, TypeError):
+                detail = r.text
+            raise RegistrationError(f"{what} failed: {r.status_code} {detail}", status=r.status_code)
+        return r.json()
+
+    def register_stream(self, token, name, salt, key_check,
+                        visibility="private", org_id=None, stream_id=None, project=None,
+                        sender_device=None) -> dict:
+        """Register (or, with a persisted stream_id, re-register) the stream.
+
+        `project` (name or id) publishes into that project of the user's organization;
+        a project API key publishes into its project without it.
+
+        `sender_device` ({public_key, binding}): this sender as a device of an encrypted project.
+
+        Returns the row ({id, share_code, ...}) plus "ticket": the `pp.` ticket
+        for the relay's publish socket, and for project streams "project"
+        ({id, e2ee, current_epoch, key}) and "sender_device_id".
+        """
+        body = {"action": "register", "name": name, "salt": salt,
+                "key_check": key_check, "visibility": visibility}
+        if org_id is not None:
+            body["org_id"] = org_id
+        if project is not None:
+            body["project"] = project
+        if stream_id is not None:
+            # Reuse a known id so a restarted sender keeps the SAME channel
+            # (viewers resume seamlessly). The server only allows it for our own id.
+            body["stream_id"] = stream_id
+        if sender_device is not None:
+            body["sender_device"] = sender_device
+        res = self._publisher(token, body, "register")
+        row = {**res["stream"], "ticket": res["ticket"], "devices": res.get("devices", [])}
+        row.update({k: res[k] for k in ("project", "sender_device_id") if k in res})
+        return row
+
+    def resolve_org(self, token, org) -> str:
+        """Resolve an --org value (UUID or name) to an organization id."""
+        try:
+            return str(uuid.UUID(str(org)))
+        except (ValueError, AttributeError, TypeError):
+            pass
+        try:
+            return self._publisher(token, {"action": "resolve_org", "org": str(org)}, "org lookup")["orgId"]
+        except RegistrationError as e:
+            if " 404 " in str(e):
+                raise RegistrationError(
+                    f"organization '{org}' not found among your organizations") from e
+            raise
+
+    def heartbeat(self, token, stream_id) -> str:
+        """Mark the stream alive; returns a fresh `pp.` publish ticket."""
+        return self.heartbeat_with_devices(token, stream_id)[0]
+
+    def heartbeat_with_devices(self, token, stream_id):
+        """(fresh `pp.` ticket, the owner's devices still lacking a key wrap)."""
+        res = self._publisher(token, {"action": "heartbeat", "stream_id": stream_id}, "heartbeat")
+        return res["ticket"], res.get("devices", [])
+
+    def heartbeat_project(self, token, stream_id, sender_device_id, epoch=0) -> dict:
+        """Heartbeat of an encrypted project's stream: {ticket, devices, project}. `epoch`: the
+        epoch the stream key is sealed under (0: none yet); one left behind by a rotation is refused."""
+        return self._publisher(token, {"action": "heartbeat", "stream_id": stream_id,
+                                       "sender_device_id": sender_device_id, "epoch": epoch}, "heartbeat")
+
+    def wrap_project_key(self, token, stream_id, epoch, sealed, sender_device_id) -> None:
+        """Upload the stream key sealed under the project key of `epoch` ({iv, ct}), from this sender's device."""
+        self._publisher(token, {"action": "wrap_keys", "stream_id": stream_id, "sender_device_id": sender_device_id,
+                                "project_wrap": {"epoch": epoch, "iv": sealed["iv"], "ct": sealed["ct"]}}, "wrap_keys")
+
+    def wrap_keys(self, token, stream_id, keys) -> None:
+        """Upload stream-key wraps: [{device_id, wrapped:{epk, iv, ct}}]."""
+        self._publisher(token, {"action": "wrap_keys", "stream_id": stream_id, "keys": keys}, "wrap_keys")
+
+    def delete_stream(self, token, stream_id) -> None:
+        # Best-effort; ignore failures. Deleting forgets the stream's project placement.
+        try:
+            self._publisher(token, {"action": "delete", "stream_id": stream_id}, "delete")
+        except Exception:
+            pass
+
+    def watch_ticket(self, api_key, stream_id):
+        """(`wt.` ticket, {id, name, salt, key_check}) for a stream this key's owner may watch."""
+        r = self.http.post(
+            f"{self.base}/functions/v1/stream-watch-ticket",
+            headers={"x-api-key": api_key, "Content-Type": "application/json"},
+            json={"streamId": stream_id},
+            timeout=10,
+        )
+        if r.status_code != 200:
+            raise RegistrationError(f"stream-watch-ticket failed: {r.status_code} {r.text}")
+        body = r.json()
+        return body["ticket"], body["stream"]

kymoscope-0.1.0/src/kymoscope/config.py

@@ -0,0 +1,66 @@
+"""Load the Kymoscope sender config (API key, optional base URL) from kymoscope-stream.json.
+
+Scripts can simply pass the API key to LiveStream; this file is for senders
+that read it from disk: {"apiKey": "kymoscope_..."} ("base" is optional).
+
+Search order when no explicit path is given:
+  1. ./kymoscope-stream.json (current directory)
+  2. %APPDATA%/kymoscope/kymoscope-stream.json  (Windows)
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from dataclasses import dataclass
+
+DEFAULT_BASE = "https://clahbbkqdskkhymymoge.supabase.co"
+
+_API_KEY_RE = re.compile(r"^((?:kymoscope|prism)_[A-Za-z0-9_-]+)(?:\.([A-Za-z0-9_-]+))?$")
+
+
+class ConfigError(Exception):
+    """The sender config is missing or invalid."""
+
+
+@dataclass
+class KymoscopeConfig:
+    base: str
+    api_key: str               # the auth part: the only part ever sent to the server
+    secret: str | None = None  # end-to-end secret: stream keys derive from it, never sent
+
+    @classmethod
+    def from_api_key(cls, api_key: str, base: str = DEFAULT_BASE) -> "KymoscopeConfig":
+        """Config from an API key pasted into a script (`kymoscope_<auth>.<secret>`)."""
+        m = _API_KEY_RE.match(api_key.strip())
+        if not m:
+            raise ConfigError("That does not look like a Kymoscope API key.")
+        return cls(base=base, api_key=m.group(1), secret=m.group(2))
+
+
+def _candidate_paths():
+    yield os.path.join(os.getcwd(), "kymoscope-stream.json")
+    appdata = os.environ.get("APPDATA")
+    if appdata:
+        yield os.path.join(appdata, "kymoscope", "kymoscope-stream.json")
+
+
+def load_config(path: str | None = None) -> KymoscopeConfig:
+    """Return a KymoscopeConfig, raising ConfigError if not found / invalid."""
+    paths = [path] if path else list(_candidate_paths())
+    for p in paths:
+        if p and os.path.isfile(p):
+            try:
+                data = json.loads(open(p, encoding="utf-8").read())
+            except (OSError, ValueError) as e:
+                raise ConfigError(f"Could not read config {p}: {e}") from e
+            base, api_key = data.get("base") or DEFAULT_BASE, data.get("apiKey")
+            if not api_key:
+                raise ConfigError(f"Config {p} must contain 'apiKey'.")
+            return KymoscopeConfig.from_api_key(api_key, base)
+    raise ConfigError(
+        "No kymoscope-stream.json found. Create an API key in Kymoscope (Account → "
+        "API & streaming), save it as {\"apiKey\": \"kymoscope_...\"} in "
+        "kymoscope-stream.json next to the sender, or pass --api-key / --config <path>."
+    )