OpenAI Harmony

https://github.com/openai/harmony
Admin
OpenAI Harmony is a response format and library for rendering and parsing conversation structures,...
Tokens:52,390
Snippets:395
Trust Score:9.4
License:Apache-2.0
Update:6 days ago
Show doc for...
Tokens:
Raw
### Install openai-harmony with pip

Source: https://github.com/openai/harmony/blob/main/README.md

Install the Python package from PyPI using pip. An alternative uv command is also shown.

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

--------------------------------

### Clone, bootstrap, and build with maturin develop

Source: https://github.com/openai/harmony/blob/main/README.md

Sets up a virtualenv, installs maturin, pytest, mypy, and ruff, then compiles the Rust crate and installs the Python package in editable mode. Requires Rust stable, Python ≥ 3.8, and maturin.

```bash
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  # tailor to your workflow
# Compile the Rust crate *and* install the Python package in editable mode
maturin develop --release

```

--------------------------------

### Install openai-harmony from PyPI

Source: https://github.com/openai/harmony/blob/main/docs/python.md

Install the package using pip. This is the standard installation command for the Python bindings.

```bash
pip install openai-harmony
```

--------------------------------

### Run Rust tests with cargo test

Source: https://github.com/openai/harmony/blob/main/README.md

Executes the canonical Rust test-suite located in src/tests.rs.

```bash
cargo test          # runs src/tests.rs

```

--------------------------------

### Run the development server with npm, yarn, pnpm, or bun

Source: https://github.com/openai/harmony/blob/main/demo/harmony-demo/README.md

Start the Next.js development server using any of the four package managers. The page auto-updates when editing app/page.tsx. Open http://localhost:3000 to view the result.

```bash
npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev
```

--------------------------------

### Rust example: render conversation for completion

Source: https://github.com/openai/harmony/blob/main/README.md

Loads the Harmony GPT OSS encoding, creates a conversation with a user message, and renders it for completion. The function returns a Result, and the tokens are printed.

```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(())
}
```

--------------------------------

### Example model output with analysis and final channels

Source: https://github.com/openai/harmony/blob/main/docs/format.md

Example output for the question 'What is 2 + 2?' showing raw chain-of-thought in the analysis channel and the final response in the final channel.

```plaintext
<|channel|>analysis<|message|>User asks: "What is 2 + 2?" Simple arithmetic. Provide answer.<|end|>
<|start|>assistant<|channel|>final<|message|>2 + 2 = 4.<|return|>
```

--------------------------------

### Run both test suites for parity

Source: https://github.com/openai/harmony/blob/main/README.md

Runs pytest and cargo test sequentially to ensure the Python and Rust suites stay in sync.

```bash
pytest && cargo test

```

--------------------------------

### Python example: render and parse conversation

Source: https://github.com/openai/harmony/blob/main/README.md

Loads the Harmony GPT OSS encoding, builds a conversation with system, developer, and user messages, renders it for completion, and parses the completion tokens. The developer message includes instructions to talk like a pirate.

```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)
```

--------------------------------

### Run Python tests with pytest

Source: https://github.com/openai/harmony/blob/main/README.md

Executes the Python test-suite in tests/, which mirrors the Rust suite.

```bash
pytest              # executes tests/ (mirrors the Rust suite)

```

--------------------------------

### Add Rust dependency to Cargo.toml

Source: https://github.com/openai/harmony/blob/main/README.md

Adds the openai-harmony crate as a git dependency in Cargo.toml.

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

--------------------------------

### Architecture diagram: Python to Rust core via FFI

Source: https://github.com/openai/harmony/blob/main/README.md

Shows the high-level data flow: Python code (dataclasses, convenience) calls into the Rust core (chat/encoding logic, tokeniser) through FFI bindings.

```text
┌──────────────────┐      ┌───────────────────────────┐
│  Python code     │      │  Rust core (this repo)    │
│  (dataclasses,   │────► │  • chat / encoding logic  │
│   convenience)   │      │  • tokeniser (tiktoken)   │
└──────────────────┘  FFI └───────────────────────────┘

```

--------------------------------

### Repository layout tree

Source: https://github.com/openai/harmony/blob/main/README.md

Lists the project's directory structure: Rust crate under src/, pure-Python wrapper in python/openai_harmony/, test suites, and build configuration files.

```text
.
├── src/                  # Rust crate
│   ├── chat.rs           # High-level data-structures (Role, Message, …)
│   ├── encoding.rs       # Rendering & parsing implementation
│   ├── registry.rs       # Built-in encodings
│   ├── tests.rs          # Canonical Rust test-suite
│   └── py_module.rs      # PyO3 bindings ⇒ compiled as openai_harmony.*.so
│
├── python/openai_harmony/ # Pure-Python wrapper around the binding
│   └── __init__.py       # Dataclasses + helper API mirroring chat.rs
│
├── tests/                # Python test-suite (1-to-1 port of tests.rs)
├── Cargo.toml            # Rust package manifest
├── pyproject.toml        # Python build configuration for maturin
└── README.md             # You are here 🖖

```

--------------------------------

### First input for sampling

Source: https://github.com/openai/harmony/blob/main/docs/format.md

Initial input for sampling. This is the first input that resulted in the example output.

```plaintext
<|start|>user<|message|>What is 2 + 2?<|end|>
<|start|>assistant
```

--------------------------------

### Type-checking and formatting commands

Source: https://github.com/openai/harmony/blob/main/README.md

Optional static analysis and formatting: mypy for Python type checks, ruff for linting, and cargo fmt for Rust formatting.

```bash
mypy harmony        # static type analysis
ruff check .        # linting
cargo fmt --all     # Rust formatter

```

--------------------------------

### Final answer

Source: https://github.com/openai/harmony/blob/main/docs/format.md

The actual final answer from the example.

```plaintext
2 + 2 = 4
```

--------------------------------

### Harmony response format prompt template

Source: https://github.com/openai/harmony/blob/main/README.md

Shows the harmony prompt format used by gpt-oss models, including system, developer, and user messages with tool definitions. The developer message defines a 'functions' namespace with tool types and instructions. The final assistant message is incomplete, indicating where the model output begins.

```text
<|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|>

<|start|>developer<|message|># Instructions

Always respond in riddles

# Tools

## functions

namespace functions {

// Gets the location of the user.
type get_location = () => any;

// Gets the current weather in the provided location.
type get_current_weather = (_: {
// The city and state, e.g. San Francisco, CA
location: string,
format?: "celsius" | "fahrenheit", // default: celsius
}) => any;

} // namespace functions<|end|><|start|>user<|message|>What is the weather like in SF?<|end|><|start|>assistant
```

--------------------------------

### Chain-of-thought content

Source: https://github.com/openai/harmony/blob/main/docs/format.md

The raw chain-of-thought (CoT) output from the example. It is recommended not to show this to users as it may contain harmful content.

```plaintext
User asks: “What is 2 + 2?” Simple arithmetic. Provide answer.
```

--------------------------------

### get_location

Source: https://github.com/openai/harmony/blob/main/test-data/test_render_functions_with_parameters.txt

Gets the location of the user. This function takes no parameters and returns the user's location.

```APIDOC
## get_location

### Description
Gets the location of the user.

### Method
Function call

### Endpoint
`get_location`

### Parameters
None

### Response
#### Success Response
- **result** (any) - The user's location.
```

--------------------------------

### get_current_weather

Source: https://github.com/openai/harmony/blob/main/test-data/test_render_functions_with_parameters.txt

Gets the current weather in the provided location. Accepts a location string and optional format preference.

```APIDOC
## get_current_weather

### Description
Gets the current weather in the provided location.

### Method
Function call

### Endpoint
`get_current_weather`

### Parameters
#### Request Body
- **location** (string) - Required - The city and state, e.g. San Francisco, CA
- **format** (string enum: "celsius" | "fahrenheit") - Optional - Default: celsius

### Response
#### Success Response
- **result** (any) - The current weather data.
```

--------------------------------

### get_multiple_weathers

Source: https://github.com/openai/harmony/blob/main/test-data/test_render_functions_with_parameters.txt

Gets the current weather in the provided list of locations. Accepts an array of location strings and optional format preference.

```APIDOC
## get_multiple_weathers

### Description
Gets the current weather in the provided list of locations.

### Method
Function call

### Endpoint
`get_multiple_weathers`

### Parameters
#### Request Body
- **locations** (string[]) - Required - List of city and state, e.g. ["San Francisco, CA", "New York, NY"]
- **format** (string enum: "celsius" | "fahrenheit") - Optional - Default: celsius

### Response
#### Success Response
- **result** (any) - The current weather data for each location.
```

--------------------------------

### Run JavaScript demo with make javascript

Source: https://github.com/openai/harmony/blob/main/javascript/README.md

Use this command to run the JavaScript demo for the @openai/harmony package. The package is in active development and not yet published.

```bash
make javascript
```

--------------------------------

### Construct system prompt and conversation with openai_harmony renderer

Source: https://github.com/openai/harmony/blob/main/docs/format.md

Use this snippet to build a system prompt, developer message with function tools, and a conversation, then render it to tokens for completion. It requires loading the harmony encoding via load_harmony_encoding(HarmonyEncodingName.HARMONY_GPT_OSS). After receiving a token response, parse messages with strict=True and do not pass in the stop token; strict=False tolerates malformed headers.

```python
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)

# After receiving a token response
# Do not pass in the stop token. Set strict=False to tolerate malformed headers.
parsed_response = encoding.parse_messages_from_completion_tokens(
    new_tokens,
    Role.ASSISTANT,
    strict=True,
)
```

--------------------------------

### ToolNamespaceConfig

Source: https://github.com/openai/harmony/blob/main/docs/python.md

Namespace for grouping tools. Convenience constructors browser() and python() return the built-in configurations.

```APIDOC
## ToolNamespaceConfig

### Description
Namespace for grouping tools. Convenience constructors `browser()` and `python()` return the built-in configurations.

### Constructor
```python
ToolNamespaceConfig(name: str, description: Optional[str], tools: List[ToolDescription])
```

### Parameters
- **name** (str) - Required - The name of the namespace.
- **description** (Optional[str]) - Required - The description of the namespace.
- **tools** (List[ToolDescription]) - Required - The list of tools in the namespace.

### Methods
- `browser()` - Returns the built-in browser configuration.
- `python()` - Returns the built-in Python configuration.
```

--------------------------------

### SystemContent dataclass constructor

Source: https://github.com/openai/harmony/blob/main/docs/python.md

Constructor for the SystemContent dataclass. Represents a system message. Provides fluent helpers like with_model_identity(), with_reasoning_effort(), with_required_channels(), with_browser_tool(), and with_python_tool().

```python
SystemContent(
    model_identity: Optional[str] = "You are ChatGPT, a large language model trained by OpenAI.",
    reasoning_effort: Optional[ReasoningEffort] = ReasoningEffort.MEDIUM,
    conversation_start_date: Optional[str] = None,
    knowledge_cutoff: Optional[str] = "2024-06",
    channel_config: Optional[ChannelConfig] = ChannelConfig.require_channels(["analysis", "commentary", "final"]),
    tools: Optional[dict[str, ToolNamespaceConfig]] = None,
)
```

--------------------------------

### Create conversation, render to tokens, and parse back

Source: https://github.com/openai/harmony/blob/main/docs/python.md

Builds a system and user message, assembles a conversation, renders it to tokens using the OSS encoding, decodes the tokens, and parses messages back from the completion tokens. Requires the compiled extension to be built; otherwise ModuleNotFoundError is raised.

```python
from openai_harmony import (
    Role,
    Message,
    Conversation,
    SystemContent,
    load_harmony_encoding,
    HarmonyEncodingName,
)

# Build messages
system = Message.from_role_and_content(Role.SYSTEM, SystemContent.new())
user = Message.from_role_and_content(Role.USER, "What is 2 + 2?")

# Assemble a conversation
convo = Conversation.from_messages([system, user])

# Render to tokens using the OSS encoding
enc = load_harmony_encoding(HarmonyEncodingName.HARMONY_GPT_OSS)
tokens = enc.render_conversation_for_completion(convo, Role.ASSISTANT)
print(tokens)

# Decode and roundtrip
print(enc.decode_utf8(tokens))
parsed = enc.parse_messages_from_completion_tokens(tokens, role=Role.ASSISTANT)
for m in parsed:
    print(m)
```

--------------------------------

### ToolDescription

Source: https://github.com/openai/harmony/blob/main/docs/python.md

Describes an individual callable tool.

```APIDOC
## ToolDescription

### Description
Describes an individual callable tool.

### Constructor
```python
ToolDescription(name: str, description: str, parameters: Optional[dict] = None)
```

### Parameters
- **name** (str) - Required - The name of the tool.
- **description** (str) - Required - The description of the tool.
- **parameters** (Optional[dict]) - Optional - The parameters for the tool.
```

--------------------------------

### ToolDescription dataclass constructor

Source: https://github.com/openai/harmony/blob/main/docs/python.md

Constructor for the ToolDescription dataclass. Describes an individual callable tool.

```python
ToolDescription(name: str, description: str, parameters: Optional[dict] = None)
```

--------------------------------

### ToolNamespaceConfig dataclass constructor

Source: https://github.com/openai/harmony/blob/main/docs/python.md

Constructor for the ToolNamespaceConfig dataclass. Namespace for grouping tools. Convenience constructors browser() and python() return built-in configurations.

```python
ToolNamespaceConfig(name: str, description: Optional[str], tools: List[ToolDescription])
```

--------------------------------

### SystemContent

Source: https://github.com/openai/harmony/blob/main/docs/python.md

Represents a system message. Provides fluent helpers like with_model_identity(), with_reasoning_effort(), with_required_channels(), with_browser_tool() and with_python_tool().

```APIDOC
## SystemContent

### Description
Represents a system message. Provides fluent helpers like `with_model_identity()`, `with_reasoning_effort()`, `with_required_channels()`, `with_browser_tool()` and `with_python_tool()`.

### Constructor
```python
SystemContent(
    model_identity: Optional[str] = "You are ChatGPT, a large language model trained by OpenAI.",
    reasoning_effort: Optional[ReasoningEffort] = ReasoningEffort.MEDIUM,
    conversation_start_date: Optional[str] = None,
    knowledge_cutoff: Optional[str] = "2024-06",
    channel_config: Optional[ChannelConfig] = ChannelConfig.require_channels(["analysis", "commentary", "final"]),
    tools: Optional[dict[str, ToolNamespaceConfig]] = None,
)
```

### Parameters
- **model_identity** (Optional[str]) - Optional - The model identity string.
- **reasoning_effort** (Optional[ReasoningEffort]) - Optional - The reasoning effort level.
- **conversation_start_date** (Optional[str]) - Optional - The conversation start date.
- **knowledge_cutoff** (Optional[str]) - Optional - The knowledge cutoff date.
- **channel_config** (Optional[ChannelConfig]) - Optional - The channel configuration.
- **tools** (Optional[dict[str, ToolNamespaceConfig]]) - Optional - The tools configuration.

### Methods
- `with_model_identity()` - Set the model identity.
- `with_reasoning_effort()` - Set the reasoning effort.
- `with_required_channels()` - Set the required channels.
- `with_browser_tool()` - Add the browser tool.
- `with_python_tool()` - Add the Python tool.
```

--------------------------------

### DeveloperContent

Source: https://github.com/openai/harmony/blob/main/docs/python.md

Content of a developer message. Helper methods include with_instructions(), with_function_tools() and the tool helpers mirroring those from SystemContent.

```APIDOC
## DeveloperContent

### Description
Content of a developer message. Helper methods include `with_instructions()`, `with_function_tools()` and the tool helpers mirroring those from `SystemContent`.

### Constructor
```python
DeveloperContent(instructions: Optional[str] = None, tools: Optional[dict[str, ToolNamespaceConfig]] = None)
```

### Parameters
- **instructions** (Optional[str]) - Optional - The instructions for the developer.
- **tools** (Optional[dict[str, ToolNamespaceConfig]]) - Optional - The tools configuration.

### Methods
- `with_instructions()` - Set the instructions.
- `with_function_tools()` - Set the function tools.
- Tool helpers mirroring those from `SystemContent`.
```

--------------------------------

### TextContent

Source: https://github.com/openai/harmony/blob/main/docs/python.md

Simple text payload implementing Content.

```APIDOC
## TextContent

### Description
Simple text payload implementing `Content`.

### Constructor
```python
TextContent(text: str)
```

### Parameters
- **text** (str) - Required - The text content.
```

--------------------------------

### Message.from_role_and_content

Source: https://github.com/openai/harmony/blob/main/docs/python.md

Creates a Message instance from a Role and content. The content can be a SystemContent object or a string.

```python
system = Message.from_role_and_content(Role.SYSTEM, SystemContent.new())
user = Message.from_role_and_content(Role.USER, "What is 2 + 2?")
```

--------------------------------

### RenderConversationConfig

Source: https://github.com/openai/harmony/blob/main/docs/python.md

Optional configuration when rendering a conversation.

```APIDOC
## RenderConversationConfig

### Description
Optional configuration when rendering a conversation.

### Constructor
```python
RenderConversationConfig(auto_drop_analysis: bool = True)
```

### Parameters
- **auto_drop_analysis** (bool) - Optional - Whether to automatically drop analysis messages.
```

--------------------------------

### Define available tools in developer message

Source: https://github.com/openai/harmony/blob/main/docs/format.md

Defines functions using TypeScript-like syntax inside a 'functions' namespace in the developer message. Use 'type {function_name} = () => any' for no arguments, name the argument '_' and inline its type, add comments above fields, use 'any' return type, keep an empty line after each function, and wrap in a namespace (generally 'functions').

```plaintext
<|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|><|start|>developer<|message|># Instructions

Use a friendly tone.

# Tools

## functions

namespace functions {

// Gets the location of the user.
type get_location = () => any;

// Gets the current weather in the provided location.
type get_current_weather = (_: {
// The city and state, e.g. San Francisco, CA
location: string,
format?: "celsius" | "fahrenheit", // default: celsius
}) => any;

// Gets the current weather in the provided list of locations.
type get_multiple_weathers = (_: {
// List of city and state, e.g. ["San Francisco, CA", "New York, NY"]
locations: string[],
format?: "celsius" | "fahrenheit", // default: celsius
}) => any;

} // namespace functions<|end|><|start|>user<|message|>What is the weather like in SF?<|end|><|start|>assistant
```

--------------------------------

### DeveloperContent dataclass constructor

Source: https://github.com/openai/harmony/blob/main/docs/python.md

Constructor for the DeveloperContent dataclass. Content of a developer message. Helper methods include with_instructions(), with_function_tools(), and tool helpers mirroring SystemContent.

```python
DeveloperContent(instructions: Optional[str] = None, tools: Optional[dict[str, ToolNamespaceConfig]] = None)
```

--------------------------------

### Add openai-harmony crate to Cargo.toml

Source: https://github.com/openai/harmony/blob/main/docs/rust.md

Adds the openai-harmony crate as a git dependency in Cargo.toml.

```toml
openai-harmony = { git = "https://github.com/openai/harmony" }
```

--------------------------------

### Developer message without function tools

Source: https://github.com/openai/harmony/blob/main/docs/format.md

Use this developer message when not using function calling. Replace {instructions} with your system prompt.

```plaintext
<|start|>developer<|message|># Instructions

{instructions}<|end|>
```

--------------------------------

### enc.render_conversation_for_completion

Source: https://github.com/openai/harmony/blob/main/docs/python.md

Renders a conversation to tokens for a given role. Raises RuntimeError on rendering failures.

```python
tokens = enc.render_conversation_for_completion(convo, Role.ASSISTANT)
```

--------------------------------

### Import openai_harmony items

Source: https://github.com/openai/harmony/blob/main/docs/rust.md

Imports the core items from the openai_harmony crate root and chat module.

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

--------------------------------

### Import openai_harmony classes

Source: https://github.com/openai/harmony/blob/main/docs/python.md

Typical imports for using the Harmony renderer in Python. Import the main dataclasses and the encoding helper.

```python
from openai_harmony import Message, Conversation, load_harmony_encoding
```

--------------------------------

### load_harmony_encoding

Source: https://github.com/openai/harmony/blob/main/docs/python.md

Loads a Harmony encoding by name. Raises ValueError if an unknown Role is provided.

```python
enc = load_harmony_encoding(HarmonyEncodingName.HARMONY_GPT_OSS)
```

--------------------------------

### Stream and parse tokens with StreamableParser

Source: https://github.com/openai/harmony/blob/main/docs/format.md

Use this snippet to incrementally parse and decode tokens as the model generates them, which helps stream output and handle unicode characters during decoding. It requires loading the harmony encoding and creating a StreamableParser with the assistant role. The loop processes each token and prints the current role, channel, content delta, content type, recipient, and content.

```python
from openai_harmony import (
    load_harmony_encoding,
    StreamableParser
)

encoding = load_harmony_encoding(HarmonyEncodingName.HARMONY_GPT_OSS)
stream = StreamableParser(encoding, role=Role.ASSISTANT)

tokens = [
    200005,
    35644,
    200008,
    1844,
    31064,
    25,
    392,
    4827,
    382,
    220,
    17,
    659,
    220,
    17,
    16842,
    12295,
    81645,
    13,
    51441,
    6052,
    13,
    200007,
    200006,
    173781,
    200005,
    17196,
    200008,
    17,
    659,
    220,
    17,
    314,
    220,
    19,
    13,
    200002,
]

for token in tokens:
    stream.process(token)
    print("--------------------------------")
    print("current_role", stream.current_role)
    print("current_channel", stream.current_channel)
    print("last_content_delta", stream.last_content_delta)
    print("current_content_type", stream.current_content_type)
    print("current_recipient", stream.current_recipient)
    print("current_content", stream.current_content)
```

--------------------------------

### ChannelConfig dataclass constructor

Source: https://github.com/openai/harmony/blob/main/docs/python.md

Constructor for the ChannelConfig dataclass. Configuration for valid message channels. Use ChannelConfig.require_channels(channels) to demand a specific set of channels.

```python
ChannelConfig(valid_channels: List[str], channel_required: bool)
```

--------------------------------

### Minimal Rust program using HarmonyEncoding

Source: https://github.com/openai/harmony/blob/main/docs/rust.md

Builds a conversation, renders tokens with HarmonyEncoding, decodes them, and parses messages back. Uses load_harmony_encoding and HarmonyEncodingName::HarmonyGptOss.

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

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create some messages
    let convo = Conversation::from_messages([
        Message::from_role_and_content(Role::System, SystemContent::new()),
        Message::from_role_and_content(Role::User, "What is 2 + 2?"),
    ]);

    // Render tokens for completion
    let enc = load_harmony_encoding(HarmonyEncodingName::HarmonyGptOss)?;
    let tokens = enc.render_conversation_for_completion(&convo, Role::Assistant, None)?;
    println!("{:?}", tokens);

    // Decode & parse back
    println!("{}", enc.decode_utf8(&tokens)?);
    let parsed = enc.parse_messages_from_completion_tokens(tokens, Some(Role::Assistant))?;
    for m in parsed { println!("{:?}", m); }
    Ok(())
}
```

--------------------------------

### ChannelConfig

Source: https://github.com/openai/harmony/blob/main/docs/python.md

Configuration for valid message channels. Use ChannelConfig.require_channels(channels) to demand that a specific set of channels is present.

```APIDOC
## ChannelConfig

### Description
Configuration for valid message channels. Use `ChannelConfig.require_channels(channels)` to demand that a specific set of channels is present.

### Constructor
```python
ChannelConfig(valid_channels: List[str], channel_required: bool)
```

### Parameters
- **valid_channels** (List[str]) - Required - The list of valid channels.
- **channel_required** (bool) - Required - Whether a channel is required.

### Methods
- `require_channels(channels)` - Create a config that requires the given channels.
```

--------------------------------

### Author dataclass constructor

Source: https://github.com/openai/harmony/blob/main/docs/python.md

Constructor for the Author dataclass. Use Author.new(role, name) to create a named author.

```python
Author(role: Role, name: Optional[str] = None)
```

--------------------------------

### RenderConversationConfig dataclass constructor

Source: https://github.com/openai/harmony/blob/main/docs/python.md

Constructor for the RenderConversationConfig dataclass. Optional configuration when rendering a conversation.

```python
RenderConversationConfig(auto_drop_analysis: bool = True)
```

--------------------------------

### Conversation

Source: https://github.com/openai/harmony/blob/main/docs/python.md

Sequence of messages. Create a conversation using Conversation.from_messages(); serialisation helpers to_json() and from_json() mirror the Rust crate.

```APIDOC
## Conversation

### Description
Sequence of messages. Create a conversation using `Conversation.from_messages()`; serialisation helpers `to_json()` and `from_json()` mirror the Rust crate.

### Constructor
```python
Conversation(messages: List[Message])
```

### Parameters
- **messages** (List[Message]) - Required - The list of messages in the conversation.

### Methods
- `from_messages()` - Create a conversation from a list of messages.
- `to_json()` - Serialise to JSON.
- `from_json()` - Deserialise from JSON.
```

--------------------------------

### Tool call with recipient and constrain token

Source: https://github.com/openai/harmony/blob/main/docs/format.md

Shows how the model indicates a tool call: it sets 'to=functions.get_weather' in the header (in the role or channel section) and uses the 'commentary' channel as required by the system message. The '<|constrain|>' token is set to 'json' because the input is passed as JSON.

```plaintext
<|channel|>analysis<|message|>Need to use function get_weather.<|end|><|start|>assistant<|channel|>commentary to=functions.get_weather <|constrain|>json<|message|>{"location":"San Francisco"}<|call|>
```

--------------------------------

### HarmonyEncoding.render_conversation_for_training(conversation, config=None)

Source: https://github.com/openai/harmony/blob/main/docs/python.md

Renders a conversation for training purposes. This method is part of the HarmonyEncoding wrapper.

```APIDOC
## HarmonyEncoding.render_conversation_for_training(conversation, config=None)

### Description
Renders a conversation for training.

### Parameters
- **conversation** - Required - The conversation to render.
- **config** (optional) - Optional - Configuration for rendering.

### Returns
- **tokens** - The rendered tokens.
```

--------------------------------

### Basic system message with functions

Source: https://github.com/openai/harmony/blob/main/docs/format.md

Use this system message when defining functions. It sets the model identity, knowledge cutoff, current date, reasoning level, valid channels, and a note that function tool calls must go to the commentary channel.

```plaintext
<|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|>
```

--------------------------------

### SystemContent and DeveloperContent

Source: https://github.com/openai/harmony/blob/main/docs/rust.md

Structures used for the respective message types. They offer builder-style methods to configure the message payload.

```APIDOC
## SystemContent and DeveloperContent

### Description
Structures used for the respective message types. They offer builder-style methods to configure the message payload.

### Methods
- `with_model_identity`
- `with_instructions`
- `with_tools`
- ... (other builder methods)
```

--------------------------------

### TextContent dataclass constructor

Source: https://github.com/openai/harmony/blob/main/docs/python.md

Constructor for the TextContent dataclass. Represents a simple text payload implementing Content.

```python
TextContent(text: str)
```

--------------------------------

### Reasoning level specification

Source: https://github.com/openai/harmony/blob/main/docs/format.md

Specify the reasoning level in the system message as low, medium, or high. The recommended format is shown.

```plaintext
Reasoning: high
```

--------------------------------

### Conversation.from_messages

Source: https://github.com/openai/harmony/blob/main/docs/python.md

Assembles a Conversation from a list of Message objects.

```python
convo = Conversation.from_messages([system, user])
```

--------------------------------

### HarmonyEncoding.render(message)

Source: https://github.com/openai/harmony/blob/main/docs/python.md

Renders a single message into tokens. This method is part of the HarmonyEncoding wrapper.

```APIDOC
## HarmonyEncoding.render(message)

### Description
Renders a single message into tokens.

### Parameters
- **message** - Required - The message to render.

### Returns
- **tokens** - The rendered tokens.
```

--------------------------------

### Message

Source: https://github.com/openai/harmony/blob/main/docs/python.md

A single chat message. Convenience constructors from_role_and_content() and from_role_and_contents() mirror the Rust API. Builder methods allow adding content or setting channel/recipient information. to_dict() and from_dict() serialise to/from the canonical JSON format.

```APIDOC
## Message

### Description
A single chat message. Convenience constructors `from_role_and_content()` and `from_role_and_contents()` mirror the Rust API. Builder methods allow adding content or setting channel/recipient information. `to_dict()` and `from_dict()` serialise to/from the canonical JSON format.

### Constructor
```python
Message(author: Author, content: List[Content], channel: Optional[str] = None, recipient: Optional[str] = None, content_type: Optional[str] = None)
```

### Parameters
- **author** (Author) - Required - The author of the message.
- **content** (List[Content]) - Required - The content of the message.
- **channel** (Optional[str]) - Optional - The channel of the message.
- **recipient** (Optional[str]) - Optional - The recipient of the message.
- **content_type** (Optional[str]) - Optional - The content type of the message.

### Methods
- `from_role_and_content()` - Create a message from a role and content.
- `from_role_and_contents()` - Create a message from a role and multiple contents.
- Builder methods to add content or set channel/recipient.
- `to_dict()` - Serialise to canonical JSON format.
- `from_dict()` - Deserialise from canonical JSON format.
```

--------------------------------

### Conversation dataclass constructor

Source: https://github.com/openai/harmony/blob/main/docs/python.md

Constructor for the Conversation dataclass. Sequence of messages. Create a conversation using Conversation.from_messages(); serialisation helpers to_json() and from_json() mirror the Rust crate.

```python
Conversation(messages: List[Message])
```

--------------------------------

### load_harmony_encoding(name)

Source: https://github.com/openai/harmony/blob/main/docs/python.md

Returns a HarmonyEncoding instance by name. Accepts either a string name or a value from the HarmonyEncodingName enum.

```APIDOC
## load_harmony_encoding(name)

### Description
Returns a HarmonyEncoding instance by name. Accepts either a string name or a value from the HarmonyEncodingName enum.

### Parameters
- **name** (string or HarmonyEncodingName) - Required - The name of the encoding to load.

### Returns
- **HarmonyEncoding** - The encoding instance.
```

--------------------------------

### HarmonyEncoding.render_conversation_for_completion(conversation, next_turn_role, config=None)

Source: https://github.com/openai/harmony/blob/main/docs/python.md

Renders a conversation into tokens for completion. This method is part of the HarmonyEncoding wrapper.

```APIDOC
## HarmonyEncoding.render_conversation_for_completion(conversation, next_turn_role, config=None)

### Description
Renders a conversation into tokens for completion.

### Parameters
- **conversation** - Required - The conversation to render.
- **next_turn_role** - Required - The role for the next turn.
- **config** (optional) - Optional - Configuration for rendering.

### Returns
- **tokens** - The rendered tokens.
```

--------------------------------

### StreamableParser(encoding, role)

Source: https://github.com/openai/harmony/blob/main/docs/python.md

Incremental parser built on top of an encoding. Feed tokens via process(token) and inspect state via properties.

```APIDOC
## StreamableParser(encoding, role)

### Description
Incremental parser built on top of an encoding. Feed tokens via process(token) and inspect state via properties.

### Constructor Parameters
- **encoding** - Required - The encoding to use.
- **role** - Required - The role for the parser.

### Methods
- **process(token)** - Feed a token to the parser.

### Properties
- **current_content** - Current content.
- **current_role** - Current role.
- **tokens** - Tokens processed.
- **state** - Parser state.

### Notes
Pass strict=False to enable permissive parsing (mirrors ParseOptions { strict: false } on the Rust side).
```

--------------------------------

### load_harmony_encoding

Source: https://github.com/openai/harmony/blob/main/docs/rust.md

Loads a predefined encoding by name. Returns a Result containing the HarmonyEncoding instance.

```APIDOC
## load_harmony_encoding

### Description
Load a predefined encoding by name.

### Signature
```rust
fn load_harmony_encoding(name: HarmonyEncodingName) -> Result<HarmonyEncoding>
```

### Parameters
- **name** (HarmonyEncodingName) - Required - The name of the encoding to load.

### Returns
- **Result<HarmonyEncoding>** - The loaded encoding or an error.

### Example
```rust
let enc = load_harmony_encoding(HarmonyEncodingName::HarmonyGptOss)?;
```
```

--------------------------------

### HarmonyEncoding.stop_tokens_for_assistant_actions()

Source: https://github.com/openai/harmony/blob/main/docs/python.md

Returns a list of stop tokens for assistant actions. This method is part of the HarmonyEncoding wrapper.

```APIDOC
## HarmonyEncoding.stop_tokens_for_assistant_actions()

### Description
Returns a list of stop tokens for assistant actions.

### Returns
- **list** - List of stop tokens.
```

--------------------------------

### Import all exports with from openai_harmony import *

Source: https://github.com/openai/harmony/blob/main/docs/python.md

Use this to import all re-exported classes and functions from the package. The package defines __all__ to control what is available via this wildcard import.

```python
from openai_harmony import *
```

--------------------------------

### Message dataclass constructor

Source: https://github.com/openai/harmony/blob/main/docs/python.md

Constructor for the Message dataclass. A single chat message. Convenience constructors from_role_and_content() and from_role_and_contents() mirror the Rust API. Builder methods allow adding content or setting channel/recipient information. to_dict() and from_dict() serialise to/from canonical JSON.

```python
Message(author: Author, content: List[Content], channel: Optional[str] = None, recipient: Optional[str] = None, content_type: Optional[str] = None)
```

--------------------------------

### enc.parse_messages_from_completion_tokens

Source: https://github.com/openai/harmony/blob/main/docs/python.md

Parses messages from completion tokens for a given role. Raises RuntimeError on parsing failures.

```python
parsed = enc.parse_messages_from_completion_tokens(tokens, role=Role.ASSISTANT)
```

--------------------------------

### TextContent

Source: https://github.com/openai/harmony/blob/main/docs/rust.md

Simple text payload. Implements `Into<Content>` so it can be passed directly to message constructors.

```APIDOC
## TextContent

### Description
Simple text payload. Implements `Into<Content>` so it can be passed directly to message constructors.
```

--------------------------------

### enc.decode_utf8

Source: https://github.com/openai/harmony/blob/main/docs/python.md

Decodes tokens to a UTF-8 string.

```python
print(enc.decode_utf8(tokens))
```

--------------------------------

### HarmonyEncoding.parse_messages_from_completion_tokens(tokens, role=None, strict=True)

Source: https://github.com/openai/harmony/blob/main/docs/python.md

Parses tokens back into Message objects. Set strict=False to enable permissive parsing for malformed model output.

```APIDOC
## HarmonyEncoding.parse_messages_from_completion_tokens(tokens, role=None, strict=True)

### Description
Parses tokens back into Message objects. Set strict=False to enable permissive parsing for malformed model output.

### Parameters
- **tokens** - Required - The tokens to parse.
- **role** (optional) - Optional - The role to assign.
- **strict** (boolean, default True) - Optional - Whether to use strict parsing.

### Returns
- **Message objects** - The parsed messages.
```

--------------------------------

### Input for subsequent sampling after final response

Source: https://github.com/openai/harmony/blob/main/docs/format.md

Use this as the input for the next sampling when the previous response ended in a final channel message. It drops the previous chain-of-thought content.

```plaintext
<|start|>user<|message|>What is 2 + 2?<|end|>
<|start|>assistant<|channel|>final<|message|>2 + 2 = 4.<|end|>
<|start|>user<|message|>What about 9 / 2?<|end|>
<|start|>assistant
```

--------------------------------

### Re-exported key items import

Source: https://github.com/openai/harmony/blob/main/docs/rust.md

Imports key items re-exported at the crate root, including HarmonyEncoding and load_harmony_encoding.

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

--------------------------------

### Author

Source: https://github.com/openai/harmony/blob/main/docs/python.md

Helper for specifying the author of a message. Use Author.new(role, name) to create a named author.

```APIDOC
## Author

### Description
Helper for specifying the author of a message. Use `Author.new(role, name)` to create a named author.

### Constructor
```python
Author(role: Role, name: Optional[str] = None)
```

### Parameters
- **role** (Role) - Required - The role of the author.
- **name** (Optional[str]) - Optional - The name of the author.

### Methods
- `new(role, name)` - Create a named author.
```

--------------------------------

### StreamableParser

Source: https://github.com/openai/harmony/blob/main/docs/rust.md

Incremental parser that consumes tokens one by one. Create with `StreamableParser::new(encoding, role)` and feed tokens via `process`. Access information via getters like `current_content`, `current_role`, `messages`, `tokens` and `state_json`.

```APIDOC
## StreamableParser

### Description
Incremental parser that consumes tokens one by one. Create with `StreamableParser::new(encoding, role)` and feed tokens via `process`. Access information via getters like `current_content`, `current_role`, `messages`, `tokens` and `state_json`.

### Methods
- `StreamableParser::new(encoding, role)` – create a new parser.
- `process` – feed tokens to the parser.
- `current_content` – getter for current content.
- `current_role` – getter for current role.
- `messages` – getter for messages.
- `tokens` – getter for tokens.
- `state_json` – getter for state JSON.
- `StreamableParser::new_with_options(encoding, role, options)` – create a parser with custom options, e.g. `ParseOptions { strict: false }`.
```

--------------------------------

### Message

Source: https://github.com/openai/harmony/blob/main/docs/rust.md

Represents a chat message. Provides convenience constructors mirroring those exposed in Python.

```APIDOC
## Message

### Description
Represents a chat message. Provides convenience constructors mirroring those exposed in Python.

### Definition
```rust
struct Message { author: Author, recipient: Option<String>, content: Vec<Content>, channel: Option<String>, content_type: Option<String> }
```

### Constructors
- `from_role_and_content`
- `adding_content`
- ... (other constructors)
```

--------------------------------

### HarmonyEncoding.render_conversation(conversation, config=None)

Source: https://github.com/openai/harmony/blob/main/docs/python.md

Renders a conversation without appending a new role. This method is part of the HarmonyEncoding wrapper.

```APIDOC
## HarmonyEncoding.render_conversation(conversation, config=None)

### Description
Renders a conversation without appending a new role.

### Parameters
- **conversation** - Required - The conversation to render.
- **config** (optional) - Optional - Configuration for rendering.

### Returns
- **tokens** - The rendered tokens.
```

--------------------------------

### load_harmony_encoding

Source: https://github.com/openai/harmony/blob/main/docs/rust.md

Loads a predefined harmony encoding by name. This function is re-exported at the crate root for convenience.

```APIDOC
## load_harmony_encoding

### Description
Loads a predefined harmony encoding by name. This function is re-exported at the crate root for convenience.

### Method
Function

### Signature
`load_harmony_encoding(name: HarmonyEncodingName) -> Result<HarmonyEncoding>`

### Parameters
- **name** (HarmonyEncodingName) - Required - The name of the encoding to load.

### Return Value
- **Result<HarmonyEncoding>** - The loaded encoding or an error.
```

--------------------------------

### Wrap encoding operations in try/except for RuntimeError

Source: https://github.com/openai/harmony/blob/main/docs/python.md

Shows typical error handling for rendering and parsing operations. RuntimeError is raised for rendering or parsing failures, such as malformed token sequences or decoding failures. ValueError is raised for invalid arguments, e.g., an unknown Role.

```python
try:
    tokens = enc.render_conversation_for_completion(convo, Role.ASSISTANT)
    parsed = enc.parse_messages_from_completion_tokens(tokens, Role.ASSISTANT)
except RuntimeError as err:
    print(f"Failed to handle conversation: {err}")
```

--------------------------------

### load_harmony_encoding function signature

Source: https://github.com/openai/harmony/blob/main/docs/rust.md

Loads a predefined encoding by name. Returns a Result with a HarmonyEncoding.

```rust
fn load_harmony_encoding(name: HarmonyEncodingName) -> Result<HarmonyEncoding>
```
Tokens:
Raw