Harmony: the response format gpt-oss is trained on and cannot skip
Renderer for the harmony response format to be used with gpt-oss
At a glance
- What is it?
- OpenAI's harmony is the conversation format gpt-oss models were trained on, and the library implements both rendering and parsing of it in Rust with Python bindings on top. Its audience is narrow by design, people writing their own inference stack, and its documentation has two rough edges: the Rust install points at git rather than a registry, and the Python example ends mid-expression.
- Who is it for?
- Harmony fits a team building its own inference path for gpt-oss, where a single implementation both renders prompts and parses output so the token sequences cannot drift apart between the two directions. It does not fit anyone calling gpt-oss through an API or a hosted runtime, since those handle the formatting already.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Activity is slowing. The repository last received commits 7 months ago.
- What is it written in?
- Mainly Rust, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- openai/harmony4,542 ★ · +37
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| openai/harmony | 4.5k | 4.5k |
37 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The warning is aimed at inference authors
The README opens with the scope and then a prohibition. The gpt-oss models were trained on the harmony response format for defining conversation structures, generating reasoning output and structuring function calls, and gpt-oss should not be used without using the harmony format as it will not work correctly.
Then it tells most readers to stop reading. If you are not using gpt-oss directly but through an API or a provider like HuggingFace, Ollama or vLLM, you will not have to be concerned about this, because your inference solution will handle the formatting.
That paragraph is the adoption test. If you send a request to a hosted endpoint, this library is not for you. If you are building your own inference solution, the guide walks you through the prompt format, and the format is designed to mimic the OpenAI Responses API, so prior experience with that API should make it feel familiar.
What the format buys is described next: output to multiple channels for chain of thought, tool calling preambles alongside regular responses, tool namespaces, structured outputs, and a clear instruction hierarchy. Channels are named in the example itself, which states that the valid channels are analysis, commentary and final, that the channel must be included for every message, and that calls to the listed tools must go to the commentary channel.
The message delimiters are literal tokens, so a document begins like this:
<|start|>system<|message|>You are ChatGPT, a large language model trained by OpenAI.One implementation renders and parses, so the tokens cannot drift
The first of the three stated reasons to use the library is consistency: a shared implementation for rendering and parsing keeps token sequences loss-free.
That is the whole argument, and it is stronger than it first looks. A format with special delimiters, named channels and a header per message has two directions that must agree exactly. If you render prompts with one library and parse responses with another, any disagreement about where a message ends or which channel a token belongs to becomes a silent corruption rather than an error. Sharing the implementation removes that class of bug.
The architecture follows from it. The majority of the rendering and parsing is built in Rust for performance and exposed to Python through thin pyo3 bindings, and the repository layout makes the split explicit: `src/encoding.rs` holds the rendering and parsing implementation, `src/chat.rs` holds the high level data structures such as Role and Message, and `src/registry.rs` holds the built-in encodings.
The Python side is a wrapper, not a port. `python/openai_harmony/__init__.py` is described as dataclasses and a helper API mirroring `chat.rs`, and `src/py_module.rs` compiles to the native extension. The tokeniser sits in the Rust core alongside the chat and encoding logic, so tokenisation does not cross the language boundary either.
The Rust dependency points at git
The Rust installation is one entry in a Cargo manifest:
[dependencies]
openai-harmony = { git = "https://github.com/openai/harmony" }There is no version constraint and no registry reference. The crate manifest does declare a version, 0.0.8, along with an Apache-2.0 licence, edition 2021 and a library name of `openai_harmony` built as both an rlib and a cdylib, and the repository has a Cargo.lock.
But the documented dependency tracks the repository's default branch rather than a published crate version, and there are no GitHub releases for this project. In practice that means a Cargo build resolves against the tip of main unless you pin a revision yourself, so a rebuild can pick up a change you have not read.
For a library whose entire value is byte-exact agreement between render and parse, that is the trade to think about. Nothing in the README says to pin, and the last push to the repository is dated 2026-04-08, so the branch is not moving quickly, but the default is still the default.
The Python side has the opposite shape, since it installs a named release from a package index.
The Python example stops mid-expression
The Python snippet in the README does not finish. It imports the surface it needs:
from openai_harmony import (
load_harmony_encoding,
HarmonyEncodingName,
Role,
Message,
Conversation,
DeveloperContent,
SystemContent,
)
enc = load_harmony_encoding(HarmonyEncodingName.HARMONY_GPT_OSS)builds a conversation from role and content pairs, with `SystemContent.new()` for the system message and `DeveloperContent.new().with_instructions(...)` for developer instructions, and then ends on `tokens = enc.render_con`, which is not a call.
The Rust example beside it completes the same operation, so the missing method name is recoverable from the working version. It calls `render_conversation_for_completion` with the conversation, the role being rendered for, and a third argument:
let tokens = enc.render_conversation_for_completion(&convo, Role::Assistant, None)?;The Python line is valid syntax, but it references a truncated attribute rather than calling a method, so it does not produce tokens. Reading both examples together is the intended fix, and the full Python documentation is linked separately from the README.
Parity is a test command, not a promise
The third stated reason to use the library is first-class Python support: install with pip, typed stubs included, with 100% test parity with the Rust suite.
Parity is enforced by construction. The repository holds a canonical Rust test suite in `src/tests.rs` and a Python test suite in `tests/` described as a one to one port of it, and the two runners are:
cargo test
pytestThe README then gives the combined command to run both in one go to ensure parity. That is a stronger statement than a coverage number: a behaviour change to rendering has to land in the Rust suite and its Python mirror or one of the two runs fails.
The layout supports it as well, since the encoding name is a first class value rather than a string, with a registry of built-in encodings behind `HarmonyEncodingName`, so the same encoding identifier is typed on both sides.
The Python package configuration reinforces the split by pointing test collection at the top level `tests` directory only, so running pytest from the repository root does not also collect anything from the virtualenv or the build artifacts.
abi3 is why one build covers CPython and PyPy
The Python packaging is a maturin project, which is the PyO3 build tool:
[build-system]
requires = ["maturin>=1.8,<2.0"]
build-backend = "maturin"The single Python dependency is `pydantic>=2.11.7`, and the version is dynamic rather than written down. Classifiers list Rust, CPython and PyPy, and `requires-python` is `>=3.8`.
The PyO3 feature list adds detail the metadata does not: the optional `python-binding` feature turns on pyo3 configured with the `extension-module` feature and `abi3-py38`. The stable ABI target means the compiled extension is not tied to one CPython minor version.
The maturin configuration also sets the module name to `openai_harmony` and points `python-source` at the `python` directory, matching the repository layout where the pure Python wrapper sits beside the Rust crate.
An optional `demo` extra installs uvicorn and fastapi, which is what the bundled demo under `demo/harmony-demo/` needs.
A wasm feature and a javascript directory nobody documents
The crate has a second optional feature that the README never mentions:
[features]
default = []
python-binding = ["pyo3"]
wasm-binding = ["wasm-bindgen", "serde-wasm-bindgen", "wasm-bindgen-futures"]Three WebAssembly dependencies sit behind it, and the repository tree contains a `javascript/` directory at the top level. So a JavaScript path exists in some form, and the README documents only two languages: it links `docs/python.md` and `docs/rust.md` and shows installation for each.
Treat that as undetermined rather than unavailable. Nothing states the package name, the npm package, the build command or the API surface, and the default feature set is empty, so the wasm bindings are opt-in for a reason someone chose and did not write down here.
The same restraint applies elsewhere in the tree. There are `run_checks.sh` and `test_python.sh` scripts at the root, a `test-data/` directory, an `AGENTS.md` and a `docs/` directory whose contents are only partly reachable from the README. The Python and Rust paths are the documented ones.
Local development needs maturin and a virtualenv
The prerequisites are a stable Rust toolchain, Python 3.8 or later with virtualenv or venv, and maturin as the build tool for PyO3 projects. The bootstrap is four commands:
python -m venv .venv
source .venv/bin/activate
pip install maturin pytest mypy ruff
maturin develop --releaseThat last one is the interesting step. `maturin develop` builds harmony with Cargo, produces a native extension named `openai_harmony.<abi>.so`, and places it in the virtualenv next to the pure Python wrapper, which the README compares to an editable install for a pure Python project.
So a local change to the Rust core is visible to the Python package immediately, without a wheel build and a reinstall. The optional quality gates are `mypy harmony` for static type analysis, `ruff check .` for linting and `cargo fmt --all` for the Rust side, and the repository root also carries `run_checks.sh` and `test_python.sh`.
The optional type checking on the Python wrapper matters for the parity claim: a mirrored API that drifts in its annotations will be caught by mypy before the runtime tests do.
Editorial conclusion
Harmony fits a team building its own inference path for gpt-oss, where a single implementation both renders prompts and parses output so the token sequences cannot drift apart between the two directions. It does not fit anyone calling gpt-oss through an API or a hosted runtime, since those handle the formatting already. Verify two things before you start: that you really need to own the format rather than delegate it, and that your Rust dependency on this repository is acceptable, because the documented install tracks the default branch and the project has no tagged releases.
Frequently asked questions
Do I need the openai-harmony library if I call gpt-oss through an API?
No. The README says that if you use gpt-oss through an API or a provider such as HuggingFace, Ollama or vLLM, your inference solution handles the formatting. The library is for people building their own inference solution.
How do I install openai-harmony for Python?
Run `pip install openai-harmony`, or `uv pip install openai-harmony`. The full Python documentation is in `docs/python.md`, and the package needs Python 3.8 or later with pydantic 2.11.7 or newer.
How do I add openai-harmony to a Rust project?
The README's Cargo manifest snippet points at git: `openai-harmony = { git = "https://github.com/openai/harmony" }`. There is no version constraint and the repository has no GitHub releases, although the crate manifest declares version 0.0.8.
What are the channels in the harmony response format?
The valid channels are analysis, commentary and final. The prompt example states that the channel must be included for every message, and that calls to the listed tools must go to the commentary channel, with functions named as the namespace.
How do I run the openai-harmony test suites?
`cargo test` runs the canonical Rust suite in `src/tests.rs`, and `pytest` runs the Python suite in `tests/`, which is a one to one port of it. Running `pytest && cargo test` together is the documented parity check.
Can I use openai-harmony from JavaScript?
The crate declares a `wasm-binding` feature pulling in wasm-bindgen, serde-wasm-bindgen and wasm-bindgen-futures, and the repository contains a `javascript/` directory, but the README documents only the Python and Rust paths, with no package name or build command for the WebAssembly binding.
Official sources
Where developers are discussing it
Posts on Hacker News, dev.to and Lobsters that link to this repository, found by our scan of those communities. 1 in the last 30 days; newest first.
- State of AI Instruction Quality: Coding Agent Comparisondev.to · Oct 21, 2026 · 6 points · 0 comments
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/openai-harmony)Star history chart for your README
[](https://hysenlabs.com/projects/openai-harmony)Was this useful?