Harmony

The harmony/ package handles the Harmony prompt/response format used by GPT-OSS-style models. Harmony divides a model's output into typed channels (analysis, commentary, final) and uses paired <|start|> / <|end|> tokens.

Purpose

GPT-OSS models can interleave reasoning, tool calls, and final answers in the same stream. The harmony parser separates them so handlers can route each channel to the right output (thinking, tool, content).

Key abstractions

| Symbol | Location | Purpose | | ------------------ | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ----- | ----- | --- | -------------------- | | Harmony parser | harmony/ | Stateful stream parser that recognizes < | start | >/< | end | > and channel tags. | | Renderer companion | model/renderers/ | Builds harmony-formatted prompts from messages. | | Detection | server/routes.go | shouldUseHarmony returns true when the model's family is gptoss and the template contains the harmony delimiter sequences. |

How it works

The parser reads tokens, watches for the start delimiter, and emits structured events for each channel:

• analysis → reasoning, surfaced as thinking.
• commentary → tool calls, surfaced as ToolCalls.
• final → the answer, surfaced as content.

The corresponding renderer takes a list of messages plus tool definitions and emits the harmony-formatted prompt the model expects.

Integration points

• Detected by shouldUseHarmony in server/routes.go; decision flows into renderer/parser selection through server/renderer_resolution.go.
• Both /api/chat and /v1/chat/completions benefit transparently — the compat middleware does not need to know about harmony.
• Harmony streaming is exercised by server/routes_harmony_streaming_test.go.

Entry points for modification

• New harmony channel → extend the parser to emit a new event type and add a corresponding output field where appropriate.
• New harmony-using model family → adjust shouldUseHarmony so the detection covers it.

Key source files

File	Purpose
harmony/	Parser, types, golden tests.
server/routes.go	shouldUseHarmony detection.
server/routes_harmony_streaming_test.go	Streaming integration test.
model/renderers/	Renderer counterpart.