auvux 0.1.0a1__tar.gz

auvux-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Auvux
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

auvux-0.1.0a1/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: auvux
+Version: 0.1.0a1
+Summary: Annotate faster. See deeper. Sound smarter.
+Author-email: Auvux <peter@dreamteam.nl>
+License: MIT
+Project-URL: Homepage, https://inference.auvux.com
+Project-URL: Repository, https://github.com/auvux/auvux-py
+Project-URL: Issues, https://github.com/auvux/auvux-py/issues
+Keywords: webrtc,jupyter,visualization,inference,audio
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Framework :: Jupyter
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiortc>=1.9.0
+Requires-Dist: websockets>=12.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: soundfile>=0.12
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/auvux/auvux-py/main/assets/logo.png" alt="auvux" width="120" />
+</p>
+
+<h1 align="center">auvux</h1>
+
+<p align="center"><em>Annotate faster. See deeper. Sound smarter.</em></p>
+
+---
+
+Push inference runs from a Python notebook to a browser viewer over WebRTC.
+
+Bytes flow peer-to-peer over a DataChannel; identical bytes across runs
+and viewers are deduplicated via per-viewer SHA-256 content addressing.
+Auth is GitHub OAuth (`user:email` scope) verified by an HMAC-signed
+JWT — your tokens never leave your machine.
+
+## Install
+
+```bash
+pip install --pre auvux
+```
+
+(`--pre` while we're on the `0.1.0a1` alpha release.)
+
+## Use
+
+```bash
+auvux login           # GitHub Device Flow, caches a JWT in ~/.auvux/
+auvux whoami          # confirm
+```
+
+```python
+import auvux
+from auvux import lanes, markers
+
+# Same as `auvux login`, but inline. Idempotent — no-op if already
+# signed in.
+auvux.login()
+
+canvas = auvux.Canvas("Beat Detection")
+canvas.add(
+    lanes.Waveform.from_path("demo.wav", size=160, label="mix"),
+    markers=[markers.vlines(beats, color="#FFFF00")],
+)
+canvas.add(lanes.Heatmap(spect, yaxis="mel", fmin=30, fmax=11000, size=256))
+canvas.add(lanes.line(t, beat_logits, color="#4CAF50", label="beats", fill=True))
+canvas.minimap(from_lane=0)
+canvas.clicks(beats, freq=800)
+canvas.show()                  # opens at https://inference.auvux.com
+```
+
+Open `https://inference.auvux.com` in your browser **before** running
+`canvas.show()` — the publisher waits up to 60 seconds for at least
+one viewer to be present.
+
+`Waveform.from_path()` accepts both local paths and `http(s)://` URLs;
+remote files are fetched once into memory and reused without a second
+round-trip on emit.
+
+## What gets sent
+
+Each call to `canvas.show()` packages:
+
+- A `manifest.json` describing the lanes and their layout
+- Sidecar files: WAV / NPY / NPZ / CSV / JSON, per lane type
+- Click-track time lists (if any)
+
+The viewer pre-announces which file hashes it already has, so unchanged
+audio across iterations is sent **once** — subsequent runs reuse the
+cached blob.
+
+## Auth flow
+
+`auvux.login()` runs the GitHub Device Flow with scope `user:email`:
+
+1. Asks GitHub for a short user code (`XXXX-XXXX`)
+2. Opens the browser to the verification URL
+3. Polls until you authorise
+4. Swaps the GitHub access token for an auvux JWT at
+   `https://inference.auvux.com/api/auth/cli-exchange`
+5. Caches the JWT in `~/.auvux/credentials.json` (chmod 600)
+
+Subsequent `auvux.login()` calls are no-ops if the cached token is
+still valid; pass `force=True` to re-authenticate.
+
+## Environment
+
+| Var | Default | Purpose |
+| --- | --- | --- |
+| `AUVUX_SIGNALLING_URL` | from `~/.auvux/credentials.json`, otherwise `wss://signalling.auvux.com/signalling/me` | Override the signalling endpoint (escape hatch for local dev) |
+| `AUVUX_API_BASE` | `https://inference.auvux.com` | Auvux API host used for `cli-exchange` |
+| `AUVUX_GH_CLIENT_ID` | built-in | GitHub OAuth App client id |
+| `AUVUX_PEER_WAIT` | `60` | Seconds to wait for a viewer before erroring |
+| `AUVUX_ACK_WAIT` | `30` | Seconds to wait per-viewer for delivery ack |
+
+## Development
+
+```bash
+git clone https://github.com/auvux/auvux-py
+cd auvux-py
+pip install -e .
+```
+
+Release a new version: bump `version` in `pyproject.toml`, then
+
+```bash
+git tag v0.1.0a2
+git push --tags
+```
+
+The `release.yml` workflow builds the wheel + sdist and publishes to
+PyPI via OIDC (Trusted Publisher) — no API token in the repo.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

auvux-0.1.0a1/README.md

@@ -0,0 +1,117 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/auvux/auvux-py/main/assets/logo.png" alt="auvux" width="120" />
+</p>
+
+<h1 align="center">auvux</h1>
+
+<p align="center"><em>Annotate faster. See deeper. Sound smarter.</em></p>
+
+---
+
+Push inference runs from a Python notebook to a browser viewer over WebRTC.
+
+Bytes flow peer-to-peer over a DataChannel; identical bytes across runs
+and viewers are deduplicated via per-viewer SHA-256 content addressing.
+Auth is GitHub OAuth (`user:email` scope) verified by an HMAC-signed
+JWT — your tokens never leave your machine.
+
+## Install
+
+```bash
+pip install --pre auvux
+```
+
+(`--pre` while we're on the `0.1.0a1` alpha release.)
+
+## Use
+
+```bash
+auvux login           # GitHub Device Flow, caches a JWT in ~/.auvux/
+auvux whoami          # confirm
+```
+
+```python
+import auvux
+from auvux import lanes, markers
+
+# Same as `auvux login`, but inline. Idempotent — no-op if already
+# signed in.
+auvux.login()
+
+canvas = auvux.Canvas("Beat Detection")
+canvas.add(
+    lanes.Waveform.from_path("demo.wav", size=160, label="mix"),
+    markers=[markers.vlines(beats, color="#FFFF00")],
+)
+canvas.add(lanes.Heatmap(spect, yaxis="mel", fmin=30, fmax=11000, size=256))
+canvas.add(lanes.line(t, beat_logits, color="#4CAF50", label="beats", fill=True))
+canvas.minimap(from_lane=0)
+canvas.clicks(beats, freq=800)
+canvas.show()                  # opens at https://inference.auvux.com
+```
+
+Open `https://inference.auvux.com` in your browser **before** running
+`canvas.show()` — the publisher waits up to 60 seconds for at least
+one viewer to be present.
+
+`Waveform.from_path()` accepts both local paths and `http(s)://` URLs;
+remote files are fetched once into memory and reused without a second
+round-trip on emit.
+
+## What gets sent
+
+Each call to `canvas.show()` packages:
+
+- A `manifest.json` describing the lanes and their layout
+- Sidecar files: WAV / NPY / NPZ / CSV / JSON, per lane type
+- Click-track time lists (if any)
+
+The viewer pre-announces which file hashes it already has, so unchanged
+audio across iterations is sent **once** — subsequent runs reuse the
+cached blob.
+
+## Auth flow
+
+`auvux.login()` runs the GitHub Device Flow with scope `user:email`:
+
+1. Asks GitHub for a short user code (`XXXX-XXXX`)
+2. Opens the browser to the verification URL
+3. Polls until you authorise
+4. Swaps the GitHub access token for an auvux JWT at
+   `https://inference.auvux.com/api/auth/cli-exchange`
+5. Caches the JWT in `~/.auvux/credentials.json` (chmod 600)
+
+Subsequent `auvux.login()` calls are no-ops if the cached token is
+still valid; pass `force=True` to re-authenticate.
+
+## Environment
+
+| Var | Default | Purpose |
+| --- | --- | --- |
+| `AUVUX_SIGNALLING_URL` | from `~/.auvux/credentials.json`, otherwise `wss://signalling.auvux.com/signalling/me` | Override the signalling endpoint (escape hatch for local dev) |
+| `AUVUX_API_BASE` | `https://inference.auvux.com` | Auvux API host used for `cli-exchange` |
+| `AUVUX_GH_CLIENT_ID` | built-in | GitHub OAuth App client id |
+| `AUVUX_PEER_WAIT` | `60` | Seconds to wait for a viewer before erroring |
+| `AUVUX_ACK_WAIT` | `30` | Seconds to wait per-viewer for delivery ack |
+
+## Development
+
+```bash
+git clone https://github.com/auvux/auvux-py
+cd auvux-py
+pip install -e .
+```
+
+Release a new version: bump `version` in `pyproject.toml`, then
+
+```bash
+git tag v0.1.0a2
+git push --tags
+```
+
+The `release.yml` workflow builds the wheel + sdist and publishes to
+PyPI via OIDC (Trusted Publisher) — no API token in the repo.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

auvux-0.1.0a1/auvux/__init__.py

@@ -0,0 +1,30 @@
+"""auvux — push inference runs from a notebook to the browser viewer
+over WebRTC. Implements the canvas-api-design.md spec.
+
+    import auvux
+    from auvux import lanes, markers
+
+    auvux.login()                         # idempotent: skips if already signed in
+
+    canvas = auvux.Canvas("title")        # duration auto-derived
+    canvas.add(lanes.Waveform.from_path(audio_path),
+               markers=[markers.vlines(beats, color="#FF0")])
+    canvas.add(lanes.Heatmap(spect, yaxis="mel", fmin=30, fmax=11000))
+    canvas.add(lanes.line(t, y, color="#0AF", label="bpm"))
+    canvas.minimap(from_lane=0)
+    canvas.clicks(beats, freq=800)
+    canvas.show()
+"""
+
+from .canvas import Canvas
+from .auth import login, logout, whoami
+from . import lanes
+from . import markers
+from . import plots
+
+__version__ = "0.1.0a1"
+
+__all__ = [
+    "Canvas", "login", "logout", "whoami",
+    "lanes", "markers", "plots", "__version__",
+]

auvux-0.1.0a1/auvux/auth.py

@@ -0,0 +1,216 @@
+"""In-process auth — same Device Flow as `auvux login`, callable from
+a notebook cell.
+
+Typical use:
+
+    import auvux
+    auvux.login()       # prints code, opens browser, polls
+    auvux.whoami()      # confirm
+    canvas.show()       # now picks up the cached JWT
+
+The CLI's `auvux login` is a thin wrapper around `login()` here, so
+behaviour stays identical across both entry points.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import webbrowser
+
+from . import credentials
+
+
+DEFAULT_SIGNALLING_URL = os.environ.get(
+    "AUVUX_SIGNALLING_URL", "wss://signalling.auvux.com/signalling/me"
+)
+DEFAULT_API_BASE = os.environ.get(
+    "AUVUX_API_BASE", "https://inference.auvux.com"
+)
+# Public OAuth App client_id — same one the browser flow uses. Safe to
+# embed; the corresponding secret lives only on Vercel.
+DEFAULT_GH_CLIENT_ID = os.environ.get(
+    "AUVUX_GH_CLIENT_ID", "Ov23liqKUtwhWWde5r73"
+)
+
+
+def login(
+    *,
+    signalling_url: str = DEFAULT_SIGNALLING_URL,
+    api_base: str = DEFAULT_API_BASE,
+    client_id: str = DEFAULT_GH_CLIENT_ID,
+    open_browser: bool = True,
+    force: bool = False,
+) -> credentials.Credentials:
+    """Run the GitHub Device Flow, swap the access_token for an auvux
+    JWT at /api/auth/cli-exchange, and cache it in
+    ~/.auvux/credentials.json. Returns the stored credentials dict.
+
+    Idempotent by default: if a valid cached JWT already exists, this
+    is a no-op (returns the cached credentials) and prints a one-line
+    confirmation. Pass `force=True` to throw away the cached token and
+    re-run the Device Flow.
+
+    Safe to call from inside Jupyter — prints the code inline and
+    opens the browser to the verification URL.
+    """
+    if not force:
+        existing = credentials.load()
+        if credentials.is_valid(existing) and existing is not None:
+            email = existing.get("email") or "<unknown>"
+            remaining = max(0, existing.get("expires_at", 0) - int(time.time()))
+            days = remaining // 86400
+            print(
+                f"auvux: already signed in as {email} "
+                f"(expires in {days}d). Pass force=True to re-authenticate."
+            )
+            return existing
+
+    device = _request_device_code(client_id)
+
+    print()
+    print("  ┌── auvux login ──────────────────────────────────────")
+    print(f"  │  Go to: {device['verification_uri']}")
+    print(f"  │  Code:  {device['user_code']}")
+    print("  └─────────────────────────────────────────────────────")
+    print()
+
+    target = device.get("verification_uri_complete") or device["verification_uri"]
+    if open_browser:
+        try:
+            webbrowser.open(target)
+            print(f"auvux: opening {target} in your browser…")
+        except Exception:
+            pass
+
+    gh_token = _poll_for_token(
+        client_id,
+        device["device_code"],
+        interval=int(device.get("interval", 5)),
+        expires_in=int(device.get("expires_in", 900)),
+    )
+
+    auvux_resp = _exchange(api_base, gh_token)
+
+    creds: credentials.Credentials = {
+        "signalling_url": signalling_url,
+        "token": auvux_resp["token"],
+        "expires_at": (
+            int(time.time()) + int(auvux_resp["expires_in"])
+            if auvux_resp.get("expires_in")
+            else 0
+        ),
+        "email": auvux_resp.get("email", ""),
+    }
+    credentials.save(creds)
+    print(f"auvux: credentials saved → {credentials.credentials_path()}")
+    if creds.get("email"):
+        print(f"auvux: signed in as {creds['email']}")
+    return creds
+
+
+def logout() -> None:
+    """Remove cached credentials. Does nothing if not logged in."""
+    credentials.clear()
+    print("auvux: credentials removed.")
+
+
+def whoami() -> credentials.Credentials | None:
+    """Return (and print) the cached identity, or None if logged out."""
+    c = credentials.load()
+    if not c:
+        print("auvux: not logged in (call `auvux.login()`).")
+        return None
+    print(f"signalling: {c.get('signalling_url', '')}")
+    print(f"email:      {c.get('email', '') or '<unknown>'}")
+    exp = c.get("expires_at", 0)
+    if exp:
+        remaining = max(0, exp - int(time.time()))
+        print(f"expires_in: {remaining}s")
+    return c
+
+
+# ── GitHub Device Flow + cli-exchange (HTTP helpers) ──────────────────
+
+def _request_device_code(client_id: str) -> dict:
+    """POST github.com/login/device/code → { device_code, user_code,
+    verification_uri, expires_in, interval }."""
+    return _post_form(
+        "https://github.com/login/device/code",
+        {"client_id": client_id, "scope": "user:email"},
+    )
+
+
+def _poll_for_token(
+    client_id: str, device_code: str, interval: int, expires_in: int,
+) -> str:
+    """Poll the GitHub token endpoint until we get an access_token, a
+    fatal error, or the device code expires. Returns the access_token."""
+    deadline = time.time() + expires_in
+    sleep_s = max(interval, 1)
+    print(f"auvux: waiting for authorisation (poll every {sleep_s}s)…")
+    while time.time() < deadline:
+        time.sleep(sleep_s)
+        try:
+            body = _post_form(
+                "https://github.com/login/oauth/access_token",
+                {
+                    "client_id": client_id,
+                    "device_code": device_code,
+                    "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
+                },
+            )
+        except urllib.error.HTTPError as e:
+            raise RuntimeError(f"GitHub token poll HTTP {e.code}") from e
+        if "access_token" in body:
+            return body["access_token"]
+        err = body.get("error")
+        if err == "authorization_pending":
+            continue
+        if err == "slow_down":
+            sleep_s += 5
+            continue
+        if err in {"expired_token", "access_denied"}:
+            raise RuntimeError(f"GitHub login failed: {err}")
+        raise RuntimeError(f"unexpected token response: {body}")
+    raise RuntimeError("login timed out — device code expired before authorisation")
+
+
+def _exchange(api_base: str, gh_token: str) -> dict:
+    """Swap a GitHub access_token for an auvux JWT.
+
+    Cloudflare bot protection blocks Python's default
+    `User-Agent: Python-urllib/…`, so we send a recognisable UA string.
+    """
+    req = urllib.request.Request(
+        api_base.rstrip("/") + "/api/auth/cli-exchange",
+        data=json.dumps({"github_token": gh_token}).encode(),
+        headers={
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": "auvux-cli/0.1 (+https://inference.auvux.com)",
+        },
+        method="POST",
+    )
+    with urllib.request.urlopen(req, timeout=30) as resp:
+        return json.loads(resp.read())
+
+
+def _post_form(url: str, fields: dict) -> dict:
+    data = urllib.parse.urlencode(fields).encode()
+    req = urllib.request.Request(
+        url,
+        data=data,
+        headers={
+            "Accept": "application/json",
+            "Content-Type": "application/x-www-form-urlencoded",
+            "User-Agent": "auvux-cli",
+        },
+        method="POST",
+    )
+    with urllib.request.urlopen(req, timeout=30) as resp:
+        return json.loads(resp.read())