Snake Jev

A desktop Snake experiment powered by Jev / System One. Jev assesses the board; Python combines its answers into a move. The original p5 Snake game handles movement, food, growth, and collisions.

One recorded run reached 29 foods in 461 ticks, then trapped itself in its body. That is one run, not a reliability guarantee. The agent detects immediate hazards; it does not plan a route through the full body layout.

Play

You need uv, a desktop with OpenGL support, and your own Jev API key. Tested on macOS with Python 3.12; other platforms are not verified. Each game tick makes one real API request and may incur API charges.

git clone https://github.com/siroccomask/snake-jev.git
cd snake-jev
uv sync
cp .env.example .env

Set JEV_API_KEY in .env, then run:

uv run python sketch.py

The game starts paused. Press Space to run until death, or pause it. The default has no request limit. For a bounded session:

uv run python sketch.py --max-calls 100

You can also supply the key through your environment or --env-file /path/to/.env. Keys stay local and are redacted from traces. Never commit your .env file.

Control	Action
Space	Run / pause
.	One API call and one game tick
R	Restart with the same food seed
D	Toggle assessments / response JSON
Up / Down	Scroll JSON
Q	Pause and quit; if a request is in flight, press again after it finishes

Pausing lets the current request finish its tick. API errors pause without moving or automatically retrying. --seed 2022 sets the food seed; --until-death starts immediately. The window is 1296 × 810. Use native screen recording to capture it.

How it works

1. inputs.py samples the existing game's sensors. simple_request() in jev_controller.py converts distances into whole moves relative to the heading.
2. One API call asks nine independent questions: wall collision, body collision, and food progress for turn left, straight, and turn right.
3. compose_assessments() combines only Jev's answers. It prefers food progress among actions Jev assesses as collision-free. If none are clear, it chooses the lowest assessed collision risk. Ties prefer lower risk, then straight.
4. jev_run.py translates the relative action into the existing Snake.dir() call and advances Snake.update() once. Rendering does not advance the game.

There is no second API call or model move Choice. Code does not inspect the game board to correct Jev's assessments. An incorrect assessment can still kill the snake.

The input fields for each relative direction are:

• moves_before_wall: steps available before hitting a wall; 0 means the next step hits.
• body_distance_moves: retained-body distance; 1 means adjacent and null means none on the ray.
• food_offset_moves: positive food offset along that axis, including diagonal food.

behind is included as an observation but is not an available action, so the agent cannot request a reversal. The model is jev-1.13.0 at the System One API endpoint.

Redacted runtime traces go to .jev_traces/ (Git-ignored). Each includes the request, API answers, separately labeled code composition, and before/after board snapshots. Two small historical fixtures are included solely for offline regression tests.

Develop

uv run pytest -q

Tests use fake inference and recorded fixtures; they do not require an API key. The original game's collision, tail, growth, and starvation behavior is preserved. This project builds on SnakePythonP5NeuralNet, with its neural-network and evolutionary training code removed.

Contributions and experiments are welcome. Please report the prompt version, food seed, and a redacted trace when sharing a failure.

License

MIT. See LICENSE.