Route chat template kwargs through tokenizer options

[jennyf19]

Route chat template kwargs through tokenizer options

Summary

• add chat_template_kwargs to the existing tokenizer option allowlist
• validate the value as a serialized JSON object and preserve typed values
• make the existing OrtxApplyChatTemplate consume those configured values
• keep messages, tools, and add_generation_prompt authoritative
• preserve OrtxApplyChatTemplateWithOptions as a per-call compatibility API
• document {} as the way to clear previously configured template kwargs
• update Python binding help and cover both create-time and runtime option paths
• synchronize tokenizer option reads and writes
• report explicit errors for null option arrays, keys, and values

Why

This is the cleaner follow-up to #1102 suggested during review of the dependent
GenAI change.

OrtxUpdateTokenizerOptions already provides a forward-compatible C surface
for extending tokenizer behavior. Routing template kwargs through it avoids
requiring callers to grow a parallel family of WithOptions entry points while
preserving the per-call API added in #1102 for compatibility. Both paths retain
typed chat-template context such as:

{"enable_thinking": false, "reasoning_effort": "low", "level": 2}

This is needed by microsoft/foundry-local#808 so Qwen 3 callers can disable
thinking before generation rather than spending a bounded completion entirely
inside the reasoning block.

Behavior

• chat_template_kwargs must be a JSON object.
• Invalid JSON and non-object values fail during tokenizer option update.
• The configured values are merged into the Minja context.
• Core request values overwrite conflicting custom values.
• Setting chat_template_kwargs to {} clears the custom context.
• OrtxApplyChatTemplateWithOptions remains available for per-call overrides.
• Tokenizer option access is synchronized for concurrent update/apply calls.
• Null option arrays, keys, and values return specific invalid-argument errors.
• Existing add_special_tokens and skip_special_tokens behavior is unchanged.

Validation

Fork-only native validation passed:

https://github.com/jennyf19/onnxruntime-extensions/actions/runs/32611271986

The run validated the review-fix commit, built the C API/native test target,
and passed the complete C++ test suite.

The dependent source-only prototypes also pass:

• GenAI cleanup: https://github.com/jennyf19/onnxruntime-genai/actions/runs/32604912346
• Full Foundry stack: https://github.com/jennyf19/foundry-local/actions/runs/32605012437

No production dependency pins in the dependent repositories have been changed.

[azure-pipelines]

Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.

[Copilot]

Pull request overview

Routes chat-template “template kwargs” through tokenizer options by introducing a chat_template_kwargs option, removing the dedicated per-call C API, and updating tests/docs accordingly.

Changes:

• Adds chat_template_kwargs to tokenizer options (C API + docs) with JSON validation.
• Updates chat template application to pull kwargs from tokenizer options rather than a per-call parameter.
• Refactors/extends tests to configure/clear chat_template_kwargs via OrtxUpdateTokenizerOptions / OrtxCreateTokenizerWithOptions.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
test/pp_api_test/test_tokenizer_chat.cc	Updates tests to configure chat template kwargs through tokenizer options and adds a “clear option” test.
shared/api/tokenizer_impl.h	Updates TokenizerImpl::ApplyChatTemplate signature to remove the explicit kwargs parameter.
shared/api/chat_template.cc	Reads chat_template_kwargs from options_map and updates related error messages.
shared/api/c_api_tokenizer.cc	Adds chat_template_kwargs as a valid option and validates it as a JSON object. Removes the OrtxApplyChatTemplateWithOptions implementation.
pyop/py_c_api.cc	Updates Python binding docstrings to mention chat_template_kwargs.
include/ortx_tokenizer.h	Documents chat_template_kwargs option and removes the OrtxApplyChatTemplateWithOptions declaration/docs.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.