Metadata-Version: 2.4
Name: lerobot-genesis
Version: 0.3.0
Summary: Run, record, and evaluate robot policies in the Genesis simulator through the standard LeRobot interfaces.
Project-URL: Homepage, https://github.com/arun-prasath2005/lerobot-genesis
Project-URL: Repository, https://github.com/arun-prasath2005/lerobot-genesis
Project-URL: Issues, https://github.com/arun-prasath2005/lerobot-genesis/issues
Author: Arun Prasath E G
License-Expression: MIT
License-File: LICENSE
Keywords: genesis,imitation-learning,lerobot,reinforcement-learning,robotics,simulation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: gymnasium>=1.0
Requires-Dist: numpy>=1.24
Provides-Extra: all
Requires-Dist: genesis-world>=0.2; extra == 'all'
Requires-Dist: lerobot>=0.4; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: genesis
Requires-Dist: genesis-world>=0.2; extra == 'genesis'
Provides-Extra: lerobot
Requires-Dist: lerobot>=0.4; extra == 'lerobot'
Description-Content-Type: text/markdown

# lerobot-genesis

[![CI](https://github.com/arun-prasath2005/lerobot-genesis/actions/workflows/ci.yml/badge.svg)](https://github.com/arun-prasath2005/lerobot-genesis/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/lerobot-genesis.svg)](https://pypi.org/project/lerobot-genesis/)
[![Python](https://img.shields.io/pypi/pyversions/lerobot-genesis.svg)](https://pypi.org/project/lerobot-genesis/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

The bridge between the [Genesis](https://github.com/Genesis-Embodied-AI/Genesis) physics
simulator and Hugging Face [LeRobot](https://github.com/huggingface/lerobot).

Genesis is a fast, open robotics simulator; LeRobot is the open standard for robot datasets and
policies. There is no official link between them — this package is that link, the same role
NVIDIA's *IsaacLab-Arena* plays for Isaac Lab. It lets you expose any Genesis scene as a
Gymnasium environment, record rollouts as a `LeRobotDataset`, and (from `v0.2`) evaluate a trained
LeRobot policy in Genesis through the standard `lerobot-eval` workflow.

```text
   Genesis scene ──▶ GenesisEnv (gym.Env) ──▶ LeRobotDataset ──▶ train a LeRobot policy
                          ▲                                              │
                          └────────────────── lerobot-eval ◀────────────┘   (v0.2)
```

## Install

```bash
pip install "lerobot-genesis[all]"   # bridge + genesis-world + lerobot
```

`genesis-world` needs a CUDA GPU and a few system libraries — see the
[Genesis install guide](https://genesis-world.readthedocs.io). The bridge itself is pure Python;
`pip install lerobot-genesis` (no extras) imports without either heavy dependency present.

## Quickstart — record a dataset

Drive a robot in a Genesis scene and save the rollout in LeRobot's format:

```python
from lerobot_genesis import GenesisEnv, GenesisRobotDriver, LeRobotDatasetSink, record_episodes

driver = GenesisRobotDriver(robot="path/to/robot.urdf")          # any URDF / MJCF / USD
env = GenesisEnv(driver, task="reach the target")
sink = LeRobotDatasetSink(
    "me/my-genesis-dataset",
    fps=30,
    state_dim=driver.state_dim,
    action_dim=driver.action_dim,
    image_shape=driver.image_shape,
    task="reach the target",
)

record_episodes(env, policy=lambda obs: env.action_space.sample(), sink=sink, n_episodes=10)
```

A runnable end-to-end example (a Franka arm, no asset download) lives in
[`examples/record_franka.py`](examples/record_franka.py).

## Quickstart — evaluate a policy in Genesis

`lerobot-genesis-eval` is `lerobot-eval` with the Genesis env registered, so a LeRobot policy
(ACT, SmolVLA, GR00T, …) can be rolled out in a Genesis scene. Smoke-test the wiring with a
from-scratch policy (no checkpoint needed):

```bash
lerobot-genesis-eval --env.type=genesis --policy.type=act \
    --eval.batch_size=1 --eval.n_episodes=1 --eval.use_async_envs=false --policy.device=cpu
```

Point `--policy.path` at a trained checkpoint to score it, and `--env.task` at your own registered
Genesis task. Training GR00T? `lerobot_genesis.groot.write_modality_json` emits the `meta/modality.json`
it needs.

## How it's designed

The simulator-specific work sits behind one small `Protocol`, so the Gymnasium contract and the
recorder are testable on a CPU with no GPU and no upstream installed.

- **`GenesisEnv`** — a `gymnasium.Env` over a Genesis scene. It owns the gym contract (the 5-tuple
  step, `info["is_success"]`, the `pixels`/`agent_pos` observation, a continuous action `Box`) and
  delegates the physics to an injected **`SceneDriver`**.
- **`GenesisRobotDriver`** — the reference `SceneDriver`: loads a robot, maps a normalised action
  onto a chosen subset of joints, steps physics, and reads a camera and joint state. Bring your own
  driver for richer scenes (objects, tasks, rewards).
- **`record_episodes` / `LeRobotDatasetSink`** — roll a policy and write a `LeRobotDataset`
  (the verified v3 `create → add_frame → save_episode → finalize` loop).
- **`GenesisEnvConfig`** — registers Genesis with LeRobot as `--env.type=genesis`.

## Relationship to `gym-genesis`

Hugging Face's [`gym-genesis`](https://github.com/huggingface/gym-genesis) provides raw Gymnasium
task scenes for Genesis. This package is complementary: it adds the LeRobot integration layer —
dataset recording, env registration, and policy evaluation — and can wrap a `gym-genesis` env just
as well as your own.

## Roadmap

- **v0.1** — `GenesisEnv`, reference driver, `LeRobotDataset` recorder, `--env.type=genesis`.
- **v0.2** — EnvHub `make_env` + `lerobot-eval` policy evaluation; GR00T `modality.json` adapter;
  native vectorised (multi-env) rollouts.

## License

[MIT](LICENSE). An independent, community project — not affiliated with the Genesis or LeRobot teams.
