Skip to content

Skip Tool Normalization for GPT-OSS/Harmony Templates #1069

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Sayan Shaw (sayanshaw24) merged 6 commits into from
Jun 8, 2026
Merged

Skip Tool Normalization for GPT-OSS/Harmony Templates #1069

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
aa5f79f
initial harmony changes
May 5, 2026
c4de4a5
Merge branch 'main' of https://github.com/microsoft/onnxruntime-exten…
May 7, 2026
2fea971
more test cases identified after genai round trip
May 11, 2026
7a8e2a6
Merge branch 'main' of https://github.com/microsoft/onnxruntime-exten…
Jun 4, 2026
65a14a6
add gpt-oss test data
Jun 4, 2026
8b8a034
address Copilot comments
Jun 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 35 additions & 7 deletions shared/api/chat_template.cc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -413,28 +413,56 @@ OrtxStatus TokenizerImpl::ApplyChatTemplate(const char* template_str, const char
// Check Phi-4-mini tool call case for quote normalization
bool phi_4_mini = false;

// Determine whether to skip tool normalization based on template content.
// GPT-OSS/Harmony templates access `tool.function` directly (they expect the raw OpenAI format),
// so NormalizeTools() would break them by unwrapping the function object.
// Other templates (Phi-4, Qwen) either use a flat format or access `tool_call.function`.
bool skip_tool_normalization = false;
{
std::string tmpl_str(activated_str);
// Look for "tool.function" in the template (Harmony/GPT-OSS expects raw OpenAI tool objects).
skip_tool_normalization = tmpl_str.find("tool.function") != std::string::npos;
}

// Case 1: Check if tools are inside messages (for Phi-4-mini)
if (actual_messages.is_array()) {
for (auto& message_obj : actual_messages) {
if (message_obj.contains("tools")) {
// Set flag for Phi-4 tools to true
phi_4_mini = true;

// Normalize the tools inside the message
json tools_json = NormalizeTools(message_obj["tools"].get<std::string>().c_str());

// Update the tools in the message
message_obj["tools"] = tools_json;
if (skip_tool_normalization) {
// GPT-OSS/Harmony: parse tools as-is without normalization
const auto tools_text = message_obj["tools"].get<std::string>();
json tools_json = json::parse(tools_text, nullptr, /*allow_exceptions=*/false);
if (tools_json.is_discarded()) {
throw std::runtime_error("Invalid tools JSON.");
}
message_obj["tools"] = std::move(tools_json);
} else {
// Normalize the tools inside the message
json tools_json = NormalizeTools(message_obj["tools"].get<std::string>().c_str());
message_obj["tools"] = tools_json;
}
}
}
}

// Case 2: Check if we received tools separately (for Qwen or others)
if (tools && *tools) {
std::string tools_str = minja::normalize_newlines(tools);
json tools_json = NormalizeTools(tools_str.c_str());
json tools_json;
if (skip_tool_normalization) {
// GPT-OSS/Harmony: pass raw tools without normalization
tools_json = json::parse(tools_str, nullptr, /*allow_exceptions=*/false);
if (tools_json.is_discarded()) {
throw std::runtime_error("Invalid tools JSON.");
}
} else {
tools_json = NormalizeTools(tools_str.c_str());
}

// Add normalized tools to the context if tools are passed separately
// Add tools to the context
context = minja::Context::make(json({
{"messages", actual_messages},
{"tools", tools_json},
Expand Down
318 changes: 318 additions & 0 deletions test/data/gpt-oss/chat_template.jinja
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,318 @@
{#-
In addition to the normal inputs of `messages` and `tools`, this template also accepts the
following kwargs:
- "builtin_tools": A list, can contain "browser" and/or "python".
- "model_identity": A string that optionally describes the model identity".
- "reasoning_effort": A string that describes the reasoning effort, defaults to "medium".
#}

{#- Tool Definition Rendering ============================================== #}
{%- macro render_typescript_type(param_spec, required_params, is_nullable=false) -%}
{%- if param_spec.type == "array" -%}
{%- if param_spec['items'] -%}
{%- if param_spec['items']['type'] == "string" -%}
{{- "string[]" }}
{%- elif param_spec['items']['type'] == "number" -%}
{{- "number[]" }}
{%- elif param_spec['items']['type'] == "integer" -%}
{{- "number[]" }}
{%- elif param_spec['items']['type'] == "boolean" -%}
{{- "boolean[]" }}
{%- else -%}
{%- set inner_type = render_typescript_type(param_spec['items'], required_params) -%}
{%- if inner_type == "object | object" or inner_type|length > 50 -%}
{{- "any[]" }}
{%- else -%}
{{- inner_type + "[]" }}
{%- endif -%}
{%- endif -%}
{%- if param_spec.nullable -%}
{{- " | null" }}
{%- endif -%}
{%- else -%}
{{- "any[]" }}
{%- if param_spec.nullable -%}
{{- " | null" }}
{%- endif -%}
{%- endif -%}
{%- elif param_spec.type is defined and param_spec.type is iterable and param_spec.type is not string and param_spec.type is not mapping and param_spec.type[0] is defined -%}
{#- Handle array of types like ["object", "object"] from Union[dict, list] #}
{%- if param_spec.type | length > 1 -%}
{{- param_spec.type | join(" | ") }}
{%- else -%}
{{- param_spec.type[0] }}
{%- endif -%}
{%- elif param_spec.oneOf -%}
{#- Handle oneOf schemas - check for complex unions and fallback to any #}
{%- set has_object_variants = false -%}
{%- for variant in param_spec.oneOf -%}
{%- if variant.type == "object" -%}
{%- set has_object_variants = true -%}
{%- endif -%}
{%- endfor -%}
{%- if has_object_variants and param_spec.oneOf|length > 1 -%}
{{- "any" }}
{%- else -%}
{%- for variant in param_spec.oneOf -%}
{{- render_typescript_type(variant, required_params) -}}
{%- if variant.description %}
{{- "// " + variant.description }}
{%- endif -%}
{%- if variant.default is defined %}
{{ "// default: " + variant.default|tojson }}
{%- endif -%}
{%- if not loop.last %}
{{- " | " }}
{% endif -%}
{%- endfor -%}
{%- endif -%}
{%- elif param_spec.type == "string" -%}
{%- if param_spec.enum -%}
{{- '"' + param_spec.enum|join('" | "') + '"' -}}
{%- else -%}
{{- "string" }}
{%- if param_spec.nullable %}
{{- " | null" }}
{%- endif -%}
{%- endif -%}
{%- elif param_spec.type == "number" -%}
{{- "number" }}
{%- elif param_spec.type == "integer" -%}
{{- "number" }}
{%- elif param_spec.type == "boolean" -%}
{{- "boolean" }}

{%- elif param_spec.type == "object" -%}
{%- if param_spec.properties -%}
{{ - "{\n" }}
{%- for prop_name, prop_spec in param_spec.properties.items() -%}
{{- prop_name -}}
{%- if prop_name not in (param_spec.required or []) -%}
{{- "?" }}
{%- endif -%}
{{- ": " }}
{{ render_typescript_type(prop_spec, param_spec.required or []) }}
{%- if not loop.last -%}
{{-", " }}
{%- endif -%}
{%- endfor -%}
{{- "}" }}
{%- else -%}
{{- "object" }}
{%- endif -%}
{%- else -%}
{{- "any" }}
{%- endif -%}
{%- endmacro -%}

{%- macro render_tool_namespace(namespace_name, tools) -%}
{{- "## " + namespace_name + "\n\n" }}
{{- "namespace " + namespace_name + " {\n\n" }}
{%- for tool in tools %}
{%- set tool = tool.function %}
{{- "// " + tool.description + "\n" }}
{{- "type "+ tool.name + " = (" }}
{%- if tool.parameters and tool.parameters.properties -%}
{{- "_: " }}
{{- "{\n" }}
{%- for param_name, param_spec in tool.parameters.properties.items() %}
{{- "// " + param_spec.description + "\n" }}
{{- param_name }}
{%- if param_name not in (tool.parameters.required or []) -%}
{{- "?" }}
{%- endif -%}
{{- ": " }}
{{- render_typescript_type(param_spec, tool.parameters.required or []) }}
{%- if param_spec.default is defined -%}
{%- if param_spec.oneOf %}
{{- "// default: " + param_spec.default }}
{%- else %}
{{- ", // default: " + param_spec.default|tojson }}
{%- endif -%}
{%- endif -%}
{%- if not loop.last %}
{{- ",\n" }}
{%- endif -%}
{%- endfor %}
{{- ",\n}) => any;\n" }}
{%- else -%}
{{- "\n}) => any;\n" }}
{%- endif -%}
{%- endfor %}
{{- "\n} // namespace " + namespace_name }}
{%- endmacro -%}

{%- macro render_builtin_tools(browser_tool, python_tool) -%}
{%- if browser_tool %}
{{- "## browser\n\n" }}
{{- "// Tool for browsing.\n" }}
{{- "// The `cursor` appears in brackets before each browsing display: `[{cursor}]`.\n" }}
{{- "// Cite information from the tool using the following format:\n" }}
{{- "// `【{cursor}†L{line_start}(-L{line_end})?】`, for example: `【6†L9-L11】` or `【8†L3】`.\n" }}
{{- "// Do not quote more than 10 words directly from the tool output.\n" }}
{{- "// sources=web (default: web)\n" }}
{{- "namespace browser {\n\n" }}
{{- "// Searches for information related to `query` and displays `topn` results.\n" }}
{{- "type search = (_: {\n" }}
{{- "query: string,\n" }}
{{- "topn?: number, // default: 10\n" }}
{{- "source?: string,\n" }}
{{- "}) => any;\n\n" }}
{{- "// Opens the link `id` from the page indicated by `cursor` starting at line number `loc`, showing `num_lines` lines.\n" }}
{{- "// Valid link ids are displayed with the formatting: `【{id}†.*】`.\n" }}
{{- "// If `cursor` is not provided, the most recent page is implied.\n" }}
{{- "// If `id` is a string, it is treated as a fully qualified URL associated with `source`.\n" }}
{{- "// If `loc` is not provided, the viewport will be positioned at the beginning of the document or centered on the most relevant passage, if available.\n" }}
{{- "// Use this function without `id` to scroll to a new location of an opened page.\n" }}
{{- "type open = (_: {\n" }}
{{- "id?: number | string, // default: -1\n" }}
{{- "cursor?: number, // default: -1\n" }}
{{- "loc?: number, // default: -1\n" }}
{{- "num_lines?: number, // default: -1\n" }}
{{- "view_source?: boolean, // default: false\n" }}
{{- "source?: string,\n" }}
{{- "}) => any;\n\n" }}
{{- "// Finds exact matches of `pattern` in the current page, or the page given by `cursor`.\n" }}
{{- "type find = (_: {\n" }}
{{- "pattern: string,\n" }}
{{- "cursor?: number, // default: -1\n" }}
{{- "}) => any;\n\n" }}
{{- "} // namespace browser\n\n" }}
{%- endif -%}

{%- if python_tool %}
{{- "## python\n\n" }}
{{- "Use this tool to execute Python code in your chain of thought. The code will not be shown to the user. This tool should be used for internal reasoning, but not for code that is intended to be visible to the user (e.g. when creating plots, tables, or files).\n\n" }}
{{- "When you send a message containing Python code to python, it will be executed in a stateful Jupyter notebook environment. python will respond with the output of the execution or time out after 120.0 seconds. The drive at '/mnt/data' can be used to save and persist user files. Internet access for this session is UNKNOWN. Depends on the cluster.\n\n" }}
{%- endif -%}
{%- endmacro -%}

{#- System Message Construction ============================================ #}
{%- macro build_system_message() -%}
{%- if model_identity is not defined %}
{{- "You are ChatGPT, a large language model trained by OpenAI.\n" -}}
{%- else %}
{{- model_identity }}
{%- endif %}
{{- "Knowledge cutoff: 2024-06\n" }}
{{- "Current date: " + strftime_now("%Y-%m-%d") + "\n\n" }}
{%- if reasoning_effort is not defined %}
{%- set reasoning_effort = "medium" %}
{%- endif %}
{{- "reasoning: " + reasoning_effort + "\n\n" }}
{%- if builtin_tools %}
{{- "# Tools\n\n" }}
{%- set available_builtin_tools = namespace(browser=false, python=false) %}
{%- for tool in builtin_tools %}
{%- if tool == "browser" %}
{%- set available_builtin_tools.browser = true %}
{%- elif tool == "python" %}
{%- set available_builtin_tools.python = true %}
{%- endif %}
{%- endfor %}
{{- render_builtin_tools(available_builtin_tools.browser, available_builtin_tools.python) }}
{%- endif -%}
{{- "# Valid channels: analysis, commentary, final. Channel must be included for every message.\n" }}
{{- "Calls to these tools must go to the commentary channel: 'functions'." }}
{%- endmacro -%}

{#- CoT Dropping Logic ================================================== #}
{%- set cot_final_indices = [] -%}
{%- for idx in range(messages|length) -%}
{%- set m = messages[idx] -%}
{%- if m.role == 'assistant' and m.get('channel', '') == 'final' -%}
{%- if cot_final_indices.append(idx) -%}{%- endif -%}
{%- endif -%}
{%- endfor -%}
{%- set cot_last_final_idx = cot_final_indices[-1] if cot_final_indices else none -%}
{%- set cot_last_user_idx = none -%}
{%- if cot_last_final_idx is not none -%}
{%- for idx in range(cot_last_final_idx - 1, -1, -1) -%}
{%- if messages[idx].role == 'user' and cot_last_user_idx is none -%}
{%- set cot_last_user_idx = idx -%}
{%- endif -%}
{%- endfor -%}
{%- endif -%}

{#- Main Template Logic ================================================= #}
{#- Set defaults #}
{%- set auto_drop = auto_drop_analysis if auto_drop_analysis is defined else true -%}

{#- Render system message #}
{{- "<|start|>system<|message|>" }}
{{- build_system_message() }}
{{- "<|end|>" }}

{#- Extract developer message #}
{%- if messages[0].role == "developer" or messages[0].role == "system" %}
{%- set developer_message = messages[0].content %}
{%- set loop_messages = messages[1:] %}
{%- else %}
{%- set developer_message = "" %}
{%- set loop_messages = messages %}
{%- endif %}

{#- Render developer message #}
{%- if developer_message or tools %}
{{- "<|start|>developer<|message|>" }}
{%- if developer_message %}
{{- "# Instructions\n\n" }}
{{- developer_message }}
{%- endif %}
{%- if tools -%}
{{- "\n\n" }}
{{- "# Tools\n\n" }}
{{- render_tool_namespace("functions", tools) }}
{%- endif -%}
{{- "<|end|>" }}
{%- endif %}

{#- Render messages #}
{%- set last_tool_call = namespace(name=none) %}
{%- for message in loop_messages -%}
{%- set skip = false -%}

{# Apply CoT dropping logic #}
{%- if auto_drop and cot_last_final_idx is not none and loop.index0 < cot_last_final_idx -%}
{%- if message.role == 'assistant' and message.get('channel', '') != 'final' -%}
{%- if cot_last_user_idx is none or loop.index0 > cot_last_user_idx -%}
{%- set skip = true -%}
{%- endif -%}
{%- elif message.role == 'user' and message.get('channel', '') == 'analysis' -%}
{%- set skip = true -%}
{%- endif -%}
{%- endif -%}

{%- if not skip -%}
{#- At this point only assistant/user/tool messages should remain #}
{%- if message.role == 'assistant' -%}
{%- if "tool_calls" in message %}
{# I'm assuming max 1 tool call per message here, which might be wrong #}
{{- "<|start|>assistant<|channel|>analysis<|message|>" + message.content }}
{{- "<|end|><|start|>assistant to=" }}
{{- "functions." + message.tool_calls[0].name + "<|channel|>commentary json<|message|>" }}
{{- message.tool_calls[0].arguments|tojson }}
{{- "<|end|>" }}
{%- set last_tool_call.name = message.tool_calls[0].name %}
{%- elif "thinking" in message %}
{#- CoT is dropped during all model inputs, so we never actually render it #}
{{- "<|start|>assistant<|channel|>final<|message|>" + message.content + "<|end|>" }}
{%- else %}
{{- "<|start|>assistant<|message|>" + message.content + "<|end|>" }}
{%- endif %}
{%- elif message.role == 'tool' -%}
{%- if last_tool_call.name is none %}
{{- raise_exception("Message has tool role, but there was no previous assistant message with a tool call!") }}
{%- endif %}
{{- "<|start|>functions." + last_tool_call.name }}
{{- " to=assistant<|channel|>commentary<|message|>" + message.content|tojson + "<|end|>" }}
{%- else -%}
{{- "<|start|>user<|message|>" + message.content + "<|end|>" }}
{%- endif -%}
{%- endif -%}
{%- endfor -%}

{#- Generation prompt #}
{%- if add_generation_prompt -%}
<|start|>assistant
{%- endif -%}
Loading
Loading