renderers 0.1.8.dev51__tar.gz → 0.1.8.dev52__tar.gz

{renderers-0.1.8.dev51 → renderers-0.1.8.dev52}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: renderers
-Version: 0.1.8.dev51
+Version: 0.1.8.dev52
 Summary: Chat template renderers — deterministic message-to-token conversion for LLM training
 License-Expression: Apache-2.0
 License-File: LICENSE
@@ -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`, `nemotron-3-ultra`, `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`, and `gpt-oss`. Anything else falls back to `DefaultRenderer`, a generic `apply_chat_template` wrapper.
 
 ## API
 
@@ -90,7 +90,7 @@ Each hand-coded bridge:
 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 an explicit typed config (e.g. `Qwen3RendererConfig()`); 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
 
@@ -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.*
 
@@ -126,7 +125,7 @@ Each break fragments a rollout into multiple training samples — every fragment
 
 ## Typed renderer configs
 
-Each renderer accepts a typed pydantic config that pins its template-control kwargs at construction. `create_renderer` and `create_renderer_pool` take one positional `config` argument:
+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
 from renderers import (
@@ -137,13 +136,15 @@ from renderers import (
     DefaultRendererConfig,
 )
 
-# Auto-resolve renderer from the tokenizer's model name. Carries the
-# shared preserve_* flags; template kwargs require an explicit choice.
+# Auto-resolve renderer from the tokenizer's model name.
 renderer = create_renderer(tokenizer)
-renderer = create_renderer(tokenizer, AutoRendererConfig(preserve_all_thinking=True))
+renderer = create_renderer(tokenizer, AutoRendererConfig(thinking_retention="all"))
+renderer = create_renderer(
+    tokenizer,
+    chat_template_kwargs={"enable_thinking": False},
+)
 
-# Explicit choice — the typed config exposes exactly the fields that
-# renderer's chat template honours.
+# 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))
 
@@ -158,21 +159,24 @@ renderer = create_renderer(
 
 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.
 
-Two shared behaviour flags live on every variant via `_BaseRendererConfig`:
+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_content` is kept, even when the chat template would drop it.
-- `preserve_thinking_between_tool_calls=True` — reasoning is kept on assistants in the in-flight tool cycle (post-last-user A-T-…-A block when it contains a tool response). A new user turn closes the block and drops its thinking.
+- `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.
 
-These OR-compose with template-level toggles (e.g. GLM-5 `clear_thinking`, Nemotron-3 `truncate_history_thinking`): either flag saying "keep" wins. preserve_* can only ever *extend* retention — never override a template kwarg into a "drop" decision. The canonical use case is **compaction**: injecting a `user` turn like *"summarize the work so far"* puts every prior assistant in a past cycle, and `preserve_all_thinking=True` keeps reasoning visible end-to-end.
+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` (vLLM convention) plus arbitrary Jinja kwargs via `DefaultRendererConfig`'s `extra="allow"`. `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.8.dev51 → renderers-0.1.8.dev52}/README.md

@@ -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`, `nemotron-3-ultra`, `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`, and `gpt-oss`. Anything else falls back to `DefaultRenderer`, a generic `apply_chat_template` wrapper.
 
 ## API
 
@@ -74,7 +74,7 @@ Each hand-coded bridge:
 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 an explicit typed config (e.g. `Qwen3RendererConfig()`); 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
 
@@ -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.*
 
@@ -110,7 +109,7 @@ Each break fragments a rollout into multiple training samples — every fragment
 
 ## Typed renderer configs
 
-Each renderer accepts a typed pydantic config that pins its template-control kwargs at construction. `create_renderer` and `create_renderer_pool` take one positional `config` argument:
+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
 from renderers import (
@@ -121,13 +120,15 @@ from renderers import (
     DefaultRendererConfig,
 )
 
-# Auto-resolve renderer from the tokenizer's model name. Carries the
-# shared preserve_* flags; template kwargs require an explicit choice.
+# Auto-resolve renderer from the tokenizer's model name.
 renderer = create_renderer(tokenizer)
-renderer = create_renderer(tokenizer, AutoRendererConfig(preserve_all_thinking=True))
+renderer = create_renderer(tokenizer, AutoRendererConfig(thinking_retention="all"))
+renderer = create_renderer(
+    tokenizer,
+    chat_template_kwargs={"enable_thinking": False},
+)
 
-# Explicit choice — the typed config exposes exactly the fields that
-# renderer's chat template honours.
+# 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))
 
@@ -142,21 +143,24 @@ renderer = create_renderer(
 
 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.
 
-Two shared behaviour flags live on every variant via `_BaseRendererConfig`:
+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_content` is kept, even when the chat template would drop it.
-- `preserve_thinking_between_tool_calls=True` — reasoning is kept on assistants in the in-flight tool cycle (post-last-user A-T-…-A block when it contains a tool response). A new user turn closes the block and drops its thinking.
+- `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.
 
-These OR-compose with template-level toggles (e.g. GLM-5 `clear_thinking`, Nemotron-3 `truncate_history_thinking`): either flag saying "keep" wins. preserve_* can only ever *extend* retention — never override a template kwarg into a "drop" decision. The canonical use case is **compaction**: injecting a `user` turn like *"summarize the work so far"* puts every prior assistant in a past cycle, and `preserve_all_thinking=True` keeps reasoning visible end-to-end.
+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` (vLLM convention) plus arbitrary Jinja kwargs via `DefaultRendererConfig`'s `extra="allow"`. `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.8.dev52/docs/renderer-config.md

@@ -0,0 +1,216 @@
+# 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` | - |
+| 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` |
+| 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` | - |
+| 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` |
+| 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, Llama 3 | `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.8.dev51 → renderers-0.1.8.dev52}/renderers/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.1.8.dev51'
-__version_tuple__ = version_tuple = (0, 1, 8, 'dev51')
+__version__ = version = '0.1.8.dev52'
+__version_tuple__ = version_tuple = (0, 1, 8, 'dev52')
 
 __commit_id__ = commit_id = None