Metadata-Version: 2.3
Name: anyverse-adp
Version: 0.3.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.

## 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
```
