openai-harmony

What it is and what it does

OpenAI Harmony is a Python library that encodes and decodes conversations in the Harmony response format, a structured format designed for OpenAI's open-weight gpt-oss models. The format enables models to output to multiple channels (analysis, commentary, final), handle chain-of-thought reasoning, and structure function calls with tool namespaces. The library wraps a Rust core via PyO3 bindings for performance, exposing a pure-Python API with dataclasses and helper functions.

You use it when building inference solutions that directly invoke gpt-oss models and need to format prompts and parse responses according to the Harmony specification. If you're using gpt-oss through an API provider (HuggingFace, Ollama, vLLM), the provider handles formatting and you don't need this library. The library depends only on Pydantic and aims to keep token sequences loss-free during rendering and parsing.

Use it for:

• Format multi-turn conversations with system, developer, and user roles for direct gpt-oss inference.
• Parse structured model outputs including reasoning, commentary, and function calls from gpt-oss completions.
• Define tool namespaces and function signatures in a format gpt-oss expects for reliable tool calling.
• Encode conversations for token counting and prompt optimization before sending to a gpt-oss model.
• Build a custom inference pipeline that requires explicit control over prompt and response formatting.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Renders and parses the Harmony response format used by OpenAI's gpt-oss models, enabling structured conversation handling, reasoning output, and function calls in Python.

Yes, if you are building a custom inference solution directly using gpt-oss models and need to handle the Harmony format yourself. No, if you are using gpt-oss through a managed API or inference provider—they handle formatting transparently. Caution: the package is aging (282 days since last release) and license terms are unclear; verify both before committing to production use.

Install

openai-harmony on PyPI

pip install openai-harmony

uv add openai-harmony

poetry add openai-harmony

Installing openai-harmony

Before you install

Medium install friction due to compiled Rust bindings; prebuilt wheels cover common platforms (x86_64, ARM, i686, ppc64le on Linux/macOS/Windows). Package is aging—last release was 282 days ago—so expect limited active maintenance.

License in practice

License status is unclear; no SPDX identifier or raw license text is available in the metadata. Verify the actual license terms before using in proprietary or restricted contexts.

Quickstart

pip install openai-harmony

from openai_harmony import (
    load_harmony_encoding,
    HarmonyEncodingName,
    Role,
    Message,
    Conversation,
    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.USER, "Hello"),
])
tokens = enc.render_conversation_for_completion(convo, Role.ASSISTANT)

Requires Python ≥3.8; compiled Rust extension must be available for your platform (wheels provided for common architectures).

Verify before relying

• Whether the package is actively maintained or in maintenance-only mode (282 days since last release, status marked 'aging').
• Actual license terms and any restrictions on commercial or derivative use.
• Whether the harmony format is stable or subject to breaking changes in future gpt-oss model releases.

Package facts

Evidence: openai_harmony-0.0.8-cp38-abi3-macosx_11_0_arm64.whl; openai_harmony-0.0.8-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl; openai_harmony-0.0.8-cp38-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl; openai_harmony-0.0.8-cp38-abi3-manylinux_2_17_i686.manylinux2014_i686.whl; openai_harmony-0.0.8-cp38-abi3-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl; openai_harmony-0.0.8-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl; openai_harmony-0.0.8-cp38-abi3-musllinux_1_2_aarch64.whl; openai_harmony-0.0.8-cp38-abi3-musllinux_1_2_armv7l.whl; openai_harmony-0.0.8-cp38-abi3-musllinux_1_2_i686.whl; openai_harmony-0.0.8-cp38-abi3-musllinux_1_2_x86_64.whl; openai_harmony-0.0.8-cp38-abi3-win32.whl; openai_harmony-0.0.8-cp38-abi3-win_amd64.whl

Tags

More Artificial Intelligence packages