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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: freesolo-flash-dev
-Version: 1.2.61
+Version: 1.2.63
 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.63}/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:

freesolo_flash_dev-1.2.63/flash/engine/huggingface.py

@@ -0,0 +1,61 @@
+"""hugging face helpers shared across control-plane and worker boundaries."""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+
+class ModelRevisionKwargs(TypedDict, total=False):
+    revision: str
+
+
+def model_revision_kwargs(revision: str = "") -> ModelRevisionKwargs:
+    """return the hub revision keyword for a nonempty pinned revision."""
+    return {"revision": revision} if revision else {}
+
+
+def hub_error_transience(exc: BaseException) -> bool | None:
+    """classify known hub and transport failures, leaving unrelated errors unknown."""
+    import httpx
+    from huggingface_hub.errors import (
+        EntryNotFoundError,
+        GatedRepoError,
+        HfHubHTTPError,
+        LocalEntryNotFoundError,
+        RepositoryNotFoundError,
+        RevisionNotFoundError,
+    )
+    from requests.exceptions import ConnectionError as RequestsConnectionError
+    from requests.exceptions import RequestException
+    from requests.exceptions import Timeout as RequestsTimeout
+
+    if isinstance(exc, (RepositoryNotFoundError, RevisionNotFoundError, GatedRepoError)):
+        return False
+    if isinstance(exc, LocalEntryNotFoundError):
+        return True
+    if isinstance(exc, EntryNotFoundError):
+        return False
+    if isinstance(
+        exc,
+        (
+            RequestsConnectionError,
+            RequestsTimeout,
+            httpx.TimeoutException,
+            httpx.NetworkError,
+            httpx.RemoteProtocolError,
+        ),
+    ):
+        return True
+    if isinstance(exc, HfHubHTTPError):
+        response = getattr(exc, "response", None)
+        status = getattr(response, "status_code", None)
+        if status in {401, 403, 404}:
+            return False
+        return (
+            status is None
+            or status in {408, 425, 429}
+            or (isinstance(status, int) and 500 <= status <= 599)
+        )
+    if isinstance(exc, RequestException):
+        return False
+    return None

{freesolo_flash_dev-1.2.61 → freesolo_flash_dev-1.2.63}/flash/engine/profiling/dataset_profile.py

@@ -333,18 +333,15 @@ def profile_packaged_sft_dataset(
         package_root=base_dir,
         contract_text=_contract_text(base_dir, params),
     )
-    from flash.content.multimodal import record_has_images
-
-    if any(record_has_images(row, raw_environment.prompt_messages(row)) for row in rows):
-        raise PackagedDatasetUnavailable(
-            "image-bearing SFT datasets cannot be profiled on the torch-free control plane. "
-            "Use text-only SFT records."
-        )
     return prepare_sft_workload(
         spec,
         raw_environment,
         tokenizer_loader=tokenizer_loader,
         producer_version=producer_version,
+        # no torch here, so no VL processor: image rows are counted arithmetically from the
+        # published vision geometry rather than tokenized through the processor. see
+        # flash/engine/profiling/image_tokens.py.
+        require_processor=False,
         allow_packing=True,
         packing_support=packing_support,
         source_examples=source_examples,

freesolo_flash_dev-1.2.63/flash/engine/profiling/image_tokens.py

@@ -0,0 +1,294 @@
+"""torch-free image token accounting for control-plane sft profiling.
+
+one rendered image placeholder expands to the published vision grid size:
+
+    pad_run = (resized_h // patch_size) * (resized_w // patch_size) // merge_size**2
+
+the upstream differential pins the resize policy, and pixels are fully loaded before quoting.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from flash.content.multimodal import (
+    MAX_IMAGES_PER_EXAMPLE,
+    MAX_TOTAL_DECODED_BYTES,
+    MAX_TOTAL_IMAGE_SOURCE_BYTES,
+    decode_descriptor_pixels,
+    inspect_image_bytes,
+    read_descriptor_source,
+)
+
+# qwen VL publishes its pixel budget under `size`, older revisions under min_pixels/max_pixels.
+# these defaults are the transformers fallbacks, used only when the config declares neither.
+_DEFAULT_MIN_PIXELS = 56 * 56
+_DEFAULT_MAX_PIXELS = 14 * 14 * 4 * 1280
+# the same bound transformers enforces: beyond it smart_resize cannot hold the aspect ratio.
+_MAX_ASPECT_RATIO = 200
+# profile-wide unique full-decode work; per-row decoded bytes keep their separate bound.
+MAX_PROFILE_DECODED_WORK_BYTES = MAX_TOTAL_DECODED_BYTES * MAX_IMAGES_PER_EXAMPLE
+
+
+@dataclass(frozen=True)
+class ImageDescriptorMetadata:
+    source_bytes: int
+    decoded_rgb_bytes: int
+    width: int
+    height: int
+
+
+@dataclass
+class ImageProfileValidationState:
+    """one profile's descriptor cache and cumulative decode budget.
+
+    a descriptor repeated across rows is validated and decoded ONCE; every occurrence still counts
+    toward the per-row limits below, so repetition cannot be used to smuggle a row past them.
+    """
+
+    descriptor_metadata: dict[str, ImageDescriptorMetadata] = field(default_factory=dict)
+    decoded_work_bytes: int = 0
+
+
+def image_descriptor_metadata(
+    descriptors: list[str],
+    package_root: str | Path | None,
+    validation_state: ImageProfileValidationState,
+    *,
+    profile_decoded_work_limit: int,
+) -> list[ImageDescriptorMetadata]:
+    """return fully validated dimensions while bounding unique profile decode work."""
+    if len(descriptors) > MAX_IMAGES_PER_EXAMPLE:
+        raise ValueError(
+            f"example contains {len(descriptors)} images, exceeding the {MAX_IMAGES_PER_EXAMPLE}-image limit"
+        )
+    pending: dict[str, tuple[bytes, ImageDescriptorMetadata]] = {}
+    metadata = []
+    source_bytes = 0
+    decoded_bytes = 0
+    new_decoded_work = 0
+    for descriptor in descriptors:
+        item = validation_state.descriptor_metadata.get(descriptor)
+        if item is None:
+            prepared = pending.get(descriptor)
+            if prepared is None:
+                data = read_descriptor_source(descriptor, package_root)
+                decoded_rgb_bytes, width, height = inspect_image_bytes(data)
+                item = ImageDescriptorMetadata(
+                    source_bytes=len(data),
+                    decoded_rgb_bytes=decoded_rgb_bytes,
+                    width=width,
+                    height=height,
+                )
+                pending[descriptor] = data, item
+                new_decoded_work += item.decoded_rgb_bytes
+            else:
+                item = prepared[1]
+        metadata.append(item)
+        source_bytes += item.source_bytes
+        if source_bytes > MAX_TOTAL_IMAGE_SOURCE_BYTES:
+            raise ValueError(
+                f"example image sources exceed the {MAX_TOTAL_IMAGE_SOURCE_BYTES}-byte limit"
+            )
+        decoded_bytes += item.decoded_rgb_bytes
+        if decoded_bytes > MAX_TOTAL_DECODED_BYTES:
+            raise ValueError(
+                f"example decoded images exceed the {MAX_TOTAL_DECODED_BYTES}-byte limit"
+            )
+
+    prospective_decoded_work = validation_state.decoded_work_bytes + new_decoded_work
+    if prospective_decoded_work > profile_decoded_work_limit:
+        raise ValueError(
+            f"profile decoded image work exceeds the {profile_decoded_work_limit}-byte limit"
+        )
+
+    # fully decode each new descriptor before committing anything: a header that parses but whose
+    # pixels are corrupt must fail the row, and must leave neither the cache nor the budget touched.
+    for data, _item in pending.values():
+        decode_descriptor_pixels(data)
+    validation_state.descriptor_metadata.update(
+        {descriptor: item for descriptor, (_data, item) in pending.items()}
+    )
+    validation_state.decoded_work_bytes = prospective_decoded_work
+    return metadata
+
+
+class ImageGeometryUnavailable(ValueError):
+    """the model's published preprocessor config does not describe its image geometry."""
+
+    def __init__(self, message: str, *, plane_fault: bool = False) -> None:
+        super().__init__(message)
+        self.plane_fault = plane_fault
+
+
+@dataclass(frozen=True)
+class ImageGeometry:
+    """the published vision geometry a checkpoint expands images with."""
+
+    patch_size: int
+    merge_size: int
+    min_pixels: int
+    max_pixels: int
+
+    @property
+    def factor(self) -> int:
+        return self.patch_size * self.merge_size
+
+
+def smart_resize(
+    height: int, width: int, factor: int, min_pixels: int, max_pixels: int
+) -> tuple[int, int]:
+    """resize dimensions to the qwen vision factor and pixel budget."""
+    if height <= 0 or width <= 0:
+        raise ValueError("image width and height must be positive")
+    if max(height, width) / min(height, width) > _MAX_ASPECT_RATIO:
+        raise ValueError(
+            f"absolute aspect ratio must be smaller than {_MAX_ASPECT_RATIO}, "
+            f"got {max(height, width) / min(height, width)}"
+        )
+    h_bar = round(height / factor) * factor
+    w_bar = round(width / factor) * factor
+    if h_bar * w_bar > max_pixels:
+        beta = math.sqrt((height * width) / max_pixels)
+        h_bar = max(factor, math.floor(height / beta / factor) * factor)
+        w_bar = max(factor, math.floor(width / beta / factor) * factor)
+    elif h_bar * w_bar < min_pixels:
+        beta = math.sqrt(min_pixels / (height * width))
+        h_bar = math.ceil(height * beta / factor) * factor
+        w_bar = math.ceil(width * beta / factor) * factor
+    return h_bar, w_bar
+
+
+def _positive_json_int(config: dict, field: str, *, required: bool = False) -> int | None:
+    if field not in config or config[field] is None:
+        if required:
+            raise ImageGeometryUnavailable(
+                f"preprocessor config must declare {field} as a positive JSON integer"
+            )
+        return None
+    value = config[field]
+    if type(value) is not int or value <= 0:
+        raise ImageGeometryUnavailable(
+            f"preprocessor config must declare {field} as a positive JSON integer"
+        )
+    return value
+
+
+def geometry_from_preprocessor_config(config: object) -> ImageGeometry:
+    """read published patch, merge, and pixel-budget geometry."""
+    if not isinstance(config, dict):
+        raise ImageGeometryUnavailable("preprocessor config is not an object")
+    patch_size = _positive_json_int(config, "patch_size", required=True)
+    merge_size = _positive_json_int(config, "merge_size", required=True)
+    assert patch_size is not None
+    assert merge_size is not None
+    size_value = config.get("size")
+    if size_value is None:
+        size: dict = {}
+    elif isinstance(size_value, dict):
+        size = size_value
+    else:
+        raise ImageGeometryUnavailable("preprocessor config field size must be an object")
+    published_min = _positive_json_int(config, "min_pixels")
+    published_max = _positive_json_int(config, "max_pixels")
+    size_min = _positive_json_int(size, "shortest_edge")
+    size_max = _positive_json_int(size, "longest_edge")
+    min_pixels = published_min or size_min or _DEFAULT_MIN_PIXELS
+    max_pixels = published_max or size_max or _DEFAULT_MAX_PIXELS
+    if min_pixels > max_pixels:
+        raise ImageGeometryUnavailable(
+            f"preprocessor config declares min_pixels {min_pixels} above max_pixels {max_pixels}"
+        )
+    return ImageGeometry(
+        patch_size=patch_size,
+        merge_size=merge_size,
+        min_pixels=min_pixels,
+        max_pixels=max_pixels,
+    )
+
+
+def load_image_geometry(model_id: str, revision: str = "") -> ImageGeometry:
+    """Fetch the model's published image geometry from the hub without importing torch."""
+    import os
+
+    from huggingface_hub import hf_hub_download
+
+    from flash.engine.huggingface import hub_error_transience, model_revision_kwargs
+
+    try:
+        path = hf_hub_download(
+            repo_id=model_id,
+            filename="preprocessor_config.json",
+            token=os.environ.get("HF_TOKEN"),
+            **model_revision_kwargs(revision),
+        )
+        with open(path, encoding="utf-8") as handle:
+            config = json.load(handle)
+    except ImageGeometryUnavailable:
+        raise
+    except Exception as exc:
+        transience = hub_error_transience(exc)
+        raise ImageGeometryUnavailable(
+            f"could not read the image geometry published by {model_id!r}; an image-bearing sft "
+            "dataset cannot be quoted without it",
+            # a downloaded local config that cannot be read is plane state, while generic worker
+            # prefetch os errors remain non-retriable at their caller boundary.
+            plane_fault=transience is True or (transience is None and isinstance(exc, OSError)),
+        ) from exc
+    return geometry_from_preprocessor_config(config)
+
+
+def image_pad_tokens(width: int, height: int, geometry: ImageGeometry) -> int:
+    """The number of pad tokens one image of this size expands to."""
+    resized_h, resized_w = smart_resize(
+        height,
+        width,
+        geometry.factor,
+        geometry.min_pixels,
+        geometry.max_pixels,
+    )
+    patches = (resized_h // geometry.patch_size) * (resized_w // geometry.patch_size)
+    return patches // (geometry.merge_size * geometry.merge_size)
+
+
+def descriptor_pad_tokens(
+    descriptors: list[str],
+    package_root: str | Path | None,
+    geometry: ImageGeometry,
+    validation_state: ImageProfileValidationState,
+) -> list[int]:
+    """return each descriptor occurrence's validated pad-token run length."""
+    metadata = image_descriptor_metadata(
+        descriptors,
+        package_root,
+        validation_state,
+        profile_decoded_work_limit=MAX_PROFILE_DECODED_WORK_BYTES,
+    )
+    return [image_pad_tokens(item.width, item.height, geometry) for item in metadata]
+
+
+def expand_image_pad_runs(
+    input_ids: list[int], pad_token_id: int, pad_counts: list[int]
+) -> list[int]:
+    """expand each rendered image placeholder to its processor pad run."""
+    expanded: list[int] = []
+    seen = 0
+    for token_id in input_ids:
+        if token_id == pad_token_id:
+            if seen >= len(pad_counts):
+                raise ValueError(
+                    "the rendered prompt contains more image placeholders than the example "
+                    "supplied images"
+                )
+            expanded.extend([pad_token_id] * pad_counts[seen])
+            seen += 1
+        else:
+            expanded.append(token_id)
+    if seen != len(pad_counts):
+        raise ValueError(
+            f"the rendered prompt contains {seen} image placeholder(s), expected {len(pad_counts)}"
+        )
+    return expanded