{"id":2144,"library":"openai-harmony","title":"OpenAI Harmony","description":"OpenAI Harmony is a Python library providing a renderer for OpenAI's 'Harmony' response format, specifically designed for its open-weight model series, gpt-oss. It enables structured conversations, reasoning output, and function calls, mimicking the OpenAI Responses API. The library, with a Rust core and Python bindings, ensures consistent formatting, efficient processing, and first-class Python support, including typed stubs. It is crucial for developers building inference solutions for gpt-oss models, as these models are trained on and require the Harmony format for correct operation.","status":"active","version":"0.0.8","language":"en","source_language":"en","source_url":"https://github.com/openai/harmony","tags":["openai","LLM","response-format","gpt-oss","AI","Rust-backed"],"install":[{"cmd":"pip install openai-harmony","lang":"bash","label":"Install from PyPI"}],"dependencies":[],"imports":[{"symbol":"load_harmony_encoding","correct":"from openai_harmony import load_harmony_encoding"},{"symbol":"HarmonyEncodingName","correct":"from openai_harmony import HarmonyEncodingName"},{"symbol":"Role","correct":"from openai_harmony import Role"},{"symbol":"Message","correct":"from openai_harmony import Message"},{"symbol":"Conversation","correct":"from openai_harmony import Conversation"},{"symbol":"DeveloperContent","correct":"from openai_harmony import DeveloperContent"},{"symbol":"SystemContent","correct":"from openai_harmony import SystemContent"}],"quickstart":{"code":"from openai_harmony import (\n    load_harmony_encoding,\n    HarmonyEncodingName,\n    Role,\n    Message,\n    Conversation,\n    DeveloperContent,\n    SystemContent,\n)\n\n# Load the Harmony encoding for GPT-OSS models\nenc = load_harmony_encoding(HarmonyEncodingName.HARMONY_GPT_OSS)\n\n# Create a conversation with system, developer instructions, and a user message\nconvo = Conversation.from_messages([\n    Message.from_role_and_content(\n        Role.SYSTEM,\n        SystemContent.new(),\n    ),\n    Message.from_role_and_content(\n        Role.DEVELOPER,\n        DeveloperContent.new().with_instructions(\"Talk like a pirate!\")\n    ),\n    Message.from_role_and_content(Role.USER, \"Arrr, how be you?\"),\n])\n\n# Render the conversation into tokens for completion. This generates the prompt.\ntokens_for_model = enc.render_conversation_for_completion(convo, Role.ASSISTANT)\nprint(\"Prompt Tokens (to send to model):\", tokens_for_model)\n\n# --- Simulate a model response ---\n# In a real scenario, `tokens_for_model` would be sent to a gpt-oss model,\n# and the model would generate a continuation. For this quickstart, we'll\n# append a sample assistant response to the prompt tokens.\nmodel_raw_completion = tokens_for_model + \"<|start|>assistant<|message|>Ahoy there, matey! I be shipshape and Bristol fashion. <|end|>\"\n\n# Parse the model's raw completion back into structured messages\nparsed_messages = enc.parse_messages_from_completion_tokens(model_raw_completion, role=Role.ASSISTANT)\n\nprint(\"\\nParsed Messages (including original prompt and simulated response):\")\nfor msg in parsed_messages:\n    # Accessing content might depend on the content type (e.g., TextContent, DeveloperContent)\n    content_value = msg.content.text if hasattr(msg.content, 'text') else str(msg.content)\n    print(f\"Role: {msg.role.name}, Content: {content_value}\")","lang":"python","description":"This quickstart demonstrates how to load the Harmony encoding, construct a conversation using various roles, render it into the token format expected by gpt-oss models, and then parse a simulated model's completion back into structured messages."},"warnings":[{"fix":"Always use the `openai-harmony` library to construct and parse prompts and completions when working with gpt-oss models. Do not manually construct the prompt strings.","message":"The `openai-harmony` format is mandatory for OpenAI's gpt-oss series models. These models were specifically trained on this format and will not function correctly or reliably if it is not used.","severity":"breaking","affected_versions":"All versions with gpt-oss models"},{"fix":"Ensure your application logic explicitly filters and only displays messages from the 'final' or 'commentary' channels to end-users, or apply strict content moderation to any 'analysis' channel output if it must be used for debugging.","message":"The 'analysis' channel, used by gpt-oss models for internal chain-of-thought reasoning, is not safety-filtered. Content from this channel should *never* be shown directly to end-users as it may contain harmful or unrefined outputs.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Refer to the official documentation and quickstart examples to ensure correct import paths and proper usage of `Role` and content types when building conversations.","message":"Common mistakes include incorrect role mapping (e.g., mapping 'system' to `Role.DEVELOPER`) or missing essential imports (`SystemContent`, `Message`, etc.) when constructing Harmony templates, leading to runtime errors or unexpected model behavior.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Monitor for updates from OpenAI regarding this specific issue. If encountering this, consider using an older, compatible version of the OpenAI SDK or carefully handling the raw response to attempt manual parsing if absolutely necessary, while awaiting a fix.","message":"When using Harmony-based GPT-5 models, some users have reported receiving malformed JSON outputs (concatenation of multiple JSONs) when interacting with OpenAI SDK versions >= 1.100.2, particularly when using `client.beta.chat.completions.parse` with `response_format`.","severity":"breaking","affected_versions":"SDK versions >= 1.100.2 (when interacting with GPT-5 models)"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}