chore: publish rSkill OpenRAL/rskill-smolvla-so101-eraser_place-bf16 v0.1.0

SKILL.md

@@ -0,0 +1,76 @@
+---
+name: rskill-smolvla-so101-eraser_place-bf16
+description: >-
+  S1 Vision-Language-Action policy. Capabilities: pick, place, pick_and_place on eraser. SmolVLA finetuned to place an eraser on a blue square with a real SO-101 follower arm (Apache-2.0). Emits 6-DoF absolute joint-position chunks (size 50, in joint degrees) from two RGB views (fixed front overview + arm-mounted wrist). 20k steps on 25 teleop episodes (10 534 frames @ 30 FPS) from makermods/eraser_place_unblurry_real. ONE training task string — "place the erase on the blue square" (upstream typo included); deploy it verbatim. Discovery view of an OpenRAL rSkill — NOT directly runnable by an agent harness; it runs via rSkill.from_pretrained + the robot HAL.
+metadata:
+  openral_rskill: true            # generated discovery view of an rSkill
+  schema_version: 0.1
+  rskill_id: OpenRAL/rskill-smolvla-so101-eraser_place-bf16
+  manifest: ./rskill.yaml
+  role: s1
+  kind: vla
+  model_family: smolvla
+  embodiment_tags: [so101_follower]
+  actions: [pick, place, pick_and_place]
+  objects: [eraser]
+  scenes: [tabletop]
+  sensors_required: ['rgb:observation.images.camera1', 'rgb:observation.images.camera2']
+  state_dim: 6
+  action_dim: 6
+  action_representation: joint_positions
+  runtime: pytorch
+  quantization: bf16/pytorch
+  min_vram_gb: {bf16: 1.5}
+  chunk_size: 50
+  n_action_steps: 50
+  latency_budget: {per_chunk_ms: 400.0}
+  license_code: Apache-2.0
+  license_weights: apache-2.0
+  weights_uri: hf://OpenRAL/rskill-smolvla-so101-eraser_place-bf16@7a9a8a0684b28fb6470f25d333aa65e31c8b781b
+  source_repo: hf://makermods/smolvla_makermods_eraser_place_unblurry_real_2026-07-31_17-35-54
+  paper_url: https://arxiv.org/abs/2506.01844
+---
+
+# rskill-smolvla-so101-eraser_place-bf16 — rSkill discovery view
+
+> **Generated view, not a hand-written skill.** This `SKILL.md` is a discovery-only
+> mirror of [`rskill.yaml`](./rskill.yaml), produced by `tools/generate_rskill_skillmd.py`.
+> It lets tools that read the standard agent-skill format find and reason about this
+> OpenRAL rSkill. The `rskill.yaml` manifest is the single source of truth
+> (CLAUDE.md §1.3). Do not edit by hand — edit the manifest and regenerate.
+
+## What it is
+
+An OpenRAL **Vision-Language-Action policy** (`role: s1`, `kind: vla`). SmolVLA finetuned to place an eraser on a blue square with a real SO-101 follower arm (Apache-2.0). Emits 6-DoF absolute joint-position chunks (size 50, in joint degrees) from two RGB views (fixed front overview + arm-mounted wrist). 20k steps on 25 teleop episodes (10 534 frames @ 30 FPS) from makermods/eraser_place_unblurry_real. ONE training task string — "place the erase on the blue square" (upstream typo included); deploy it verbatim.
+
+## Capabilities
+
+- **Verbs:** pick · place · pick_and_place
+- **Objects:** eraser
+- **Scenes:** tabletop
+- **Embodiments:** so101_follower
+
+## Why this is discovery-only
+
+An agent skill is natural-language instructions loaded into an LLM's context. An rSkill
+is an executable artifact: it carries a typed capability/embodiment contract, model weights,
+a runtime, and a license/provenance gate — none of which fit in freeform markdown. So an
+agent can use this view to *select* the right skill, but cannot *execute* it by loading
+this file. Execution always goes through the OpenRAL loader and the robot HAL.
+
+## License
+
+- **Code:** Apache-2.0.
+- **Weights:** `apache-2.0` — permissive / commercial-use OK
+
+## How to actually run it (not via an agent harness)
+
+```python
+from openral_rskill import rSkill
+
+skill = rSkill.from_pretrained("OpenRAL/rskill-smolvla-so101-eraser_place-bf16")
+# the loader validates embodiment / sensors / runtime / quantization against the target
+# RobotDescription and enforces the weight-license gate before any weights load.
+```
+
+See [`rskill.yaml`](./rskill.yaml) for the authoritative, validated manifest.

rskill.yaml

@@ -0,0 +1,207 @@
+# rSkill manifest — OpenRAL packaging format V1 (CLAUDE.md §3 "rSkill packaging")
+#
+# Wraps: makermods/smolvla_makermods_eraser_place_unblurry_real_2026-07-31_17-35-54
+#        (Apache-2.0) — SmolVLA finetuned from lerobot/smolvla_base (20k steps,
+#        batch 32, AdamW 1e-4, lerobot 0.6.0) on a real SO-ARM follower teleop
+#        dataset (makermods/eraser_place_unblurry_real: 25 episodes, 10 534
+#        frames @ 30 FPS), single task "place the erase on the blue square".
+#        Recorded with TWO 640x480 cameras: an arm-mounted "wrist" view and a
+#        fixed "front" view.
+# Base:  lerobot/smolvla_base (arxiv:2506.01844)
+#
+# EMBODIMENT — the checkpoint's `train_config.json` and the dataset's
+# `meta/info.json` both record `robot_type: "so_follower"`, lerobot 0.6.0's
+# UNIFIED SO-ARM class: it does not distinguish SO-100 from SO-101. The arm was
+# confirmed out-of-band to be an SO-101 follower, so this manifest declares
+# `so101_follower` (the same lerobot Feetech driver + identical 6-joint chain
+# serves both revisions — see robots/so101_follower/robot.yaml `hal.real`).
+#
+# JOINT ENVELOPE — the training distribution slightly EXCEEDS the SO-101 MJCF
+# `new_calib` limits this repo's robot manifest carries. Measured over the
+# dataset's own normalizer stats (lerobot units == the manifest's declared
+# `degrees`):
+#   shoulder_lift  min -103.8  vs robot limit -100.0  (-1.7453 rad)
+#   elbow_flex     max  +97.0  vs robot limit  +90.0  (+1.5708 rad)
+#   wrist_flex     max +103.4  vs robot limit  +95.0  (+1.6581 rad)
+# Those are the tails of a per-arm servo calibration, not a different
+# kinematic chain. The safety kernel clamps/rejects anything past the manifest
+# limits, so expect clipping at the very top of the elbow / wrist_flex range.
+# Do NOT widen robots/so101_follower/robot.yaml to accommodate this checkpoint:
+# the limits are the mechanical contract, and loosening them is a safety-WG
+# decision with a hazard-log entry (CLAUDE.md §3 "Safety"), not a packaging fix.
+#
+# UNITS — degrees: the normalizer observation.state/action stats span
+# ~[-103.8, +103.4] (MEAN_STD), i.e. the lerobot SO-ARM joint scale the repo
+# models as DEGREES (radians would be ±3.14). The runner converts deg<->rad at
+# the HAL boundary; declared explicitly below so it does not fall back to the
+# stats-magnitude heuristic. Same posture as the two sibling SO-101 SmolVLA
+# skills (rskill-smolvla-so101-pen-bf16 / -pick_place_pen-bf16).
+#
+# PROVENANCE — weights are the OpenRAL MIRROR
+# `OpenRAL/rskill-smolvla-so101-eraser_place-bf16`, byte-identical to upstream
+# `makermods/smolvla_makermods_eraser_place_unblurry_real_2026-07-31_17-35-54`
+# (Apache-2.0): model.safetensors sha256
+# 58d656e494a3143c00b19261a14f2b312656751cedd98253ab8a5f3fbcc73609 matches the
+# upstream LFS digest, verified before upload. Mirroring is the catalog standard
+# (rskills/README.md, "One rSkill <-> one HF repo") and it is not ceremony — the
+# sibling rskill-smolvla-so101-pen-bf16 points at a third-party repo that went
+# GATED after packaging, and now needs HF_HUB_OFFLINE=1 plus a warm cache to
+# deploy at all. `weights_uri` is pinned to the mirror's commit SHA for
+# reproducible loads (CLAUDE.md §1.8).
+#
+# The mirror carries ONLY the 7 root inference files, not the 20
+# `checkpoints/<step>/` training snapshots (~21 GB with optimizer state) the
+# upstream repo also holds. `SmolVLAPolicy.from_pretrained` loads the repo root
+# directly, and every OpenRAL fetch path here is per-file `hf_hub_download`,
+# never `snapshot_download`. No config sanitize is needed: the config carries no
+# stray keys that lerobot 0.6.0's draccus `SmolVLAConfig` rejects.
+
+# ── Identity ───────────────────────────────────────────────────────────────
+schema_version: "0.1"
+name: "OpenRAL/rskill-smolvla-so101-eraser_place-bf16"
+version: "0.1.0"
+license: "apache-2.0"
+role: "s1"
+kind: "vla"
+
+# ── Policy identity ────────────────────────────────────────────────────────
+model_family: "smolvla"
+
+# ── Compatibility contract ─────────────────────────────────────────────────
+embodiment_tags:
+  - "so101_follower"
+
+# Two RGB streams, trained at 640x480 (the policy's own
+# resize_imgs_with_padding takes them to 512x512). The runner matches each
+# entry against the robot's SensorSpec.vla_feature_key declared in
+# robots/so101_follower/robot.yaml (top -> camera1, wrist -> camera2); the
+# `image_preprocessing.aliases` below then rename those slots to this
+# checkpoint's own input-feature keys (front / wrist).
+sensors_required:
+  - modality: "rgb"
+    vla_feature_key: "observation.images.camera1"
+    min_width: 224
+    min_height: 224
+  - modality: "rgb"
+    vla_feature_key: "observation.images.camera2"
+    min_width: 224
+    min_height: 224
+
+# Output side. The loader auto-fills n_dof + vla_action_key from
+# robots/so101_follower/robot.yaml. Absolute joint-position targets.
+actuators_required:
+  - kind: "joint_position"
+    control_mode_semantics:
+      mode: "absolute"
+
+# ── Home / starting pose ─────────────────────────────────────────────────
+# Joint order = robots/so101_follower manifest joints:
+# [shoulder_pan, shoulder_lift, elbow_flex, wrist_flex, wrist_roll, gripper].
+#
+# THIS IS A REAL HOME POSE, not just "where episode 0 happened to begin". The
+# teleop operator both STARTS and RETURNS to it: per-joint medians over all 25
+# episodes' first frames and last frames agree to 2 decimals
+# (lerobot units):
+#            shoulder_pan  shoulder_lift  elbow_flex  wrist_flex  wrist_roll  gripper
+#   first        -7.21        -102.68        95.12       56.70        6.15      1.95
+#   last         -7.21        -102.68        94.59       56.70        6.15      1.95
+# MEDIAN is used, not mean: wrist_flex has a few long-start outliers (up to
+# 74.46) that drag the mean to 59.02 while the median sits at 56.70 — and the
+# last-frame median independently agrees at 56.70. shoulder_lift std is 0.09,
+# i.e. a hard mechanical home stop.
+#
+# UNITS — mixed, per the OpenRAL joint-channel contract:
+#   * 5 arm joints: DEGREES -> RADIANS (math.radians).
+#   * gripper: the SO-101 gripper channel is NORMALISED [0, 1], NOT an angle
+#     (SO100FollowerHAL._obs_to_positions divides the lerobot 0-100 reading by
+#     100; MujocoArmHAL's AFFINE_LOW_HIGH read mode documents the same [0, 1]
+#     public surface). So lerobot 1.95 -> 0.0195, i.e. jaws essentially closed
+#     — NOT radians(1.95) = 0.034, which would command a slightly OPEN jaw. The
+#     sibling SO-101 skills' gripper 0.5 is likewise "half open" on this scale.
+#
+# Two arm channels are CLAMPED to the so101 manifest limits (see JOINT ENVELOPE
+# above): shoulder_lift -1.7921 -> -1.7453, elbow_flex +1.6602 -> +1.5708.
+# Both clamps are <= 5 deg and stay inside the observed home spread, so the
+# first VLA tick still sees an in-distribution pose.
+starting_pose: [-0.1258, -1.7453, 1.5708, 0.9897, 0.1074, 0.0195]
+
+# ── Runtime / weights ──────────────────────────────────────────────────────
+runtime: "pytorch"
+quantization:
+  dtype: "bf16"
+  backend: "pytorch"
+# VRAM footprint for the VLA<->reward co-residency preflight. MEASURED on an
+# RTX 4070 Laptop: 1.13 GiB resident after load, 1.19 GiB peak across a
+# 2-camera inference (450.0 M params, SmolVLM2-500M backbone) — the declared
+# 1.5 keeps ~0.3 GB of headroom, matching the two sibling SO-101 skills.
+# 1.5 + Robometer NF4 3.6 + 0.5 margin = 5.6 GB on an 8 GB card.
+min_vram_gb:
+  bf16: 1.5
+# Pair this VLA with its task-progress reward monitor so a reward-enabled
+# deploy auto-resolves the Robometer NF4 manifest.
+reward_rskill_name: "OpenRAL/rskill-robometer_4b-any-general-nf4"
+weights_uri: "hf://OpenRAL/rskill-smolvla-so101-eraser_place-bf16@7a9a8a0684b28fb6470f25d333aa65e31c8b781b"
+
+# ── Preprocessing (all knobs needed to interpret IO) ───────────────────────
+processors:
+  preprocessor_uri: "hf://OpenRAL/rskill-smolvla-so101-eraser_place-bf16@7a9a8a0684b28fb6470f25d333aa65e31c8b781b/policy_preprocessor.json"
+  postprocessor_uri: "hf://OpenRAL/rskill-smolvla-so101-eraser_place-bf16@7a9a8a0684b28fb6470f25d333aa65e31c8b781b/policy_postprocessor.json"
+# Real SO-101 teleop recorded upright — no rotation. Aliases are keyed by the
+# VLA SLOT names (camera1/camera2): by the time the adapter sees the batch the
+# runner has already re-keyed the manifest sensor names via vla_feature_key
+# (top -> camera1, wrist -> camera2 in robots/so101_follower). The aliases then
+# rename those slots to the checkpoint's input-feature keys
+# (observation.images.front / observation.images.wrist): the robot's fixed
+# overhead camera (camera1) fills the training "front" view.
+image_preprocessing:
+  flip_180: false
+  aliases:
+    camera1: "front"
+    camera2: "wrist"
+state_contract:
+  dim: 6
+
+# ── Execution semantics ────────────────────────────────────────────────────
+# SmolVLA chunk_size=50 (checkpoint config); full-chunk synchronous replay.
+chunk_size: 50
+n_action_steps: 50
+latency_budget:
+  # 191 ms measured (steady-state median, 524 ms first call) on an RTX 4070
+  # Laptop over the two-camera batch, + margin. A 50-step chunk covers 1.67 s
+  # of a 30 Hz arm, so inference is not the bottleneck.
+  per_chunk_ms: 400.0
+
+# ── Provenance ─────────────────────────────────────────────────────────────
+paper_url: "https://arxiv.org/abs/2506.01844"
+dataset_uri: "hf://makermods/eraser_place_unblurry_real"
+source_repo: "hf://makermods/smolvla_makermods_eraser_place_unblurry_real_2026-07-31_17-35-54"
+
+description: >
+  SmolVLA finetuned to place an eraser on a blue square with a real SO-101
+  follower arm (Apache-2.0). Emits 6-DoF absolute joint-position chunks (size
+  50, in joint degrees) from two RGB views (fixed front overview + arm-mounted
+  wrist). 20k steps on 25 teleop episodes (10 534 frames @ 30 FPS) from
+  makermods/eraser_place_unblurry_real. ONE training task string — "place the
+  erase on the blue square" (upstream typo included); deploy it verbatim.
+
+# Action vocabulary for the reasoner LLM tool palette.
+actions:
+  - "pick"
+  - "place"
+  - "pick_and_place"
+objects:
+  - "eraser"
+scenes:
+  - "tabletop"
+
+# Per-checkpoint action contract.
+action_contract:
+  dim: 6
+  # SO-101 emits absolute joint positions (5 arm joints + 1 gripper).
+  representation: "joint_positions"
+  # EXPLICIT joint units — normalizer stats span ~[-103.8, +103.4] (verified:
+  # observation.state.min=-102.86 / .max=+101.10, action.min=-103.82 /
+  # .max=+103.38), i.e. DEGREES on the lerobot SO-ARM scale. The runner
+  # converts deg<->rad at the policy boundary. Declared so the runner does NOT
+  # rely on the stats-magnitude heuristic.
+  joint_units: "degrees"