freesolo-flash-dev 1.2.61__tar.gz → 1.2.64__tar.gz

{freesolo_flash_dev-1.2.61 → freesolo_flash_dev-1.2.64}/CHANGELOG.md

@@ -54,6 +54,10 @@ This file starts at 1.1.35. Earlier releases are not reconstructed here; use
 
 ### Fixed
 
+- Completed verl children now finish each captured W&B run before the W&B service shuts down,
+  avoiding teardown tracebacks, and `flash env setup` now gives every starter config explicit W&B
+  project and folder-derived run metadata.
+
 - An ordered `[gpu] type` list is now priced over every class it declares acceptable, not just the
   first. Allocation cost-ranks the whole set, so quoting the head alone priced a shape the run may
   never be given — an authored `["B200", "H100"]` quoted roughly 3x the H100 the allocator would

{freesolo_flash_dev-1.2.61 → freesolo_flash_dev-1.2.64}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: freesolo-flash-dev
-Version: 1.2.61
+Version: 1.2.64
 Summary: Flash — managed LoRA post-training (SFT/GRPO/OPD) for Freesolo environments, driven by the `flash` CLI
 Project-URL: Homepage, https://github.com/freesolo-co/flash
 Project-URL: Repository, https://github.com/freesolo-co/flash

{freesolo_flash_dev-1.2.61 → freesolo_flash_dev-1.2.64}/flash/cli/commands/env/setup.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import json
 import sys
 import tomllib
+from collections.abc import Mapping
 from pathlib import Path
 
 from flash._internal.channel import CLI_NAME
@@ -13,6 +14,7 @@ from flash.cli.commands.env.retained import (
     _warn_if_environment_form_disagrees,
     _warn_if_retained_starter_files_describe_another_plane,
 )
+from flash.cli.commands.env.setup_wandb import _wandb_block, _wandb_project
 from flash.cli.scaffold import TRAINING_MD
 from flash.cli.ui import render
 from flash.envs.evaluations import _DEFAULT_EVALUATIONS_PATH
@@ -358,22 +360,14 @@ _REASONING_OPTIONS = [
 _SKIP_TRACES = ""  # sentinel option value: scaffold the starter rows instead of importing
 
 
-def _require_setup_project(args) -> str:
+def _require_setup_project(args, *, api_url: str | None, api_key: str) -> Mapping[str, object]:
     """Resolve and validate the one explicit project used by the whole scaffold."""
-    from flash.client import ClientError, list_projects, resolve_project_id
-    from flash.client.config import load_credentials
+    from flash.client import ClientError, list_projects, resolve_project
     from flash.client.http import has_freesolo_backend
 
-    api_url, api_key = load_credentials()
-    if not api_key:
-        raise ClientError(
-            f"not logged in. Run `{CLI_NAME} login` before `{CLI_NAME} env setup` "
-            "so the project can be validated"
-        )
-
     supplied = str(getattr(args, "project", "") or "").strip()
     if supplied:
-        return resolve_project_id(supplied, api_key, api_url)
+        return resolve_project(supplied, api_key, api_url)
     if not _setup_interactive(args):
         raise ClientError(
             "--project PROJECT_UUID is required in noninteractive mode, with redirected stdin, or with --yes"
@@ -395,7 +389,7 @@ def _require_setup_project(args) -> str:
             f"`{CLI_NAME} projects create NAME`"
         )
     selected = render.select_required("Choose the Freesolo project for this environment", options)
-    return resolve_project_id(selected, api_key, api_url)
+    return resolve_project(selected, api_key, api_url)
 
 
 # Guidance the starter .py docstrings carry, per plane kind. The templates hold placeholders
@@ -450,7 +444,7 @@ def _render_starter(template: str, project_id: str, *, can_publish: bool) -> str
     return template.replace("PROJECT_UUID", project_id)
 
 
-def _plane_can_publish_environments() -> bool:
+def _plane_can_publish_environments(api_url: str | None) -> bool:
     """Whether `flash env push` can actually publish for the logged-in plane.
 
     Publishing uploads to the plane, which commits into the managed environment hub
@@ -462,10 +456,8 @@ def _plane_can_publish_environments() -> bool:
     operator-run Freesolo-compatible backend has a project directory (which is what that helper
     answers) but still cannot publish to the hub.
     """
-    from flash.client.config import load_credentials
     from flash.serve.urls import is_freesolo_hosted_url
 
-    api_url, _ = load_credentials()
     # Unset means the built-in default, which is the managed plane.
     return api_url is None or is_freesolo_hosted_url(api_url)
 
@@ -553,7 +545,7 @@ def _existing_reasoning(configs: tuple[Path, ...]) -> bool | None:
     return next(iter(found.values()), None)
 
 
-def _traces_dataset(args, project_id: str) -> str | None:
+def _traces_dataset(args, project_id: str, api_key: str) -> str | None:
     """Optionally export traces from the already-selected project."""
     if not _setup_interactive(args):
         return None
@@ -568,7 +560,7 @@ def _traces_dataset(args, project_id: str) -> str | None:
     if use_traces == _SKIP_TRACES:
         return None
     try:
-        exported = traces.fetch_records(project_id)
+        exported = traces.fetch_records(project_id, api_key)
     except Exception as exc:  # trace import is optional after project validation succeeds
         _warn(f"could not export traces from {project_id} ({exc}); using the starter dataset")
         return None
@@ -692,6 +684,7 @@ def _write_rl_config(
     rl: Path,
     project_line: str,
     thinking_line: str,
+    wandb_block: str,
     env_comment: str,
     max_examples_line: str,
     rl_reasoning_train: str,
@@ -704,6 +697,7 @@ def _write_rl_config(
             'algorithm = "grpo"\n'
             f"{thinking_line}"
             "\n"
+            f"{wandb_block}"
             f"{env_comment}"
             "[train]\n"
             "epochs = 1\n"
@@ -722,6 +716,7 @@ def _write_sft_config(
     sft: Path,
     project_line: str,
     thinking_line: str,
+    wandb_block: str,
     env_comment: str,
     max_examples_line: str,
     sft_reasoning_note: str,
@@ -734,6 +729,7 @@ def _write_sft_config(
             'algorithm = "sft"\n'
             f"{thinking_line}"
             "\n"
+            f"{wandb_block}"
             f"{env_comment}"
             "[train]\n"
             "epochs = 1\n"
@@ -766,6 +762,7 @@ def _write_opd_config(
     project_line: str,
     project_id: str,
     thinking_line: str,
+    wandb_block: str,
     max_examples_line: str,
     *,
     can_publish: bool = True,
@@ -788,6 +785,7 @@ def _write_opd_config(
             'algorithm = "opd"   # on-policy distillation from a managed parasail teacher (default glm 5.2)\n'
             f"{thinking_line}"
             "\n"
+            f"{wandb_block}"
             + _environment_comment(
                 project_id,
                 can_publish=can_publish,
@@ -816,15 +814,34 @@ def _write_training_guide(training: Path, project_id: str) -> None:
         )
 
 
+def _resolve_setup_identity(args) -> tuple[str, str, str, str, str]:
+    """Resolve the credential, project, and folder identity used by every setup phase."""
+    from flash.client import ClientError
+    from flash.client.config import load_credentials
+
+    api_url, api_key = load_credentials()
+    if not api_key:
+        raise ClientError(
+            f"not logged in. Run `{CLI_NAME} login` before `{CLI_NAME} env setup` "
+            "so the project can be validated"
+        )
+    project = _require_setup_project(args, api_url=api_url, api_key=api_key)
+    project_id = str(project["id"])
+    folder_name = Path.cwd().name
+    if not folder_name.strip():
+        raise ClientError("the current environment folder name must be nonblank")
+    return api_url, api_key, project_id, _wandb_project(project), folder_name
+
+
 def cmd_env_setup(args) -> int:
-    project_id = _require_setup_project(args)
+    api_url, api_key, project_id, project_name, folder_name = _resolve_setup_identity(args)
     _validate_existing_config_projects(project_id)
     starter_env = Path("environment.py")
     starter_evaluations = Path(_DEFAULT_EVALUATIONS_PATH)
     dataset = Path("dataset/train.jsonl")
     # trace import is optional and can only read the selected project. an existing dataset is never
     # overwritten, so importing into it would be a silently discarded download.
-    traces_jsonl = None if dataset.exists() else _traces_dataset(args, project_id)
+    traces_jsonl = None if dataset.exists() else _traces_dataset(args, project_id, api_key)
     multi_turn, starter_env_exists = _resolve_turn_mode(args, starter_env, dataset)
 
     rl = Path("configs/rl.toml")
@@ -837,7 +854,7 @@ def cmd_env_setup(args) -> int:
     reasoning_configs = (rl, opd, sft)
     reasoning = _resolve_reasoning_mode(args, reasoning_configs)
 
-    can_publish = _plane_can_publish_environments()
+    can_publish = _plane_can_publish_environments(api_url)
     _warn_if_environment_form_disagrees(reasoning_configs, can_publish=can_publish, warn=_warn)
     env_py = _render_starter(
         _STARTER_ENV_MULTITURN_PY if multi_turn else _STARTER_ENV_PY,
@@ -908,6 +925,7 @@ def cmd_env_setup(args) -> int:
         rl,
         project_line,
         thinking_line,
+        _wandb_block(project_name, f"{folder_name}-grpo"),
         env_comment,
         max_examples_line,
         rl_reasoning_train,
@@ -916,6 +934,7 @@ def cmd_env_setup(args) -> int:
         sft,
         project_line,
         thinking_line,
+        _wandb_block(project_name, f"{folder_name}-sft"),
         env_comment,
         max_examples_line,
         sft_reasoning_note,
@@ -927,6 +946,7 @@ def cmd_env_setup(args) -> int:
         project_line,
         project_id,
         thinking_line,
+        _wandb_block(project_name, f"{folder_name}-opd"),
         max_examples_line,
         can_publish=can_publish,
     )

freesolo_flash_dev-1.2.64/flash/cli/commands/env/setup_wandb.py

@@ -0,0 +1,30 @@
+"""W&B metadata helpers for environment scaffolds."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+
+_WANDB_PROJECT_MAX_LENGTH = 128
+_WANDB_PROJECT_FORBIDDEN = frozenset("/\\#?%:")
+
+
+def _wandb_project(project: Mapping[str, object]) -> str:
+    """Adapt a resolved canonical project to a W&B-safe project name."""
+    project_id = str(project["id"])
+    name = project.get("name")
+    if not isinstance(name, str) or not name.strip():
+        return project_id
+    if len(name) > _WANDB_PROJECT_MAX_LENGTH or any(
+        character in _WANDB_PROJECT_FORBIDDEN for character in name
+    ):
+        return project_id
+    return name
+
+
+def _wandb_block(project_name: str, run_name: str) -> str:
+    return (
+        "[wandb]\n"
+        f"project = {json.dumps(project_name, ensure_ascii=False)}\n"
+        f"run_name = {json.dumps(run_name, ensure_ascii=False)}\n\n"
+    )

{freesolo_flash_dev-1.2.61 → freesolo_flash_dev-1.2.64}/flash/cli/commands/traces.py

@@ -77,8 +77,8 @@ def fetch_records(
 ) -> dict:
     """A project's traces in the requested shape, converted server-side.
 
-    Omitting `api_key` reads the stored credential, which is right for `env_setup`'s call: it holds
-    no snapshot this key has to agree with.
+    Omitting `api_key` reads the stored credential. Callers that already resolved configuration
+    should pass the key from that snapshot so a concurrent login cannot change the request identity.
     """
     key = _require_api_key(api_key or load_credentials()[1])
     return export_trace_records(project_id, key, export_format=export_format)

{freesolo_flash_dev-1.2.61 → freesolo_flash_dev-1.2.64}/flash/cli/scaffold/TRAINING.md

@@ -272,8 +272,10 @@ lora_rank = 32              # lora_alpha defaults to 2 x lora_rank; set it to ov
 # All knobs live under [train]. Do not add [sft], [grpo], or [opd] tables.
 
 [wandb]
-# project  = "my-project"   # the table allows exactly `project` and `run_name`;
-# run_name = "sft-run-1"    # `name` is rejected
+# new scaffolds set `project` from the selected Freesolo project and `run_name` from the folder
+# plus algorithm. edit either value as needed; only `project` and `run_name` are allowed.
+# project  = "my-project"
+# run_name = "sft-run-1"
 ```
 
 **Knobs are scoped by algorithm.** `[train]` is one flat table shared by all three algorithms,

{freesolo_flash_dev-1.2.61 → freesolo_flash_dev-1.2.64}/flash/client/__init__.py

@@ -1,5 +1,7 @@
 """HTTP client for the managed Flash control plane (used by the CLI)."""
 
+from collections.abc import Mapping
+
 from flash._internal.channel import CLI_NAME
 from flash.client.config import load_credentials, save_credentials
 from flash.client.http import (
@@ -20,8 +22,10 @@ from flash.client.http import (
 from flash.core.spec import require_project_id
 
 
-def resolve_project_id(project_id: str, api_key: str, api_url: str | None = None) -> str:
-    """Resolve one project id, turning "not yours / not there" into the actionable CLI refusal.
+def resolve_project(
+    project_id: str, api_key: str, api_url: str | None = None
+) -> Mapping[str, object]:
+    """Resolve one project, turning "not yours / not there" into the actionable CLI refusal.
 
     403 and 404 are the same answer to a CLI user -- this project is not one you can record against
     -- and neither is distinguishable from a typo, so they collapse into one message naming the way
@@ -48,9 +52,9 @@ def resolve_project_id(project_id: str, api_key: str, api_url: str | None = None
     at call time, which is the binding the CLI tests patch.
     """
     if api_url is not None and not has_freesolo_backend(api_url):
-        return require_project_id(project_id)
+        return {"id": require_project_id(project_id)}
     try:
-        return str(get_project(project_id, api_key)["id"])
+        return get_project(project_id, api_key)
     except ApiError as exc:
         if exc.status not in {403, 404}:
             raise
@@ -60,6 +64,11 @@ def resolve_project_id(project_id: str, api_key: str, api_url: str | None = None
         ) from exc
 
 
+def resolve_project_id(project_id: str, api_key: str, api_url: str | None = None) -> str:
+    """Resolve and return one canonical project id."""
+    return str(resolve_project(project_id, api_key, api_url)["id"])
+
+
 __all__ = [
     "ApiClient",
     "ApiError",
@@ -72,6 +81,7 @@ __all__ = [
     "list_projects",
     "list_trace_projects",
     "load_credentials",
+    "resolve_project",
     "resolve_project_id",
     "save_credentials",
     "upload_eval_run",

{freesolo_flash_dev-1.2.61 → freesolo_flash_dev-1.2.64}/flash/content/multimodal.py

@@ -9,6 +9,7 @@ import json
 import urllib.parse
 from dataclasses import dataclass
 from pathlib import Path
+from typing import Any
 
 MAX_IMAGES_PER_EXAMPLE = 8
 MAX_IMAGE_SOURCE_BYTES = 20 * 1024 * 1024
@@ -140,20 +141,32 @@ def _validate_dimensions(width: int, height: int) -> int:
     return pixels * 3
 
 
-def _inspect_image_bytes(data: bytes) -> int:
+def inspect_image_bytes(data: bytes) -> tuple[int, int, int]:
+    """Validate one image's header and return its (decoded_rgb_bytes, width, height).
+
+    Reads the header only: the pixels are not decoded here.
+    """
     try:
         from PIL import Image
     except ImportError as exc:
         raise RuntimeError("Pillow is required for multimodal image training") from exc
     try:
         with Image.open(io.BytesIO(data)) as image:
-            return _validate_dimensions(image.width, image.height)
+            return (
+                _validate_dimensions(image.width, image.height),
+                image.width,
+                image.height,
+            )
     except ValueError:
         raise
     except Exception as exc:
         raise ValueError("image source is not a valid image") from exc
 
 
+def _inspect_image_bytes(data: bytes) -> int:
+    return inspect_image_bytes(data)[0]
+
+
 def _pil_descriptor(image: object) -> str:
     width = int(getattr(image, "width", 0) or 0)
     height = int(getattr(image, "height", 0) or 0)
@@ -165,14 +178,26 @@ def _pil_descriptor(image: object) -> str:
     return _descriptor("bytes", base64.b64encode(data).decode("ascii"))
 
 
-def normalize_image_source(source: object, package_root: str | Path | None) -> str:
-    """Convert one supported image source to an Arrow-safe descriptor."""
+def normalize_image_source(
+    source: object,
+    package_root: str | Path | None,
+    *,
+    defer_validation: bool = False,
+) -> str:
+    """Convert one supported image source to an Arrow-safe descriptor.
+
+    ``defer_validation`` skips the per-source pixel inspection for EVERY source kind, for a caller
+    that validates the resulting descriptors itself. Profiling does exactly that, through one cached
+    pass that bounds total decode work; inspecting here as well would decode each image twice and
+    charge only some kinds to that budget. Every other caller validates eagerly.
+    """
     root = Path(package_root) if package_root is not None else None
     if isinstance(source, bytearray):
         source = bytes(source)
     if isinstance(source, bytes):
         _check_source_size(len(source))
-        _inspect_image_bytes(source)
+        if not defer_validation:
+            _inspect_image_bytes(source)
         return _descriptor("bytes", base64.b64encode(source).decode("ascii"))
     if _is_pil_image(source):
         return _pil_descriptor(source)
@@ -183,7 +208,8 @@ def normalize_image_source(source: object, package_root: str | Path | None) -> s
     scheme = parsed.scheme.lower()
     if scheme == "data":
         data = _data_uri_bytes(value)
-        _inspect_image_bytes(data)
+        if not defer_validation:
+            _inspect_image_bytes(data)
         return _descriptor("data_uri", value)
     if scheme in {"http", "https"}:
         # flash never fetches a user-supplied URL server-side. download the image ahead of time
@@ -198,8 +224,10 @@ def normalize_image_source(source: object, package_root: str | Path | None) -> s
     if scheme:
         raise ValueError(f"unsupported image URL scheme: {scheme}")
     path = _package_image_path(value, root)
-    _inspect_image_bytes(path.read_bytes())
-    return _descriptor("path", path.relative_to(root.resolve()).as_posix())
+    descriptor = _descriptor("path", path.relative_to(root.resolve()).as_posix())
+    if not defer_validation:
+        _inspect_image_bytes(path.read_bytes())
+    return descriptor
 
 
 def _image_source_from_block(block: dict) -> object | None:
@@ -284,7 +312,11 @@ def text_only_prompt_messages(messages: list[dict]) -> list[dict]:
     return stripped
 
 
-def _reject_literal_image_placeholder(text: str, message_index: int) -> None:
+def _reject_literal_image_placeholder(
+    text: str,
+    message_index: int,
+    markers: tuple[str, ...] = (IMAGE_TEACHER_PLACEHOLDER, IMAGE_PAD_TOKEN),
+) -> None:
     """Reject prompt text that already contains a reserved image marker.
 
     two distinct markers, one reason. the rendered prompt marks image positions with
@@ -298,8 +330,12 @@ def _reject_literal_image_placeholder(text: str, message_index: int) -> None:
     contributes a run the renderer never produced -- and a run from text can make up for an image
     the provider silently dropped, which is exactly the failure the guard exists to catch. keeping
     it out of the source text is what makes "one run per image" mean what it says.
+
+    ``markers`` narrows the set for callers where only one of the two is live. local sft training
+    never renders the teacher placeholder, so a literal ``<|media_pad|>`` there is ordinary text
+    for a qwen tokenizer and rejecting it would be a false refusal.
     """
-    for marker in (IMAGE_TEACHER_PLACEHOLDER, IMAGE_PAD_TOKEN):
+    for marker in markers:
         if marker in text:
             raise ValueError(
                 f"message {message_index} text contains the reserved image marker "
@@ -364,8 +400,14 @@ def normalize_prompt_images(
     record: dict,
     messages: list[dict],
     package_root: str | Path | None,
+    *,
+    defer_validation: bool = False,
 ) -> NormalizedImages:
-    """Normalize prompt image blocks and top-level fields without mutating the record."""
+    """Normalize prompt image blocks and top-level fields without mutating the record.
+
+    ``defer_validation`` is forwarded to :func:`normalize_image_source`; see it for when a caller
+    may skip the per-source pixel inspection.
+    """
     if not isinstance(messages, list) or not all(isinstance(message, dict) for message in messages):
         raise ValueError("prompt messages must be a list of message objects")
     pending = list(_top_level_sources(record))
@@ -381,14 +423,18 @@ def normalize_prompt_images(
                 f"example contains {image_count} images, exceeding the "
                 f"{MAX_IMAGES_PER_EXAMPLE}-image limit"
             )
-        descriptor = normalize_image_source(source, package_root)
+        descriptor = normalize_image_source(
+            source,
+            package_root,
+            defer_validation=defer_validation,
+        )
         descriptor_bytes += _descriptor_size(descriptor)
         if descriptor_bytes > MAX_TOTAL_IMAGE_DESCRIPTOR_BYTES:
             raise ValueError(
                 f"example encoded image descriptors total {descriptor_bytes} bytes, exceeding the "
                 f"{MAX_TOTAL_IMAGE_DESCRIPTOR_BYTES}-byte limit"
             )
-        source_bytes += descriptor_source_size(descriptor, package_root)
+        source_bytes += _descriptor_source_size(descriptor, package_root)
         if source_bytes > MAX_TOTAL_IMAGE_SOURCE_BYTES:
             raise ValueError(
                 f"example image sources total {source_bytes} bytes, exceeding the "
@@ -465,10 +511,27 @@ def normalize_prompt_images(
             add_descriptor(source)
             image_blocks.append({"type": "image"})
         normalized[first_user]["content"] = [*content, *image_blocks]
+    # checked here, on the finished blocks, rather than inside the loop above: string content never
+    # enters that loop, and the top-level-image path appends to a message the loop already passed.
+    # this is the one point every shape has converged to the same form.
+    #
+    # the unit is a RUN of consecutive text blocks, not one block, for the reason the teacher
+    # renderer already documents: "<|image_" and "pad|>" are each harmless alone and only become
+    # the reserved marker once the template concatenates them. an image block ends a run, since the
+    # processor puts its own expansion there and user text cannot reach across it.
+    for message_index, message in enumerate(normalized):
+        text_run: list[str] = []
+        for block in message["content"]:
+            if block.get("type") == "text":
+                text_run.append(block["text"])
+                continue
+            _reject_literal_image_placeholder("".join(text_run), message_index, (IMAGE_PAD_TOKEN,))
+            text_run = []
+        _reject_literal_image_placeholder("".join(text_run), message_index, (IMAGE_PAD_TOKEN,))
     return NormalizedImages(normalized, descriptors)
 
 
-def descriptor_source_size(descriptor: str, package_root: str | Path | None) -> int:
+def _descriptor_source_size(descriptor: str, package_root: str | Path | None) -> int:
     kind, value = _parse_descriptor(descriptor)
     if kind == "bytes":
         return len(base64.b64decode(value, validate=True))
@@ -481,7 +544,8 @@ def descriptor_source_size(descriptor: str, package_root: str | Path | None) ->
     raise ValueError("invalid internal image descriptor kind")
 
 
-def _read_descriptor_source(descriptor: str, package_root: str | Path | None) -> bytes:
+def read_descriptor_source(descriptor: str, package_root: str | Path | None) -> bytes:
+    """Read one descriptor's raw source bytes under the per-source size limit."""
     kind, value = _parse_descriptor(descriptor)
     if kind == "bytes":
         try:
@@ -532,7 +596,7 @@ def image_descriptors_to_data_uris(
     source_bytes = 0
     decoded_bytes = 0
     for descriptor in descriptors:
-        data = _read_descriptor_source(descriptor, package_root)
+        data = read_descriptor_source(descriptor, package_root)
         source_bytes += len(data)
         if source_bytes > MAX_TOTAL_IMAGE_SOURCE_BYTES:
             raise ValueError(
@@ -553,20 +617,65 @@ def _decode_image_bytes(data: bytes):
         from PIL import Image
     except ImportError as exc:
         raise RuntimeError("Pillow is required for multimodal image training") from exc
+    converted = None
     try:
         with Image.open(io.BytesIO(data)) as image:
             _validate_dimensions(image.width, image.height)
             image.load()
-            return image.convert("RGB")
+            converted = image.convert("RGB")
+            converted.load()
+            return converted
     except ValueError:
+        if converted is not None:
+            converted.close()
         raise
     except Exception as exc:
+        if converted is not None:
+            converted.close()
         raise ValueError("image source is not a valid image") from exc
 
 
+def messages_with_decoded_images(messages: list[dict], images: list[object]) -> list[dict]:
+    """Bind decoded images into a message list's image blocks, in order.
+
+    Shared by sft, opd, and grpo: each algorithm decodes the row's descriptors itself and then
+    needs the same binding into the chat-template input.
+    """
+    image_iter = iter(images)
+    prepared = []
+    for message in messages:
+        copied = dict(message)
+        content = copied.get("content")
+        if isinstance(content, list):
+            blocks = []
+            for block in content:
+                copied_block = dict(block)
+                if copied_block.get("type") == "image":
+                    copied_block["image"] = next(image_iter)
+                blocks.append(copied_block)
+            copied["content"] = blocks
+        prepared.append(copied)
+    try:
+        next(image_iter)
+    except StopIteration:
+        return prepared
+    raise ValueError("unused decoded image while preparing multimodal sft tokens")
+
+
+def decode_descriptor_pixels(data: bytes) -> None:
+    """Fully decode one image's pixels for validation, then release it.
+
+    Header inspection accepts an image whose pixel data is truncated or corrupt; only a full decode
+    finds that, and the caller wants the failure, not the image.
+    """
+    image = _decode_image_bytes(data)
+    image.close()
+
+
 def decode_image_descriptors(
     descriptors: list[str], package_root: str | Path | None
 ) -> list[object]:
+    """decode one row to fully loaded rgb images under aggregate limits."""
     if len(descriptors) > MAX_IMAGES_PER_EXAMPLE:
         raise ValueError(
             f"example contains {len(descriptors)} images, exceeding the {MAX_IMAGES_PER_EXAMPLE}-image limit"
@@ -575,7 +684,7 @@ def decode_image_descriptors(
     source_bytes = 0
     decoded_bytes = 0
     for descriptor in descriptors:
-        data = _read_descriptor_source(descriptor, package_root)
+        data = read_descriptor_source(descriptor, package_root)
         source_bytes += len(data)
         if source_bytes > MAX_TOTAL_IMAGE_SOURCE_BYTES:
             raise ValueError(
@@ -587,7 +696,14 @@ def decode_image_descriptors(
                 f"example decoded images exceed the {MAX_TOTAL_DECODED_BYTES}-byte limit"
             )
         prepared.append(data)
-    return [_decode_image_bytes(data) for data in prepared]
+    images: list[Any] = []
+    try:
+        images.extend(_decode_image_bytes(data) for data in prepared)
+    except Exception:
+        for image in images:
+            image.close()
+        raise
+    return images
 
 
 def resolve_image_pad_token_id(processor, tok) -> int: