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.
