review: address second-pass docs and code comments

- Replace bare assert in both synthetic deserializers with an explicit
  isinstance check + RuntimeError, matching guidellm's style for
  unexpected-type guards.
- docs/guides/multimodal/index.md: expand "VLM" to "Vision-Language
  Model (VLM)" on the Synthetic Vision card to avoid the
  VLM/vLLM/LLM visual collision.
- docs/guides/multimodal/synthetic_vision.md:
    - drop the "wire-size pin" phrasing from the bitrate example
    - "pin"/"pinned" -> "specify"/"fixed" in the video_bitrate bullet
    - rewrite the ffmpeg/PIL note to just warn about byte-level
      variability across versions, instead of recommending users
      modify the uv.lock file
- pyproject.toml unchanged; uv.lock regenerated via `uv sync --extra
  vision` so it tracks the vision-extra dependency closure.

Signed-off-by: Zakaria el hjouji <zakaria@overshoot.ai>

Author: zakariaelh

docs/guides/multimodal/index.md

@@ -53,7 +53,7 @@ Ensure you have a running inference server and model compatible with the OpenAI
 
   ______________________________________________________________________
 
-  Generate images and short videos on the fly to benchmark VLM serving configurations without bringing your own dataset. Covers the `synthetic_image` and `synthetic_video` `--data` types.
+  Generate images and short videos on the fly to benchmark Vision-Language Model (VLM) serving configurations without bringing your own dataset. Covers the `synthetic_image` and `synthetic_video` `--data` types.
 
   [:octicons-arrow-right-24: Synthetic Vision Guide](synthetic_vision.md)
 

docs/guides/multimodal/synthetic_vision.md

@@ -66,7 +66,7 @@ guidellm benchmark run \
   --data "type=synthetic_video,width=854,height=480,frames=6,fps=1,text_tokens=64,output_tokens=128"
 ```
 
-A twelve-frame 720p clip at 3 fps with a wire-size pin:
+A twelve-frame 720p clip at 3 fps with an explicit h264 target bitrate:
 
 ```bash
 guidellm benchmark run \
@@ -80,7 +80,7 @@ guidellm benchmark run \
 - `height`: Height of the generated video in pixels. The same `resolution` / `aspect_ratio` shorthands as for synthetic image apply.
 - `frames`: Number of frames in the clip.
 - `fps`: Frames per second. Combined with `frames`, this also determines the clip duration.
-- `video_bitrate`: Optional h264 target bitrate (e.g. `1M`, `500k`) — useful when wire size needs to be pinned across runs.
+- `video_bitrate`: Optional h264 target bitrate (e.g. `1M`, `500k`) — useful when you want to specify a fixed wire size across runs.
 - `content`: Per-row clip content. `gradient` (default) emits a seeded gradient with a coordinate warp so each clip compresses similarly to real video; `noise` emits uniform random pixels for worst-case wire size.
 - `text_tokens`: Average number of tokens in the accompanying text prompt; same `stdev` / `min` / `max` suffixes as synthetic image. `prompt_tokens` is accepted as an alias.
 - `output_tokens`: Average number of tokens the model should generate; same `stdev` / `min` / `max` suffixes apply.
@@ -90,4 +90,4 @@ guidellm benchmark run \
 
 - A processor/tokenizer is required for the text portion of the request. By default the model passed in or retrieved from the server is used; otherwise specify one with `--processor`.
 - Per-row seeded gradients produce byte-different payloads on every request, which bypasses vLLM's multimodal preprocessor cache. If you want to deliberately hit the cache, set `content=solid` or pin a fixed `seed` and `samples`.
-- Reproducibility of exact mp4 bytes depends on the installed `ffmpeg` and `PIL` versions. Pin via the lockfile if you compare runs across machines.
+- The exact mp4 bytes produced for a given seed depend on the installed `ffmpeg` and `PIL` versions. Output token counts and request shape stay stable across versions, but if you are comparing byte-level outputs or wire-size measurements across machines, expect small variation.

src/guidellm/data/deserializers/synthetic_image.py

@@ -75,8 +75,12 @@ def _build_prompt(
             text = unique + faker.text(max_nb_chars=num_chars)
             token_ids = processor.encode(text)
         decoded = processor.decode(token_ids[:token_count], skip_special_tokens=True)
-        assert isinstance(decoded, str)  # noqa: S101
-        return decoded
+        if isinstance(decoded, str):
+            return decoded
+        raise RuntimeError(
+            "Processor.decode returned a non-string value while generating "
+            "synthetic image prompt text."
+        )
 
     def __iter__(self) -> Iterator[tuple[int, dict[str, Any]]]:
         iter_seed = self.random_seed + self.iteration_count

src/guidellm/data/deserializers/synthetic_video.py

@@ -69,8 +69,12 @@ def _build_prompt(
             text = unique + faker.text(max_nb_chars=num_chars)
             token_ids = processor.encode(text)
         decoded = processor.decode(token_ids[:token_count], skip_special_tokens=True)
-        assert isinstance(decoded, str)  # noqa: S101
-        return decoded
+        if isinstance(decoded, str):
+            return decoded
+        raise RuntimeError(
+            "Processor.decode returned a non-string value while generating "
+            "synthetic video prompt text."
+        )
 
     def __iter__(self) -> Iterator[tuple[int, dict[str, Any]]]:
         iter_seed = self.random_seed + self.iteration_count