| # AGENTS.md — Florence–Bridge OPTR |
|
|
| ## Mission |
|
|
| Reproduce or extend Florence–Bridge continuations without changing the experimental contract. Treat `EXPERIMENT_CONTRACT.md` and the downloaded 20K state as authoritative. |
|
|
| ## Non-negotiable rules |
|
|
| - Do not use Git operations for this handoff. |
| - Never overwrite the 20K common start, frozen proposal, or published 20.5K snapshots. |
| - New runs use new output directories. |
| - Resume new branches from the complete 20K Accelerate state, never from a 20.5K model-only file. |
| - Do not add code, path, manifest, or self-referential checksum launch gates. |
| - Keep dataset, episode, valid-anchor and proposal-support identity checks. |
| - Checkpoint readiness is established by required-file presence, byte size, loadability and semantic contract checks. |
| - Do not silently change world size, global batch, continuation seed, proposal, correction, budget or evaluation panel. |
|
|
| ## Required local assets |
|
|
| Set these variables before launch: |
|
|
| ```bash |
| export OPTR_PROJECT_ROOT=/path/to/this/repository |
| export OPTR_RUN_ROOT=/path/to/new/runs |
| export OPTR_PYTHON=/path/to/python |
| export FLORENCE_MODEL_PATH=/path/to/Florence-2-large |
| export BRIDGE_DATA_ROOT=/path/to/OXE_LEROBOT_DATASET |
| export BRIDGE_STATISTICS_PATH=/path/to/dataset_statistics.json |
| export BRIDGE_PROVENANCE_PATH=$OPTR_PROJECT_ROOT/manifests/data_provenance.json |
| export BRIDGE_FINGERPRINT_PATH=$OPTR_PROJECT_ROOT/manifests/content_fingerprints.json |
| export BRIDGE_MANIFEST_PATH=$OPTR_PROJECT_ROOT/manifests/valid_anchor_manifest_florence_scratch_v1.json |
| export COMMON_START_20K=$OPTR_PROJECT_ROOT/common_start_20k/checkpoints/steps_20000_accelerate |
| ``` |
|
|
| ## Locked training contract |
|
|
| - Base: Florence-2-large; action head: DiT-B; horizon 16; state/action dim 7. |
| - Two GPUs, BF16, DeepSpeed ZeRO-2. |
| - Micro-batch 4/GPU × world size 2 × accumulation 8 = global batch 64. |
| - Parent seed 42; continuation/sampler seed 117465; model RNG 588643; transform RNG 298226. |
| - Resume step 20,000; stop and save at step 20,500. |
| - AdamW `(0.9, 0.95)`, eps `1e-8`, weight decay `1e-8`; clipping 1.0. |
| - Cosine scheduler, 5K warmup, min LR `5e-7`; preserve restored scheduler state. |
| - Residual: K=8, alpha=0.2, epsilon=0.1, linear within-episode interpolation, ordinary p/q correction. |
|
|
| ## Commands |
|
|
| ```bash |
| bash scripts/run_florence_bridge_arm.sh uniform <new-run-id> |
| bash scripts/run_florence_bridge_arm.sh residual <new-run-id> \ |
| proposals/residual_temporal_proposal_k8_alpha0.2.json |
| ``` |
|
|
| After start, verify exact resume at 20K, global batch 64, and the first update above 20K. A valid finish has exit code 0 and a complete step-20500 model snapshot. |
|
|
| ## Evaluation |
|
|
| Use `scripts/evaluate_bridge_384_no_video.sh`. The locked panel has policy seeds 518957/765353/686765/516408; tasks Stack/Carrot/Spoon/Eggplant; 24 episodes per seed-task; BF16; no video; 384 rollouts per checkpoint. Preserve raw episode outcomes. |
|
|
| ## Where to look first |
|
|
| - Bridge training and evaluation seeds for Rebuttal: `BRIDGE_SEED_PROTOCOL.md` |
| - Contract and factual provenance: `EXPERIMENT_CONTRACT.md` |
| - File roles and sizes: `ASSET_MANIFEST.json` |
| - Source authority and known corrections: `SOURCE_INVENTORY.md` |
| - Training config: `configs/florence_bridge_20k_plus500.yaml` |
| - Sampling implementation: `starVLA/dataloader/temporal_proposal.py`, `infoflow_sampler.py` |
| - Training integration: `starVLA/training/infoflow.py`, `train_starvla.py` |
|
|
