Metadata-Version: 2.5
Name: so101-nexus
Version: 0.12.0
Summary: End-to-end simulation and training stack for the SO-101 arm: record demonstrations, clone behavior, and reinforce with GPU-parallel MuJoCo / MuJoCo Warp environments, built on LeRobot
License-Expression: Apache-2.0
License-File: LICENSE.md
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: gymnasium<2,>=1.0.0
Requires-Dist: huggingface-hub<2
Requires-Dist: mujoco<4,>=3.17.0
Requires-Dist: numpy<3
Requires-Dist: platformdirs<5,>=4
Requires-Dist: scipy<2
Requires-Dist: trimesh<5
Requires-Dist: tyro<2,>=0.9.0
Provides-Extra: decomp
Requires-Dist: coacd<2,>=1.0.13; extra == 'decomp'
Requires-Dist: rtree<2,>=1.4; extra == 'decomp'
Requires-Dist: threadpoolctl<4,>=3.1; extra == 'decomp'
Provides-Extra: dm05
Requires-Dist: lerobot[dm05,peft-dep]<0.8,>=0.7.0; extra == 'dm05'
Requires-Dist: transformers<5.23,>=5.22.0; extra == 'dm05'
Provides-Extra: molmoact2
Requires-Dist: lerobot[molmoact2]<0.8,>=0.7.0; extra == 'molmoact2'
Requires-Dist: transformers<5.23,>=5.22.0; extra == 'molmoact2'
Provides-Extra: rocm
Requires-Dist: pytorch-triton-rocm; (sys_platform == 'linux' and platform_machine == 'x86_64') and extra == 'rocm'
Requires-Dist: torch; (sys_platform == 'linux' and platform_machine == 'x86_64') and extra == 'rocm'
Requires-Dist: triton-rocm; (sys_platform == 'linux' and platform_machine == 'x86_64') and extra == 'rocm'
Provides-Extra: sysid
Requires-Dist: mujoco[sysid]<4,>=3.17.0; extra == 'sysid'
Provides-Extra: teleop
Requires-Dist: gradio>=5.0.0; extra == 'teleop'
Requires-Dist: lerobot[dataset,feetech,placo-dep]<0.8,>=0.7.0; extra == 'teleop'
Requires-Dist: opencv-python>=4.8.0; extra == 'teleop'
Requires-Dist: pillow; extra == 'teleop'
Requires-Dist: plotly>=6.0.0; extra == 'teleop'
Provides-Extra: train
Requires-Dist: tensorboard>=2.0.0; extra == 'train'
Requires-Dist: torch; extra == 'train'
Requires-Dist: wandb[media]>=0.16.0; extra == 'train'
Provides-Extra: viz
Requires-Dist: pillow; extra == 'viz'
Provides-Extra: warp
Requires-Dist: mujoco-warp<4,>=3.13.0; extra == 'warp'
Requires-Dist: torch<2.10; (sys_platform != 'linux' or (platform_machine != 'aarch64' and platform_machine != 'arm64')) and extra == 'warp'
Requires-Dist: torch<2.12,>=2.11; (sys_platform == 'linux' and (platform_machine == 'aarch64' or platform_machine == 'arm64')) and extra == 'warp'
Requires-Dist: warp-lang<1.16,>=1.15; extra == 'warp'
Description-Content-Type: text/markdown

<div align="center">

<img src="https://raw.githubusercontent.com/johnsutor/so101-nexus/main/assets/so101.png" width="250" alt="SO-101 Arm">

<h3>SO101-Nexus: from demonstrations to a trained policy</h3>

[Docs](https://so101-nexus.com/docs) · [Releases](https://github.com/johnsutor/so101-nexus/releases) · [Discord](https://discord.gg/37kKRXDh8)

</div>

**Record. Clone. Reinforce.** Control a simulated SO-101 with an SO-100 or SO-101 leader arm,
record [LeRobot](https://github.com/huggingface/lerobot) demonstrations, train with behavior cloning,
then fine-tune with reinforcement learning. One Python library connects the workflow.

## Get started

With Python 3.12 or newer, install the library:

```bash
pip install so101-nexus
```

Run a simulated robot. No hardware is required:

```python
import gymnasium as gym
import so101_nexus.mujoco  # registers the MuJoCo environments

env = gym.make("MuJoCoPickLift-v1", render_mode="human")
obs, info = env.reset(seed=0)
env.action_space.seed(0)

for _ in range(1000):
    obs, reward, terminated, truncated, info = env.step(env.action_space.sample())
    if terminated or truncated:
        obs, info = env.reset()

env.close()
```

See [Installation](https://so101-nexus.com/docs/getting-started/installation) for optional extras and source setup.
The [Quickstart](https://so101-nexus.com/docs/getting-started/quickstart) explains the example and shows how to change objects.

To train without a local setup, open the
[BC + PPO Colab notebook](https://colab.research.google.com/github/johnsutor/so101-nexus/blob/main/examples/bc_ppo_warp_colab.ipynb).
Select a GPU runtime and run all cells with the published demonstrations.

## From demonstrations to policy

1. [Record](https://so101-nexus.com/docs/workflow/teleoperation) demonstrations with a leader arm.
2. [Clone](https://so101-nexus.com/docs/workflow/training) the demonstrations with behavior cloning.
3. [Reinforce](https://so101-nexus.com/docs/workflow/training#recommended-commands) the policy with GPU-parallel PPO.

[Environments](https://so101-nexus.com/docs/environments) lists the tasks.
[Examples](examples/README.md) lists the scripts and notebooks.
MuJoCo provides Gymnasium simulation and CPU batching. The optional Warp backend provides GPU batching.
See [Backends](https://so101-nexus.com/docs/concepts/backends) for requirements and physics differences.

This library is in beta. See [Stability and versioning](https://so101-nexus.com/docs/api/stability) before you depend on an API.

## Contribute

Follow the [source installation guide](https://so101-nexus.com/docs/getting-started/installation#install-from-source), then run:

```bash
make format lint typecheck
make test
```

See [CONTRIBUTING.md](CONTRIBUTING.md). Source code uses the [Apache-2.0 License](LICENSE.md).
