simrig 0.2.2__tar.gz → 0.4.0__tar.gz

simrig-0.4.0/PKG-INFO

@@ -0,0 +1,426 @@
+Metadata-Version: 2.4
+Name: simrig
+Version: 0.4.0
+Summary: Agent- and human-friendly workflows for MuJoCo Playground training and evaluation.
+Author: SimRig contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Su1eym4n/simrig
+Project-URL: Repository, https://github.com/Su1eym4n/simrig
+Project-URL: Issues, https://github.com/Su1eym4n/simrig/issues
+Project-URL: Changelog, https://github.com/Su1eym4n/simrig/blob/main/CHANGELOG.md
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: mujoco
+Requires-Dist: mujoco; extra == "mujoco"
+Provides-Extra: hf
+Requires-Dist: huggingface_hub; extra == "hf"
+Provides-Extra: playground
+Requires-Dist: gymnasium[mujoco]==1.3.0; extra == "playground"
+Requires-Dist: mujoco==3.10.0; extra == "playground"
+Requires-Dist: mujoco-mjx==3.10.0; extra == "playground"
+Requires-Dist: jax==0.10.2; extra == "playground"
+Requires-Dist: brax==0.14.2; extra == "playground"
+Requires-Dist: playground==0.2.0; extra == "playground"
+Requires-Dist: warp-lang==1.13.0; extra == "playground"
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: numpy; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# SimRig
+
+<div align="center">
+
+<img src="assets/g1-greeting.gif" alt="Unitree G1 waving hello in SimRig's interactive browser preview" width="100%">
+
+<br>
+
+<em>A pretrained Unitree G1 policy preview with a scripted greeting.</em>
+
+</div>
+
+Turn MuJoCo robots into trained policies with agent-guided task design, PPO
+training, evaluation, and interactive previews.
+
+SimRig combines:
+
+- a Python CLI that inspects models, runs MuJoCo Playground environments,
+  trains Brax PPO policies, evaluates checkpoints, and serves previews;
+- an agent skill that teaches Codex, Claude Code, and Cursor how to use that
+  pipeline safely.
+
+Raw robot XML is not automatically a training task. SimRig helps the agent move
+from a model and a requested behavior to explicit observations, actions,
+rewards, resets, termination conditions, validation, training, and evaluation.
+
+## From prompt to simulation
+
+### Train Go1 through a smoke-gated cloud workflow
+
+SimRig prepares the existing Go1 locomotion environment and runs local smoke
+tests before requesting the user's Lambda Cloud details. The full cloud run
+starts only after that handoff. The recorded result below shows the trained
+checkpoint downloaded and running in SimRig's interactive browser preview.
+
+<details>
+<summary><strong>Prompt</strong></summary>
+
+> Prepare the full Go1 robot training setup and run local smoke tests to verify
+> everything works. Once the tests pass, ask me for my Lambda Cloud details
+> before starting the full training run.
+
+</details>
+
+<img src="assets/go1-training.gif" alt="Codex running a smoke-gated Go1 training workflow and previewing the trained policy in SimRig" width="100%">
+
+### Trace a five-pointed star with Franka Panda
+
+This example uses a directly scripted Cartesian trajectory and inverse
+kinematics—no reinforcement learning is needed. The controller keeps the
+end-effector orientation fixed, moves smoothly between star vertices, and
+publishes the running simulation and visible trace through SimRig's browser
+viewer.
+
+<details>
+<summary><strong>Prompt</strong></summary>
+
+> Can you configure a Franka Panda robotic arm in simulation so that its end
+> effector traces a five-pointed star trajectory?
+>
+> Please:
+>
+> - Use the Franka Panda arm and gripper.
+> - Move the end effector along a clear five-pointed star path in Cartesian
+>   space.
+> - Keep the end-effector orientation fixed and stable throughout the motion.
+> - Use inverse kinematics, trajectory planning, or a direct scripted controller
+>   rather than reinforcement learning unless training is genuinely necessary.
+> - Add a visible trajectory trace, marker, or drawing surface so the completed
+>   star can be verified.
+> - Make the motion smooth, with controlled velocity and acceleration between
+>   each star vertex.
+> - Provide the complete runnable script and all required launch commands.
+> - Explain how to modify the star size, star position, drawing plane,
+>   end-effector height, motion speed, and number of repetitions.
+> - State clearly whether the solution is directly scripted or trained, and
+>   explain why that method is appropriate.
+> - Prefer the simplest reliable direct-control implementation.
+
+</details>
+
+<img src="assets/franka-panda-star.gif" alt="Codex configuring a Franka Panda arm to trace a five-pointed star in SimRig's browser viewer" width="100%">
+
+## What SimRig can do
+
+| Goal | SimRig workflow |
+|---|---|
+| Train a known Playground robot | Inspect the environment, smoke-test it, train, evaluate, and preview |
+| Use a custom MJCF/XML robot | Inspect the model, define the task, create an editable environment, then validate and train |
+| Build locomotion or posture behaviors | Design command tracking, contacts, rewards, failures, and evaluation scenarios |
+| Build custom scenes | Add terrain, props, targets, sensors, cameras, or contact rules in ordinary MJCF and Python |
+| Evaluate an existing policy | Run reproducible headless rollouts and open a browser or native MuJoCo preview |
+
+SimRig v0 uses MuJoCo and MuJoCo Playground. Isaac Lab is not currently a
+supported backend.
+
+## Installation
+
+SimRig requires Python 3.11 or newer. Install the Playground training stack
+from PyPI:
+
+```bash
+python3.12 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install "simrig[playground]"
+
+simrig --version
+```
+
+For an editable source installation, clone the repository and install from its
+root instead:
+
+```bash
+git clone https://github.com/Su1eym4n/simrig.git
+cd simrig
+python3.12 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e ".[playground]"
+```
+
+Development dependencies, tests, and contribution checks are documented in
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Install the agent skill
+
+Inside this repository, Codex discovers the SimRig skill automatically through
+`.agents/skills/simrig`.
+
+To make the skill available from any project, install it globally with the
+Skills CLI:
+
+```bash
+npx skills add Su1eym4n/simrig --skill simrig --global
+```
+
+The installer supports Codex, Claude Code, Cursor, and other agents. Restart the
+agent after installation. See
+[Agent skill installation](docs/skill-installation.md) for provider-specific
+commands, manual installation, and troubleshooting.
+
+## Use SimRig
+
+Open a project containing a MuJoCo robot or scene and ask the agent naturally:
+
+> Train this MuJoCo robot to walk forward.
+
+> Create a crouching task for this robot, smoke-test it, and start a small
+> training run.
+
+> Evaluate this checkpoint across five seeds and preview the policy.
+
+You can invoke the workflow explicitly with `$simrig`, but the skill can also
+activate automatically when the request matches its description.
+
+### Existing Playground environment
+
+```bash
+simrig list-envs --backend mujoco-playground
+simrig inspect-env Go1JoystickFlatTerrain
+simrig smoke Go1JoystickFlatTerrain --steps 10
+simrig train Go1JoystickFlatTerrain --preset smoke --impl auto --seed 0
+```
+
+Use the `smoke` preset before a longer `local` or `cloud` configuration.
+For registered Playground environments, SimRig starts from the environment's
+tuned Brax PPO/network configuration and declared domain randomizer, then
+bounds the expensive dimensions for `smoke` or `local`. The `cloud` preset uses
+the full upstream task configuration unless you pass explicit overrides.
+
+`--impl auto` uses the environment's default implementation when supported. It
+selects MuJoCo Warp on a JAX-visible GPU when the environment defaults to Warp,
+and falls back to JAX on CPU-only hosts. Use `--impl jax` or `--impl warp` to
+make the choice explicit. Disable an available randomizer only for a deliberate
+baseline with `--no-domain-randomization`.
+
+### Custom robot or scene
+
+Inspect the model before designing a task:
+
+```bash
+simrig inspect-model path/to/robot.xml --save-report
+simrig view-model path/to/robot.xml --port 8766
+```
+
+Open `http://127.0.0.1:8766/` to inspect the compiled model, orbit/zoom/pan the
+camera, and adjust named joints. The default `threejs` renderer sends MuJoCo's
+visual meshes and primitives to a GPU-accelerated WebGL scene, so camera motion
+stays smooth. When the MJCF contains named cameras, the page also shows a
+**Robot View** inset. Its default **Emulated** mode uses a second Three.js camera
+with the compiled MuJoCo camera's live world pose and vertical field of view,
+giving it the same visual design as the orbit view. Switch to **Sensor** for the
+native MuJoCo offscreen image, use the camera dropdown to switch cameras, or
+choose the initial camera with `--camera NAME`. The inset follows joint-slider
+changes while the main Three.js camera remains freely movable. The emulation is
+for human inspection; vision policies train on MJX/Warp pixels, not this WebGL
+render. If the MJCF defines a keyframe, the viewer starts from its first
+authored pose and **Reset Joints** restores it.
+
+The Three.js modules are pinned and loaded from jsDelivr, so the default viewer
+needs an internet connection when the page first loads. For an entirely local
+MuJoCo-rendered image stream, use:
+
+```bash
+simrig view-model path/to/robot.xml --render-mode mujoco --port 8766
+```
+
+Use `--render-mode topdown` only for the schematic debugging fallback.
+
+### View a running MuJoCo script
+
+Standalone controllers can publish the `MjModel` and `MjData` they already own
+to the same Three.js viewer. SimRig does not step, pause, or replay the script:
+
+```python
+from simrig import LiveWebViewer
+
+with LiveWebViewer(
+    model,
+    data,
+    name="my controller",
+    tracking_body="end_effector",
+) as web:
+    while running:
+        with web.lock:
+            data.ctrl[:] = controller(data)
+            mujoco.mj_step(model, data)
+            web.sync(phase="moving")
+```
+
+Open the printed `http://127.0.0.1:8767/` URL. The page receives lightweight
+geom transforms while the Python script retains full control of simulation
+timing and state. A named `tracking_body` also draws its live path. Use
+`wait_for_client()` when motion should begin only after the page is ready.
+
+After defining the task, scaffold and validate an editable environment:
+
+```bash
+simrig new-env my_task --model path/to/scene.xml --template mjx
+simrig validate-env envs/my_task.py
+simrig validate-env envs/my_task.py --runtime
+simrig smoke envs/my_task.py --steps 10
+simrig train envs/my_task.py --preset smoke --seed 0
+```
+
+The generated environment is a starter, not an invented task definition. The
+reward, observations, actions, resets, and termination logic remain explicit
+and editable in Python.
+
+### Train from rendered pixels
+
+Custom environments can declare a Brax vision CNN instead of the legacy MLP.
+The included cartpole example renders real 64x64 MuJoCo frames, stacks three
+grayscale frames, feeds pixels plus the previous action to the actor, and gives
+the critic additional simulator state:
+
+```bash
+# CPU-safe metadata check
+simrig validate-env examples/vision_cartpole.py --vision
+
+# These require a JAX-visible CUDA GPU and MuJoCo Warp.
+simrig validate-env examples/vision_cartpole.py --runtime --vision
+simrig smoke examples/vision_cartpole.py --steps 5
+simrig train examples/vision_cartpole.py --preset smoke \
+  --output runs/vision-cartpole-smoke
+```
+
+A vision module declares literal `NETWORK_SPEC`, `VISION_SPEC`, and
+`DEFAULT_CONFIG` mappings for import-free static validation. Runtime hooks
+`network_spec()`, `vision_spec()`, and optionally `training_config()` may enrich
+those declarations after dependencies are installed. SimRig persists the
+selected `network_type` and complete network factory in `config.json`, then
+reconstructs the same CNN for `eval`, `demo`, and `preview`. Checkpoints created
+before vision support remain MLP by default.
+
+#### Run the pretrained vision reference
+
+The published reference policy was trained for 5,079,040 PPO steps with a
+1,000-step episode horizon. It completed all 1,000 requested steps without
+termination for evaluation seeds 0 through 4. Install both optional extras so
+SimRig can run the Playground environment and resolve the Hub artifact:
+
+```bash
+python3.11 -m venv .venv
+.venv/bin/python -m pip install -e ".[playground,hf]"
+
+.venv/bin/simrig eval \
+  hf://ssuleiman/simrig-vision-cartpole/policy.params \
+  --env examples/vision_cartpole.py \
+  --hf-revision v1 \
+  --steps 1000 \
+  --seed 0
+
+.venv/bin/simrig preview \
+  hf://ssuleiman/simrig-vision-cartpole/policy.params \
+  --env examples/vision_cartpole.py \
+  --hf-revision v1 \
+  --auto-reset \
+  --port 8765
+```
+
+Both commands require a JAX-visible CUDA GPU and MuJoCo Warp. Hub resolution
+downloads `policy.params` with its sibling `config.json` so SimRig can rebuild
+the recorded vision CNN. Exact evaluation should use the recorded Python and
+package versions. `--allow-runtime-mismatch` is only for an explicitly
+qualitative preview on a different compatible runtime. The checkpoint,
+training configuration, metrics, environment snapshot, and five-seed report
+are published at
+[ssuleiman/simrig-vision-cartpole](https://huggingface.co/ssuleiman/simrig-vision-cartpole).
+
+### Evaluate and preview
+
+```bash
+simrig eval runs/<run-dir>/policy.params \
+  --env Go1JoystickFlatTerrain \
+  --steps 500 \
+  --seed 0 \
+  --command 0.5 0.0 0.0
+
+simrig preview runs/<run-dir>/policy.params \
+  --env Go1JoystickFlatTerrain \
+  --command 0.5 0.0 0.0 \
+  --auto-reset \
+  --port 8765
+```
+
+Open `http://127.0.0.1:8765/` to orbit, zoom, pan, change supported commands,
+toggle automatic episode reset, pause, and inspect the live rollout. Preview
+uses the Three.js renderer by default: the
+policy advances on a server-side rollout clock while lightweight MuJoCo geom
+transforms update the browser scene. The camera follows the robot without
+coupling policy stepping to display rendering. Environments with named MuJoCo
+cameras also get a **Robot View** inset, selectable without moving the human
+orbit camera. **Emulated** renders the live authored camera pose and FOV in the
+same Three.js scene; **Sensor** shows the native MuJoCo offscreen image for
+comparison. Neither changes policy input: training and rollout inference keep
+using the environment's configured observation pipeline. Use
+`--render-mode mujoco` for the older full-page local image stream or
+`--render-mode topdown` for the schematic fallback.
+
+### Train on a Lambda Cloud GPU
+
+After launching a Lambda On-Demand instance with an SSH key, SimRig can connect,
+sync this checkout, verify JAX GPU visibility, train, monitor a detached run,
+and download its artifacts:
+
+```bash
+simrig cloud lambda connect INSTANCE_IP --identity ~/Downloads/lambda-key.pem
+simrig cloud lambda prepare INSTANCE_IP --identity ~/Downloads/lambda-key.pem
+simrig cloud lambda smoke INSTANCE_IP Go1JoystickFlatTerrain \
+  --identity ~/Downloads/lambda-key.pem
+simrig cloud lambda train INSTANCE_IP Go1JoystickFlatTerrain \
+  --identity ~/Downloads/lambda-key.pem \
+  --preset smoke \
+  --impl auto \
+  --seed 0
+```
+
+Only after the environment and PPO smoke gates pass, start a detached large
+run with `--preset cloud --detach`. SimRig operates on an instance you already
+provisioned; it never launches or terminates billable Lambda resources. See the
+complete [Lambda Cloud GPU guide](docs/lambda-cloud.md), including persistent
+storage, monitoring, artifact download, and shutdown reminders.
+
+Lambda preparation requires Python 3.11+ and installs a pinned Playground
+training stack. Every run records its resolved PPO/network configuration,
+implementation, seed, randomizer, source hashes, Git state, JAX devices,
+precision-related environment, and package versions. Checkpoint eval, demo, and
+preview reconstruct the recorded implementation and network, and reject a
+different runtime unless `--allow-runtime-mismatch` is explicitly selected for
+qualitative review.
+
+## Documentation
+
+- [Examples](examples/README.md)
+- [Agent workflow](docs/agent_workflow.md)
+- [Lambda Cloud GPU training](docs/lambda-cloud.md)
+- [Agent skill installation](docs/skill-installation.md)
+- [Contributing](CONTRIBUTING.md)
+- [SimRig skill source](skills/simrig/SKILL.md)
+
+## Outputs
+
+SimRig writes project-local artifacts:
+
+- `reports/` — model, environment, and evaluation reports
+- `runs/` — training configuration, metrics, checkpoints, and policy parameters
+- `envs/` — editable custom environment modules
+- `artifacts/` and `configs/` — user-managed outputs and configuration
+
+## License
+
+[MIT](LICENSE)