README.md

---
title: ZeroGPU Cube Q-Learning Lab
emoji: "🧊"
colorFrom: indigo
colorTo: blue
sdk: gradio
sdk_version: 6.20.0
app_file: app.py
short_description: Train a local neural Q-agent to solve 2x2x2 cube states.
python_version: "3.12"
---

# ZeroGPU Cube Q-Learning Lab

An interface-ready ZeroGPU project for a future reinforcement-learning demonstration
of the 2x2x2 Rubik's Cube.

The planned agent will observe a 24-sticker cube state and train a compact local
neural network to estimate action values for the 12 quarter-turn actions.

## Try it

1. Paste an initial quarter-turn sequence or generate a random legal sequence.
2. Inspect the resulting CSS 3D cube preview.
3. Invoke the deployed model to return its proposed solution.

Training is intentionally outside the website. The Space accepts an initial state
sequence and will run the deployed trained model. The current scaffold does not
include a trained checkpoint yet, so it reports that status instead of returning a
fabricated solution.

## Method

For a reverse trajectory `(s, a, s')`, the update is:

```text
Q(s, a) <- Q(s, a) + alpha * (r + gamma * max_a' Q(s', a') - Q(s, a))
```

where `r = 1` only for a transition into the solved state and `r = 0` otherwise.
The fallback is deliberately separate from the RL policy so the interface makes
the distinction between learned control and search explicit.