renderers 0.1.9.dev0__tar.gz → 0.1.9.dev2__tar.gz

renderers-0.1.9.dev2/.github/workflows/publish-dev.yml

@@ -0,0 +1,67 @@
+name: Publish Dev
+
+# Every push to main publishes a pre-release wheel to PyPI. The version
+# is derived at build time by hatch-vcs from ``git describe`` distance
+# to the latest stable ``renderers-v<MAJOR>.<MINOR>.<PATCH>`` tag (see
+# ``[tool.hatch.version.raw-options]`` in pyproject.toml) — no per-commit
+# tag is created. ``local_scheme = "no-local-version"`` strips the
+# ``+gHASH`` segment so PyPI accepts the wheel directly.
+
+on:
+  push:
+    branches: [main]
+
+concurrency:
+  group: publish-dev-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  # Build (no OIDC) → publish (OIDC only). The build job runs ``uv build``
+  # with ``contents: read`` only so a poisoned build-time dep cannot mint
+  # the OIDC token. The publish job has ``id-token: write`` and the
+  # pypi-prod environment but no source checkout — it only downloads the
+  # prebuilt artifact and runs the SHA-pinned pypa publish action.
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # hatch-vcs needs the full tag history to resolve the version
+          # from the latest stable tag's distance.
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v7
+
+      - name: Build renderers
+        run: uv build
+
+      - name: Show derived version
+        run: ls -1 dist/
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist-dev
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi-prod
+    permissions:
+      id-token: write
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist-dev
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
+        with:
+          skip-existing: true

{renderers-0.1.9.dev0 → renderers-0.1.9.dev2}/.gitignore

@@ -31,3 +31,6 @@ coverage.xml
 .idea/
 .vscode/
 *.swp
+
+# agent harness state
+.claude/

{renderers-0.1.9.dev0 → renderers-0.1.9.dev2}/PKG-INFO

@@ -1,15 +1,15 @@
 Metadata-Version: 2.4
 Name: renderers
-Version: 0.1.9.dev0
+Version: 0.1.9.dev2
 Summary: Chat template renderers — deterministic message-to-token conversion for LLM training
 License-Expression: Apache-2.0
 License-File: LICENSE
 Requires-Python: <3.14,>=3.10
-Requires-Dist: fastokens>=0.1.1
 Requires-Dist: jinja2
 Requires-Dist: numpy
-Requires-Dist: openai-harmony>=0.0.8
+Requires-Dist: openai-harmony>=0.0.4
 Requires-Dist: openai>=1.108.1
+Requires-Dist: prime-pydantic-config>=0.3.0.dev83
 Requires-Dist: tiktoken
 Requires-Dist: transformers>=4.50.0
 Description-Content-Type: text/markdown
@@ -33,7 +33,7 @@ from transformers import AutoTokenizer
 from renderers import create_renderer
 
 tok = AutoTokenizer.from_pretrained("Qwen/Qwen3-8B")
-r = create_renderer(tok, renderer="auto")           # → Qwen3Renderer
+r = create_renderer(tok)                            # → Qwen3Renderer (auto-resolved)
 
 prompt_ids = r.render_ids(
     [{"role": "user", "content": "hi"}],
@@ -56,7 +56,7 @@ next_prompt_ids = r.bridge_to_next_turn(
 )
 ```
 
-Hand-coded renderers ship for `qwen3`, `qwen3-vl`, `qwen3.5`, `qwen3.6`, `glm-5`, `glm-5.1`, `glm-4.5`, `minimax-m2`, `deepseek-v3`, `kimi-k2`, `kimi-k2.5`, `nemotron-3`, `gpt-oss`. Anything else falls back to `DefaultRenderer`, a generic `apply_chat_template` wrapper.
+Hand-coded renderers ship for `qwen3`, `qwen3-vl`, `qwen3.5`, `qwen3.6`, `glm-5`, `glm-5.1`, `glm-4.5`, `minimax-m2`, `deepseek-v3`, `deepseek-r1`, `kimi-k2`, `kimi-k2.5` / `kimi-k2.6`, `nemotron-3`, `nemotron-3-ultra`, `llama-3`, `gpt-oss`, `hy3`, and `prime-qwen3`. Anything else falls back to `DefaultRenderer`, a generic `apply_chat_template` wrapper.
 
 ## API
 
@@ -87,17 +87,17 @@ Each hand-coded bridge:
 ### Picking a renderer
 
 ```python
-r = create_renderer(tok, renderer="auto")
+r = create_renderer(tok)                # AutoRendererConfig is the implicit default
 ```
 
-Auto-detect matches `tokenizer.name_or_path` against `MODEL_RENDERER_MAP` by **exact match**. Prefix matching is intentionally off — same architecture can ship different chat templates (base vs instruct, fine-tune renames). Fine-tunes must pass `renderer=<name>` explicitly; unknown names fall back to `DefaultRenderer`.
+Auto-detect matches `tokenizer.name_or_path` against `MODEL_RENDERER_MAP` by **exact match**. Prefix matching is intentionally off — same architecture can ship different chat templates (base vs instruct, fine-tune renames). Fine-tunes must pass an explicit typed config (e.g. `Qwen3RendererConfig()`). Unknown text-only names fall back to `DefaultRenderer`, unless `AutoRendererConfig(thinking_retention=...)` was set; the default renderer cannot implement that bridge policy.
 
 ### Pools
 
 ```python
 from renderers import create_renderer_pool
 
-pool = create_renderer_pool("Qwen/Qwen3-8B", renderer="auto", size=16)
+pool = create_renderer_pool("Qwen/Qwen3-8B", size=16)
 with pool.checkout() as r:
     ids = r.render_ids(messages)
 ```
@@ -111,7 +111,6 @@ For RL the trainer must see the exact token ids the sampler saw. The standard al
 - **Boolean round-trip.** Engine emits `false`; client parses to Python `bool(False)`; `apply_chat_template` re-renders via `str(False)` → `"False"`. Capital F. Reproducible on Qwen3.5-35B-A3B + mini-swe-agent-plus at ~50% break rate per rollout.
 - **BPE retokenization drift.** The same substring tokenizes differently depending on neighbouring bytes. `json` + `p` + `enderer` (3 tokens) vs `jsonp` + `enderer` (2 tokens) when whitespace shifts by one character. Every subsequent token is shifted from there on.
 - **Tool-call XML drift.** The engine emits a no-arg call with a stylistic empty `</parameter>`; the Jinja re-render of the reconstructed dict drops it. Extension property broken at every such call.
-- **Thinking stripped from non-latest assistants.** Some templates strip `<think>…</think>` blocks from prior assistant turns when re-rendering. The recorded stream has the thinking; the next prompt does not.
 - **Max-seq-len truncation zeroing the anchor.** Client-side `max_seq_len` enforcement zeros `completion_ids` when `prompt_len > max_seq_len`. The bridge anchor is empty, falling back to full re-render — triggering every mode above.
 - **Scaffold-level history rewriting.** Some agent scaffolds (e.g. opencode's `experimental_repairToolCall`) rewrite tool calls before sending them back as history. The next turn's prompt contains a tool call the model never emitted. *A renderer cannot fix this — the drift happens before rendering.*
 
@@ -124,30 +123,60 @@ Empirical delta on Qwen3.5-35B-A3B + mini-swe-agent-plus, step 0:
 
 Each break fragments a rollout into multiple training samples — every fragment re-encodes its prefix, inflating compute roughly linearly with the number of breaks.
 
-## Compaction overrides
+## Typed renderer configs
 
-`create_renderer` and `create_renderer_pool` accept two constructor-only flags:
+Each renderer accepts a typed pydantic config at construction. Some fields mirror chat-template kwargs; others configure renderer-only behavior such as image caching, parsers, or Harmony preamble construction. `create_renderer` and `create_renderer_pool` take one positional `config` argument and an optional keyword-only `chat_template_kwargs` mapping:
 
 ```python
-preserve_all_thinking: bool = False
-preserve_thinking_between_tool_calls: bool = False
+from renderers import (
+    create_renderer,
+    AutoRendererConfig,
+    Qwen3RendererConfig,
+    GLM5RendererConfig,
+    DefaultRendererConfig,
+)
+
+# Auto-resolve renderer from the tokenizer's model name.
+renderer = create_renderer(tokenizer)
+renderer = create_renderer(tokenizer, AutoRendererConfig(thinking_retention="all"))
+renderer = create_renderer(
+    tokenizer,
+    chat_template_kwargs={"enable_thinking": False},
+)
+
+# Explicit choice — use the renderer-specific fields it exposes.
+renderer = create_renderer(tokenizer, Qwen3RendererConfig(enable_thinking=False))
+renderer = create_renderer(tokenizer, GLM5RendererConfig(clear_thinking=False))
+
+# Default renderer (apply_chat_template fallback) — extra fields are
+# captured via pydantic ``extra="allow"`` and forwarded to the Jinja
+# template; tool / reasoning parsers are typed.
+renderer = create_renderer(
+    tokenizer,
+    DefaultRendererConfig(tool_parser="qwen3", reasoning_parser="think"),
+)
 ```
 
-Defaults preserve byte-identity with the model's chat template. Flipping a flag at construction restores `reasoning_content` the template would otherwise drop:
+Discriminated union: every per-renderer config is a variant of `RendererConfig`, dispatched on the `name` field. Bogus combinations (e.g. `add_vision_id` under `name="qwen3"`) error at construction with a `pydantic.ValidationError`. Downstream pydantic configs (prime-rl orchestrator, verifiers `ClientConfig`) hold a single field typed as `RendererConfig` and inherit the same strict-per-variant validation.
+
+When `chat_template_kwargs` is passed with `config=None` / `AutoRendererConfig`, renderers first resolves the concrete renderer from the model name, then validates those kwargs against that renderer's config. `Auto + unknown model + chat_template_kwargs` fails loudly; use an explicit typed config or explicit `DefaultRendererConfig` for opaque fallback templates.
+
+One shared behaviour flag lives on typed renderer configs: `thinking_retention`, an optional bridge-policy override. Leave it unset to derive bridge behaviour from the chat template and its renderer-exposed kwargs.
 
-- `preserve_all_thinking=True` — every past assistant's reasoning is kept.
-- `preserve_thinking_between_tool_calls=True` — reasoning is kept on assistants in the in-flight tool cycle (no-op for current renderers; reserved for future templates that drop it).
+- `thinking_retention=None` (default) — derive from the chat template / renderer kwargs.
+- `thinking_retention="tool_cycle"` — bridge within the in-flight tool cycle; a new user query falls back to a full re-render.
+- `thinking_retention="all"` — bridge across user-query boundaries when the bridge is otherwise structurally valid.
 
-The canonical use case is **compaction**. Injecting a `user` turn like *"summarize the work so far"* puts every prior assistant in a "past cycle", so template-default rules drop their `reasoning_content` before the summarizer sees it. Build the renderer with `preserve_all_thinking=True` to keep reasoning visible end-to-end on those flows. Both flags only ever *add* tokens vs the template default.
+Generic `thinking_retention` does **not** change full `render()` output: a full re-render always follows the Python chat-template implementation. Only real template knobs can change full-render thinking behaviour. GLM-5 `clear_thinking=False`, Nemotron-3 `truncate_history_thinking=False`, Qwen3.6 `preserve_thinking=True`, and GPT-OSS `auto_drop_analysis=False` all imply bridge policy `"all"`; no-thinking generation knobs also imply `"all"` when `thinking_retention` is unset. Setting a direct keep/drop template knob and a contradictory `thinking_retention` raises at config-load. The full per-renderer mapping lives in [`docs/renderer-config.md`](docs/renderer-config.md).
 
 ## `DefaultRenderer`
 
-Fallback for unsupported models. Wraps `apply_chat_template` and accepts `tool_parser` / `reasoning_parser` kwargs (vLLM convention). `bridge_to_next_turn` returns `None` because the template's close is unknown, so multi-turn rollouts fall back to full re-render. Implementing a hand-coded renderer is a few hundred lines of Python (`render_ids` + `parse_response` + `bridge_to_next_turn`) and is the only path that closes the failure modes above by construction.
+Fallback for unsupported text-only models. Wraps `apply_chat_template` and accepts `tool_parser` / `reasoning_parser` (vLLM convention) plus arbitrary Jinja kwargs via `DefaultRendererConfig`'s `extra="allow"`. Explicit `thinking_retention` is rejected: `bridge_to_next_turn` returns `None` because the template's close is unknown, so multi-turn rollouts fall back to full re-render. Implementing a hand-coded renderer is a few hundred lines of Python (`render_ids` + `parse_response` + `bridge_to_next_turn`) and is the only path that closes the failure modes above by construction.
 
 ## Roadmap
 
-- **VLM support.** `ContentPart` is text-only today; `Qwen3VLRenderer` ships only because Qwen3-VL's text-only chat template differs from Qwen3's. Plan: add `ImagePart` / `VideoPart`, multimodal bridges, validate against a Qwen3-VL RL run.
-- **Patched chat templates.** Some shipped templates re-tokenize history, normalize JSON, or auto-strip thinking — each breaks the extension property. Plan: a `use_patched` opt-in per renderer that renders the same surface form while avoiding known-bad patterns.
+- **VLM expansion.** `ImagePart` support exists for Qwen3-VL and Qwen3.5-family multimodal templates. Remaining work: video support, broader VLM coverage, and more RL validation.
+- **Patched chat templates.** Some shipped templates re-tokenize history or normalize JSON in ways that break token identity. Plan: a `use_patched` opt-in per renderer that renders the same surface form while avoiding known-bad patterns. (Auto-stripping thinking from past turns is *not* one of these — that's intended template behaviour the renderer reproduces; use `thinking_retention` to override it.)
 
 ## Testing
 

{renderers-0.1.9.dev0 → renderers-0.1.9.dev2}/README.md

@@ -17,7 +17,7 @@ from transformers import AutoTokenizer
 from renderers import create_renderer
 
 tok = AutoTokenizer.from_pretrained("Qwen/Qwen3-8B")
-r = create_renderer(tok, renderer="auto")           # → Qwen3Renderer
+r = create_renderer(tok)                            # → Qwen3Renderer (auto-resolved)
 
 prompt_ids = r.render_ids(
     [{"role": "user", "content": "hi"}],
@@ -40,7 +40,7 @@ next_prompt_ids = r.bridge_to_next_turn(
 )
 ```
 
-Hand-coded renderers ship for `qwen3`, `qwen3-vl`, `qwen3.5`, `qwen3.6`, `glm-5`, `glm-5.1`, `glm-4.5`, `minimax-m2`, `deepseek-v3`, `kimi-k2`, `kimi-k2.5`, `nemotron-3`, `gpt-oss`. Anything else falls back to `DefaultRenderer`, a generic `apply_chat_template` wrapper.
+Hand-coded renderers ship for `qwen3`, `qwen3-vl`, `qwen3.5`, `qwen3.6`, `glm-5`, `glm-5.1`, `glm-4.5`, `minimax-m2`, `deepseek-v3`, `deepseek-r1`, `kimi-k2`, `kimi-k2.5` / `kimi-k2.6`, `nemotron-3`, `nemotron-3-ultra`, `llama-3`, `gpt-oss`, `hy3`, and `prime-qwen3`. Anything else falls back to `DefaultRenderer`, a generic `apply_chat_template` wrapper.
 
 ## API
 
@@ -71,17 +71,17 @@ Each hand-coded bridge:
 ### Picking a renderer
 
 ```python
-r = create_renderer(tok, renderer="auto")
+r = create_renderer(tok)                # AutoRendererConfig is the implicit default
 ```
 
-Auto-detect matches `tokenizer.name_or_path` against `MODEL_RENDERER_MAP` by **exact match**. Prefix matching is intentionally off — same architecture can ship different chat templates (base vs instruct, fine-tune renames). Fine-tunes must pass `renderer=<name>` explicitly; unknown names fall back to `DefaultRenderer`.
+Auto-detect matches `tokenizer.name_or_path` against `MODEL_RENDERER_MAP` by **exact match**. Prefix matching is intentionally off — same architecture can ship different chat templates (base vs instruct, fine-tune renames). Fine-tunes must pass an explicit typed config (e.g. `Qwen3RendererConfig()`). Unknown text-only names fall back to `DefaultRenderer`, unless `AutoRendererConfig(thinking_retention=...)` was set; the default renderer cannot implement that bridge policy.
 
 ### Pools
 
 ```python
 from renderers import create_renderer_pool
 
-pool = create_renderer_pool("Qwen/Qwen3-8B", renderer="auto", size=16)
+pool = create_renderer_pool("Qwen/Qwen3-8B", size=16)
 with pool.checkout() as r:
     ids = r.render_ids(messages)
 ```
@@ -95,7 +95,6 @@ For RL the trainer must see the exact token ids the sampler saw. The standard al
 - **Boolean round-trip.** Engine emits `false`; client parses to Python `bool(False)`; `apply_chat_template` re-renders via `str(False)` → `"False"`. Capital F. Reproducible on Qwen3.5-35B-A3B + mini-swe-agent-plus at ~50% break rate per rollout.
 - **BPE retokenization drift.** The same substring tokenizes differently depending on neighbouring bytes. `json` + `p` + `enderer` (3 tokens) vs `jsonp` + `enderer` (2 tokens) when whitespace shifts by one character. Every subsequent token is shifted from there on.
 - **Tool-call XML drift.** The engine emits a no-arg call with a stylistic empty `</parameter>`; the Jinja re-render of the reconstructed dict drops it. Extension property broken at every such call.
-- **Thinking stripped from non-latest assistants.** Some templates strip `<think>…</think>` blocks from prior assistant turns when re-rendering. The recorded stream has the thinking; the next prompt does not.
 - **Max-seq-len truncation zeroing the anchor.** Client-side `max_seq_len` enforcement zeros `completion_ids` when `prompt_len > max_seq_len`. The bridge anchor is empty, falling back to full re-render — triggering every mode above.
 - **Scaffold-level history rewriting.** Some agent scaffolds (e.g. opencode's `experimental_repairToolCall`) rewrite tool calls before sending them back as history. The next turn's prompt contains a tool call the model never emitted. *A renderer cannot fix this — the drift happens before rendering.*
 
@@ -108,30 +107,60 @@ Empirical delta on Qwen3.5-35B-A3B + mini-swe-agent-plus, step 0:
 
 Each break fragments a rollout into multiple training samples — every fragment re-encodes its prefix, inflating compute roughly linearly with the number of breaks.
 
-## Compaction overrides
+## Typed renderer configs
 
-`create_renderer` and `create_renderer_pool` accept two constructor-only flags:
+Each renderer accepts a typed pydantic config at construction. Some fields mirror chat-template kwargs; others configure renderer-only behavior such as image caching, parsers, or Harmony preamble construction. `create_renderer` and `create_renderer_pool` take one positional `config` argument and an optional keyword-only `chat_template_kwargs` mapping:
 
 ```python
-preserve_all_thinking: bool = False
-preserve_thinking_between_tool_calls: bool = False
+from renderers import (
+    create_renderer,
+    AutoRendererConfig,
+    Qwen3RendererConfig,
+    GLM5RendererConfig,
+    DefaultRendererConfig,
+)
+
+# Auto-resolve renderer from the tokenizer's model name.
+renderer = create_renderer(tokenizer)
+renderer = create_renderer(tokenizer, AutoRendererConfig(thinking_retention="all"))
+renderer = create_renderer(
+    tokenizer,
+    chat_template_kwargs={"enable_thinking": False},
+)
+
+# Explicit choice — use the renderer-specific fields it exposes.
+renderer = create_renderer(tokenizer, Qwen3RendererConfig(enable_thinking=False))
+renderer = create_renderer(tokenizer, GLM5RendererConfig(clear_thinking=False))
+
+# Default renderer (apply_chat_template fallback) — extra fields are
+# captured via pydantic ``extra="allow"`` and forwarded to the Jinja
+# template; tool / reasoning parsers are typed.
+renderer = create_renderer(
+    tokenizer,
+    DefaultRendererConfig(tool_parser="qwen3", reasoning_parser="think"),
+)
 ```
 
-Defaults preserve byte-identity with the model's chat template. Flipping a flag at construction restores `reasoning_content` the template would otherwise drop:
+Discriminated union: every per-renderer config is a variant of `RendererConfig`, dispatched on the `name` field. Bogus combinations (e.g. `add_vision_id` under `name="qwen3"`) error at construction with a `pydantic.ValidationError`. Downstream pydantic configs (prime-rl orchestrator, verifiers `ClientConfig`) hold a single field typed as `RendererConfig` and inherit the same strict-per-variant validation.
+
+When `chat_template_kwargs` is passed with `config=None` / `AutoRendererConfig`, renderers first resolves the concrete renderer from the model name, then validates those kwargs against that renderer's config. `Auto + unknown model + chat_template_kwargs` fails loudly; use an explicit typed config or explicit `DefaultRendererConfig` for opaque fallback templates.
+
+One shared behaviour flag lives on typed renderer configs: `thinking_retention`, an optional bridge-policy override. Leave it unset to derive bridge behaviour from the chat template and its renderer-exposed kwargs.
 
-- `preserve_all_thinking=True` — every past assistant's reasoning is kept.
-- `preserve_thinking_between_tool_calls=True` — reasoning is kept on assistants in the in-flight tool cycle (no-op for current renderers; reserved for future templates that drop it).
+- `thinking_retention=None` (default) — derive from the chat template / renderer kwargs.
+- `thinking_retention="tool_cycle"` — bridge within the in-flight tool cycle; a new user query falls back to a full re-render.
+- `thinking_retention="all"` — bridge across user-query boundaries when the bridge is otherwise structurally valid.
 
-The canonical use case is **compaction**. Injecting a `user` turn like *"summarize the work so far"* puts every prior assistant in a "past cycle", so template-default rules drop their `reasoning_content` before the summarizer sees it. Build the renderer with `preserve_all_thinking=True` to keep reasoning visible end-to-end on those flows. Both flags only ever *add* tokens vs the template default.
+Generic `thinking_retention` does **not** change full `render()` output: a full re-render always follows the Python chat-template implementation. Only real template knobs can change full-render thinking behaviour. GLM-5 `clear_thinking=False`, Nemotron-3 `truncate_history_thinking=False`, Qwen3.6 `preserve_thinking=True`, and GPT-OSS `auto_drop_analysis=False` all imply bridge policy `"all"`; no-thinking generation knobs also imply `"all"` when `thinking_retention` is unset. Setting a direct keep/drop template knob and a contradictory `thinking_retention` raises at config-load. The full per-renderer mapping lives in [`docs/renderer-config.md`](docs/renderer-config.md).
 
 ## `DefaultRenderer`
 
-Fallback for unsupported models. Wraps `apply_chat_template` and accepts `tool_parser` / `reasoning_parser` kwargs (vLLM convention). `bridge_to_next_turn` returns `None` because the template's close is unknown, so multi-turn rollouts fall back to full re-render. Implementing a hand-coded renderer is a few hundred lines of Python (`render_ids` + `parse_response` + `bridge_to_next_turn`) and is the only path that closes the failure modes above by construction.
+Fallback for unsupported text-only models. Wraps `apply_chat_template` and accepts `tool_parser` / `reasoning_parser` (vLLM convention) plus arbitrary Jinja kwargs via `DefaultRendererConfig`'s `extra="allow"`. Explicit `thinking_retention` is rejected: `bridge_to_next_turn` returns `None` because the template's close is unknown, so multi-turn rollouts fall back to full re-render. Implementing a hand-coded renderer is a few hundred lines of Python (`render_ids` + `parse_response` + `bridge_to_next_turn`) and is the only path that closes the failure modes above by construction.
 
 ## Roadmap
 
-- **VLM support.** `ContentPart` is text-only today; `Qwen3VLRenderer` ships only because Qwen3-VL's text-only chat template differs from Qwen3's. Plan: add `ImagePart` / `VideoPart`, multimodal bridges, validate against a Qwen3-VL RL run.
-- **Patched chat templates.** Some shipped templates re-tokenize history, normalize JSON, or auto-strip thinking — each breaks the extension property. Plan: a `use_patched` opt-in per renderer that renders the same surface form while avoiding known-bad patterns.
+- **VLM expansion.** `ImagePart` support exists for Qwen3-VL and Qwen3.5-family multimodal templates. Remaining work: video support, broader VLM coverage, and more RL validation.
+- **Patched chat templates.** Some shipped templates re-tokenize history or normalize JSON in ways that break token identity. Plan: a `use_patched` opt-in per renderer that renders the same surface form while avoiding known-bad patterns. (Auto-stripping thinking from past turns is *not* one of these — that's intended template behaviour the renderer reproduces; use `thinking_retention` to override it.)
 
 ## Testing
 

renderers-0.1.9.dev2/docs/renderer-config.md

@@ -0,0 +1,221 @@
+# Renderer config
+
+`renderers.RendererConfig` is the typed input to `create_renderer` and
+`create_renderer_pool`. It pins the renderer choice and its config at
+construction time.
+
+```python
+from renderers import create_renderer, Qwen35RendererConfig
+
+r = create_renderer(tokenizer, Qwen35RendererConfig(enable_thinking=False))
+r = create_renderer(tokenizer, chat_template_kwargs={"enable_thinking": False})
+```
+
+`RendererConfig` is a pydantic discriminated union, one variant per renderer,
+dispatched on the `name` field. Most variants reject unknown fields at
+construction. A field can either mirror a chat-template kwarg or configure a
+renderer-only behavior such as parsing, image caching, or Harmony preamble
+construction.
+
+## Per-renderer configs
+
+Use `type(config).template_field_names()` to inspect the fields that mirror
+chat-template kwargs. Those fields are covered by parity tests against
+`apply_chat_template` in `tests/test_renderer_config_parity.py`.
+
+| Renderer | Config class | Template fields | Renderer-only fields |
+| --- | --- | --- | --- |
+| Qwen3 | `Qwen3RendererConfig` | `enable_thinking` | - |
+| PrimeIntellect Qwen3 | `PrimeQwen3RendererConfig` | - | - |
+| Qwen3.5 | `Qwen35RendererConfig` | `enable_thinking`, `add_vision_id` | `image_cache_max` |
+| Qwen3.6 | `Qwen36RendererConfig` | `enable_thinking`, `add_vision_id`, `preserve_thinking` | `image_cache_max` |
+| Qwen3-VL | `Qwen3VLRendererConfig` | `add_vision_id` | `image_cache_max` |
+| GLM-5 / 5.1 | `GLM5RendererConfig` / `GLM51RendererConfig` | `enable_thinking`, `clear_thinking` | - |
+| GLM-4.5 | `GLM45RendererConfig` | `enable_thinking` | - |
+| gpt-oss | `GptOssRendererConfig` | `reasoning_effort`, `conversation_start_date` | `use_system_prompt`, `knowledge_cutoff`, `model_identity`, `auto_drop_analysis` |
+| Hy3 | `Hy3RendererConfig` | `reasoning_effort`, `preserved_thinking`, `is_training`, `raw_last_assistant`, `fallback_strategy` | - |
+| Kimi K2 | `KimiK2RendererConfig` | - | `enable_thinking` |
+| Kimi K2.5 / 2.6 | `KimiK25RendererConfig` | `thinking` | `image_cache_max` |
+| Laguna XS.2 | `LagunaXS2RendererConfig` | `enable_thinking`, `render_assistant_messages_raw` | - |
+| Laguna XS-2.1 | `LagunaXS21RendererConfig` | `enable_thinking` | - |
+| Llama 3 | `Llama3RendererConfig` | `date_string`, `tools_in_user_message` | - |
+| MiniMax M2 | `MiniMaxM2RendererConfig` | `model_identity` | - |
+| Nemotron-3 Nano / Super | `Nemotron3RendererConfig` | `enable_thinking`, `truncate_history_thinking`, `low_effort` | - |
+| Nemotron-3 Ultra | `Nemotron3UltraRendererConfig` | `enable_thinking`, `truncate_history_thinking`, `medium_effort` | - |
+| DeepSeek V3 | `DeepSeekV3RendererConfig` | - | - |
+| DeepSeek R1 | `DeepSeekR1RendererConfig` | - | - |
+
+Configs are frozen value objects. To override a field, construct a new instance
+or call `config.model_copy(update={...})`.
+
+## Auto-resolution
+
+`create_renderer(tokenizer)` resolves the renderer from `tokenizer.name_or_path`
+via `MODEL_RENDERER_MAP`:
+
+```python
+from renderers import AutoRendererConfig, GLM5RendererConfig
+
+r = create_renderer(tokenizer)
+r = create_renderer(tokenizer, AutoRendererConfig(thinking_retention="all"))
+r = create_renderer(tokenizer, GLM5RendererConfig(clear_thinking=False))
+```
+
+`AutoRendererConfig` carries only the shared `thinking_retention` override.
+Callers that receive run-scoped chat-template kwargs can pass them separately:
+
+```python
+r = create_renderer(
+    tokenizer,
+    chat_template_kwargs={"enable_thinking": False},
+)
+pool = create_renderer_pool(
+    "Qwen/Qwen3-8B",
+    chat_template_kwargs={"enable_thinking": False},
+)
+```
+
+Renderers resolves auto configs before applying `chat_template_kwargs`, so the
+kwargs validate against the concrete renderer config. Unknown kwargs, or kwargs
+that conflict with an explicit `thinking_retention`, fail at construction.
+
+Auto-resolution fails loudly for VLMs without an exact registered renderer.
+Text-only unknown models fall back to `DefaultRenderer`, unless
+`AutoRendererConfig(thinking_retention=...)` was set. The default renderer
+cannot implement selective bridge retention, so that combination raises.
+`AutoRendererConfig` with `chat_template_kwargs` also raises for unknown models,
+because renderers cannot validate those kwargs without a concrete renderer.
+Use an explicit model-specific config, or `DefaultRendererConfig(...)` when you
+intentionally want opaque `apply_chat_template` kwargs.
+
+## `thinking_retention`
+
+Every typed renderer config carries one shared optional bridge-policy override:
+
+```python
+thinking_retention: Literal["tool_cycle", "all"] | None = None
+```
+
+| Value | Meaning |
+| --- | --- |
+| `None` | Derive the effective bridge policy from the renderer's template knobs and defaults. |
+| `"tool_cycle"` | Bridge within the current tool cycle; re-render when the extension opens a new user query. |
+| `"all"` | Allow bridging across user-query boundaries when the bridge is otherwise structurally valid. |
+
+`thinking_retention` affects `bridge_to_next_turn`, not full `render()`.
+A full render always follows the Python chat-template implementation. Only real
+template fields, such as `clear_thinking`, `preserve_thinking`, or
+`truncate_history_thinking`, can change full-render historical thinking.
+
+Internally, renderers resolve an `effective_thinking_retention` at construction:
+
+| Internal policy | Bridge behavior |
+| --- | --- |
+| `"template"` | Decline bridging; caller falls back to a full re-render. |
+| `"tool_cycle"` | Bridge unless `new_messages` introduces a user query. |
+| `"all"` | Do not block bridging for thinking retention. |
+
+`"template"` is not a public config value. Leave `thinking_retention` unset to
+get template-derived behavior.
+
+## Derived retention defaults
+
+When `thinking_retention` is unset, each renderer derives its bridge policy from
+the knobs its template actually exposes:
+
+| Renderer | Derived policy |
+| --- | --- |
+| Qwen3 | `enable_thinking=False -> all`, else `tool_cycle` |
+| Qwen3.5 | `enable_thinking=False -> all`, else `tool_cycle` |
+| Qwen3.6 | `preserve_thinking=True -> all`; else `enable_thinking=False -> all`; else `tool_cycle` |
+| GLM-5 / 5.1 | `clear_thinking=False -> all`; else `enable_thinking=False -> all`; else `tool_cycle` |
+| GLM-4.5 | `enable_thinking=False -> all`, else `tool_cycle` |
+| gpt-oss | `auto_drop_analysis=False -> all`, else `tool_cycle` |
+| Hy3 | `preserved_thinking=True -> all`, else `tool_cycle` |
+| Kimi K2.5 / 2.6 | `thinking=False -> all`, else `tool_cycle` |
+| Nemotron-3 | `truncate_history_thinking=False -> all`; else `enable_thinking=False -> all`; else `tool_cycle` |
+| DeepSeek R1 | `template` |
+| MiniMax M2 | `tool_cycle` |
+| DeepSeek V3, Qwen3-VL, Kimi K2, Laguna XS.2 / XS-2.1, Llama 3 | `all` |
+| PrimeIntellect Qwen3 | `all` |
+
+Config construction raises when an explicit template knob directly contradicts
+an explicit generic bridge policy. For example:
+
+```python
+GLM5RendererConfig(clear_thinking=False, thinking_retention="tool_cycle")
+# ValueError: clear_thinking=False implies thinking_retention="all"
+```
+
+Generation-only no-thinking knobs, such as `enable_thinking=False`, do not
+conflict with an explicit conservative `thinking_retention="tool_cycle"`. They
+only change the derived default when `thinking_retention` is unset.
+
+## `DefaultRendererConfig`
+
+`DefaultRenderer` wraps `tokenizer.apply_chat_template` for unsupported
+text-only models. Its config sets `extra="allow"` so unknown fields are
+forwarded as Jinja kwargs:
+
+```python
+from renderers import create_renderer, DefaultRendererConfig
+
+r = create_renderer(
+    tokenizer,
+    DefaultRendererConfig(
+        tool_parser="qwen3",
+        reasoning_parser="think",
+        enable_thinking=False,
+        custom_jinja_kwarg=True,
+    ),
+)
+```
+
+`tool_parser` and `reasoning_parser` configure `DefaultRenderer` itself. Every
+other extra field lands in `model_extra` and is forwarded to
+`apply_chat_template`.
+
+`DefaultRenderer` rejects explicit `thinking_retention` and the removed
+`preserve_*` flags. Its bridge always returns `None`, because the template's
+turn-close structure is opaque to the renderer.
+
+## Downstream integration
+
+Downstream pydantic configs can hold a single field typed as `RendererConfig`:
+
+```python
+from pydantic import BaseModel, Field
+from renderers import AutoRendererConfig, RendererConfig
+
+
+class ClientConfig(BaseModel):
+    renderer: RendererConfig = Field(default_factory=AutoRendererConfig)
+```
+
+In TOML or YAML, the `name` discriminator selects the variant:
+
+```toml
+[client.renderer]
+name = "qwen3.5"
+enable_thinking = false
+add_vision_id = true
+thinking_retention = "all"
+```
+
+Bogus combinations, such as `add_vision_id` under `name = "qwen3"`, raise at
+config load with a pydantic validation error.
+
+To construct a config from a renderer name string:
+
+```python
+from renderers import config_from_name
+
+cfg = config_from_name("glm-5")  # GLM5RendererConfig()
+cfg = config_from_name("auto")  # None, the implicit auto form
+```
+
+## Renaming a renderer is a breaking change
+
+The discriminator key is the renderer name string. Renaming `"qwen3.5"` to
+something else would break downstream configs that reference it by name. Add
+new renderers instead of renaming existing ones.

{renderers-0.1.9.dev0 → renderers-0.1.9.dev2}/examples/sglang/multiturn_generate_sglang.py

@@ -22,6 +22,7 @@ import json
 import os
 
 import sglang as sgl
+from renderers.configs import Qwen35RendererConfig
 from renderers.gpt_oss import GptOssRenderer
 from renderers.qwen35 import Qwen35Renderer
 from transformers import AutoTokenizer
@@ -52,7 +53,9 @@ TOOLS = [
 def make_renderer(model: str, enable_thinking: bool | None):
     tokenizer = AutoTokenizer.from_pretrained(model, trust_remote_code=False)
     if model.startswith("Qwen/Qwen3.5-"):
-        return Qwen35Renderer(tokenizer, enable_thinking=enable_thinking)
+        return Qwen35Renderer(
+            tokenizer, Qwen35RendererConfig(enable_thinking=enable_thinking)
+        )
     if model == "openai/gpt-oss-20b":
         return GptOssRenderer(tokenizer)
     raise ValueError(f"unsupported demo model: {model}")
@@ -62,8 +65,9 @@ def print_parsed(label: str, turn: str, parsed) -> None:
     print(f"\n[{label}] {turn}")
     if parsed.reasoning_content:
         print(f"reasoning: {parsed.reasoning_content[:240]}")
-    if parsed.tool_calls:
-        print(f"tool_calls: {json.dumps(parsed.tool_calls, ensure_ascii=False)}")
+    for tc in parsed.tool_calls:
+        # ``parse_response`` returns ``ParsedToolCall`` dataclasses, not dicts.
+        print(f"tool_call: {tc.name}({tc.arguments}) [{tc.status.value}]")
     if parsed.content:
         print(f"content: {parsed.content}")
 
@@ -141,21 +145,33 @@ def main() -> None:
         if parsed1.reasoning_content:
             assistant["reasoning_content"] = parsed1.reasoning_content
         if parsed1.tool_calls:
-            assistant["tool_calls"] = parsed1.tool_calls
+            # Convert the parsed dataclasses back to OpenAI-format tool_calls.
+            assistant["tool_calls"] = [
+                {
+                    "id": tc.id or f"call_{idx}",
+                    "type": "function",
+                    "function": {
+                        "name": tc.name,
+                        "arguments": tc.arguments
+                        if isinstance(tc.arguments, str)
+                        else json.dumps(tc.arguments),
+                    },
+                }
+                for idx, tc in enumerate(parsed1.tool_calls)
+            ]
         messages.append(assistant)
 
         if parsed1.tool_calls:
             new_messages = []
             for idx, tool_call in enumerate(parsed1.tool_calls):
-                fn = tool_call.get("function") or tool_call
-                tool_args = fn.get("arguments") or {}
+                tool_args = tool_call.arguments or {}
                 if isinstance(tool_args, str):
                     tool_args = json.loads(tool_args)
                 new_messages.append(
                     {
                         "role": "tool",
-                        "tool_call_id": tool_call.get("id", f"call_{idx}"),
-                        "name": fn.get("name", "multiply"),
+                        "tool_call_id": tool_call.id or f"call_{idx}",
+                        "name": tool_call.name or "multiply",
                         "content": json.dumps(
                             {"result": int(tool_args["a"]) * int(tool_args["b"])}
                         ),
@@ -167,11 +183,14 @@ def main() -> None:
             ]
 
         # Turn 2: bridge extends prompt_ids + completion1 exactly.
-        bridged_ids = renderer.bridge_to_next_turn(
+        # ``bridge_to_next_turn`` returns a ``RenderedTokens`` (or None); the
+        # extended id stream is on ``.token_ids``.
+        bridged = renderer.bridge_to_next_turn(
             prompt_ids, completion1, new_messages, tools=TOOLS
         )
-        if bridged_ids is None:
+        if bridged is None:
             raise RuntimeError("bridge_to_next_turn returned None")
+        bridged_ids = bridged.token_ids
         assert bridged_ids[: len(prompt_ids) + len(completion1)] == (
             prompt_ids + completion1
         )