repository·main·Indexed 25 days ago
https://github.com/openai/harmonyA response format designed for the gpt-oss open-weight model series. It provides a structured way to handle conversation flows, reasoning (chain of thought), and tool/function calling across multiple channels (final, analysis, and commentary). The library is available for Python and Rust, offering tools to render conversations for model input and parse completion tokens back into structured messages.
The package installs a module named openai_harmony. You can import specific dataclasses and helpers, or use a wildcard import to access all exported members.
Typical imports:
from openai_harmony import Message, Conversation, load_harmony_encodingOr import everything:
from openai_harmony import *To develop the library locally, you must have a stable Rust toolchain, Python ≥ 3.8, and maturin installed.
pip install maturin pytest mypy ruff.maturin develop --release.git clone https://github.com/openai/harmony.git
cd harmony
# Create & activate a virtualenv
python -m venv .venv
source .venv/bin/activate
# Install maturin and test dependencies
pip install maturin pytest mypy ruff
# Compile the Rust crate *and* install the Python package in editable mode
maturin develop --releaseInstall the openai-harmony package from PyPI using pip to access the Harmony renderer in Python via PyO3 bindings.
pip install openai-harmonyAdd the crate to your Cargo.toml using the git repository and import the necessary modules for chat and encoding functionality.
openai-harmony = { git = "https://github.com/openai/harmony" }use openai_harmony::{load_harmony_encoding, HarmonyEncodingName};
use openai_harmony::chat::{Message, Role, Conversation};The openai_harmony library (available via PyPI or crates.io) is the recommended way to handle message rendering and tokenization. It automates the conversion of structured messages into the specific prompt format required by gpt-oss models.
Key components include:
load_harmony_encoding: Loads the specific encoding (e.g., HarmonyEncodingName.HARMONY_GPT_OSS).Conversation: A container for a sequence of Message objects.SystemContent & DeveloperContent: Specialized content types for system and developer roles.Message.from_role_and_content: Creates messages with specific roles and content..with_channel(): Assigns a channel (final, analysis, or commentary) to an assistant message..with_recipient(): Specifies the target of a message (e.g., a function name or assistant).from openai_harmony import (
Author,
Conversation,
DeveloperContent,
HarmonyEncodingName,
Message,
Role,
SystemContent,
ToolDescription,
load_harmony_encoding,
ReasoningEffort
)
encoding = load_harmony_encoding(HarmonyEncodingName.HARMONY_GPT_OSS)
system_message = (
SystemContent.new()
.with_reasoning_effort(ReasoningEffort.HIGH)
.with_conversation_start_date("2025-06-28")
)
developer_message = (
DeveloperContent.new()
.with_instructions("Always respond in riddles")
.with_function_tools(
[
ToolDescription.new(
"get_current_weather",
"Gets the current weather in the provided location.",
parameters={
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA",
},
"format": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"default": "celsius",
},
},
"required": ["location"],
},
),
]
)
)
convo = Conversation.from_messages(
[
Message.from_role_and_content(Role.SYSTEM, system_message),
Message.from_role_and_content(Role.DEVELOPER, developer_message),
Message.from_role_and_content(Role.USER, "What is the weather in Tokyo?"),
Message.from_role_and_content(
Role.ASSISTANT,
'User asks: "What is the weather in Tokyo?" We need to use get_weather tool.',
).with_channel("analysis"),
Message.from_role_and_content(Role.ASSISTANT, '{"location": "Tokyo"}')
.with_channel("commentary")
.with_recipient("functions.get_weather")
.with_content_type("<|constrain|> json"),
Message.from_author_and_content(
Author.new(Role.TOOL, "functions.lookup_weather"),
'{ "temperature": 20, "sunny": true }',
)
.with_channel("commentary")
.with_recipient("assistant"),
]
)
tokens = encoding.render_conversation_for_completion(convo, Role.ASSISTANT)Install the openai-harmony package from PyPI to use the Harmony response format in Python applications. This package includes typed stubs and high-performance Rust bindings.
pip install openai-harmony
# or if you are using uv
uv pip install openai-harmonyThe system message defines model identity, meta dates, reasoning effort, available channels, and built-in tools.
Key requirements:
You are ChatGPT, a large language model trained by OpenAI.low, medium, or high using the format Reasoning: <level>.# Valid channels: analysis, commentary, final. Channel must be included for every message.commentary channel.<|start|>system<|message|>You are ChatGPT, a large language model trained by OpenAI.
Knowledge cutoff: 2024-06
Current date: 2025-06-28
Reasoning: high
# Valid channels: analysis, commentary, final. Channel must be included for every message.
Calls to these tools must go to the commentary channel: 'functions'.<|end|>To start the harmony-demo project locally, use one of the following package manager commands to run the development server. Once running, open http://localhost:3000 in your browser to view the application.
npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun devAdd openai-harmony as a dependency in your Cargo.toml to use the core Rust implementation of the Harmony format.
[dependencies]
openai-harmony = { git = "https://github.com/openai/harmony" }@openai/harmony package is currently in active development and is not yet published to a package registry. To run the project for demonstration purposes, use the make javascript command.make javascriptA message follows the structure: <|start|>{header}<|message|>{content}<|end|>.
In a chat conversation, the model may output multiple messages (e.g., chain-of-thought in the analysis channel) separated by <|end|>. The model stops inference when it emits <|return|> (done with final answer) or <|call|> (needs a tool call).
Important Implementation Note: When adding an assistant's reply to conversation history for the next turn, replace the trailing <|return|> with <|end|> to ensure the message is fully formed. Prior messages in prompts should always end with <|end|>.
### Example input<|start|>user<|message|>What is 2 + 2?<|end|> <|start|>assistant
### Example output<|channel|>analysis<|message|>User asks: "What is 2 + 2?" Simple arithmetic. Provide answer.<|end|> <|start|>assistant<|channel|>final<|message|>2 + 2 = 4.<|return|>
Most functions return anyhow::Result<T>. Common error sources include:
LoadError: Occurs when loading encodings.RenderFormattingTokenError: Occurs during rendering.You can propagate errors using the ? operator or match on underlying error kinds via anyhow::Error for specific handling.