twanghcmut/backup-VR-SmallVLA/onf-v3 - Storage Bucket

ONF — graph-grounded recovery for frozen VLA policies

A frozen vision-language-action policy fails in two distinct ways when the world is perturbed: it can start from a pose it has never seen, and it can drift off the demonstrated manifold mid-rollout. This repo answers both with one mechanism — a demonstration graph plus a small trained retrieval head — and two regimes on top of it.

regime	when	what it does
entry (t=0)	once, before the policy's first step, if ‖q₀ − q*‖ > 0.08 rad	rewinds the arm to the uniform barycentre of this task's start-pose cloud on the graph
sentinel (t>0)	every check, while the rollout runs	a belief filter over the graph; fires on an e-process (basin ∪ progress) and steers back to the tracked basin

Both regimes read the same artifacts, and neither touches the policy: the graph is trained once per suite from demo data alone, then drives a frozen StableVLA and a frozen GR00T-N1.7 unchanged.

• Method in detail: docs/method.md
• How to run it: docs/usage.md

Results

cell	StableVLA	GR00T-N1.7
t=0 entry, long × Robot_Initial_States (n=393)	378/393 = 96.2%	353/393 = 89.8%
t>0 sentinel, long × Objects_Layout (n=312)	not measured	208/312 = 66.7%

Scope, stated up front: the 66.7% cell has no same-session base baseline and GR00T is stochastic (±2.4 pp); and on GR00T at Robot-Init a fixed-home baseline (94.7%) still beats this method. docs/method.md §5 carries the full caveats and the list of what has not been measured.

Install

conda env create -f envs/onf-core.yml && conda activate onf-core
pip install -e .
bash scripts/setup_external.sh
export ONF_DATA=... ONF_OUTPUTS=... ONF_RESULTS=...

Four runtimes are needed in total (core / StableVLA / libero-plus / GR00T) — see envs/README.md.

Layout

src/onf/
  graph/        the method: nodes, edges, gnn head, train, retrieve (t=0), track (t>0),
                readout arms (euc_raw = t=0, basin = t>0), schema, cli
  recovery/     the t=0 arm: joint-space PD controller + graph target
  sentinel/     the t>0 arm: per-step check loop + FilterRule (WHEN)
  manifold/     flow field + data builders (train-time inputs)
  field/        ONFField — training-time cleanliness weighting ONLY, on no inference path
  config.py     Paths + GraphConfig / RecoveryConfig / SentinelConfig (all env-driven)

evals/
  common/modes.sh              the ONLY definition of base / entry / sentinel
  libero_plus/                 vendored sim client, scorer, McNemar
  gr00t/run_gr00t.py           GR00T-N1.7 benchmark driver
  stablevla/                   StableVLA policy server

scripts/
  run_sr.py                    StableVLA benchmark driver (ladder, scheduling, ledger)
  build_sentinel_artifacts.py  fits g_track.npz (kernel, null banks, basin geometry)
  capture_golden.py            regenerates the bit-parity golden file
  setup_external.sh            provisions the vendored deps into external/

configs/  suites.yaml (suites, axes, checkpoints) · sr_ladder.yaml (the eval ladder)
tests/    incl. tests/test_parity.py — bit-exact golden parity for BOTH regimes

data/, results/ and outputs/ are symlinks into a shared working tree; point ONF_DATA, ONF_RESULTS, ONF_OUTPUTS elsewhere to relocate. Data and weights are not in the clone.

Reproducibility

OMP_NUM_THREADS=4 PYTHONPATH=src pytest tests/ -q

tests/test_parity.py replays 64 recorded t=0 retrievals and 64 t>0 tracker steps against the real trained artifacts and asserts exact float equality (float.hex(), not approx) with tests/golden/parity.json. Artifacts carry a graph_hash stamp and are refused on mismatch, and every result directory carries a run.json tying its number to a git commit and a specific artifact.

Upstream provenance for the vendored simulator/policy code: UPSTREAM.md.