restore detailed card and figures

README.md

@@ -1,70 +1,109 @@
 ---
-datasets: aailabkaist/so101_recovery_2task
+license: gemma
 library_name: lerobot
-license: apache-2.0
-model_name: pi05
 pipeline_tag: robotics
 tags:
 - lerobot
-- pi05
 - robotics
+- pi0.5
+- pi05
+- vla
+- so101
+- manipulation
+- full-finetune
+base_model:
+- lerobot/pi05_base
+datasets:
+- aailabkaist/so101_recovery_2task
 ---
 
-# Model Card for pi05
+# π0.5 · SO-101 pick & place (2-task) — **full fine-tune**, 10,000 steps
 
-<!-- Provide a quick summary of what the model is/does. -->
+A [π0.5](https://www.physicalintelligence.company/blog/pi05) (`pi05`) vision-language-action policy
+fine-tuned on an SO-101 arm for a two-task cup manipulation setup: pick a cup up from the table and
+place it onto a blue circle.
 
+**The entire model was trained** — PaliGemma VLM (vision encoder + language model) and the action
+expert together (`train_expert_only=false`, `freeze_vision_encoder=false`).
 
-**π₀.₅ (Pi05) Policy**
+- **Base model:** [`lerobot/pi05_base`](https://huggingface.co/lerobot/pi05_base) — the last
+  pre-relative-actions revision, matching LeRobot `0.4.x`
+- **Dataset:** [`aailabkaist/so101_recovery_2task`](https://huggingface.co/datasets/aailabkaist/so101_recovery_2task)
+  (749 episodes · 151,255 frames · 30 fps · 8 operators)
+- **Checkpoint:** step **10,000** of a 10,000-step run (batch 64 → **640,000** samples ≈ **4.2 epochs**)
+- **Framework:** [LeRobot](https://github.com/huggingface/lerobot)
+- **Robot:** SO-101, 6-DoF, two RGB cameras (`front`, `wrist`, 480×640)
+- **Siblings:** `expert 5K` · `expert 10K` · `full 5K` — see the
+  [two-task collection](https://huggingface.co/collections/nevertmr/so-101-cup-blue-circle-two-task-6a5f8e25fbd8c0bccda23cd7)
 
-π₀.₅ is a Vision-Language-Action model with open-world generalization, from Physical Intelligence. The LeRobot implementation is adapted from their open source OpenPI repository.
+## Task and data
 
-**Model Overview**
+Two instructions, both used at training time verbatim:
 
-π₀.₅ represents a significant evolution from π₀, developed by Physical Intelligence to address a big challenge in robotics: open-world generalization. While robots can perform impressive tasks in controlled environments, π₀.₅ is designed to generalize to entirely new environments and situations that were never seen during training.
+```
+pick up the cup near the blue circle
+place the cup on the blue circle
+```
 
-For more details, see the [Physical Intelligence π₀.₅ blog post](https://www.physicalintelligence.company/blog/pi05).
+![cup start positions](pick_start_positions_anon.png)
 
+Pick-episode cup start positions (394 episodes, per-operator colors, anonymized). The cups form a
+ring around the blue circle rather than covering the workspace uniformly.
 
-This policy has been trained and pushed to the Hub using [LeRobot](https://github.com/huggingface/lerobot).
-See the full documentation at [LeRobot Docs](https://huggingface.co/docs/lerobot/index).
+![cup transport](place_transport_anon.png)
 
----
+Place-episode transport vectors, start → placed (350 of 355 place episodes — 5 excluded where the
+cup is fully occluded by the gripper in the start frame). Endpoints converge tightly on the
+blue circle; the release target is nearly constant across the dataset.
 
-## How to Get Started with the Model
+## Training
 
-For a complete walkthrough, see the [training guide](https://huggingface.co/docs/lerobot/il_robots#train-a-policy).
-Below is the short version on how to train and run inference/eval:
+| | |
+|---|---|
+| Trainable parameters | **3.617 B (100 %)** |
+| Frozen | none |
+| Steps | 10,000 (run stopped early at 10K; config said 20K) |
+| Batch size | 64 |
+| Precision | bfloat16, `gradient_checkpointing=true` |
+| Optimizer | AdamW · lr 2.5e-5 · wd 0.01 · betas (0.9, 0.95) · grad-clip 1.0 |
+| Schedule | cosine decay with warmup — auto-scaled by LeRobot (20K steps < 30K decay): warmup 1,000→666, decay 30,000→20,000; peak 2.5e-5, LR at this checkpoint ≈1.4e-5 (configured floor 2.5e-6 never reached — run stopped at 10K) |
+| Chunk | `chunk_size=50`, `n_action_steps=50`, `n_obs_steps=1` |
+| Seed | 1000 |
+| Hardware | 1× NVIDIA RTX PRO 6000 Blackwell (97 GB) |
+| VRAM / speed | 45.4 GB · 4.93 s/step |
+| **Final loss at this checkpoint** | **0.039** |
 
-### Train from scratch
+![loss curve](loss_curve.png)
 
-```bash
-lerobot-train \
-  --dataset.repo_id=${HF_USER}/<dataset> \
-  --policy.type=act \
-  --output_dir=outputs/train/<desired_policy_repo_id> \
-  --job_name=lerobot_training \
-  --policy.device=cuda \
-  --policy.repo_id=${HF_USER}/<desired_policy_repo_id>
-  --wandb.enable=true
-```
+![loss curve, log scale](loss_curve_log.png)
 
-_Writes checkpoints to `outputs/train/<desired_policy_repo_id>/checkpoints/`._
+Both runs used identical data, batch size and dtype — the only difference is what was trainable, so
+the two curves are directly comparable. `expert-only` is essentially flat after warmup (~step 1K):
+0.129 → 0.087 over the remaining ~3.8 epochs; full fine-tuning keeps descending. The run was stopped
+at 10K rather than the configured 20K on the strength of these curves.
 
-### Evaluate the policy/run inference
+## Usage
 
-```bash
-lerobot-record \
-  --robot.type=so100_follower \
-  --dataset.repo_id=<hf_user>/eval_<dataset> \
-  --policy.path=<hf_user>/<desired_policy_repo_id> \
-  --episodes=10
+```python
+from lerobot.policies.pi05.modeling_pi05 import PI05Policy
+
+policy = PI05Policy.from_pretrained("aailabkaist/pi05_recovery_2task_full_10k")
 ```
 
-Prefix the dataset repo with **eval\_** and supply `--policy.path` pointing to a local or hub checkpoint.
+Or serve it for async inference:
 
----
+```bash
+python -m lerobot.async_inference.policy_server --host=0.0.0.0 --port=8080 --fps=30
+python -m lerobot.async_inference.robot_client \
+    --server_address=<host>:8080 \
+    --policy_type=pi05 --pretrained_name_or_path=aailabkaist/pi05_recovery_2task_full_10k \
+    --task="pick up the cup near the blue circle" \
+    --actions_per_chunk=50 --chunk_size_threshold=0.2 \
+    --aggregate_fn_name=weighted_average --fps=30
+```
 
-## Model Details
+---
 
-- **License:** apache-2.0
+*A single-task variant of this setup — one instruction covering the whole pick-and-place motion,
+with a plain white cup — lives in the
+[SO-101 · cup → blue circle (single-task) collection](https://huggingface.co/collections/nevertmr/so-101-cup-blue-circle-single-task-6a58a5ef4ebe2dc6c028f093).*