Metadata-Version: 2.4
Name: orbit-robotics
Version: 0.3.0
Summary: Data engineering copilot for robot imitation learning datasets
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
Requires-Dist: pyarrow>=14.0
Requires-Dist: scikit-learn>=1.3
Provides-Extra: vision
Requires-Dist: torch>=2.0; extra == "vision"
Requires-Dist: transformers>=4.36; 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

Orbit analyzes your robot training data and tells you what's wrong before you waste 8 hours training.

```bash
pip install orbit-robotics
orbit analyze lerobot/your-dataset
```

## The Workflow

### 1. Analyze your dataset

```bash
orbit analyze lerobot/xarm_lift_medium
```

```
Dataset Readiness: C (score: 65/100)
Usable but has problems — run orbit clean first

  ✓ High consistency (1.00)
  ✓ Sufficient episodes (800) for diffusion_policy
  ✓ Good policy fit (1.00)
  ✗ 4 joints clipping (>10% of frames)
  ✗ High action divergence (0.46) — demos contradict each other in similar states

YOUR DATA AT A GLANCE
  Episodes:       800     (top 25%)
  Coverage:       0.84  ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░
  Signal Health:  0.00  ░░░░░░░░░░░░░░░░░░░░░░░░░
```

### 2. Clean bad episodes

```bash
orbit clean lerobot/xarm_lift_medium --dry-run
```

```
┌────────────────────┬──────────┐
│ Original episodes  │ 800      │
│ Episodes to remove │ 0 (0%)   │
│ Episodes to keep   │ 800      │
│ Dead joints        │ 0 of 4   │
│ Quality            │ 71 → 71  │
└────────────────────┴──────────┘
```

When bad episodes are found, `orbit clean` removes them using the LeRobot API and tells you exactly what was wrong with each one.

### 3. Get a training command

```bash
orbit suggest lerobot/xarm_lift_medium
```

```
Recommended: Diffusion Policy (fit: 1.00)
┌─────────────┬──────────────────────┐
│ Episodes    │ 800                  │
│ Cameras     │ 1 x 480p             │
│ Action dims │ 4                    │
│ FPS         │ 15                   │
│ Alternative │ SmolVLA (fit: 1.00)  │
└─────────────┴──────────────────────┘

lerobot-train \
  --dataset.repo_id=lerobot/xarm_lift_medium \
  --policy.type=diffusion_policy \
  --batch_size=32 \
  --steps=500000 \
  --policy.horizon=4 \
  ...
```

## What Orbit Catches

- **Dead servos** that stopped moving during data collection — wasting model capacity learning zero outputs
- **Aborted or corrupted episodes** that are too short, too long, or have no meaningful motion
- **Clipping joints** hitting their position limits, which creates discontinuous action targets
- **Inconsistent demonstrations** where you did different things in similar states, confusing behavior cloning
- **Wrong policy for your data** — ACT needs consistent demos, Diffusion Policy handles multimodal strategies, SmolVLA needs fewer episodes but wants cameras
- **Not enough data** for your chosen policy, with specific targets: ACT wants 50+, Diffusion Policy wants 100+, BC wants 200+
- **Timing problems** — frame drops, FPS jitter, and state-action lag from slow teleoperation setups
- **Low workspace coverage** — demonstrations that only cover a narrow region of the task space

## More Commands

```bash
# Plan a data collection session
orbit plan "pick up cups" --robot so100 --policy act

# Diagnose training failures from logs
orbit debug outputs/train/my-run

# Browse 82 published benchmarks
orbit benchmark --task pick_and_place --min-success 0.7

# Track progress against your collection plan
orbit track lerobot/my-dataset

# JSON output for scripting
orbit analyze lerobot/my-dataset --json

# Deep AI analysis (requires API key)
orbit analyze lerobot/my-dataset --deep
```

## Policy Support

| Policy | Flag | Best for |
|--------|------|----------|
| ACT | `--policy act` | Consistent, high-res demos (50+ episodes) |
| Diffusion Policy | `--policy diffusion_policy` | Multimodal strategies (100+ episodes) |
| SmolVLA | `--policy smolvla` | Vision-language tasks, fewer episodes needed |
| DP3 | `--policy dp3` | 3D point cloud observations |
| BC / BC-RNN | `--policy bc` | Large datasets (200+ episodes) |

`--policy auto` (default) recommends the best policy for your data.

## Install

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

## License

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