Consume the typed RendererConfig surface

configs/ci/integration/alphabet_sort.toml

@@ -26,4 +26,5 @@ args = { min_turns = 2, max_turns = 2, min_names_per_turn = 1, max_names_per_tur
 # Mirror of Qwen/Qwen3-0.6B; PI's template patch always re-emits prior
 # <think> blocks. Match that with the qwen3 renderer's preserve_all_thinking.
 [orchestrator.renderer]
+name = "auto"
 preserve_all_thinking = true

configs/gsm8k/rl.toml

@@ -27,4 +27,5 @@ args = { dataset_name = "openai/gsm8k", dataset_subset = "main", math_verify_max
 # Mirror of Qwen/Qwen3-0.6B; PI's template patch always re-emits prior
 # <think> blocks. Match that with the qwen3 renderer's preserve_all_thinking.
 [orchestrator.renderer]
+name = "auto"
 preserve_all_thinking = true

configs/multimodal/rl_color_codeword_feat_renderer.toml

@@ -35,7 +35,11 @@ gpus_per_node = 2
 [orchestrator]
 batch_size = 16
 group_size = 8
-use_renderer = true
+# 64 concurrent rollouts (batch_size=16 × group_size=4) want
+# more than one tokenizer slot to avoid serialization queueing. The
+# image processor (CPU-bound) dominates for VLMs so returns diminish
+# past 4; bump to 4 as the default for multimodal runs.
+pool_size = 4
 
 # Track zero-advantage groups but don't drop them — we're validating the
 # multimodal renderer path on 20 steps, not optimizing training efficiency.
@@ -58,13 +62,8 @@ max_completion_tokens = 64
 id = "color-codeword"
 args = { images_per_turn = 2, max_turns = 2, num_examples = 100, seed = 42 }
 
-[orchestrator.renderer]
-name = "auto"
-# 64 concurrent rollouts (batch_size=16 × group_size=4) want
-# more than one tokenizer slot to avoid serialization queueing. The
-# image processor (CPU-bound) dominates for VLMs so returns diminish
-# past 4; bump to 4 as the default for multimodal runs.
-pool_size = 4
+# Default renderer (AutoRendererConfig) resolves Qwen3-VL-4B-Instruct from
+# MODEL_RENDERER_MAP to Qwen3VLRenderer at runtime; no explicit name needed.
 
 [trainer]
 

docs/multimodal.md

@@ -47,7 +47,7 @@ To add permanent support for a new model family, add an entry to `VLM_REGISTRY`
 
 ## How Multi-Turn VLM RL Training Works
 
-VLM rollouts go through the renderer-backed TITO client (`orchestrator.use_renderer = true`, the default and required for VLMs). The renderer owns the HuggingFace processor per-slot and emits multimodal tensors alongside tokens.
+VLM rollouts go through the renderer-backed TITO client (`orchestrator.renderer` set, the default and required for VLMs). The renderer owns the HuggingFace processor per-slot and emits multimodal tensors alongside tokens.
 
 1. **Render**: For each trajectory step, the renderer tokenizes messages and emits per-image multimodal tensors (e.g. `pixel_values`, `image_grid_thw` for Qwen3-VL) as `multi_modal_data`.
 2. **Pack**: `interleave_rollout` concatenates the per-image tensors emitted across a sample's merged step range into a single `mm_kwargs` dict on the `TrainingSample`. Per-token `mm_token_type_ids` (0=text, 1=image, 2=video) come from `renderer.mm_token_type_id_map`.

packages/prime-rl-configs/pyproject.toml

@@ -7,12 +7,7 @@ requires-python = "~=3.12.0"
 dependencies = [
     "pydantic>=1.10.13",
     "prime-pydantic-config>=0.3.0.dev82",
-    # OrchestratorConfig validates renderer.name='auto' against
-    # renderers.base.MODEL_RENDERER_MAP. Renderers itself is light; its only
-    # weighty transitive (transformers) is lazy-imported via the validator,
-    # so plain `from prime_rl.configs.orchestrator import OrchestratorConfig`
-    # still doesn't pull it into sys.modules.
-    "renderers>=0.1.8.dev4",
+    "renderers>=0.1.8.dev28",
     "tomli>=2.2.1",
     "tomli-w>=1.2.0",
 ]

packages/prime-rl-configs/src/prime_rl/configs/orchestrator.py

@@ -3,7 +3,9 @@
 from pathlib import Path
 from typing import Annotated, Any, Literal, TypeAlias
 
-from pydantic import AliasChoices, Field, model_validator
+from pydantic import AliasChoices, Field, model_serializer, model_validator
+from pydantic_core.core_schema import SerializerFunctionWrapHandler
+from renderers import AutoRendererConfig, RendererConfig
 
 from prime_rl.configs.shared import (
     BaseModelConfig,
@@ -12,7 +14,6 @@
     HeartbeatConfig,
     LogConfig,
     PrimeMonitorConfig,
-    RendererConfig,
     TransportConfig,
     WandbWithExtrasConfig,
 )
@@ -570,8 +571,30 @@ class OrchestratorConfig(BaseConfig):
 
     tokenizer: TokenizerConfig = TokenizerConfig()
 
-    renderer: RendererConfig = RendererConfig()
-    """Client-side renderer configuration. Only consumed when ``use_renderer=true``."""
+    renderer: RendererConfig | None = AutoRendererConfig()
+    """Typed renderer config (``renderers.RendererConfig`` discriminated
+    union). Defaults to ``"auto"``, which resolves from
+    ``tokenizer.name_or_path`` via ``MODEL_RENDERER_MAP``. ``None``
+    opts into MITO (``openai_chat_completions``); SFT mode forces this."""
+
+    pool_size: int | None = Field(None, ge=1)
+    """Number of renderer slots shared across concurrent rollouts. Bump
+    for long multi-turn prompts where client-side jinja tokenization
+    serializes. Only meaningful when ``renderer`` is not ``None``."""
+
+    @model_serializer(mode="wrap")
+    def _preserve_mito_renderer(self, handler: SerializerFunctionWrapHandler) -> dict[str, Any]:
+        """Emit ``renderer = "None"`` (string) when MITO so
+        ``model_dump(exclude_none=True)`` round-trips: dumped TOML has
+        ``renderer = "None"``, and on reload
+        ``BaseConfig._none_str_to_none`` coerces it back to ``None``.
+        Without this, a MITO orchestrator config saved to
+        ``control/orch.toml`` would lose the renderer key entirely and
+        reload as the default ``AutoRendererConfig()`` (TITO)."""
+        result = handler(self)
+        if self.renderer is None:
+            result["renderer"] = "None"
+        return result
 
     optim: OptimizerConfig = OptimizerConfig()
     """Per-run optimizer configuration for multi-run training."""
@@ -647,9 +670,6 @@ class OrchestratorConfig(BaseConfig):
     heartbeat: HeartbeatConfig | None = None
     """BetterStack heartbeat configuration for monitoring training progress."""
 
-    use_renderer: bool = True
-    """Use the renderer-backed TITO client (client-side tokenization via the ``renderers`` package, served by ``/v1/generate``). When True, the ``[orchestrator.renderer]`` block (name / tool_parser / reasoning_parser / pool_size) applies. Default for both text-only and VLM rollouts; VLMs require it. False falls back to MITO (``openai_chat_completions``)."""
-
     env_install_prerelease: bool = False
     """Allow pre-release versions when installing environments (e.g. ``verifiers>=0.1.12.dev5``). Passes ``--prerelease`` to ``prime env install``."""
 
@@ -777,11 +797,11 @@ def validate_unique_filter_types(self):
     @model_validator(mode="after")
     def _force_no_renderer_for_sft(self):
         """SFT rolls out via the teacher's plain chat-completions endpoint; the
-        renderer client doesn't apply. Force use_renderer=False so the user
+        renderer client doesn't apply. Force ``renderer=None`` so the user
         doesn't have to remember to set it. Declared before the renderer
         validators below so they see the corrected value."""
         if self.training_mode == "sft":
-            self.use_renderer = False
+            self.renderer = None
         return self
 
     @model_validator(mode="after")
@@ -795,33 +815,15 @@ def validate_training_mode(self):
         return self
 
     @model_validator(mode="after")
-    def validate_renderer_args(self):
-        """``[orchestrator.renderer]`` knobs are only meaningful when
-        ``use_renderer=True``. Reject otherwise so callers don't silently
-        pass them and wonder why they're ignored."""
-        if self.use_renderer:
-            return self
-
-        renderer_args_set = []
-        if self.renderer.name != "auto":
-            renderer_args_set.append(f"renderer.name={self.renderer.name!r}")
-        if self.renderer.tool_parser is not None:
-            renderer_args_set.append(f"renderer.tool_parser={self.renderer.tool_parser!r}")
-        if self.renderer.reasoning_parser is not None:
-            renderer_args_set.append(f"renderer.reasoning_parser={self.renderer.reasoning_parser!r}")
-        if self.renderer.pool_size is not None:
-            renderer_args_set.append(f"renderer.pool_size={self.renderer.pool_size!r}")
-        if self.renderer.preserve_all_thinking:
-            renderer_args_set.append(f"renderer.preserve_all_thinking={self.renderer.preserve_all_thinking!r}")
-        if self.renderer.preserve_thinking_between_tool_calls:
-            renderer_args_set.append(
-                f"renderer.preserve_thinking_between_tool_calls={self.renderer.preserve_thinking_between_tool_calls!r}"
-            )
-
-        if renderer_args_set:
+    def validate_pool_size(self):
+        """``pool_size`` is only meaningful when the renderer is enabled
+        (``renderer is not None``). Reject otherwise so callers don't
+        silently pass it and wonder why it's ignored."""
+        if self.renderer is None and self.pool_size is not None:
             raise ValueError(
-                "Renderer-specific args set without orchestrator.use_renderer=True: "
-                f"{', '.join(renderer_args_set)}. Either enable the renderer client or remove these knobs."
+                f"orchestrator.pool_size={self.pool_size!r} is set but "
+                "orchestrator.renderer is None (MITO mode). Either configure a renderer "
+                "or remove pool_size."
             )
         return self
 
@@ -833,9 +835,9 @@ def vlm_requires_renderer(self):
         tokens, and ships generic ``mm_kwargs`` keyed by whatever the
         model's forward signature expects.
         """
-        if self.student.model.vlm is not None and not self.use_renderer:
+        if self.student.model.vlm is not None and self.renderer is None:
             raise ValueError(
-                "orchestrator.use_renderer must be true when model.vlm is set. "
+                "orchestrator.renderer must be set when model.vlm is set. "
                 "VLMs must go through a renderer (e.g. Qwen3VLRenderer) that owns the processor."
             )
         return self
@@ -844,36 +846,36 @@ def vlm_requires_renderer(self):
     def validate_renderer_auto_resolves(self):
         """Reject the silent DefaultRenderer fallback at config time.
 
-        When ``use_renderer=True`` with ``renderer.name='auto'`` and the
-        model isn't in ``MODEL_RENDERER_MAP``, ``create_renderer`` would
-        fall back to ``DefaultRenderer``. That fallback doesn't fix the
-        position-dependent chat-template bug the renderer client exists to
-        solve, and rejects envs that pass tools (the rollout dies with
-        "RendererPool does not support tools") unless
-        ``renderer.tool_parser`` is configured. Surface at config time so
-        ``--dry-run`` reports the error.
+        When ``renderer.name='auto'`` and the model isn't in
+        ``MODEL_RENDERER_MAP``, ``create_renderer`` would fall back to
+        ``DefaultRenderer``. That fallback doesn't fix the
+        position-dependent chat-template bug the renderer client exists
+        to solve, and rejects envs that pass tools (the rollout dies
+        with "RendererPool does not support tools") unless
+        ``DefaultRendererConfig.tool_parser`` is configured. Surface at
+        config time so ``--dry-run`` reports the error.
         """
-        if not self.use_renderer or self.renderer.name != "auto":
+        if self.renderer is None or self.renderer.name != "auto":
             return self
         from renderers.base import MODEL_RENDERER_MAP
 
         model_id = self.tokenizer.name or self.student.model.name
         if model_id in MODEL_RENDERER_MAP:
             return self
         raise ValueError(
-            f"orchestrator.use_renderer=True with renderer.name='auto' but "
+            f"orchestrator.renderer.name='auto' but "
             f"{model_id!r} is not in renderers.base.MODEL_RENDERER_MAP, so it "
             f"would silently fall back to DefaultRenderer. Pick one: "
             f"(a) [orchestrator.renderer] name='default' — for fine-tunes / "
             f"vendored mirrors with custom chat templates (DefaultRenderer "
-            f"calls apply_chat_template); pair with tool_parser=<name> if "
-            f"the env uses tools. "
+            f"calls apply_chat_template); set tool_parser=<name> if the env "
+            f"uses tools. "
             f"(b) [orchestrator.renderer] name=<model-specific renderer> — "
             f"if {model_id!r} is template-identical to a mapped family "
             f"(and ideally also add it upstream to "
             f"renderers.base.MODEL_RENDERER_MAP). "
-            f"(c) orchestrator.use_renderer=false — opt out of the renderer "
-            f"client entirely."
+            f"(c) orchestrator.renderer='none' — opt out of the renderer "
+            f"client entirely (MITO)."
         )
 
     @model_validator(mode="after")

packages/prime-rl-configs/src/prime_rl/configs/sft.py

@@ -3,10 +3,10 @@
 from typing import Annotated, Literal, TypeAlias
 
 from pydantic import Field, model_validator
+from renderers import RendererConfig
 
 from prime_rl.configs.shared import (
     HeartbeatConfig,
-    RendererConfig,
     SlurmConfig,
     TrainerLogConfig,
     WandbConfig,
@@ -175,11 +175,13 @@ class SFTConfig(BaseConfig):
 
     tokenizer: TokenizerConfig = TokenizerConfig()
 
-    renderer: RendererConfig = RendererConfig()
-    """Client-side renderer configuration. Only consumed when ``use_renderer=true``."""
-
-    use_renderer: bool = False
-    """Tokenize SFT samples through the ``renderers`` library (single ``render()`` + ``message_indices`` mask) instead of the default ``build_incremental_token_mask`` path. Required for chat templates that render position-dependently (e.g. Qwen3, Qwen3.5)."""
+    renderer: RendererConfig | None = None
+    """Typed renderer config (``renderers.RendererConfig`` discriminated
+    union). When set, SFT tokenizes samples through the ``renderers``
+    library (single ``render()`` + ``message_indices`` mask) instead of
+    the default ``build_incremental_token_mask`` path. Required for chat
+    templates that render position-dependently (e.g. Qwen3, Qwen3.5).
+    ``None`` (default) uses the legacy tokenization path."""
 
     data: DataConfig = SFTDataConfig()
 
@@ -319,59 +321,13 @@ def dont_do_massive_traces(self):
 
     @model_validator(mode="after")
     def validate_renderer_vs_vlm(self):
-        if self.use_renderer and self.model.vlm is not None:
+        if self.renderer is not None and self.model.vlm is not None:
             raise ValueError(
-                "use_renderer is not supported for VLMs. The renderer tokenizes "
+                "renderer is not supported for VLMs in SFT. The renderer tokenizes "
                 "text-only message dicts client-side and cannot handle image inputs."
             )
         return self
 
-    @model_validator(mode="after")
-    def validate_renderer_args(self):
-        # pool_size is orchestrator-only. An in-process renderer pool exists
-        # to amortize tokenization across concurrent rollouts in the
-        # orchestrator (many async requests render at once, HF fast
-        # tokenizers release the GIL during Rust encoding, so a pool of N
-        # tokenizer copies parallelizes well). SFT has no such concurrency:
-        # the StatefulDataLoader is constructed with num_workers=0, so the
-        # main process tokenizes one example at a time, between training
-        # steps. Across DP, each rank already owns its own renderer — an
-        # implicit pool of size world_size. Pooling within a rank gives
-        # nothing on top of that. Reject so callers don't silently set a
-        # knob that does nothing; if SFT tokenization ever becomes a
-        # bottleneck the fix is num_workers on the dataloader, not a pool.
-        if self.renderer.pool_size is not None:
-            raise ValueError(
-                f"renderer.pool_size={self.renderer.pool_size!r} is only used by the orchestrator. "
-                "SFT tokenizes synchronously (num_workers=0) and already gets one renderer per DP "
-                "rank — an in-process pool adds nothing. If tokenization is a bottleneck, raise "
-                "num_workers on the dataloader instead."
-            )
-
-        if self.use_renderer:
-            return self
-
-        renderer_args_set = []
-        if self.renderer.name != "auto":
-            renderer_args_set.append(f"renderer.name={self.renderer.name!r}")
-        if self.renderer.tool_parser is not None:
-            renderer_args_set.append(f"renderer.tool_parser={self.renderer.tool_parser!r}")
-        if self.renderer.reasoning_parser is not None:
-            renderer_args_set.append(f"renderer.reasoning_parser={self.renderer.reasoning_parser!r}")
-        if self.renderer.preserve_all_thinking:
-            renderer_args_set.append(f"renderer.preserve_all_thinking={self.renderer.preserve_all_thinking!r}")
-        if self.renderer.preserve_thinking_between_tool_calls:
-            renderer_args_set.append(
-                f"renderer.preserve_thinking_between_tool_calls={self.renderer.preserve_thinking_between_tool_calls!r}"
-            )
-
-        if renderer_args_set:
-            raise ValueError(
-                "Renderer-specific args set without use_renderer=True: "
-                f"{', '.join(renderer_args_set)}. Either enable the renderer or remove these knobs."
-            )
-        return self
-
     @model_validator(mode="after")
     def validate_lora_adapter_saving(self):
         if self.ckpt and self.ckpt.weights and self.ckpt.weights.save_adapter_separately:

packages/prime-rl-configs/src/prime_rl/configs/shared.py

@@ -84,26 +84,6 @@ def is_vlm(self) -> bool:
         return self.vlm is not None
 
 
-class RendererConfig(BaseConfig):
-    name: str = "auto"
-    """Renderer used for chat-template tokenization. One of: ``auto`` (detect from tokenizer), ``qwen3``, ``qwen3_vl``, ``qwen3.5``, ``glm5``, ``glm4.5``, ``minimax-m2``, ``deepseek_v3``, ``kimi_k2``, ``kimi_k25``, ``nemotron3``, ``gpt_oss``, ``default``."""
-
-    tool_parser: str | None = None
-    """Tool parser from ``renderers.parsers``. Only consumed by DefaultRenderer; model-specific renderers bake their own parsing in. Options: ``qwen3``, ``qwen3.5``, ``glm``, ``deepseek_v3``."""
-
-    reasoning_parser: str | None = None
-    """Reasoning parser from ``renderers.parsers``. Only consumed by DefaultRenderer. Options: ``think``."""
-
-    pool_size: int | None = Field(None, ge=1)
-    """Number of renderer slots shared across concurrent rollouts. Bump for long multi-turn prompts where client-side jinja tokenization serializes."""
-
-    preserve_all_thinking: bool = False
-    """Re-emit every past-assistant turn's ``reasoning_content`` between ``<think>``/``</think>`` (or the model's equivalent), even when the chat template would drop it. Strict superset of preserve_thinking_between_tool_calls."""
-
-    preserve_thinking_between_tool_calls: bool = False
-    """Preserve past-assistant ``reasoning_content`` only inside the current tool cycle — the contiguous assistant→tool→…→assistant block after the most recent user message, when that block contains at least one tool response. A new user turn closes the block."""
-
-
 class ElasticConfig(BaseConfig):
     hostname: str
     """DNS hostname that resolves to inference server IPs."""