- Category
- AI Tools
- Rank
- No. 615Tools index
- Pricing
- Open Source
- Type
- TOOL
- Builder
- openai
- GitHub
- 4.5k stars
- Date
About
OpenAI's renderer for the Harmony response format used by gpt-oss — chat templates, tool calls, and structured outputs for open-weight GPT models.
What it does
Harmony acts as a conversation compiler for gpt-oss. It turns typed messages, roles, instructions, channels, and tool definitions into model-ready tokens, then reconstructs generated tokens as messages. It supports completion and training preparation, incremental parsing, stop-token discovery, and direct token encoding or decoding.
Why it's ranked here
This is a strong fit when correctness at the token boundary matters. One Rust implementation handles both directions, while Python and WebAssembly bindings reuse that core. Canonical Rust tests cover conversations, reasoning channels, tool calls, instruction hierarchy, and exact expected token sequences. Its value is concentrated, however, around one registered gpt-oss encoding.
What's good
Rendering and parsing share the same Rust core, reducing drift between prompt construction and output interpretation. The parser can consume tokens incrementally, which suits streamed generation. Typed conversation models cover system, developer, user, assistant, and tool roles, plus recipients and channels. Python users get typed wrappers, while browser-oriented consumers can use WebAssembly bindings.
Tradeoffs
The library is specialized rather than provider-neutral. Its registry exposes only the gpt-oss Harmony encoding, and the README says provider-hosted inference usually handles formatting already. Python installation includes a compiled native extension, while local development requires Rust and Maturin. Vocabulary loading may use a remote public file unless a local encoding directory is configured.
How to use it well
Use Harmony when you run gpt-oss through your own inference stack, training pipeline, or token-stream processor. Build conversations with its typed message model, render exact input tokens, apply its stop tokens during generation, and feed output tokens into the streaming parser. Skip it when HuggingFace, Ollama, vLLM, or another provider already owns prompt formatting. It does not supply inference hosting or model execution.
Technical notes+
The Rust crate is rooted at src/lib.rs; src/chat.rs defines the serialized conversation model, src/encoding.rs implements rendering, parsing, training formatting, stop tokens, and StreamableParser, and src/registry.rs registers only HarmonyEncodingName::HarmonyGptOss. src/py_module.rs passes conversation structures across PyO3 as JSON, while src/wasm_module.rs uses serde_wasm_bindgen and exports TypeScript interfaces. src/tiktoken_ext/public_encodings.rs downloads or locally loads hashed vocabulary data. src/tiktoken.rs contains the BPE implementation and uses an unsafe transmute to derive a numeric thread identifier for thread-local regex selection. src/tests.rs checks exact token output and parsed messages.
Observed
- License
- Apache-2.0
- Primary language
- Rust, with Python and WebAssembly bindings
- Python packaging
- Published package installs with pip or uv and requires Python 3.8 or newer
- Rust packaging
- Cargo library crate with rlib and cdylib outputs
- Interfaces
- Rust library, Python library, and optional WebAssembly library
- Python build
- Maturin builds a PyO3 native extension with a typed Python wrapper
- Test structure
- Canonical Rust tests have a top-level Python test suite described as a direct port
- Encoding scope
- The public Harmony registry contains one gpt-oss encoding
Read from README.md, Cargo.toml, pyproject.toml, src/lib.rs, src/chat.rs, src/tests.rs, src/encoding.rs, src/registry.rs, src/tiktoken.rs, src/py_module.rs, src/wasm_module.rs, src/tiktoken_ext/mod.rs, src/tiktoken_ext/public_encodings.rs.
What it can do
Render Harmony response format
Harmony-formatted data → Rendered response content
Process chat templates
Chat template definitions → Formatted chat responses
Execute tool calls
Tool call specifications → Tool execution results
Generate structured outputs
Structured data requirements → Formatted structured data
Support open-weight GPT models
Open-weight GPT model requests → Compatible model responses
Tags
Tech Stack
Comments (0)
No comments yet
Editorially curated, with community endorsements as a secondary signal. Corrections welcome.