docs: design pi05 UR Gradio Space

docs/superpowers/specs/2026-07-22-pi05-ur-gradio-design.md

@@ -0,0 +1,116 @@
+# π₀.₅ UR Hugging Face Gradio Deployment Design
+
+## Goal
+
+Turn `pi0.5` into a self-contained Hugging Face Gradio Space for the locally
+trained, state-conditioned UR policy. The Space loads a
+`pi05_ur_demo_state` checkpoint, accepts the same observations used during
+training, and returns a ten-step UR action chunk without controlling hardware.
+
+## Scope
+
+The deployment supports only `pi05_ur_demo_state`. It does not expose LIBERO,
+DROID, or the no-state UR configuration, and it does not host a websocket robot
+control service. The Space is an inspection and action-prediction interface.
+
+## Runtime Packaging
+
+The Space repository contains the OpenPI runtime required by the local UR
+configuration instead of installing the upstream OpenPI repository at runtime.
+This preserves the locally added `LeRobotURDataConfig`, `URInputs`,
+`UROutputs`, and `pi05_ur_demo_state` configuration. Runtime files are copied
+from the checked-in `VLA/openpi` implementation and reduced only where tests
+prove the removed modules are unnecessary.
+
+The Hugging Face Space uses Python 3.11 because it matches OpenPI's supported
+runtime and dependency constraints. Python dependencies are pinned where the
+OpenPI stack requires exact compatibility. The app uses a Hugging Face GPU
+Space and decorates inference with the `spaces.GPU` helper while retaining a
+local fallback when the `spaces` module is unavailable.
+
+## Model Artifacts and Loading
+
+The UI accepts a Hugging Face model repository ID and checkpoint subdirectory.
+The defaults come from environment variables so the public Space can be
+configured without modifying code. A model manager:
+
+1. validates the repository ID and relative checkpoint path;
+2. downloads the checkpoint snapshot with `huggingface_hub`;
+3. verifies that the checkpoint and UR normalization statistics exist;
+4. builds the local `pi05_ur_demo_state` training configuration;
+5. creates the trained policy on CUDA; and
+6. caches one loaded model keyed by repository ID and checkpoint path.
+
+Changing either artifact field unloads the previous model before loading the
+new one. Loading is lazy, so Space startup remains responsive and model-load
+failures appear in the status output instead of crashing module import.
+
+## Inputs and Data Flow
+
+The Gradio interface collects:
+
+- one fixed-camera RGB image (`video.image_0` during training);
+- one wrist-camera RGB image (`video.wrist` during training);
+- a required English task instruction;
+- seven finite state values in the order `x, y, z, roll, pitch, yaw, gripper`;
+- an integer trial index used to derive a deterministic inference seed; and
+- the Hugging Face model repository and checkpoint path.
+
+The inference adapter converts both images to RGB `uint8` arrays and constructs
+the policy observation as `observation/image`, `observation/wrist_image`,
+`observation/state`, and `prompt`. State is passed to the π₀.₅ discrete state
+input configured during training. The policy's output transforms apply the
+checkpoint's UR normalization statistics and return exactly the first seven
+action dimensions.
+
+The result must have shape `(10, 7)`. Columns are labelled `dx`, `dy`, `dz`,
+`droll`, `dpitch`, `dyaw`, and `gripper`. The UI displays the action table and
+offers a JSON download containing the input instruction, state, seed, artifact
+identity, action labels, and action values.
+
+## Interface
+
+The page follows the existing `qwengr00t` Space pattern: artifact controls at
+the top, two image inputs in one row, instruction and state controls below,
+then a primary prediction button, status text, action table, and JSON download.
+It clearly states that predictions do not directly command a robot.
+
+The app queues requests with concurrency one to prevent simultaneous access to
+the heavyweight policy. The first-request status explains that model download
+and loading can take several minutes.
+
+## Validation and Error Handling
+
+Before model execution, the adapter rejects missing images, blank instructions,
+non-finite or incorrectly sized state vectors, and invalid trial indices.
+Artifact paths must remain relative and cannot contain parent traversal.
+
+Model download, initialization, and inference exceptions are caught at the UI
+boundary and rendered as status messages. A failed load is not cached as a
+model. On CUDA failures the app runs garbage collection and empties the CUDA
+cache, while preserving enough error detail for diagnosis.
+
+## Testing
+
+CPU-only tests use fake policies and download/load functions. They verify:
+
+- Space metadata selects Gradio, Python 3.11, and the correct app entry point;
+- input validation and exact UR observation-key mapping;
+- RGB image conversion and seven-value state ordering;
+- deterministic seed selection;
+- enforcement of the `(10, 7)` action shape;
+- action table and JSON formatting;
+- lazy, keyed, thread-safe model caching and replacement;
+- artifact path validation and actionable load errors; and
+- Gradio component wiring without downloading a checkpoint.
+
+A syntax/import smoke test runs locally. Full checkpoint inference is documented
+as an optional GPU smoke test because it requires large external artifacts and
+a compatible CUDA environment.
+
+## Success Criteria
+
+The `pi0.5` repository can be pushed directly to a Hugging Face GPU Space. With
+a valid state-conditioned UR checkpoint repository configured, a user can
+upload both camera images, provide the current seven-value UR state and an
+instruction, and download a deterministic ten-by-seven action prediction.