Reorganize examples into self-contained per-example folders - #6820
Merged
Conversation
|
The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: eead7acd45
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
sergiopaniego
left a comment
sergiopaniego
left a comment
Member
There was a problem hiding this comment.
LGTM! my only concern is on the links that will be broken after merging but I'll try to update the ones that can be updated (blogs, other repos...) 🫠
some nits from agent review:
- The new
example_overview.mdonly has#indexand#distributed-trainingas anchors, but three links still point to the removed sections:jobs_training.md:212(example_overview#scripts) andopenenv.md:8and:135(#openenv-scripts/#openenv-notebooks). Pointing them toexample_overview#indexfixes it (same as Codex's finding). - Some inner filenames don't match their folder (
sft_qwen3_vl/sft_qwen_vl.ipynb,grpo_qlora/grpo_trl_lora_qlora.ipynb,grpo_wordle/openenv_wordle_grpo.ipynb,grpo_sudoku/openenv_sudoku_grpo.ipynb,sft_qlora/sft_trl_lora_qlora.ipynb). Since external links break anyway because of the folder move, normalizing them now is free; after merge it would cost a second round of broken links. .gitignore:144still hasexamples/notebooks/wandb/.grpo_sudoku/sudoku.pydocuments running from the repo root, but--system-prompt-pathdefaults to the cwd-relative"sudoku_prompt.txt", so the documented command doesn't find the prompt. Pre-existing, but the move to self-contained folders is the natural moment to switch it toPath(__file__).parent / "sudoku_prompt.txt", likesft_tool_calling/sft_tiny_aya_tool_calling.pyalready does.
This was referenced Aug 20, 2026
sergiopaniego
added a commit
to huggingface/blog
that referenced
this pull request
Aug 20, 2026
sergiopaniego
added a commit
to huggingface/blog
that referenced
this pull request
Aug 20, 2026
pcuenca
approved these changes
Aug 20, 2026
Member
|
Is GOLD ending up as intended? |
sergiopaniego
added a commit
to huggingface/smol-course
that referenced
this pull request
Aug 20, 2026
qgallouedec
force-pushed
the
reorg-examples
branch
3 times, most recently
from
August 24, 2026 14:38
c15eb3a to
f0f2368
Compare
Member
Author
|
@sergiopaniego yes good catch. The gold.py deletion is intended: it was one of the generic CLI wrappers this PR removes across the board. But |
qgallouedec
force-pushed
the
reorg-examples
branch
from
August 24, 2026 16:25
7e70831 to
0042a0f
Compare
- One folder per example, named method + task (grpo_wordle, sft_gpt_oss, ...); each folder holds everything the example needs (scripts, notebooks, prompts, chat templates, eval code) - Split the openenv, vlm, and ppo buckets into per-example folders - Drop thin single-trainer example scripts, redundant with trl/scripts (CLI) and the runnable snippets in each trainer's doc page - Drop orphaned examples/cli_configs - Rewrite example_overview.md as a single index of examples; rewire all doc links, Colab badges, and the harbor runtime path strings
Suggested by @sergiopaniego in review.
The reorg removed the Scripts / OpenEnv Scripts / OpenEnv Notebooks sections; jobs_training.md and openenv.md still linked to their anchors.
The reorg renamed folders but kept legacy file names (sft_qwen_vl.ipynb under sft_qwen3_vl/, openenv_sudoku_grpo.ipynb, grpo_trl_lora_qlora.ipynb, *_vlm.py, bare ppo.py/rloo.py/gspo.py). Every folder's main entry is now examples/<name>/<name>.py or .ipynb; variant and helper files keep their suffixed names. All Colab badges, doc links, and docstring run commands updated in the same sweep.
Deleting examples/scripts/gold.py removed text-mode GOLD's only end-to-end recipe (there is no trl gold CLI). It comes back as examples/gold_chatbot_arena/, with its doc section and Index row. The online DPO benchmark blocks still invoke the deleted examples/scripts/online_dpo.py; the prose now says to run them from a v1.10.0 checkout.
- openenv.md: enumerate the 8 ready-to-use OpenEnv examples instead of pointing at the generic Index - jobs_training.md: say which Index entries are uv-submittable, and stop calling trl/scripts/sft.py an example script - add the missing run-command docstrings (grpo_2048, ppo_sentiment, ppo_tldr) and drop rloo_math's pip line that disagreed with its script header - examples/README.md: defer the layout description to the docs page instead of duplicating it - distillation_trainer.md: the section documents the CLI, not an example script - drop the stale examples/notebooks/wandb/ gitignore entry - add a test asserting the example_overview Index stays in sync with the examples/ folders
qgallouedec
force-pushed
the
reorg-examples
branch
from
August 24, 2026 19:18
b153620 to
62dd7aa
Compare
Member
Author
|
External link audit for this reorg: I scanned org:huggingface repos (GitHub code search, then cloned and grepped all 84 removed paths). 43 files in 8 repos reference paths this PR deletes or renames. GitHub doesn't redirect renamed paths, so these 404 once this merges. One row per link (identical links within a file are deduped, lines listed). Fix PR column: ✅ = fixed correctly by the open PR,
so tldr: fix PRs are open for all 8 repos. huggingface/blog#3516 (6 links), huggingface/OpenEnv#1086 (4 links) and huggingface/cookbook#367 (1 link) keep the old file names and need a follow-up commit, flagged in a comment on each. huggingface/smol-course#306, huggingface/openenv-course#8, huggingface/huggingface-llama-recipes#89, huggingface/skills#234 and huggingface/ml-intern#360 are good to go. Scanned with zero affected: course, notebooks, transformers, accelerate, peft, huggingface_hub, lerobot, optimum-habana (only tag-pinned or already-dead references, e.g. examples/scripts/grpo.py, vsft_llava.py, gpt2-sentiment.ipynb are already gone from main today). |
Member
Author
|
merging this one. |
This was referenced Aug 24, 2026
sergiopaniego
added a commit
to huggingface/blog
that referenced
this pull request
Aug 25, 2026
The reorg also renames each example's main file after its folder, so the previous paths still 404. Also retargets the GOLD link to its new home in examples/gold_chatbot_arena/ instead of the v1.10.0 pin.
sergiopaniego
added a commit
to huggingface/cookbook
that referenced
this pull request
Aug 25, 2026
The reorg also renames each example's main file after its folder.
sergiopaniego
added a commit
to huggingface/OpenEnv
that referenced
this pull request
Aug 25, 2026
The reorg also renames each example's main file after its folder, so the previous paths still 404.
sergiopaniego
added a commit
to huggingface/blog
that referenced
this pull request
Aug 25, 2026
* Update TRL example paths after examples/ reorg (huggingface/trl#6820) * Update TRL example paths in older posts (examples/ reorg, huggingface/trl#6820) * Pin GOLD example link to v1.10.0 (script removed in examples/ reorg, huggingface/trl#6820) * Use the new per-example file names (huggingface/trl#6820) The reorg also renames each example's main file after its folder, so the previous paths still 404. Also retargets the GOLD link to its new home in examples/gold_chatbot_arena/ instead of the v1.10.0 pin. * Rename the inline link labels to match the new file names
q-qp-p
pushed a commit
to q-qp-p/meta-pytorch-OpenEnv
that referenced
this pull request
Aug 25, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
examples/was split by format (scripts/vsnotebooks/), which scatters related files:sft_nemotron_3existed as both a script and a notebook in different folders, the OpenEnv notebooks lived apart from the OpenEnv scripts, andsudoku_prompt.txtsat loose next to unrelated scripts.I don't think this makes a lot of sense.
I suggest a new approach:
grpo_wordle,sft_gpt_oss,ppo_tldr), and the folder holds everything the example needs (scripts, notebooks, prompts, chat templates, eval code). Exception: sharedaccelerate_configs/and thedatasets/generation scripts stay at the root.trl/scripts/(CLI) and every trainer doc page has a runnable snippet.Layout
Before
After
Accepted breakage / open questions
examples/scripts/...andexamples/notebooks/...(blog posts, issues) will 404.trl/scripts/is an alternative.sdft_privileged_context(the example has no fixed dataset),grpo_harbor/grpo_seta(task = the environment).gspo_visual_math(it isgrpo_visual_mathplus--importance_sampling_level sequence),grpo_rnj_1_instruct(same story asgrpo_qloraon a niche model),sft_gemma3(borderline bare training script), andcarla_vlm_gemma.pyinsidegrpo_carla.Note
Low Risk
Documentation and example layout only; no training library logic changes, though external links to old
examples/scripts/paths will break until updated.Overview
Reorganizes
examples/from ascripts/vsnotebooks/split into one folder per story (e.g.grpo_wordle,async_distillation_math), each holding scripts, notebooks, prompts, harnesses, and eval code together. Shared assets stay atexamples/accelerate_configs/andexamples/datasets/.Removes thin “demo” training scripts from
examples/scripts/(BCO, CPO, distillation, GKD, KTO, Nash-MD, online DPO, ORPO, PRM, reward modeling, XPO, and stub redirects for DPO/SFT). Those flows are expected viatrl/scriptsCLIs (e.g. distillation docs now usetrl distillation) or inline snippets on trainer doc pages (e.g. expandedBCOTrainerexample). Task-specific scripts that remain are moved and renamed under the new folders, with docstrings and cross-links updated throughout docs (example_overview, OpenEnv, Harbor, GOLD, Jobs, etc.).Docs and discoverability:
example_overview.mdis rewritten around a single Index table (Colab badges point at co-located notebooks).examples/README.mdadds conventions for new examples.examples/notebooks/README.mdandexamples/cli_configs/example_config.yamlare dropped;.gitignoredropsexamples/notebooks/wandb/.Reviewed by Cursor Bugbot for commit 62dd7aa. Bugbot is set up for automated code reviews on this repo. Configure here.