Metadata-Version: 2.3
Name: anyverse-adp
Version: 0.4.0
Summary: CLI and Python SDK for the Anyverse Data Platform Episode catalog
Requires-Dist: tomli>=2.0 ; python_full_version < '3.11'
Requires-Dist: httpx>=0.28,<1
Requires-Dist: prompt-toolkit>=3.0,<4
Requires-Dist: rich>=13.9,<14
Requires-Dist: questionary>=2,<3
Requires-Dist: typer>=0.15,<1
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# Anyverse ADP CLI and Python SDK

`anyverse-adp` provides the `adp-cli` command and a read-only Python SDK for reading the Anyverse Data Platform's registered LeRobot catalog and exporting Episode metadata CSV files.

Install it with `pip install anyverse-adp`. Create a Platform API Key with `episodes:read`, then configure it with an environment variable or reuse the CLI's secure `~/.adp-cli/config.toml`.

```text
adp-cli list
adp-cli --version
adp-cli browse
adp-cli info <dataset-slug>
adp-cli export <dataset-slug> <collection-key> --region <region> --output <directory-or-file.csv>
```

`adp-cli browse` is an inline terminal selector. It redraws a single `Anyverse Data Platform CLI` panel in the current terminal so the selected Dataset, Collection, region, and latest result stay together. Use Up/Down and Enter to select a Dataset, Collection, region, and export mode; type in Dataset and Collection menus to filter choices, and use Backspace to clear the filter. Press Esc to return to the previous level (or exit from Dataset). After a dry-run or completed export, its result remains visible and the selector offers continue or exit. It does not open a full-screen UI or switch to an alternate terminal screen.

The command reads catalog metadata, including the selected Artifact `oss://bucket/prefix/` root in the `oss_location` CSV column, the Episode UUID, and `video_refs` keyed by the original camera/view feature name. Each video reference contains its stable OSS path and indexed start/end offsets in nanoseconds. It does not read or download dataset objects, expose raw annotations, or grant object-storage access.

## Parquet references (0.4.0)

Version 0.4.0 appends `parquet_filepath`, `parquet_row_start`, and `parquet_row_end` to CSV exports. The filepath is a stable `oss://` URI resolved from the selected region's unique Artifact location and the API's relative file path. The row range is zero-based `[start, end)` inside that file, with `end - start == frame_count`; it is not the Episode index. Unindexed references produce three empty cells. Older APIs without all three metadata fields also produce empty cells, so deploy the updated API before using 0.4.0 for Parquet exports. Partial or invalid references fail the export instead of publishing an incomplete CSV.

SDK Episodes expose `parquet_relative_path`, `parquet_filepath`, `parquet_row_start`, and `parquet_row_end`. These are `None` when the reference is unavailable. Resolving a complete path requires exactly one Artifact location in the client's selected region; ambiguous locations raise `AdpResponseError`.

## Python SDK

The SDK uses a synchronous `Client` and lazy resource handles. Creating handles does not make a network request; iterating a collection or LeRobot reads pages as needed.

```python
from anyverse_adp import AdpError, Client

client = Client()  # explicit api_key, ADP_API_KEY, ADP_CLI_API_KEY, then ~/.adp-cli/config.toml
try:
    dataset = client.get_dataset("agibot_world")
    collection = dataset.get_collection("raw")
    for lerobot in collection.get_lerobots():
        for episode in lerobot:
            print(lerobot.artifact_id, episode.index)
except AdpError as exc:
    print(f"catalog request failed: {exc}")
finally:
    client.close()
```

The default endpoint is `https://data-platform.cloud.anyverse.work` and the default region is `cn-shanghai`. Pass `endpoint=`, `region=`, or `api_key=` to override them. API Key precedence is explicit `api_key`, `ADP_API_KEY`, `ADP_CLI_API_KEY`, then the CLI config file `~/.adp-cli/config.toml`. The SDK reads that file only, preserves its permission and symlink checks, never prompts, and never writes it.

Use `client.get_episode(artifact_id, episode_index)` or `lerobot.get_episode(episode_index)` for one Episode. This may scan multiple API pages because the current Platform API exposes cursor pagination rather than a direct index lookup. SDK failures are subclasses of `AdpError`; call `client.close()` when the client is no longer needed. The SDK only reads catalog metadata and does not download OSS objects.

可直接运行的完整示例位于 `examples/sdk_catalog.py`：

```bash
ADP_API_KEY='<完整 API Key>' \
python packages/anyverse-adp/examples/sdk_catalog.py agibot_world --collection raw
```
