JEVANY / DOCUMENTATION

Games, robotics, and application examples

Open the playground

To run a model locally, choose a CPU or GPU model and open the Playground. Start with Try your own decision to edit a task and see the model's choices and probabilities; the environments below add live actions.

For the bundled replays, run from the repository root after creating the Python environment in the installation guide:

python -m pip install -e .
jevany demo

Open http://127.0.0.1:8090 if your browser does not open automatically. Replays work offline and need no GPU, model weights, Docker, or cloud account. Use --port 8091 to change the port or --no-open on a remote machine. For a remote host, forward the chosen port to your computer before opening the URL.

The playground has three modes:

All three replays are archived runs from an earlier compatible checkpoint, with the recorded option probabilities. Crafter uses model-selected objectives before each native action; the robot uses primitive Cartesian controls and a measured subgoal harness. Fresh runs execute and record the model's choices and their outcomes.

Play locally or connect your model

For both games:

python -m pip install -e '.[demo]'
jevany demo

Choose Play yourself and click the action controls. No inference server is needed. Change the seed and start a new run to change the initial world.

For multimodal decisions, start the model server with a shared image directory:

mkdir -p /tmp/jevany-media
JEVANY_MEDIA_ROOT=/tmp/jevany-media jevany serve \
  --checkpoint SimpleJev/JevAny-Qwen3.8-27B-LoRA --device cuda --dtype bf16

In a second terminal on the same host:

jevany demo --base-url http://127.0.0.1:8008 --media-root /tmp/jevany-media

Choose Run model, then One decision or Run automatically. Use Pause after this step to stop after the current request finishes. The environment pauses while inference runs; Doom does not keep advancing while waiting for the model. Each action then executes a bounded amount of simulation. The browser shows the result of the model's action and the returned probability for every candidate.

The demo writes each camera image under --media-root while inference runs, then removes the file. The model server must see that directory at the same path. A compatible server accepting inline images can omit --media-root. Use --text-only to send measurements without images; images remain visible in the browser. See the server setup for prerequisites. Use --model MODEL_ID to set the request's model identity and --timeout 300 if your server needs longer than the default 120 seconds per request. Hardware requirements belong to the model server; the playground itself runs on CPU. Download trace saves the states, actions and distributions from the current run. Live trace exports do not include image frames.

Platform requirements

The base replay viewer uses only the ordinary JevAny client installation. For live games, ViZDoom's prebuilt wheels support recent Linux, Apple Silicon macOS and x86-64 Windows. Older Linux distributions may fall back to a source build; use a recent Linux environment to avoid that step. On Intel macOS, install vizdoom==1.2.4 together with the game extra.

The optional robot environment is installed separately:

python -m pip install -e '.[robotics]'

PyBullet 3.2.7 has no Python 3.12 wheels on PyPI, so this step requires a C++ build toolchain and can take several minutes. This does not affect robot replays or either game. The game and robot extras can coexist with the training and serving extras.

Doom corridor (3D)

ViZDoom runs a focused version of deadly_corridor with the included Freedoom assets. The player starts in the final room with its original two enemies; enemies in earlier rooms are removed. No commercial Doom installation or separate WAD download is required. The instruction given to the model is: kill the enemy on the left and the enemy on the right, then move forward through the cleared room.

Eight controls cover forward/backward movement, strafing, turning, shooting and waiting. A move or shot advances eight game ticks; a turn advances four. Observations contain the current screenshot, health, ammunition, visible enemies' positions relative to the crosshair, and the previous action's actual hits and kills. Corpses are identified separately. Success requires hitting and killing both enemies, then advancing through the room; reaching armor alone does not complete the task. An episode is limited to 160 decisions.

Crafter survival (2D)

Crafter is a pixel-art survival game with 17 native actions. This task asks for a complete crafting sequence: gather wood, place a table, make a wood pickaxe, and mine stone while remaining alive. Movement, crafting, food, health and resource use are handled by the game.

The adapter preserves all native actions, including unavailable crafting attempts that consume a turn. The checkpoint sees the current screenshot, inventory, recipe requirements, a 9 × 7 visible map, and remembered locations from earlier views. It first chooses an immediate objective, then chooses one of the 17 native actions using the same screenshot. Position history and actual action effects provide feedback for the next turn. Runs stop at goal completion, death or 200 decisions. The included model replay completes the crafting sequence.

Robot peg insertion

This task adapts JevAny's existing Franka Panda peg-insertion case. The 14 controls move the gripper along ±X, ±Y and ±Z in 1 cm or 5 cm increments, or close and open its fingers in place. PyBullet contact and gravity determine whether the peg is grasped, carried and inserted.

A deterministic harness supplies the current pick-and-place subgoal, target coordinates, signed position error and current grasp feedback. Jev receives these measurements with the camera image and chooses every primitive action from the full set. This example tests action selection with supplied subgoals; the harness provides the task plan.

Success requires a prior two-finger grasp, alignment with the cyan socket, correct insertion depth, an upright peg, released fingers and a settled object. An empty grasp or a peg left outside the socket fails these checks. Runs have a 120-decision limit. See the harness and recorded results for its stages, recovery behavior and evaluation conditions.

Environment API

The implementations live in jevany/demos. Optional engines load only when a live environment is created:

from jevany.demos import make_environment

env = make_environment("crafter", seed=17)
try:
    state = env.observe()
    actions = env.get_all_actions()
    state, reward, done, info = env.step("move_right")
    image = env.render()  # RGB array
finally:
    env.close()

Environments implement reset, step, get_all_actions, render and close, and provide ACTION_LOOKUP descriptions. They can also be used with jevany.agent.run_episode, whose default request contains structured state only. The browser adds camera images and game-specific context. Crafter makes two checkpoint calls per turn; the arm's decision_request(model, history) method supplies its measured subgoals.

The viewer serves packaged HTML, CSS, JavaScript and frames without a frontend build or CDN. To record fresh game replays, connect the recorder to your running model server:

python scripts/record_demo_previews.py \
  --base-url http://127.0.0.1:8008 --model SimpleJev/JevAny-Qwen3.8-27B-LoRA \
  --media-root /tmp/jevany-media --out /tmp/jevany-replays

The recorder uses the same harness as the browser and saves all run outcomes. Recorded game imagery and upstream notices are described in recordings/LICENSES.txt.

Command-line application examples

Run from the repository root after starting a server. These examples adapt three scenarios from the existing showcase into small, text-only applications.

python -m examples.inbox
python -m examples.sql_repair
python -m examples.service_recovery

The SQL and recovery programs execute and report the model's choices, and exit with status 1 if their checks fail. Results can vary between runs.

Use your own server or load a checkpoint directly, with the same application code:

python -m examples.sql_repair --base-url http://127.0.0.1:8008
python -m examples.sql_repair --checkpoint runs/my-jev --device cuda
python -m examples.service_recovery \
  --checkpoint SimpleJev/JevAny-Qwen3.8-27B-LoRA --device cuda --dtype bf16

--checkpoint needs the local extra; the released vision-capable checkpoint also needs multimodal. The full base model must fit on the chosen device.

For your own environment, reuse jevany.agent.run_episode. It takes a callable client, a goal, and an environment implementing reset, step, and get_all_actions. The environment supplies finite actions and owns execution. The recovery example shows this protocol.

request.json is a ready-to-send request:

jevany decide examples/request.json
jevany decide examples/request.json --checkpoint runs/my-jev

The Bedrock harness and symbolic tree examples use an LLM planner to construct bounded decisions. See INTEGRATIONS.md for their additional dependencies.