{"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.","language":"python","status":"active","last_verified":"Wed May 13","install":{"commands":["pip install openai-harmony"],"cli":null},"imports":["from openai_harmony import load_harmony_encoding","from openai_harmony import HarmonyEncodingName","from openai_harmony import Role","from openai_harmony import Message","from openai_harmony import Conversation","from openai_harmony import DeveloperContent","from openai_harmony import SystemContent"],"auth":{"required":false,"env_vars":[]},"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.","tag":null,"tag_description":null,"last_tested":"2026-04-25","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]},"compatibility":{"tag":null,"tag_description":null,"last_tested":"2026-05-13","installed_version":"0.0.8","pypi_latest":"0.0.8","is_stale":false,"summary":{"python_range":"3.10–3.9","success_rate":100,"avg_install_s":3.3,"avg_import_s":0.6,"wheel_type":"wheel"},"results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"openai-harmony","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.43,"mem_mb":11.3,"disk_size":"35.8M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"openai-harmony","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.62,"mem_mb":11.3,"disk_size":"35.8M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"openai-harmony","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":3.8,"import_time_s":0.29,"mem_mb":11.3,"disk_size":"35M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"openai-harmony","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.37,"mem_mb":11.3,"disk_size":"35M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"openai-harmony","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.67,"mem_mb":12.6,"disk_size":"38.4M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"openai-harmony","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.93,"mem_mb":12.6,"disk_size":"38.4M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"openai-harmony","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":3,"import_time_s":0.59,"mem_mb":12.6,"disk_size":"38M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"openai-harmony","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.84,"mem_mb":12.6,"disk_size":"38M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"openai-harmony","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.8,"mem_mb":12.4,"disk_size":"30.2M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"openai-harmony","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.99,"mem_mb":12.4,"disk_size":"30.2M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"openai-harmony","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":2.5,"import_time_s":0.82,"mem_mb":12.4,"disk_size":"30M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"openai-harmony","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.13,"mem_mb":12.4,"disk_size":"30M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"openai-harmony","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.39,"mem_mb":8.7,"disk_size":"29.9M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"openai-harmony","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.46,"mem_mb":8.7,"disk_size":"29.8M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"openai-harmony","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":2.7,"import_time_s":0.37,"mem_mb":8.7,"disk_size":"29M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"openai-harmony","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.52,"mem_mb":8.7,"disk_size":"29M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"openai-harmony","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.36,"mem_mb":10.4,"disk_size":"35.3M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"openai-harmony","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.58,"mem_mb":10.4,"disk_size":"35.3M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"openai-harmony","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":4.5,"import_time_s":0.4,"mem_mb":10.4,"disk_size":"35M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"openai-harmony","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.44,"mem_mb":10.4,"disk_size":"35M"}]}}