Metadata-Version: 2.4
Name: robot-data-audit
Version: 0.4.11
Summary: Robot Data Audit (RDA) - Quality auditing tool for robot datasets
Author-email: Niu Su Tech <dev@niusutech.com>
License: MIT
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: click>=8.0
Requires-Dist: pydantic>=2.0
Requires-Dist: numpy>=1.24
Provides-Extra: lerobot
Requires-Dist: lerobot>=0.6; extra == "lerobot"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Provides-Extra: ui
Requires-Dist: streamlit>=1.30.0; extra == "ui"
Requires-Dist: plotly>=5.18.0; extra == "ui"
Requires-Dist: pandas>=2.0; extra == "ui"
Provides-Extra: all
Requires-Dist: lerobot>=0.6; extra == "all"
Requires-Dist: streamlit>=1.30.0; extra == "all"
Requires-Dist: plotly>=5.18.0; extra == "all"
Requires-Dist: pandas>=2.0; extra == "all"

# Robot Data Audit (RDA)

Quality auditing tool for robot datasets. RDA provides comprehensive metrics for
evaluating the integrity, temporal consistency, motion quality, and distribution
coverage of robot trajectory datasets.

## Features

- **Integrity Metrics**: Missing frames, NaN values, schema validation
- **Temporal Metrics**: Timestamp consistency, sensor sync, jitter analysis
- **Motion Metrics**: Joint limits, velocity profiles, discontinuities, idle detection
- **Distribution Metrics**: Distribution statistics, coverage analysis
- **Three-tier classification**: PASS / REVIEW / EXCLUDE
- **CLI-first design**: Easy to integrate into data pipelines
- **Streamlit UI** (coming in v0.2.0): Interactive dashboard for exploring results

## Installation

### From PyPI

> **Note:** PyPI publishing is planned for the v0.2.0 release.
> Until then, install from source as described below.

```bash
# Coming soon — PyPI package name: robot-data-assurance
# pip install robot-data-assurance
```

### From source (development)

```bash
git clone <repository-url>
cd robot-data-audit
pip install -e .
```

### With UI support (v0.2.0+)

```bash
pip install -e ".[ui]"
```

## Quick Start

### 1. Audit a dataset

```bash
rda audit /path/to/lerobot/dataset
```

This will run all 12 RDA metrics against every episode in the dataset and print a
text summary to the console. A JSON report is automatically saved to
`<dataset_path>/rda_report.json`.

### 2. Use example datasets

```bash
# See examples and usage tips
rda example
```

### 3. Customize output

```bash
# Save report to a specific path
rda audit /path/to/dataset --output my_report.json

# Output JSON to stdout (for piping)
rda audit /path/to/dataset --format json

# Verbose mode with platform info
rda audit /path/to/dataset --platform so101 -v
```

### 4. Preview the UI (coming soon)

```bash
rda audit /path/to/dataset --ui
```

## CLI Reference

### `rda audit`

Audit a LeRobot dataset at the given PATH.

```bash
rda audit [OPTIONS] PATH
```

| Option | Description |
|--------|-------------|
| `-o, --output FILE` | Path to save the JSON audit report. Defaults to `<path>/rda_report.json`. |
| `--format [json\|text]` | Output format for the audit report. Default: `text`. |
| `--platform TEXT` | Robot platform name (e.g. `so101`, `droid`). Used for Tier 3 platform-specific metrics. |
| `--ui` | Launch the Streamlit web UI after the audit completes. *(v0.2.0 preview)* |
| `-v, --verbose` | Enable verbose output. |
| `-V, --version` | Show version and exit. |
| `-h, --help` | Show help message and exit. |

### `rda example`

Show example usage and sample dataset paths.

```bash
rda example
```

## Exit Codes

| Code | Meaning |
|------|---------|
| `0` | Audit completed successfully, no EXCLUDE verdicts |
| `1` | Error (invalid path, dataset loading failed, etc.) |
| `2` | Audit completed successfully, at least one EXCLUDE verdict |

## Project Structure

```
rda/
├── cli/          # Click CLI entry points
├── io/           # Data loading and schema definitions
├── metrics/      # Audit metric implementations (12 metrics total)
├── audit/        # Dataset and episode-level audit orchestration
└── report/       # Report generation and summary

docs/             # API documentation and design specs
examples/         # Example scripts
  ├── basic_audit.py       # Core workflow demo (synthetic data ready)
  └── custom_metrics.py    # How to write custom audit metrics
tests/            # 155 unit tests
```

## Documentation

- **[API Reference](docs/API.md)** — Full Python API documentation
- **[MVP Product Spec](docs/MVP_PRODUCT_SPEC.md)** — Product requirements (v0.2.0)
- **[Technical Design](TECHNICAL_DESIGN.md)** — Architecture and design decisions
- **[Project Charter](PROJECT_CHARTER.md)** — Mission, goals, and scope
- **[Roadmap](ROADMAP.md)** — Release plan and milestones
- **[Changelog](CHANGELOG.md)** — Version history

## Python API Quick Start

```python
from rda.audit.dataset_audit import DatasetAuditor
from rda.io.lerobot_loader import iter_episodes, load_lerobot_dataset
from rda.report import generate_dataset_report

dataset_info = load_lerobot_dataset("/path/to/dataset")
auditor = DatasetAuditor()
result = auditor.audit_dataset(dataset_info, iter_episodes("/path/to/dataset"))

report = generate_dataset_report(result)
print(f"DHI: {report['quality']['dhi']} / 100")
```

See [docs/API.md](docs/API.md) for the complete API reference, or
[examples/](examples/) for runnable scripts.

## Development

### Running tests

```bash
pytest
```

### Linting

```bash
pip install -e ".[dev]"
ruff check rda/
```

## License

MIT
