dejavu-client 0.1.1__tar.gz

dejavu_client-0.1.1/.gitignore

@@ -0,0 +1,24 @@
+.visualizer-credentials
+node_modules/
+.next/
+episode_index_out/
+manifests_out/
+
+# Local Netlify folder
+.netlify
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+*.egg-info/
+dist/
+build/
+
+# Python build artifacts
+client/dist/

dejavu_client-0.1.1/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: dejavu-client
+Version: 0.1.1
+Summary: Client for the Deja Vu robot-data platform: curation manifests, checkpoints, artifacts, and rollout results
+Project-URL: Homepage, https://github.com/tabtabtabai/data-visualizer
+Project-URL: Issues, https://github.com/tabtabtabai/data-visualizer/issues
+Author: TabTabTab
+License-Expression: MIT
+Keywords: checkpoints,datasets,lerobot,machine-learning,robotics
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# dejavu-client
+
+Python client for the **Deja Vu** robot-data platform — curation manifests,
+checkpoints, cached artifacts, and inference/sim rollout results.
+
+Stdlib only, no dependencies: it installs identically on a laptop, a GCP or
+Azure VM, Baseten, or inside a Dockerfile with no credentials configured.
+
+```bash
+pip install dejavu-client
+```
+
+## Use
+
+```python
+from dejavu_client import DejaVu
+
+dv = DejaVu()                     # DEJAVU_API_KEY, DEJAVU_API_URL from env
+
+# what exists, and how curated it is
+for d in dv.datasets():
+    print(d["dataset"], d["episodes"], d["flagged"], d["bad"])
+
+# episodes this run should skip — step one of any dataloader
+m = dv.manifest("G1_Dex1_FoldTowel")
+skip = set(m["drop"])             # record m["version"] alongside the run
+
+# cache something expensive to recompute
+key = dv.artifact_key("G1_Dex1_FoldTowel", 42,
+                      transform="crop224", encoder="siglip-v1")
+blob = dv.artifact_get(key)
+if blob is None:
+    blob = expensive_encode(...)
+    dv.artifact_put(key, blob)
+
+# save a checkpoint — a set of files, not one
+dv.upload_checkpoint(
+    ["step1000.pt", "config.yaml", "dataset_statistics.json"],
+    wandb_run_id=run.id, step=1000,
+    metrics={"val_loss": 0.42},
+    manifest={"schema": "unibot-checkpoint/v0", "control_space": "ee"},
+    manifest_version=m["version"],
+)
+
+# inspect stats without pulling gigabytes of weights
+dv.download_checkpoint(ckpt_id, "./out", only=["dataset_statistics.json"])
+```
+
+## Things worth knowing
+
+**Bytes never pass through the API.** It hands out presigned URLs and you
+transfer straight to object storage, so a 19 GB checkpoint isn't limited by
+request size or timeouts. Uploads over 5 GB go multipart automatically.
+
+**Artifact reads bypass the API entirely** and hit the CDN, so a cache miss
+costs one HTTP request to an edge node rather than a round trip to the
+server. That is also what makes the cache shared across GPU boxes.
+
+**Artifact keys are content-addressed** — `hash(dataset, episode, transform,
+encoder)`. Change the recipe and you get a different key, so nothing needs
+invalidating; stale entries are simply never requested again.
+
+**A checkpoint is a set of files.** Weights plus `config.yaml` plus
+`dataset_statistics.json`, because a serving stack often needs the small
+ones and shouldn't have to download the weights to read them.
+
+**There is no authorization.** A valid key may read and write anything; keys
+exist for attribution and revocation. Keep them out of source control.
+
+## Configuration
+
+| Variable | Default |
+|---|---|
+| `DEJAVU_API_KEY` | *(required)* |
+| `DEJAVU_API_URL` | `https://visualizer.tabtabtab.ai` |
+
+Mint a key from the Deja Vu UI; it is shown once and stored only as a hash.
+
+## Note
+
+This is a client for a specific hosted service. It is published so that
+ephemeral training boxes across clouds can install it without credentials —
+it is not useful without access to a Deja Vu deployment.

dejavu_client-0.1.1/README.md

@@ -0,0 +1,83 @@
+# dejavu-client
+
+Python client for the **Deja Vu** robot-data platform — curation manifests,
+checkpoints, cached artifacts, and inference/sim rollout results.
+
+Stdlib only, no dependencies: it installs identically on a laptop, a GCP or
+Azure VM, Baseten, or inside a Dockerfile with no credentials configured.
+
+```bash
+pip install dejavu-client
+```
+
+## Use
+
+```python
+from dejavu_client import DejaVu
+
+dv = DejaVu()                     # DEJAVU_API_KEY, DEJAVU_API_URL from env
+
+# what exists, and how curated it is
+for d in dv.datasets():
+    print(d["dataset"], d["episodes"], d["flagged"], d["bad"])
+
+# episodes this run should skip — step one of any dataloader
+m = dv.manifest("G1_Dex1_FoldTowel")
+skip = set(m["drop"])             # record m["version"] alongside the run
+
+# cache something expensive to recompute
+key = dv.artifact_key("G1_Dex1_FoldTowel", 42,
+                      transform="crop224", encoder="siglip-v1")
+blob = dv.artifact_get(key)
+if blob is None:
+    blob = expensive_encode(...)
+    dv.artifact_put(key, blob)
+
+# save a checkpoint — a set of files, not one
+dv.upload_checkpoint(
+    ["step1000.pt", "config.yaml", "dataset_statistics.json"],
+    wandb_run_id=run.id, step=1000,
+    metrics={"val_loss": 0.42},
+    manifest={"schema": "unibot-checkpoint/v0", "control_space": "ee"},
+    manifest_version=m["version"],
+)
+
+# inspect stats without pulling gigabytes of weights
+dv.download_checkpoint(ckpt_id, "./out", only=["dataset_statistics.json"])
+```
+
+## Things worth knowing
+
+**Bytes never pass through the API.** It hands out presigned URLs and you
+transfer straight to object storage, so a 19 GB checkpoint isn't limited by
+request size or timeouts. Uploads over 5 GB go multipart automatically.
+
+**Artifact reads bypass the API entirely** and hit the CDN, so a cache miss
+costs one HTTP request to an edge node rather than a round trip to the
+server. That is also what makes the cache shared across GPU boxes.
+
+**Artifact keys are content-addressed** — `hash(dataset, episode, transform,
+encoder)`. Change the recipe and you get a different key, so nothing needs
+invalidating; stale entries are simply never requested again.
+
+**A checkpoint is a set of files.** Weights plus `config.yaml` plus
+`dataset_statistics.json`, because a serving stack often needs the small
+ones and shouldn't have to download the weights to read them.
+
+**There is no authorization.** A valid key may read and write anything; keys
+exist for attribution and revocation. Keep them out of source control.
+
+## Configuration
+
+| Variable | Default |
+|---|---|
+| `DEJAVU_API_KEY` | *(required)* |
+| `DEJAVU_API_URL` | `https://visualizer.tabtabtab.ai` |
+
+Mint a key from the Deja Vu UI; it is shown once and stored only as a hash.
+
+## Note
+
+This is a client for a specific hosted service. It is published so that
+ephemeral training boxes across clouds can install it without credentials —
+it is not useful without access to a Deja Vu deployment.

dejavu_client-0.1.1/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "dejavu-client"
+version = "0.1.1"
+description = "Client for the Deja Vu robot-data platform: curation manifests, checkpoints, artifacts, and rollout results"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "TabTabTab" }]
+keywords = ["robotics", "lerobot", "machine-learning", "checkpoints", "datasets"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+# Deliberately none. Training boxes are ephemeral and span GCP, Azure and
+# Baseten; a stdlib-only client installs identically everywhere with no
+# wheels to build and nothing to conflict with a trainer's pinned stack.
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/tabtabtabai/data-visualizer"
+Issues = "https://github.com/tabtabtabai/data-visualizer/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dejavu_client"]

dejavu_client-0.1.1/src/dejavu_client/__init__.py

@@ -0,0 +1,22 @@
+"""Client for the Deja Vu robot-data platform.
+
+    from dejavu_client import DejaVu
+
+    dv = DejaVu()                                    # DEJAVU_API_KEY=dvk_...
+    skip = set(dv.manifest("G1_Dex1_FoldTowel")["drop"])
+
+See the DejaVu class docstring for the full contract.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .client import DejaVu
+
+__all__ = ["DejaVu", "__version__"]
+
+try:
+    # Read from installed metadata so the version lives in exactly one place
+    # (pyproject.toml) and a release bump cannot leave the two disagreeing.
+    __version__ = version("dejavu-client")
+except PackageNotFoundError:  # running from a source checkout
+    __version__ = "0.0.0.dev0"

dejavu_client-0.1.1/src/dejavu_client/client.py

@@ -0,0 +1,279 @@
+"""Client for the Deja Vu platform API.
+
+Everything a trainer needs, with no dependencies beyond the standard
+library — it installs identically on GCP, Azure, Baseten or a laptop.
+
+    pip install dejavu-client
+
+    export DEJAVU_API_KEY=dvk_...          # mint one in the Deja Vu UI
+    export DEJAVU_API_URL=https://visualizer.tabtabtab.ai
+
+    from dejavu_client import DejaVu
+    dv = DejaVu()
+
+    # 1. which episodes should this run skip?
+    m = dv.manifest("G1_Dex1_FoldTowel")
+    skip = set(m["drop"])              # record m["version"] with your run
+
+    # 2. cache an expensive artifact (latents, preprocessed tensors)
+    key = dv.artifact_key("G1_Dex1_FoldTowel", 42, transform="crop224", encoder="siglip-v1")
+    blob = dv.artifact_get(key)        # None on miss — reads bypass the API
+    if blob is None:
+        blob = expensive_encode(...)
+        dv.artifact_put(key, blob)
+
+    # 3. save a checkpoint (streams straight to R2, not through the API)
+    dv.upload_checkpoint(["step1000.pt", "config.yaml", "dataset_statistics.json"],
+                         wandb_run_id=run.id, step=1000,
+                         metrics={"val_loss": 0.42},
+                         manifest={"schema": "unibot-checkpoint/v0", ...},
+                         manifest_version=m["version"])
+
+Design notes worth knowing:
+  * Bytes never pass through the API service — it hands out presigned R2
+    URLs and you transfer directly. Cloud Run caps requests at 32 MB.
+  * Artifact READS go straight to the CDN with no auth and no API call, so
+    a cache miss check costs one HTTP HEAD against an edge node.
+  * There is no authorization: any valid key can do anything. Keys exist so
+    the request log can attribute writes and so they can be revoked.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+DEFAULT_URL = "https://visualizer.tabtabtab.ai"  # the Python backend
+PUBLIC_CDN = "https://data.tabtabtab.page"
+
+# R2 caps a single PUT at 5 GB; our base checkpoints are ~19 GB.
+PART_SIZE = 256 * 1024 * 1024
+
+
+class DejaVu:
+    def __init__(self, api_key: str | None = None, url: str | None = None):
+        self.key = api_key or os.environ["DEJAVU_API_KEY"]
+        self.url = (url or os.environ.get("DEJAVU_API_URL", DEFAULT_URL)).rstrip("/")
+
+    # ---------------------------------------------------------------- http
+    def _call(self, method: str, path: str, body: dict | None = None) -> dict:
+        req = urllib.request.Request(
+            f"{self.url}{path}",
+            method=method,
+            data=json.dumps(body).encode() if body is not None else None,
+            headers={
+                "Authorization": f"Bearer {self.key}",
+                **({"Content-Type": "application/json"} if body is not None else {}),
+            },
+        )
+        with urllib.request.urlopen(req, timeout=120) as r:
+            return json.loads(r.read() or "{}")
+
+    # ------------------------------------------------------------ curation
+    def datasets(self) -> list[dict]:
+        """Datasets the platform knows about, with their curation state.
+
+        Derived server-side from Postgres, so it cannot drift from reality
+        the way a hardcoded list does. Each entry carries episode, flagged,
+        reviewed and bad counts.
+        """
+        return self._call("GET", "/api/datasets")["datasets"]
+
+    def manifest(self, dataset: str, strict: bool = False) -> dict:
+        """Episodes to skip. `strict` also drops flagged-but-unreviewed ones."""
+        return self._call("GET", f"/api/manifest/{dataset}" + ("?strict=1" if strict else ""))
+
+    def scores(self, dataset: str) -> dict:
+        return self._call("GET", f"/api/scores?dataset={dataset}")
+
+    def set_verdict(self, dataset: str, episode: int, verdict: str | None, note: str = "") -> dict:
+        return self._call("POST", "/api/verdict", {
+            "dataset": dataset, "episode": episode, "verdict": verdict, "note": note,
+        })
+
+    # ------------------------------------------------------------ artifacts
+    @staticmethod
+    def artifact_key(dataset: str, episode: int, transform: str, encoder: str) -> str:
+        """Content-addressed key: change the recipe, get a different key.
+
+        That is the whole invalidation story — stale entries are simply never
+        requested again, so nothing has to be purged.
+        """
+        digest = hashlib.sha256(
+            f"{dataset}|{episode}|{transform}|{encoder}".encode()
+        ).hexdigest()[:32]
+        return f"latents/{digest}"
+
+    def artifact_get(self, key: str) -> bytes | None:
+        """Fetch an artifact, or None on a miss.
+
+        Deliberately reads the CDN directly: no API round trip, and the edge
+        caches it, which is what makes this shared across GPU boxes.
+
+        Not read-after-write consistent — a GET issued immediately after a PUT
+        can still miss while the write propagates to the edge. That is fine
+        for the intended pattern (on a miss you compute the value and already
+        hold it in memory); just don't write a artifact and then read it back
+        to obtain it.
+        """
+        try:
+            with urllib.request.urlopen(f"{PUBLIC_CDN}/derived/artifacts/{key}", timeout=60) as r:
+                return r.read()
+        except urllib.error.HTTPError as e:
+            # R2's public domain answers 403 for a key that isn't there (it
+            # will not confirm absence), so a miss is 403 or 404. Treating
+            # only 404 as a miss makes every cold cache raise.
+            if e.code in (403, 404):
+                return None
+            raise
+
+    def artifact_list(self, namespace: str | None = None, limit: int = 100) -> dict:
+        """What's cached. Objects are world-readable but not enumerable from
+        outside (no directory index, keys are hashes) — this is our view."""
+        q = f"?limit={limit}" + (f"&namespace={namespace}" if namespace else "")
+        return self._call("GET", f"/api/artifacts{q}")
+
+    def artifact_put(self, key: str, blob: bytes) -> str:
+        resp = self._call("POST", f"/api/artifacts/{key}")
+        _put(resp["upload_url"], blob)
+        return resp["read_url"]
+
+    # ---------------------------------------------------------- checkpoints
+    def list_checkpoints(self, wandb_run_id: str | None = None) -> list[dict]:
+        q = f"?run={wandb_run_id}" if wandb_run_id else ""
+        return self._call("GET", f"/api/checkpoints{q}")["checkpoints"]
+
+    def download_checkpoint(self, checkpoint_id: str, dest_dir: str | Path,
+                            only: list[str] | None = None) -> list[Path]:
+        """Download a checkpoint's files. `only` fetches a subset by filename —
+        e.g. ["dataset_statistics.json"] to inspect stats without the weights."""
+        info = self._call("GET", f"/api/checkpoints/{checkpoint_id}")
+        dest_dir = Path(dest_dir)
+        dest_dir.mkdir(parents=True, exist_ok=True)
+        written = []
+        for f in info["files"]:
+            if only and f["filename"] not in only:
+                continue
+            out = dest_dir / f["filename"]
+            with urllib.request.urlopen(f["download_url"], timeout=3600) as r, out.open("wb") as fh:
+                while chunk := r.read(8 * 1024 * 1024):
+                    fh.write(chunk)
+            written.append(out)
+        return written
+
+    def upload_checkpoint(
+        self,
+        paths: str | Path | list[str | Path],
+        wandb_run_id: str,
+        step: int,
+        metrics: dict | None = None,
+        manifest: dict | None = None,
+        manifest_version: str | None = None,
+        wandb_url: str | None = None,
+    ) -> str:
+        """Upload a checkpoint straight to R2 and register it. Returns the id.
+
+        A checkpoint is a SET of files — weights plus config.yaml plus
+        dataset_statistics.json — because the serving stack needs the small
+        ones and should not have to pull 19 GB of weights to read them.
+
+        `manifest` is the unibot-checkpoint/v0 document describing how to load
+        this checkpoint (regime, base_model, control_space, serving_env). It
+        is stored as its own queryable column, separate from `metrics`, which
+        is only for scalars.
+        """
+        files = [Path(p) for p in ([paths] if isinstance(paths, (str, Path)) else paths)]
+
+        reg = self._call("POST", "/api/checkpoints", {
+            "wandb_run_id": wandb_run_id,
+            "wandb_url": wandb_url,
+            "step": step,
+            "files": [{"filename": f.name, "size": f.stat().st_size} for f in files],
+            "metrics": metrics or {},
+            "manifest": manifest or {},
+            "manifest_version": manifest_version,
+        })
+
+        by_name = {f.name: f for f in files}
+        completed = []
+        for entry in reg["files"]:
+            src = by_name[entry["filename"]]
+            if "part_urls" in entry:
+                # >5 GB: a single presigned PUT cannot take it.
+                etags = []
+                with src.open("rb") as fh:
+                    for i, url in enumerate(entry["part_urls"], start=1):
+                        etags.append({"PartNumber": i, "ETag": _put(url, fh.read(PART_SIZE))})
+                completed.append({
+                    "filename": entry["filename"],
+                    "upload_id": entry["upload_id"],
+                    "parts": etags,
+                })
+            else:
+                _put(entry["upload_url"], src.read_bytes())
+
+        # Completing verifies every file actually landed, so a crashed upload
+        # never appears as a usable checkpoint.
+        self._call("POST", f"/api/checkpoints/{reg['id']}/complete",
+                   {"files": completed})
+        return reg["id"]
+
+
+    # --------------------------------------------------------------- results
+    def create_result_set(self, wandb_run_id: str, name: str, kind: str = "eval") -> dict:
+        """Open a result set. Returns {id, prefix}."""
+        return self._call("POST", "/api/results", {
+            "wandb_run_id": wandb_run_id, "name": name, "kind": kind,
+        })
+
+    def upload_result_file(self, result_id: str, rel_path: str, data: bytes,
+                           content_type: str | None = None) -> str:
+        """Upload one file into the set, keeping LeRobot's directory layout.
+
+        e.g. rel_path='meta/info.json', 'videos/observation.images.cam/…mp4',
+        'data/chunk-000/file-000.parquet' — the same shape as a training
+        dataset, which is what lets the viewer play these back.
+        """
+        resp = self._call("POST", f"/api/results/{result_id}",
+                          {"path": rel_path, "content_type": content_type})
+        _put(resp["upload_url"], data)
+        return resp["key"]
+
+    def upload_result_dir(self, result_id: str, root: str | Path) -> int:
+        root = Path(root)
+        n = 0
+        for f in sorted(root.rglob("*")):
+            if f.is_file():
+                self.upload_result_file(result_id, str(f.relative_to(root)), f.read_bytes())
+                n += 1
+        return n
+
+    def complete_result_set(self, result_id: str, episode_count: int | None = None) -> dict:
+        """Close the set. Fails if nothing was uploaded."""
+        return self._call("POST", f"/api/results/{result_id}/complete",
+                          {"episode_count": episode_count})
+
+    def result_files(self, result_id: str) -> dict:
+        """Set metadata plus presigned URLs — playable directly, no proxy."""
+        return self._call("GET", f"/api/results/{result_id}")
+
+    def list_result_sets(self, wandb_run_id: str | None = None) -> list[dict]:
+        q = f"?run={wandb_run_id}" if wandb_run_id else ""
+        return self._call("GET", f"/api/results{q}")["results"]
+
+
+def _put(url: str, data: bytes) -> str:
+    req = urllib.request.Request(url, method="PUT", data=data)
+    with urllib.request.urlopen(req, timeout=3600) as r:
+        return r.headers.get("ETag", "")
+
+
+if __name__ == "__main__":
+    dv = DejaVu()
+    m = dv.manifest("G1_Dex1_PlacePhotoFrame")
+    print(f"manifest version={m['version']} drop={len(m['drop'])} flagged={len(m['flagged'])}")
+    print(f"checkpoints: {len(dv.list_checkpoints())}")