Metadata-Version: 2.4
Name: orbit-robotics
Version: 0.2.0
Summary: Predict whether your robot learning data will actually train successfully
Author: Rahil Lasne
License-Expression: MIT
Project-URL: Homepage, https://github.com/Rahillasne/orbit-robotics
Project-URL: Repository, https://github.com/Rahillasne/orbit-robotics
Project-URL: Issues, https://github.com/Rahillasne/orbit-robotics/issues
Keywords: robotics,machine-learning,data-quality,imitation-learning,lerobot
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
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
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: scipy>=1.10
Requires-Dist: huggingface-hub>=0.20
Provides-Extra: vision
Requires-Dist: torch>=2.0; extra == "vision"
Requires-Dist: transformers>=4.36; extra == "vision"
Requires-Dist: scikit-learn>=1.3; extra == "vision"
Requires-Dist: opencv-python>=4.8; extra == "vision"
Requires-Dist: decord>=0.6; extra == "vision"
Requires-Dist: Pillow>=10.0; extra == "vision"
Provides-Extra: vlm
Requires-Dist: google-generativeai>=0.5; extra == "vlm"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Provides-Extra: all
Requires-Dist: orbit-robotics[vision,vlm]; extra == "all"
Dynamic: license-file

# ORBIT

**Predict whether your robot learning data will actually train successfully.**

ORBIT analyzes your robot demonstration dataset and predicts your policy's success rate — before you spend hours training. It connects to any [LeRobot](https://huggingface.co/lerobot) dataset on HuggingFace Hub.

## Quick Start

```bash
pip install orbit-robotics
orbit analyze lerobot/aloha_sim_transfer_cube_human
```

## What You Get

- **Quality score** with component breakdown (position diversity, action diversity, consistency, temporal coverage)
- **Dead joint detection** — catches stuck servos that waste training compute
- **Gripper analysis** — continuous and discrete gripper detection via bimodal clustering
- **Directional bias detection** — distinguishes goal-directed motion from data collection problems
- **Calibrated success rate prediction** with confidence interval, benchmarked against 82 published results
- **Policy fit analysis** — ACT, Diffusion Policy, SmolVLA, DP3, BC, BC-RNN
- **Community comparison** against 82 benchmarked datasets from published papers
- **Actionable recommendations** with specific joint/episode numbers

## Commands

```bash
orbit analyze <dataset>                  # full analysis
orbit analyze <dataset> --json           # machine-readable output
orbit analyze <dataset> --policy act     # specific policy fit
orbit analyze <dataset> --skip-embeddings --skip-ai-assessment  # fast mode
orbit benchmark                          # browse 82 benchmark entries
orbit benchmark --task pick_and_place --min-success 0.7
orbit benchmark aloha --top 5
orbit plan "pick up cups" --robot so100 --policy act
```

## Policy Support

| Policy | Flag | Notes |
|--------|------|-------|
| ACT | `--policy act` | Action Chunking Transformer — needs consistent, high-res demos |
| Diffusion Policy | `--policy diffusion_policy` | Handles multimodal data well |
| SmolVLA | `--policy smolvla` | Vision-Language-Action — language-conditioned |
| DP3 | `--policy dp3` | 3D Diffusion Policy |
| BC | `--policy bc` | Behavioral Cloning baseline |
| BC-RNN | `--policy bc_rnn` | Recurrent Behavioral Cloning |

Use `--policy auto` (default) to let ORBIT recommend the best policy for your data.

## Robot Support

| Robot | Type | Arms |
|-------|------|------|
| SO-100 | Desktop arm | 1 |
| SO-101 | Desktop arm | 1 |
| Koch v1.1 | Desktop arm | 1 |
| ALOHA | Bimanual | 2 |
| xArm | Industrial | 1 |
| Custom | Any | `--robot custom` |

## Advanced Usage

### VLM-enhanced analysis

```bash
pip install orbit-robotics[vlm]
export GOOGLE_API_KEY=your_key
orbit analyze lerobot/aloha_sim_transfer_cube_human
```

Gemini Flash analyzes your observation frames to identify task type, failure modes, and difficulty — improving prediction accuracy.

### Embedding analysis

```bash
pip install orbit-robotics[vision]
orbit analyze lerobot/pusht
```

SigLIP embeddings measure visual diversity across episodes and detect outliers.

### JSON output

```bash
orbit analyze lerobot/pusht --json
```

### Policy comparison

```bash
orbit analyze lerobot/pusht --policy act
orbit analyze lerobot/pusht --policy diffusion_policy
```

## How It Works

ORBIT fetches dataset metadata and episode samples from HuggingFace Hub without downloading the full dataset. It runs signal diagnostics on every joint dimension to detect dead joints, clipping, and directional bias. Task complexity is estimated from action dimensionality, temporal structure, and coordination patterns. Policy fit scores how well your data matches the requirements of your chosen policy (episode count, consistency, action dimensions). All factors feed into a calibrated predictor benchmarked against 82 ground truth results from published papers (ACT, Diffusion Policy, BC variants across Push-T, ALOHA, RoboMimic, and more).

## Install Options

```bash
pip install orbit-robotics          # Core analysis (no GPU needed)
pip install orbit-robotics[vision]  # + SigLIP embedding analysis
pip install orbit-robotics[vlm]     # + Gemini VLM task analysis
pip install orbit-robotics[all]     # Everything
```

## Citation

```bibtex
@software{orbit2026,
  title  = {ORBIT: Predict Robot Policy Success from Training Data},
  author = {Lasne, Rahil},
  year   = {2026},
  url    = {https://github.com/Rahillasne/orbit-robotics}
}
```

## License

MIT — see [LICENSE](LICENSE) for details.
