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 · 简体中文

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 ↗

• 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.

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.

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.

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 →

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

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 →

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 →

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.

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.