onf/UPSTREAM.md

# Upstream provenance

The `onf` package (everything under `src/onf`, `evals/`) is **original code**
for this project. It depends on a few third-party trees that are **not** copied into this repo — they
are reached through `external/` (symlinks today; pin as sub-clones before any public release). Commits
are the same ones vendored by the parent `vla-bottleneck` working repo.

**Exception — vendored LIBERO client.** The small set of eval-harness files actually needed to run
LIBERO / LIBERO-Plus rollouts has been copied OUT of the VLA-JEPA donor repo INTO this repo at
`evals/libero_plus/harness/` so that running the evals no longer requires `external/VLA-JEPA`.
Vendored files (from `ginwind/VLA-JEPA` @ `ec8c70f6e155e2377bbd4d787004c14179c00c7c`):
`examples/LIBERO/eval_libero.py`, `examples/LIBERO/model2libero_interface.py`,
`examples/SimplerEnv/eval_files/adaptive_ensemble.py`, and the websocket / msgpack transport under
`deployment/model_server/tools/` (`websocket_policy_client.py`, `websocket_policy_server.py`,
`msgpack_numpy.py`, `image_tools.py`). Imports were rewired to be self-contained (`tools.*` +
sibling modules); a thin `harness/deployment/model_server/tools/` compat package re-exports the
transport under the server's legacy import path. The `grc_*` retrieval-grounding modules were NOT
vendored (they were reached only by exploratory ablation env-flags; that code has since been
removed from this repo). The full donor repo is not needed; clone it from the URL below only if you
want to diff against it.

| `external/` path   | Role                                   | Source repo | Commit pinned | License |
|--------------------|----------------------------------------|-------------|---------------|---------|
| `evals/libero_plus/harness/` (vendored, in-repo) | LIBERO-Plus eval harness (StableVLA/GR00T sim client) — copied out of VLA-JEPA | [ginwind/VLA-JEPA](https://github.com/ginwind/VLA-JEPA) | `ec8c70f6e155e2377bbd4d787004c14179c00c7c` | ⚠️ no LICENSE shipped upstream — resolve before redistribution |
| `external/LIBERO-plus` (gitignored) | LIBERO-Plus benchmark (`libero` pkg + perturbation suites + bddl) | [sylvestf/LIBERO-plus](https://github.com/sylvestf/LIBERO-plus) (a fork of [Lifelong-Robot-Learning/LIBERO](https://github.com/Lifelong-Robot-Learning/LIBERO)) | `4976dc30028e805ff8094b55501d532c48fec182` (main) | see tree `LICENSE` |
| `VLA-JEPA/` (not needed) | original donor repo for the vendored client above | [ginwind/VLA-JEPA](https://github.com/ginwind/VLA-JEPA) | `ec8c70f6e155e2377bbd4d787004c14179c00c7c` | ⚠️ no LICENSE shipped upstream — resolve before redistribution |
| `VLANeXt/`         | modules / recipes for exploratory ablation work (that code has since been removed from this repo) | [DravenALG/VLANeXt](https://github.com/DravenALG/VLANeXt) | `f4162397af201bddbdb2ec17e836bde4743c1913` | see tree `LICENSE` |
| `Isaac-GR00T/`     | GR00T-N1.7 cross-policy eval server    | NVIDIA Isaac-GR00T (sibling working tree) | local `Jul 14` checkout | see tree `LICENSE` |
| `evals/stablevla/stablevla_policy_server.py` (vendored, in-repo) | StableVLA/HumanNet websocket policy server — copied from vla-bottleneck eval tree so evals are self-contained | [DAGroup-PKU/HumanNet](https://github.com/DAGroup-PKU/HumanNet) lineage via `vla-bottleneck/eval/libero_plus/` | same as StableVLA trunk commit `68eb86d555fc4d3b09003319cff7644cd4c8b571` | see tree `LICENSE` |

The StableVLA **trunk** (model code, from
[DAGroup-PKU/HumanNet](https://github.com/DAGroup-PKU/HumanNet) `src/model/StableVLA`,
commit `68eb86d555fc4d3b09003319cff7644cd4c8b571`) goes at the repo root as `stablevla/`, which is
where `scripts/run_sr.py`, `evals/gr00t/run_gr00t.py`, `evals/stablevla/stablevla_policy_server.py`
and every ckpt path in `configs/suites.yaml` look for it. Sparse-checkout command and the separate
**weights** download under `stablevla/hf_weights/`: [`docs/SETUP.md`](docs/SETUP.md). The trunk is a
runtime dependency of the evals, not of the core
`onf` package.

## Data
`data/` (fields, demos, datasets) and `results/` (rollouts, figures) are symlinks into the parent
`vla-bottleneck` tree. Relocating the data into this repo is deferred (large; see README "Data").
Trained fields live under `data/fwm/<suite>/` — `onf_head.npz` + `q_flow.npz` + `q_home.npz` per
suite (`spatial`, `long`, `goal`, `aloha_left`, and the top-level object/base).