openai

harmony: Render and Parse OpenAI Harmony Conversations

OpenAI Harmony is a Rust-based library with Python bindings for rendering and parsing the conversation format used by gpt-oss. It is useful for developers building inference systems that need to handle Harmony messages, channels, and tool calls directly.

RustApache-2.0PythonLLMLibrary
View on GitHub Compare
Stars
4.5k
Forks
311
Stars, last 30 days
+13

Our take

Health score

29/100

How it is scored
Activity
19
Community
56
Issues
21
Pull requests
20

+13 stars in the last 30 days

Project history

Daily GitHub snapshots since Oct 7, 2026. History covers stars and forks; health signals are not tracked historically.

Selected snapshot

Stars

4,542

Forks

319

Change since Nov 16, 2026: 0 stars·0 forks

Overview

OpenAI Harmony provides shared rendering and parsing for Harmony-formatted conversations, the response format used by OpenAI's gpt-oss models. It helps inference developers construct model inputs and interpret outputs without implementing the format themselves, including its conversation structure and tool-call conventions.

The Rust implementation is also exposed through a Python package. This is most relevant when you operate or build an inference stack that exposes Harmony tokens directly; API and provider integrations may handle the formatting for you.

Key Features

  • Render conversations into Harmony-formatted model inputs and parse completion tokens back into messages.
  • Represent roles, messages, and conversations with Rust data structures and a corresponding Python API.
  • Support Harmony channels, tool-call preambles, tool namespaces, and structured outputs.
  • Use built-in encodings, including the gpt-oss Harmony encoding.
  • Run the core implementation in Rust, with Python bindings provided through PyO3.
  • Install the Python package from PyPI or use the Rust crate from the repository.

Use Cases

  • Inference-platform developers can format prompts and decode completions when serving gpt-oss directly.
  • Rust application developers can integrate Harmony rendering and parsing into model-serving or orchestration code.
  • Python developers can build custom inference workflows with the package's message and conversation helpers.
  • Teams testing format compatibility can use the Rust and Python test suites to check their integrations.

Getting Started

Install the Python package:

pip install openai-harmony

For Rust setup, usage details, and development instructions, see the repository README.

Considerations

  • Harmony formatting is important for using gpt-oss correctly in a custom inference solution. If an API or hosting provider handles the format, you may not need this library.
  • The Rust crate is the core implementation. Building the Python package from source requires a Rust toolchain and maturin.
  • The README recommends Python 3.8 or later for local development. Check the project documentation for further language-specific guidance.

Found this useful?

Share it with someone who would like harmony.