# Harmony: OpenAI's Renderer for GPT-OSS Response Format

This repository profile is provided by osrepos.com, an open source repository discovery platform.

Source: osrepos.com
Repository profile: https://osrepos.com/repo/openai-harmony
Generated for open source discovery and AI-assisted research.

Harmony is OpenAI's dedicated renderer for its `harmony` response format, specifically designed for use with `gpt-oss` open-weight models. This library provides a robust solution for defining conversation structures, generating reasoning output, and structuring function calls, ensuring consistent and efficient token-sequence handling for both rendering and parsing. It offers first-class support for both Python and Rust development.

GitHub: https://github.com/openai/harmony
OSRepos URL: https://osrepos.com/repo/openai-harmony

## Summary

Harmony is OpenAI's dedicated renderer for its `harmony` response format, specifically designed for use with `gpt-oss` open-weight models. This library provides a robust solution for defining conversation structures, generating reasoning output, and structuring function calls, ensuring consistent and efficient token-sequence handling for both rendering and parsing. It offers first-class support for both Python and Rust development.

## Topics

- Rust
- Python
- AI
- LLM
- OpenAI
- GPT-OSS
- Response Format
- Developer Tools

## Repository Information

Last analyzed by OSRepos: Tue Oct 14 2025 16:01:39 GMT+0100 (Western European Summer Time)
Detail views: 10
GitHub clicks: 11

## Safety Notice

OSRepos shares public repositories for knowledge and discovery only. Review source code, dependencies, licenses, and security implications before running or installing anything.

## Content

## Introduction

OpenAI Harmony is a dedicated library for rendering and parsing the `harmony` response format, crucial for interacting with OpenAI's `gpt-oss` open-weight model series. The `gpt-oss` models are trained on this specific format, which defines conversation structures, generates reasoning output, and structures function calls. While users interacting with `gpt-oss` through an API or providers like HuggingFace, Ollama, or vLLM might not need to handle this format directly, developers building custom inference solutions will find Harmony essential for ensuring correct model operation. The format is designed to mimic the OpenAI Responses API, making it familiar to those who have used that API before.

## Installation

Harmony offers robust support for both Python and Rust, allowing developers to integrate it seamlessly into their projects.

### Python

Install the package from PyPI:

bash
pip install openai-harmony
# or if you are using uv
uv pip install openai-harmony

For comprehensive documentation, please refer to the [official Python documentation](https://github.com/openai/harmony/blob/main/docs/python.md).

### Rust

Add the dependency to your `Cargo.toml`:

toml
[dependencies]
openai-harmony = { git = "https://github.com/openai/harmony" }

For comprehensive documentation, please refer to the [official Rust documentation](https://github.com/openai/harmony/blob/main/docs/rust.md).

## Examples

Here are examples demonstrating how to use Harmony in both Python and Rust to render and parse conversations.

### Python Example

python
from openai_harmony import (
    load_harmony_encoding,
    HarmonyEncodingName,
    Role,
    Message,
    Conversation,
    DeveloperContent,
    SystemContent,
)
enc = load_harmony_encoding(HarmonyEncodingName.HARMONY_GPT_OSS)
convo = Conversation.from_messages([
    Message.from_role_and_content(
        Role.SYSTEM,
        SystemContent.new(),
    ),
    Message.from_role_and_content(
        Role.DEVELOPER,
        DeveloperContent.new().with_instructions("Talk like a pirate!")
    ),
    Message.from_role_and_content(Role.USER, "Arrr, how be you?"),
])
tokens = enc.render_conversation_for_completion(convo, Role.ASSISTANT)
print(tokens)
# Later, after the model responded …
parsed = enc.parse_messages_from_completion_tokens(tokens, role=Role.ASSISTANT)
print(parsed)


### Rust Example

rust
use openai_harmony::chat::{Message, Role, Conversation};
use openai_harmony::{HarmonyEncodingName, load_harmony_encoding};

fn main() -> anyhow::Result<()> {
    let enc = load_harmony_encoding(HarmonyEncodingName::HarmonyGptOss)?;
    let convo =
        Conversation::from_messages([Message::from_role_and_content(Role::User, "Hello there!")]);
    let tokens = enc.render_conversation_for_completion(&convo, Role::Assistant, None)?;
    println!("{:?}", tokens);
    Ok(())
}


## Why Use Harmony?

Harmony offers several compelling advantages for developers working with `gpt-oss` models:

*   **Consistent formatting**: A shared implementation for both rendering and parsing ensures token-sequences remain loss-free, maintaining data integrity.
*   **Blazing fast performance**: The core logic, built in Rust, provides high performance for demanding applications.
*   **First-class Python support**: Enjoy seamless integration with Python projects, including easy installation via `pip`, comprehensive typed stubs, and 100% test parity with the Rust suite.

## Links

Explore Harmony and related resources further:

*   **GitHub Repository**: [openai/harmony](https://github.com/openai/harmony)
*   **Try `gpt-oss`**: [gpt-oss.com](https://gpt-oss.com)
*   **Learn more about `gpt-oss`**: [OpenAI Cookbook](https://cookbook.openai.com/topic/gpt-oss)
*   **`gpt-oss` Model Card**: [OpenAI](https://openai.com/index/gpt-oss-model-card/)
*   **Learn more about the `harmony` format**: [OpenAI Cookbook](https://cookbook.openai.com/articles/openai-harmony)