Metadata-Version: 2.4
Name: os3-upload-client
Version: 0.3.1
Summary: OS3 presigned dataset upload client (A4.2): hash, upload with resume, seal, verify the manifest.
License: Proprietary
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: httpx<1,>=0.27

# os3-upload-client

The platform's presigned dataset upload client (A4.2): `UploadClient.upload_dataset_version`
scans a LeRobot v3 tree, declares each file's sha256 and size, PUTs the files with resume,
seals the version and checks the sealed `manifest_sha256` against the local manifest. The
module docstring has the details.

Since 0.2.0 (X08-F) a version may also hold the robot's recording provenance sidecars at
their own paths (`PROVENANCE_PATH`: JSON/JSONL at the dataset root, `rl_timelines/*.jsonl`,
`provenance/**`), and `provenance={"robot_ref", "operator_id", "customer_id", "source_ref"}`
declares who recorded it: the platform stores it on the version and in its manifest.
Since 0.2.1 `scan()` skips `rl_features/`, modeltraining's frozen-feature cache that
`training/rl/extract_features.py` writes inside the dataset tree; the version still carries
the pooled `meta/episode_embeddings.parquet` the A16.1 dataset diff reads.
Since 0.3.0 (SW-SEAL) the platform seals a version off the request: `POST .../seal` answers 202
and the client reads the version until it is sealed, or refused (`seal_error`, raised as
`SealRejected`). Earlier clients get the 202 as an error; their next run finds the version sealed.
Since 0.3.1 `scan()` checks every path before it hashes any file, so a stray file is reported
at once, and the `hook` also gets `("scanned", "<files> <bytes>")` after the scan,
`("todo", "<files>")` with the number of files this run PUTs (a resume's left over) and
`("seal", status)` each time the client reads a version still being sealed (`os3 upload`
prints its progress from them).

It depends on `httpx` only, so the robot NUC installs it without the platform's server
stack. The platform (`os3-platform`) depends on it through a path source, re-exports it as
`os3_platform.storage.client` and imports its dataset path rules
(`is_dataset_path`) in `os3_platform/storage/backend.py`.

```bash
pip install https://api.os3robotics.com/downloads/os3_upload_client-0.3.1-py3-none-any.whl  # or ./upload_client
OS3_API_URL=... OS3_API_KEY=... python -m os3_upload_client upload <dataset id> <dir>
```

The version is in `pyproject.toml` and `__version__`. robotcontrol vendors this directory
verbatim at a trainingportal commit (its `upload_client/VENDOR.md`), as it does `contracts/`:
change the client here, bump the version, then re-vendor there.
