PROVENANCE-ENFORCED VLA DISTILLATION · COMPRESSION · RUNTIME EXPORT

Quickstart · How it works · Students · CLI · Evaluation · Docs

---

Large VLA teachers can control robots, but their memory and latency requirements often exceed edge deployment budgets.

FORGE provides a measured path through that problem. It generates provenance-tracked labels from registered teachers, trains defined student variants, compresses them, and validates runtime exports through one CLI. Performance claims remain unpublished until their real-data artifacts pass the launch gates below.

flowchart LR
    A["TEACHER FLEET<br/>OpenVLA · RDT-2 · SmolVLA · +"] -->|soft labels| B["DISTILL<br/>bridge warmup → full KD → action tune"]
    B --> C["COMPRESS<br/>chunk-aware prune + QVLA / TurboQuant"]
    C --> D["EXPORT<br/>ONNX · TensorRT · MLX"]
    D --> E["DEPLOY<br/>async runtime · FastAPI · edge"]
    style A fill:#1A1A1A,stroke:#FF3B00,color:#fff
    style B fill:#1A1A1A,stroke:#FF3B00,color:#fff
    style C fill:#1A1A1A,stroke:#FF3B00,color:#fff
    style D fill:#1A1A1A,stroke:#FF3B00,color:#fff
    style E fill:#050505,stroke:#00FF88,color:#00FF88

Loading

Why FORGE

Multi-teacher distillation	Ensemble any registered teachers; a learned router weights them per-sample, with confidence-aware routing, diversity and consistency losses
Modern action heads	Diffusion, flow matching, and chunked action prediction — plus consistency distillation that collapses inference to a single step
Compression that respects control	Chunk-aware layer pruning and action-centric quantization (QVLA, TurboQuant-MSE, PolarQuant) protect temporal coherence, not just accuracy
Runtime export paths	ONNX, TensorRT engines, MLX for Apple Silicon, FastAPI serving, and an async engine with action-chunk buffering
Training that manages itself	Curriculum learning, plateau-adaptive LR, hard-example mining, teacher dropout, Optuna auto-hyperparameter search
Agent-native by design	Automation-facing status and artifact commands provide strict --json; forge top returns a full machine-readable system snapshot

Part of the ANIMA robotics stack by RobotFlow Labs.

Quickstart

The one-line Linux/macOS installer sets up an isolated FORGE tool, selects the CPU or CUDA backend, and puts forge on PATH:

curl -fsSL https://raw.githubusercontent.com/RobotFlow-Labs/anima-forge/refs/heads/main/install.sh | sh

Use --cpu or --cuda to force the Torch backend. The CPU path resolves official PyTorch CPU wheels while still installing FORGE's complete mandatory runtime set.

For a manual environment or an exact version pin, use the package path below.

# install (Python 3.12, NVIDIA GPU recommended)
pip install anima-forge

# is this machine ready? (GPU, models, disk)
forge doctor

# fetch the nano stack + real sample labels, then distill for 200 steps
forge quickstart --yes

If you need an unreleased checkout instead of the public PyPI package, install the wheel built from this repository and pass a real local label directory. See the fully copy-pasteable docs/QUICKSTART.md path and its publication status note.

How it works

Stage	What happens	Key tech
1 · Teacher labels	Teachers run over demonstrations; soft labels stored as HDF5	auto-discovering teacher registry, adapter pattern
2 · Distillation	3-phase KD: bridge warmup → full KD → action fine-tune	multi-teacher routing, curriculum, hard-example mining
3 · Compression	Layer pruning + mixed-precision quantization	Shallow-Pi, QVLA, TurboQuant, chunk-aware importance
4 · Export	Runtime conversion + validation + benchmark	torch dynamo ONNX, TensorRT INT8/FP16, MLX

Release-smoke benchmarks

The current launch artifacts were trained for 5,000 steps per variant on four NVIDIA L4 GPUs using the corrected SigLIP2 real-label provenance pack, then exported and benchmarked with real PushT video input. These numbers are release-smoke latency/export/provenance measurements, not broad robot task-success claims. The exact machine-readable summary is saved in hf_upload/benchmark_summary.json.

Variant	Train steps	Final loss	QVLA INT4 ratio	QVLA INT4 artifact	ONNX CUDA p50	ONNX FPS	PyTorch CUDA p50	PyTorch FPS
micro	5,000	0.086293	6.927×	304.1 MB	64.931 ms	15.365	126.958 ms	7.770
nano	5,000	0.085447	5.580×	621.9 MB	77.788 ms	12.898	142.064 ms	6.978
small	5,000	0.085069	5.090×	1397.2 MB	105.381 ms	9.444	160.774 ms	6.189
medium	5,000	0.085358	4.611×	2604.2 MB	163.489 ms	6.096	172.796 ms	5.764

Export status: ONNX Runtime CUDA and MLX exports completed for all four variants with finite action outputs. TensorRT was attempted on micro, but engine build did not produce a usable .engine on this host, so TensorRT numbers are intentionally not published here.

Student variants

One architecture, four sizes — frozen SigLIP2-SO400M → Bridge Attention → LoRA'd LLM backbone → action head. AutoSense reads model configs and wires dimensions for you.

Variant	Backbone	Backbone params	Intended role
micro	SmolLM2-135M	0.135B	smallest development/edge student
nano (default)	Qwen3-0.6B	0.6B	default edge student
small	Qwen3-1.7B	1.7B	larger edge/server student
medium	Qwen3-4B	4.0B	largest canonical student

CLI tour

forge info                          # system + model readiness
forge teacher list                  # the teacher fleet
forge pipeline --device cuda        # end-to-end distillation
forge quantize run --method turboquant-mse --bits 4 --device cuda --json
forge benchmark list                # packaged real-world benchmark catalog
forge benchmark all --device cuda   # all suites; JSON artifacts land in benchmarks/
forge benchmark run --checkpoint outputs/checkpoints/best.pt --device cuda --json
forge hyperparam auto --trials 30 --seed 42  # reproducible Optuna search
forge eval run libero --checkpoint outputs/checkpoints/best.pt
forge serve --checkpoint outputs/checkpoints/best.pt --port 8000
forge web --port 3000               # Command Center dashboard
forge top --json                    # agent-oriented status snapshot

Full reference: docs/CLI_REFERENCE.md

Evaluation

FORGE ships a VLA evaluation harness: it serves your student over WebSocket/msgpack and drives standard benchmarks in Docker — LIBERO, SimplerEnv, VLABench.

forge eval setup                    # pull benchmark images (one-time)
forge eval run-all --checkpoint outputs/checkpoints/best.pt --variant nano
forge eval compare --a v1.pt --b v2.pt

Architecture

src/forge/
├── teachers/         teacher adapters + auto-discovering registry
├── student.py        SigLIP → Bridge Attention → LoRA backbone → action head
├── modules/          bridge attention · diffusion/flow/chunk heads · LoRA
├── distill.py        3-phase KD loop        trainer.py     production trainer
├── multi_teacher.py  learned routing        curriculum.py  adaptive training
├── prune*.py         chunk-aware pruning    quantize/      QVLA · TurboQuant · PolarQuant
├── export/           ONNX · TensorRT · MLX  runtime/       asynchronous action engine
├── eval/             VLA benchmark harness  serve.py       FastAPI endpoint
└── web/              Command Center dashboard + JSON API

Deep dive: docs/ARCHITECTURE.md

Documentation

Doc	Contents
docs/README.md	Overview + quick start
docs/QUICKSTART.md	Real-label first distillation
docs/TROUBLESHOOTING.md	Common failures and exact fixes
docs/PIPELINE.md	4-stage pipeline walkthrough
docs/CLI_REFERENCE.md	Every command
docs/CONFIGURATION.md	YAML + FORGE_* env vars
docs/EVALUATION.md	VLA benchmark guide
docs/DEPLOYMENT.md	Edge deployment
docs/HYPERPARAMETER_GUIDE.md	Auto-HP (Optuna) + tuning

Development

uv run ruff check src/ scripts/ tests/
uv run ruff format --check src/ scripts/ tests/
uv run mypy src/forge/ scripts/
uv run pytest tests/ -m "not gpu"

PRs target develop; main is release-only. Public usage and architecture documentation live in docs/.

License

Apache-2.0 © RobotFlow Labs / AIFLOW LABS