README.md

Explore robot control with Jev, local physics previews, and configurable tasks.

Open the interactive Decision Lab ↗

Demos · Quick start · How it works · Results · Task configs · 简体中文

Demos

Close the microwave	Close the top drawer
14 decisions · 111 environment steps MP4 · Full record	20 decisions · 155 environment steps MP4 · Full record
Grasp and lower alphabet soup into the basket
40 decisions · 314 environment steps MP4 · Full record

Three LIBERO task configurations share one control engine. Videos follow simulation time, with decision and physics-preview waiting omitted.

Explore the interactive replay — follow Jev’s choices and probabilities alongside each video ↗

Features

• Fine-grained control. 27 inputs covering Cartesian translations, wrist rotations, gripper open/close, and hold.
• Layered decisions. Jev selects an intent, a contact/motion family, and an input, with each choice informing the next.
• Local physics previews. Reversible simulator branches evaluate candidate effects before execution.
• Configurable tasks. Select measurements, exported features, contact rules, goals, and per-layer Jev inputs in JSON through one shared interface.
• Inspectable runs. Save model requests, predictions, controls, simulator states, costs, and trajectory media together.

Quick start

1 · Install

Use Python 3.10 or 3.11 in your preferred environment:

git clone https://github.com/Dimweaker/jev-libero.git
cd jev-libero
pip install -e .

jev-libero tasks
jev-libero inspect examples/records/top_drawer_seed1

The core package lets you browse tasks and recorded results. To run episodes, connect a LIBERO environment next.

2 · Connect LIBERO

Already have a compatible LIBERO / robosuite / MuJoCo environment? Keep your simulator dependencies, add the geometry libraries, and point the package to your checkout:

pip install python-fcl scipy
export LIBERO_ROOT=/path/to/LIBERO
export MUJOCO_GL=egl

pip install torch==2.2.0 --index-url https://download.pytorch.org/whl/cpu
pip install -e '.[robot]'

git clone https://github.com/Lifelong-Robot-Learning/LIBERO.git ../LIBERO
git -C ../LIBERO checkout 8f1084e3132a39270c3a13ebe37270a43ece2a01
export LIBERO_ROOT="$(cd ../LIBERO && pwd)"
export MUJOCO_GL=egl

Use EGL for off-screen rendering, or add --no-render to save controls and states without camera output. See setup for dependency and renderer options.

3 · Choose an API and run

Official TypeSafe API — get a key · API docs

export TYPESAFE_API_KEY_FILE=/path/to/private/typesafe.key
# Or set TYPESAFE_API_KEY in your environment.

jev-libero run --provider typesafe --task top_drawer --seed 1 \
  --out runs/drawer-s1 --max-decisions 100 --budget-usd 0.10

OpenRouter — get a key

export OPENROUTER_API_KEY_FILE=/path/to/private/openrouter.key
# Or set OPENROUTER_API_KEY in your environment.

jev-libero run --provider openrouter --task microwave --seed 1 \
  --out runs/microwave-s1 --max-decisions 100 --budget-usd 0.10

Both routes use the same control pipeline. TypeSafe calls /v1/systemone with jev-latest; OpenRouter uses typesafe/jev-1.13 and is the CLI default.

Choose a new output directory for each episode. --max-decisions bounds its length, and --budget-usd sets a client-side spending guard. Runs use paid API calls: OpenRouter reports costs directly; TypeSafe costs are estimated from token usage. API setup and billing details →

Configure your own task

Use the bundled tasks as starting points, or pass your own JSON file:

cp src/jev_libero/tasks/top_drawer.json my-task.json
# Edit the task binding, goals, measurements, and prompts.
jev-libero validate-task my-task.json
jev-libero run --provider typesafe --task my-task.json --out runs/custom

microwave.json, top_drawer.json, and alphabet_soup.json use the same measurement interface. measurements selects what to compute, features selects what to expose, and policy selects what each Jev layer receives; record_features selects per-step logging. No task-specific executor is needed. See the configuration guide.

Run the grasp task with:

jev-libero run --provider typesafe --task alphabet_soup --seed 1 \
  --out runs/soup-s1 --max-decisions 60 --budget-usd 0.03

How it works

flowchart LR
    S[Simulator state] --> P[Reversible physics previews]
    P --> C[Task effect criteria]
    C --> I[Jev: intent]
    I --> F[Jev: contact / motion family]
    F --> A[Jev: one atomic input]
    A --> E[Execute and observe]
    E --> S

The engine reads simulator state and previews each input for up to 8 environment steps / 0.4 simulation seconds. MuJoCo supplies the dynamics, FCL measures collision-shape distances, and the task configuration determines which effects qualify.

Jev chooses among those candidates. If a useful move needs repositioning first, two-step previews look for a route to the desired effect. The controller executes one selected input, observes the result, and chooses again.

Architecture and implementation details →

Recorded results

One recorded example passing the original LIBERO criterion per bundled task:

All use saved initial-state index 0. Microwave and drawer use OpenRouter; soup uses TypeSafe, with cost estimated from input-token pricing. Costs cover model calls. Run records and analysis →

Replay a recording

To inspect an existing trajectory, use the reference environment above and run:

jev-libero replay examples/records/top_drawer_seed1

Replay applies the saved controls and checks the resulting states and task outcome, without API calls. The environment reference lists the versions used to create these recordings.

Development

pip install -e '.[dev]'
ruff check src tests tools
ruff format --check src tests tools
pytest
pytest --simulation  # optional physics checks with LIBERO configured

Tests use mock or recorded API responses. The simulation suite covers control replay, geometry, snapshot restoration, and two-step previews.

src/jev_libero/      # API client, policy, simulator, and CLI
  tasks/            # bundled task definitions
examples/records/   # recorded episodes
tests/              # core and simulation tests
docs/               # guides and demo media

The Decision Lab website has its own static build and browser checks.

Want to report a bug or improve the code? See how to contribute.

Third-party acknowledgements · MIT License

Built on LIBERO, robosuite, MuJoCo, python-fcl, and TypeSafe Jev. Decision-interface inspiration: Typesafe Mario.