orbit-robotics 0.2.0__tar.gz

orbit_robotics-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rahil Lasne
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

orbit_robotics-0.2.0/PKG-INFO

@@ -0,0 +1,164 @@
+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.

orbit_robotics-0.2.0/README.md

@@ -0,0 +1,122 @@
+# 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.

orbit_robotics-0.2.0/pyproject.toml

@@ -0,0 +1,86 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "orbit-robotics"
+version = "0.2.0"
+description = "Predict whether your robot learning data will actually train successfully"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    {name = "Rahil Lasne"},
+]
+keywords = ["robotics", "machine-learning", "data-quality", "imitation-learning", "lerobot"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "click>=8.0",
+    "rich>=13.0",
+    "numpy>=1.24",
+    "pandas>=2.0",
+    "scipy>=1.10",
+    "huggingface-hub>=0.20",
+]
+
+[project.optional-dependencies]
+vision = [
+    "torch>=2.0",
+    "transformers>=4.36",
+    "scikit-learn>=1.3",
+    "opencv-python>=4.8",
+    "decord>=0.6",
+    "Pillow>=10.0",
+]
+vlm = [
+    "google-generativeai>=0.5",
+]
+dev = [
+    "pytest>=7.0",
+    "ruff>=0.1",
+]
+all = [
+    "orbit-robotics[vision,vlm]",
+]
+
+[project.urls]
+Homepage = "https://github.com/Rahillasne/orbit-robotics"
+Repository = "https://github.com/Rahillasne/orbit-robotics"
+Issues = "https://github.com/Rahillasne/orbit-robotics/issues"
+
+[project.scripts]
+orbit = "orbit.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+orbit = ["planner/templates/*.json", "planner/robot_configs/*.json", "analyzer/data/*.json"]
+
+[tool.ruff]
+target-version = "py310"
+src = ["src"]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "UP"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "integration: marks tests as integration tests (require torch/transformers)",
+]
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false

orbit_robotics-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

orbit_robotics-0.2.0/src/orbit/__init__.py

@@ -0,0 +1,3 @@
+"""orbit-robotics: Data strategy copilot for robot policy training."""
+
+__version__ = "0.1.0"

orbit_robotics-0.2.0/src/orbit/analyzer/community_comparison.py

@@ -0,0 +1,220 @@
+"""Community comparison — compare a dataset against the benchmark database.
+
+Finds similar entries by task_type and robot_type, then produces a structured
+comparison showing how the user's dataset stacks up against successful peers.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+GROUND_TRUTH_PATH = Path(__file__).parent / "data" / "ground_truth_condensed.json"
+
+
+@dataclass
+class PeerEntry:
+    """A single benchmark peer for display."""
+
+    id: str
+    dataset: str
+    num_episodes: int
+    success_rate: float
+    policy: str
+    task_type: str
+
+
+@dataclass
+class CommunityComparison:
+    """Result of comparing a dataset against the benchmark database."""
+
+    similar_successful: list[PeerEntry]  # peers with >70% success
+    similar_all: list[PeerEntry]  # all matched peers (for stats)
+    your_episodes: int
+    peer_avg_episodes: float
+    your_episode_percentile: str  # "bottom 25%", "middle 50%", etc.
+    your_coverage: float | None  # overall coverage-like metric
+    peer_avg_coverage: float | None
+    actionable_tip: str  # one-liner recommendation
+
+
+def compute_community_comparison(
+    dataset_name: str,
+    task_type: str | None,
+    robot_type: str | None,
+    num_episodes: int,
+    coverage_score: float | None = None,
+    policy_type: str | None = None,
+) -> CommunityComparison | None:
+    """Find similar benchmark entries and build a comparison.
+
+    Returns None if the benchmark database can't be loaded or no similar
+    entries are found.
+    """
+    try:
+        with open(GROUND_TRUTH_PATH) as f:
+            ground_truth: list[dict] = json.load(f)
+    except (FileNotFoundError, json.JSONDecodeError) as e:
+        logger.warning("Failed to load benchmark database: %s", e)
+        return None
+
+    if not ground_truth:
+        return None
+
+    # Score each entry for similarity
+    scored: list[tuple[float, dict]] = []
+    task_lower = (task_type or "").lower()
+    robot_lower = (robot_type or "").lower()
+    dataset_lower = dataset_name.lower()
+
+    for entry in ground_truth:
+        score = 0.0
+        entry_task = entry.get("task_type", "").lower()
+        entry_summary = entry.get("features_summary", "").lower()
+
+        # Task type match (strongest signal)
+        if task_lower and task_lower == entry_task:
+            score += 5.0
+        elif task_lower and task_lower in entry_task:
+            score += 3.0
+
+        # Robot type / bimanual matching via summary
+        if robot_lower:
+            if robot_lower in entry_summary:
+                score += 3.0
+            elif "aloha" in robot_lower and "bimanual" in entry_summary:
+                score += 2.0
+            elif "aloha" in dataset_lower and "aloha" in entry.get("id", "").lower():
+                score += 3.0
+
+        # Dataset name keyword overlap
+        name_parts = [
+            p for p in dataset_lower.replace("/", " ").replace("_", " ").split()
+            if len(p) > 2 and p not in ("sim", "the", "and", "lerobot")
+        ]
+        for part in name_parts:
+            if part in entry.get("id", "").lower() or part in entry_summary:
+                score += 1.0
+
+        if score > 0:
+            scored.append((score, entry))
+
+    if not scored:
+        return None
+
+    # Sort by score, take top 5
+    scored.sort(key=lambda x: -x[0])
+    top_entries = [e for _, e in scored[:5]]
+
+    if len(top_entries) < 1:
+        return None
+
+    # Build peer entries
+    all_peers = [
+        PeerEntry(
+            id=e["id"],
+            dataset=e["dataset"],
+            num_episodes=e.get("num_episodes", 0),
+            success_rate=e.get("success_rate", 0.0),
+            policy=e.get("policy", "unknown"),
+            task_type=e.get("task_type", "unknown"),
+        )
+        for e in top_entries
+    ]
+
+    successful_peers = [p for p in all_peers if p.success_rate >= 0.70]
+
+    # Compute stats from all peers
+    peer_episodes = [p.num_episodes for p in all_peers if p.num_episodes > 0]
+    peer_avg_ep = sum(peer_episodes) / len(peer_episodes) if peer_episodes else 0
+
+    # Episode percentile
+    if peer_episodes:
+        below = sum(1 for ep in peer_episodes if num_episodes < ep)
+        ratio = below / len(peer_episodes)
+        if ratio >= 0.75:
+            percentile = "bottom 25%"
+        elif ratio >= 0.50:
+            percentile = "below average"
+        elif ratio >= 0.25:
+            percentile = "above average"
+        else:
+            percentile = "top 25%"
+    else:
+        percentile = "unknown"
+
+    # Actionable tip
+    tip = _generate_tip(num_episodes, peer_avg_ep, successful_peers, coverage_score)
+
+    return CommunityComparison(
+        similar_successful=successful_peers,
+        similar_all=all_peers,
+        your_episodes=num_episodes,
+        peer_avg_episodes=peer_avg_ep,
+        your_episode_percentile=percentile,
+        your_coverage=coverage_score,
+        peer_avg_coverage=None,  # benchmark doesn't store coverage
+        actionable_tip=tip,
+    )
+
+
+def _generate_tip(
+    num_episodes: int,
+    peer_avg_ep: float,
+    successful_peers: list[PeerEntry],
+    coverage_score: float | None,
+) -> str:
+    """Generate one actionable recommendation from the comparison."""
+    if not successful_peers:
+        return "No similar datasets with >70% success found — you're pioneering this task type."
+
+    min_success_eps = min(p.num_episodes for p in successful_peers)
+    avg_success_eps = sum(p.num_episodes for p in successful_peers) / len(successful_peers)
+
+    if num_episodes < min_success_eps:
+        gap = int(min_success_eps - num_episodes)
+        return f"Collect ~{gap} more episodes to match the smallest successful peer ({min_success_eps} eps)."
+
+    if num_episodes < avg_success_eps * 0.8:
+        gap = int(avg_success_eps - num_episodes)
+        return f"Collect ~{gap} more episodes to match successful peers (avg {int(avg_success_eps)} eps)."
+
+    if coverage_score is not None and coverage_score < 0.70:
+        return "Episode count matches peers — focus on diversity (varied start positions, speeds, approaches)."
+
+    return "Your dataset size matches successful peers — focus on data quality and policy tuning."
+
+
+def comparison_to_dict(comp: CommunityComparison) -> dict:
+    """Convert to a JSON-serializable dict."""
+    return {
+        "similar_successful": [
+            {
+                "id": p.id,
+                "dataset": p.dataset,
+                "num_episodes": p.num_episodes,
+                "success_rate": p.success_rate,
+                "policy": p.policy,
+            }
+            for p in comp.similar_successful
+        ],
+        "similar_all": [
+            {
+                "id": p.id,
+                "dataset": p.dataset,
+                "num_episodes": p.num_episodes,
+                "success_rate": p.success_rate,
+                "policy": p.policy,
+                "task_type": p.task_type,
+            }
+            for p in comp.similar_all
+        ],
+        "your_episodes": comp.your_episodes,
+        "peer_avg_episodes": round(comp.peer_avg_episodes, 1),
+        "your_episode_percentile": comp.your_episode_percentile,
+        "actionable_tip": comp.actionable_tip,
+    }