8000 Advance development to 0.10.0.dev0 by DaoyuanLi2816 · Pull Request #78 · DaoyuanLi2816/mini-verl · GitHub
[go: up one dir, main page]

Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions PROJECT_STATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,12 @@ current product and evidence state rather than repeating release history.

Last updated: 2026-08-13.

Canonical release state: releasing `v0.9.1`.
Canonical release state: stable `v0.9.1` (`6c0f3d818c10419e0bfba81f3ad1c5adf24eaf09`), development `0.10.0.dev0`.

## Release state

- Release candidate: `v0.9.1` (release commit pending).
- Stable: `v0.9.1` at `6c0f3d818c10419e0bfba81f3ad1c5adf24eaf09`.
- Development: `0.10.0.dev0`.
- Stable docs: <https://daoyuanli2816.github.io/mini-verl/>.
- Development docs: <https://daoyuanli2816.github.io/mini-verl/dev/>.
- Historical build log: [v0.1-v0.9 archive](docs/history/project-state-v0.1-v0.9.md).
Expand All @@ -23,7 +24,7 @@ of official verl `v0.8.0` at commit
`n=1`, reward-free direct GKD `forward_kl_topk` and token-mean reduction in one
local process on one NVIDIA CUDA GPU.

The v0.9.1 development repair makes dtype, quantization, attention, student
The stable v0.9.1 repair makes dtype, quantization, attention, student
adapter input, logical/physical batch limits and placement legality explicit.
Executable compatibility claims are mutation-tested and recorded in
`docs/generated/verl-opd-v0.8-field-effects.json`. Quantized roles cannot swap;
Expand Down
44 changes: 22 additions & 22 deletions PYPI.md
8000
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<p align="center">
<img src="https://raw.githubusercontent.com/DaoyuanLi2816/mini-verl/v0.9.1/docs/banner.svg" alt="miniVERL — run verl-style OPD on one consumer GPU" width="880">
<img src="https://raw.githubusercontent.com/DaoyuanLi2816/mini-verl/main/docs/banner.svg" alt="miniVERL — run verl-style OPD on one consumer GPU" width="880">
</p>

<div align="center">
Expand All @@ -8,15 +8,15 @@
[![Build](https://github.com/DaoyuanLi2816/mini-verl/actions/workflows/build.yml/badge.svg)](https://github.com/DaoyuanLi2816/mini-verl/actions/workflows/build.yml)
[![PyPI](https://img.shields.io/pypi/v/miniverl.svg)](https://pypi.org/project/miniverl/)
[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)](https://www.python.org)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/DaoyuanLi2816/mini-verl/blob/v0.9.1/LICENSE)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/DaoyuanLi2816/mini-verl/blob/main/LICENSE)

</div>

<p align="center">
<a href="https://pypi.org/project/miniverl/"><strong>PyPI</strong></a> ·
<a href="https://daoyuanli2816.github.io/mini-verl/"><strong>Stable docs</strong></a> ·
<a href="https://daoyuanli2816.github.io/mini-verl/dev/">Development docs</a> ·
<a href="https://github.com/DaoyuanLi2816/mini-verl/blob/v0.9.1/README.zh-CN.md">中文</a>
<a href="https://github.com/DaoyuanLi2816/mini-verl/blob/main/README.zh-CN.md">中文</a>
</p>

**Run a documented subset of verl-style on-policy distillation on one consumer
Expand Down Expand Up @@ -51,14 +51,14 @@ recipe and produce an inspectable PEFT adapter.

The `train` extra installs the ML runtime, but does not choose the correct CUDA
PyTorch wheel. The optional `cuda` extra adds bitsandbytes only. Follow the
[one-GPU installation and memory guide](https://github.com/DaoyuanLi2816/mini-verl/blob/v0.9.1/docs/single-gpu-guide.md) before a real
[one-GPU installation and memory guide](https://github.com/DaoyuanLi2816/mini-verl/blob/main/docs/single-gpu-guide.md) before a real
run.

## Architecture

<picture>
<source media="(max-width: 640px)" srcset="https://raw.githubusercontent.com/DaoyuanLi2816/mini-verl/v0.9.1/docs/verl-local-runtime-mobile.svg">
<img src="https://raw.githubusercontent.com/DaoyuanLi2816/mini-verl/v0.9.1/docs/verl-local-runtime.svg" alt="verl-shaped YAML, overrides and Parquet prompts pass through a typed compiler; one CUDA GPU runs actor rollout, teacher scoring and actor update; inspectable artifacts can be handed to pinned verl while distributed execution remains outside miniVERL.">
<source media="(max-width: 640px)" srcset="https://raw.githubusercontent.com/DaoyuanLi2816/mini-verl/main/docs/verl-local-runtime-mobile.svg">
<img src="https://raw.githubusercontent.com/DaoyuanLi2816/mini-verl/main/docs/verl-local-runtime.svg" alt="verl-shaped YAML, overrides and Parquet prompts pass through a typed compiler; one CUDA GPU runs actor rollout, teacher scoring and actor update; inspectable artifacts can be handed to pinned verl while distributed execution remains outside miniVERL.">
</picture>

miniVERL uses one ordinary process and schedules model roles in phases. It does
Expand Down Expand Up @@ -114,13 +114,13 @@ miniverl plan --profile verl-opd-v0.8-single-gpu-v1 --config verl-opd.yaml \

External YAML must explicitly accept the high-risk local mappings printed by
`plan` before `run`; the packaged profile carries a value-bound reviewed
manifest. [Override precedence and safe input forms](https://github.com/DaoyuanLi2816/mini-verl/blob/v0.9.1/docs/config-overrides.md)
manifest. [Override precedence and safe input forms](https://github.com/DaoyuanLi2816/mini-verl/blob/main/docs/config-overrides.md)
are documented without executing Hydra interpolation or shell text.

The public built-in profile deliberately uses upstream-shaped `name: vllm`
values. miniVERL classifies both rollout and teacher engine names as local
reinterpretations and executes them with sequential local HF phases; this is
not vLLM equivalence. See [For verl users](https://github.com/DaoyuanLi2816/mini-verl/blob/v0.9.1/docs/for-verl-users.md) for config,
not vLLM equivalence. See [For verl users](https://github.com/DaoyuanLi2816/mini-verl/blob/main/docs/for-verl-users.md) for config,
data, role and error mappings.

## Tested profile boundary
Expand Down Expand Up @@ -151,8 +151,8 @@ with a 64-token response bound, and completed **8 current-policy updates** at
**3.1914 GiB peak reserved VRAM**. Median steady-state rollout, teacher-scoring
and update times were 9.7200, 0.4864 and 2.3260 seconds. A matched 4-update
interruption resumed to the same byte-identical trajectories, adapter and
optimizer tensors. See the [data-bound figure and full record](https://github.com/DaoyuanLi2816/mini-verl/blob/v0.9.1/docs/verl-opd-reference-workload.md);
the original one-update [pip smoke](https://github.com/DaoyuanLi2816/mini-verl/blob/v0.9.1/docs/opd-quickstart.md) remains preserved.
optimizer tensors. See the [data-bound figure and full record](https://github.com/DaoyuanLi2816/mini-verl/blob/main/docs/verl-opd-reference-workload.md);
the original one-update [pip smoke](https://github.com/DaoyuanLi2816/mini-verl/blob/main/docs/opd-quickstart.md) remains preserved.
A separate pinned SmolLM2-360M/1.7B compatibility smoke completed one full
rollout/scoring/update cycle; it is not a second measured recipe.

Expand All @@ -174,7 +174,7 @@ Automatic BF16/FP16 selection follows device support; it is not inferred from
marketing names such as 3070, 4080, 5090 or Titan. `miniverl doctor` reports the
installed CUDA/PyTorch path. Normal planning is weight-free; explicit
`plan --probe` adds bounded, cached CUDA measurements with zero optimizer
updates. See [hardware planning](https://github.com/DaoyuanLi2816/mini-verl/blob/v0.9.1/docs/hardware-planning.md). There is no
updates. See [hardware planning](https://github.com/DaoyuanLi2816/mini-verl/blob/main/docs/hardware-planning.md). There is no
automatic downgrade to a different model,
teacher, context, top-k or loss when memory is tight.

Expand Down Expand Up @@ -202,30 +202,30 @@ The v0.9 export preserves student/teacher identities, Parquet bytes and pure
OPD overrides, but reports `launchable: false` until exact base snapshots are
materialized and validated against the installed pinned verl commit. Only then
does `bridge materialize` publish a checksummed `launch.sh`; distributed
execution remains untested. Review the [current scale-out contract](https://github.com/DaoyuanLi2816/mini-verl/blob/v0.9.1/docs/verl-opd-scaleout.md),
[legacy bridge](https://github.com/DaoyuanLi2816/mini-verl/blob/v0.9.1/docs/legacy-verl-bridge.md) and [compatibility policy](https://github.com/DaoyuanLi2816/mini-verl/blob/v0.9.1/docs/compatibility.md).
execution remains untested. Review the [current scale-out contract](https://github.com/DaoyuanLi2816/mini-verl/blob/main/docs/verl-opd-scaleout.md),
[legacy bridge](https://github.com/DaoyuanLi2816/mini-verl/blob/main/docs/legacy-verl-bridge.md) and [compatibility policy](https://github.com/DaoyuanLi2816/mini-verl/blob/main/docs/compatibility.md).

The intended operating loop is **plan → inspect → run → inspect → export**.
`plan --out` byte-binds the YAML, ordered overrides and scanned Parquet inputs
to the exact native config; `run --plan` rejects drift before loading weights.
Its digest follows the run manifest, teacher cache and checkpoints. Direct
`run --config` remains available for experiments. See [immutable execution
plans](https://github.com/DaoyuanLi2816/mini-verl/blob/v0.9.1/docs/immutable-plans.md).
plans](https://github.com/DaoyuanLi2816/mini-verl/blob/main/docs/immutable-plans.md).

## Research and validation

miniVERL keeps every measured study—including negative results, superseded
runs and preregistered early stops—public under the documentation. None is used
as a claim that OPD universally beats SFT, DPO or KD: see the
[v0.7 External Alignment Gate](https://github.com/DaoyuanLi2816/mini-verl/blob/v0.9.1/docs/alignment-external/alignment-external-v1.md),
[Alignment Lab](https://github.com/DaoyuanLi2816/mini-verl/blob/v0.9.1/docs/alignment-lab/alignment-lab-v1.md),
[RecoveryBench](https://github.com/DaoyuanLi2816/mini-verl/blob/v0.9.1/docs/recoverybench/recoverybench-v1.md), and the
[calculator study](https://github.com/DaoyuanLi2816/mini-verl/blob/v0.9.1/docs/benchmarking.md).
[v0.7 External Alignment Gate](https://github.com/DaoyuanLi2816/mini-verl/blob/main/docs/alignment-external/alignment-external-v1.md),
[Alignment Lab](https://github.com/DaoyuanLi2816/mini-verl/blob/main/docs/alignment-lab/alignment-lab-v1.md),
[RecoveryBench](https://github.com/DaoyuanLi2816/mini-verl/blob/main/docs/recoverybench/recoverybench-v1.md), and the
[calculator study](https://github.com/DaoyuanLi2816/mini-verl/blob/main/docs/benchmarking.md).

New runs establish tokenizer compatibility through structural identity. The
legacy behavioral fingerprint is retained only for migration and is not an
identity proof. Scientific caveats and immutable source hashes remain in the
detailed reports and [limitations](https://github.com/DaoyuanLi2816/mini-verl/blob/v0.9.1/docs/limitations.md).
detailed reports and [limitations](https://github.com/DaoyuanLi2816/mini-verl/blob/main/docs/limitations.md).

## Development, security and license

Expand All @@ -238,6 +238,6 @@ pytest -q -m "not gpu and not network"

Contributions should keep the one-GPU boundary explicit and include tests for
new failure modes. Report vulnerabilities privately through
[SECURITY.md](https://github.com/DaoyuanLi2816/mini-verl/blob/v0.9.1/SECURITY.md). See [CONTRIBUTING.md](https://github.com/DaoyuanLi2816/mini-verl/blob/v0.9.1/CONTRIBUTING.md), the
[changelog](https://github.com/DaoyuanLi2816/mini-verl/blob/v0.9.1/CHANGELOG.md), [citation metadata](https://github.com/DaoyuanLi2816/mini-verl/blob/v0.9.1/CITATION.cff),
[reproducibility guide](https://github.com/DaoyuanLi2816/mini-verl/blob/v0.9.1/docs/reproducibility.md), and [Apache-2.0 license](https://github.com/DaoyuanLi2816/mini-verl/blob/v0.9.1/LICENSE).
[SECURITY.md](https://github.com/DaoyuanLi2816/mini-verl/blob/main/SECURITY.md). See [CONTRIBUTING.md](https://github.com/DaoyuanLi2816/mini-verl/blob/main/CONTRIBUTING.md), the
[changelog](https://github.com/DaoyuanLi2816/mini-verl/blob/main/CHANGELOG.md), [citation metadata](https://github.com/DaoyuanLi2816/mini-verl/blob/main/CITATION.cff),
[reproducibility guide](https://github.com/DaoyuanLi2816/mini-verl/blob/main/docs/reproducibility.md), and [Apache-2.0 license](https://github.com/DaoyuanLi2816/mini-verl/blob/main/LICENSE).
29 changes: 21 additions & 8 deletions docs/generated/quality.json
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
{
"schema_version": 2,
"release": "0.9.1",
"status": "candidate",
"status": "released",
"quality_floor": "2,000+ tests and 80%+ branch coverage at v0.9.1",
"local_validation": {
"scope": "the maintainer's workstation, where the GPU and Windows-specific paths actually run",
"commit": "b3223f2e5f038ce9cb72cb4376f0a01d86050e32",
"commit_relationship": "semantic-contract and documentation product head before release-only metadata",
"commit": "7dd7bdbf65207e15fdebed7e9ceb0eb82883046a",
"commit_relationship": "final release PR head; the squash merge carries the same product tree",
"measured_at": "2026-08-13T22:10:22-07:00",
"platform": "Windows 11",
"python": "CPython 3.10 for coverage; CPython 3.12 for CUDA",
"python": "CPython 3.10 for coverage, local CUDA tests and the clean public CUDA install",
"coverage_mode": "branch",
"cpu_non_gpu_non_network": {
"passed": 2234,
Expand All @@ -28,10 +28,23 @@
},
"release_validation": {
"scope": "the exact immutable v0.9.1 release commit",
"commit": "pending",
"workflows": {},
"conclusion": "pending",
"commit": "6c0f3d818c10419e0bfba81f3ad1c5adf24eaf09",
"workflows": {
"ci": "https://github.com/DaoyuanLi2816/mini-verl/actions/runs/31772652832",
"build": "https://github.com/DaoyuanLi2816/mini-verl/actions/runs/31772652856",
"docs": "https://github.com/DaoyuanLi2816/mini-verl/actions/runs/31772945978",
"pinned_verl_bridge": "https://github.com/DaoyuanLi2816/mini-verl/actions/runs/31772652801",
"release": "https://github.com/DaoyuanLi2816/mini-verl/actions/runs/31772945981"
},
"conclusion": "success",
"gpu_coverage": "none; no GPU runner is configured for this repository, so the GPU counts above exist only from the local measurement",
"publication": null
"publication": {
"pypi": "https://pypi.org/project/miniverl/0.9.1/",
"github_release": "https://github.com/DaoyuanLi2816/mini-verl/releases/tag/v0.9.1",
"documentation": "https://daoyuanli2816.github.io/mini-verl/",
"immutable_documentation_build": "https://github.com/DaoyuanLi2816/mini-verl/actions/runs/31772945978",
"wheel_sha256": "3cf1bd61b915e8ae57e0cccdc6ca9c017bbe5bcf1b81ac7ed20c7c9ed9808825",
"sdist_sha256": "9fc4e63d6efb70a0b635af4f61c4b01a99d3496634841d7a8e8e6d8d06784e9e"
}
}
}
4 changes: 2 additions & 2 deletions docs/overrides/main.html
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
{% extends "base.html" %}

{% block announce %}
<div class="docs-channel" data-stable-version="0.9.1" data-dev-version="0.9.1">
<div class="docs-channel" data-stable-version="0.9.1" data-dev-version="0.10.0.dev0">
<strong id="docs-channel-label">Stable documentation</strong>
<label for="docs-version-selector">Version</label>
<select id="docs-version-selector" aria-label="Documentation version">
<option value="stable">Stable 0.9.1</option>
<option value="dev">Development 0.9.1</option>
<option value="dev">Development 0.10.0.dev0</option>
</select>
</div>
{% endblock %}
29 changes: 29 additions & 0 deletions docs/release-checklist.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,18 @@ This is the release gate and publication record for miniVERL. A checked item
names an invariant exercised on the stated source. Publication begins only
after the exact release commit and its remote checks are green.

## v0.10.0 development

- [x] Begin from the verified v0.9.1 release and `0.10.0.dev0` canonical state.
- [ ] Add the versioned internal compatibility-profile registry and profile
identity binding without an unrestricted plugin loader.
- [ ] Add the pinned verl v0.8 policy-gradient k1 profile with scalar, gradient,
freshness, resume and export conformance.
- [ ] Publish bounded RTX 4080 systems evidence for PG k1 and a full SmolLM2
direct-GKD developer recipe; do not add a task-quality benchmark.
- [ ] Add validated community hardware records and document the measured or
explicitly unmeasured Linux/WSL state.

## v0.9.1 development

The focused v0.9.1 scope repairs the verl OPD semantic contract: explicit
Expand Down Expand Up @@ -204,6 +216,23 @@ unauthorized after checkpoint-selection failure**.

## After the tag

- [x] v0.9.1 release run
[`31772945981`](https://github.com/DaoyuanLi2816/mini-verl/actions/runs/31772945981)
completed the full release gate, OIDC Trusted Publishing, per-file
attestations, exact public install and GitHub Release creation for commit
`6c0f3d818c10419e0bfba81f3ad1c5adf24eaf09`.
- [x] PyPI and the
[v0.9.1 GitHub Release](https://github.com/DaoyuanLi2816/mini-verl/releases/tag/v0.9.1)
expose identical files: wheel SHA-256
`3cf1bd61b915e8ae57e0cccdc6ca9c017bbe5bcf1b81ac7ed20c7c9ed9808825`,
sdist SHA-256
`9fc4e63d6efb70a0b635af4f61c4b01a99d3496634841d7a8e8e6d8d06784e9e`.
- [x] A fresh CPython 3.10 environment installed CUDA PyTorch 2.13.0+cu130,
public `miniverl[train,cuda]==0.9.1` and bitsandbytes 0.50.1; `doctor`
reported RTX 4080 CUDA, BF16 and QLoRA capabilities available.
- [x] Advance subsequent development to `0.10.0.dev0`; the main-only docs
deployment is verified after this state-sync PR merges.

- [x] v0.9.0 release run
[`31681888075`](https://github.com/DaoyuanLi2816/mini-verl/actions/runs/31681888075)
completed the full release gate, OIDC Trusted Publishing, one public
Expand Down
6 changes: 3 additions & 3 deletions release-state.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -17,13 +17,13 @@
# such distinction, which is how its tag shipped a docs selector still
# advertising "Stable 0.6.1 / Development 0.6.2.dev0".
schema_version: 1
phase: release
phase: development

stable:
version: "0.9.1"
tag: "v0.9.1"
release_commit: "pending"
release_commit: "6c0f3d818c10419e0bfba81f3ad1c5adf24eaf09"
released_at: "2026-08-13"

development:
version: "0.9.1"
version: "0.10.0.dev0"
2 changes: 1 addition & 1 deletion src/miniverl/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,6 @@

from __future__ import annotations

__version__ = "0.9.1"
__version__ = "0.10.0.dev0"

__all__ = ["__version__"]
0