### Install openai-harmony with uv

Source: https://context7.com/openai/harmony/llms.txt

Install the openai-harmony package using uv, a fast Python package installer. This is an alternative to pip.

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

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

### Install openai-harmony Package

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

Install the openai-harmony package using pip. This is the first step to using the Harmony renderer in Python.

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

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

### Install openai-harmony Python Package

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

Install the openai-harmony library using pip or uv. This library provides tools for working with the Harmony response format.

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

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

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

### Harmony Prompt Format Example

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

This is an example of the Harmony response format, including system, developer, and user messages. It demonstrates how to specify reasoning channels and tool calls.

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

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

### Python Example: Render and Parse Conversation

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

This Python example demonstrates how to load a Harmony encoding, create a conversation with system, developer, and user messages, render it into completion tokens, and then parse tokens back into messages.

```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 Development Server

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

Use these commands to start the Next.js development server. Open http://localhost:3000 in your browser to view the application.

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

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

### Shopping List Schema Example

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

Example of a developer message defining a JSON schema for a shopping list.

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

You are a helpful shopping assistant

# Response Formats

Reasoning: high

{"properties":{"items":{"type":"array","description":"entries on the shopping list","items":{"type":"string"}}},"type":"object"}<|end|><|start|>user<|message|>I need to buy coffee, soda and eggs<|end|><|start|>assistant
```

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

### Chat Conversation Input Example

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

A basic chat input sequence starting with a user message and initiating an assistant response.

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

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

### Rust Example: Load Encoding and Render Conversation

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

This Rust example shows how to load a Harmony encoding and render a simple user conversation into completion tokens. Ensure you have the 'openai-harmony' dependency added to your Cargo.toml.

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

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

### Clone and Bootstrap Harmony Project

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

Steps to clone the repository, set up a virtual environment, install dependencies, and compile the Rust crate with Python bindings in editable mode.

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

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

### Initialize StreamableParser

Source: https://context7.com/openai/harmony/llms.txt

Provides an example of initializing a StreamableParser for incremental processing of tokens as they stream from the model. This is useful for real-time applications.

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

encoding = load_harmony_encoding(HarmonyEncodingName.HARMONY_GPT_OSS)

# Create a streaming parser
parser = StreamableParser(encoding, role=Role.ASSISTANT)
```

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

### Chat Conversation Output Example

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

An example of the model outputting chain-of-thought analysis followed by a final answer.

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

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

### Example Rendered Conversation

Source: https://context7.com/openai/harmony/llms.txt

A sample of how a conversation appears when rendered with special tokens.

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

Be helpful and concise.

# Tools

## functions

namespace functions {

// Gets the current weather.
type get_weather = (_: {
// The city name
location: string,
}) => any;

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

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

### Streaming and Parsing Tokens with StreamableParser

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

This example shows how to use the StreamableParser to process a sequence of tokens, decoding them as they arrive. It's useful for streaming output and handling Unicode characters during decoding. The parser provides real-time updates on the current role, channel, 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)

```

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

### GET /functions/get_multiple_weathers

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

Retrieves the current weather for a list of locations.

```APIDOC
## GET /functions/get_multiple_weathers

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

### Method
GET

### Endpoint
/functions/get_multiple_weathers

### Parameters
#### Query Parameters
- **locations** (array) - Required - List of city and state, e.g. ["San Francisco, CA", "New York, NY"]
- **format** (string) - Optional - celsius or fahrenheit (default: celsius)
```

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

### Create System Content

Source: https://context7.com/openai/harmony/llms.txt

Creates system message content, configuring model identity, reasoning effort, knowledge cutoff, conversation start date, required channels, and built-in tools. You can also use default system content.

```python
from openai_harmony import SystemContent, ReasoningEffort

# Create a fully configured system content
system_content = (
    SystemContent.new()
    .with_model_identity("You are ChatGPT, a large language model trained by OpenAI.")
    .with_reasoning_effort(ReasoningEffort.HIGH)
    .with_knowledge_cutoff("2024-06")
    .with_conversation_start_date("2025-06-28")
    .with_required_channels(["analysis", "commentary", "final"])
    .with_browser_tool()  # Add built-in browser tool
    .with_python_tool()   # Add built-in Python tool
)

# Use default system content (medium reasoning, standard identity)
default_system = SystemContent.new()
```

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

### Get Multiple Weathers

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

Retrieves the current weather for a list of specified locations.

```APIDOC
## GET /functions/get_multiple_weathers

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

### Method
GET

### Endpoint
/functions/get_multiple_weathers

### Parameters
#### Query Parameters
- **locations** (string[]) - Required - List of city and state, e.g. ["San Francisco, CA", "New York, NY"]
- **format** (string) - Optional - The temperature format, can be "celsius" or "fahrenheit". Defaults to "celsius".

### Request Example
None (parameters are passed as query parameters)

### Response
#### Success Response (200)
- **any** - Weather information for the specified locations.

#### Response Example
```json
{
  "San Francisco, CA": {
    "sunny": true,
    "temperature": 20,
    "format": "celsius"
  },
  "New York, NY": {
    "sunny": false,
    "temperature": 15,
    "format": "celsius"
  }
}
```
```

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

### Get User Location

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

Retrieves the current location of the user.

```APIDOC
## GET /functions/get_location

### Description
Gets the location of the user.

### Method
GET

### Endpoint
/functions/get_location

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **any** - The user's location information.

#### Response Example
```json
{
  "city": "San Francisco",
  "state": "CA"
}
```
```

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

### Get Stop Tokens

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

Retrieve the list of stop tokens used by the tokenizer. Also provides stop tokens specifically for assistant actions.

```python
stop_tokens()
```

```python
stop_tokens_for_assistant_actions()
```

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

### Run demo build for @openai/harmony

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

Executes the make command to build the project for demonstration purposes.

```bash
make javascript
```

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

### Create and Serialize Messages

Source: https://context7.com/openai/harmony/llms.txt

Demonstrates creating different types of messages, including user, assistant with channel, tool calls, and tool responses. Shows serialization to dictionary and JSON formats.

```python
from openai_harmony import Message, Role, Author

# Create a simple user message
user_message = Message.from_role_and_content(Role.USER, "What is the weather in Tokyo?")

# Create an assistant message with channel
assistant_cot = (
    Message.from_role_and_content(
        Role.ASSISTANT,
        "User asks about weather in Tokyo. Need to call weather tool."
    )
    .with_channel("analysis")
)

# Create a tool call message with recipient and content type
tool_call = (
    Message.from_role_and_content(Role.ASSISTANT, '{"location": "Tokyo"}')
    .with_channel("commentary")
    .with_recipient("functions.get_weather")
    .with_content_type("<|constrain|>json")
)

# Create a tool response message
tool_response = (
    Message.from_author_and_content(
        Author.new(Role.TOOL, "functions.get_weather"),
        '{"temperature": 20, "sunny": true}'
    )
    .with_channel("commentary")
    .with_recipient("assistant")
)

# Serialize to dict or JSON
message_dict = user_message.to_dict()
message_json = user_message.to_json()

# Deserialize from dict
restored_message = Message.from_dict(message_dict)
```

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

### Preamble Action Plan

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

Shows how the model communicates an action plan to the user via the commentary channel before executing multiple tool calls.

```text
<|channel|>analysis<|message|>{long chain of thought}<|end|><|start|>assistant<|channel|>commentary<|message|>**Action plan**:
1. Generate an HTML file
2. Generate a JavaScript for the Node.js server
3. Start the server
---
Will start executing the plan step by step<|end|><|start|>assistant<|channel|>commentary to=functions.generate_file<|constrain|>json<|message|>{"template": "basic_html", "path": "index.html"}<|call|>
```

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

### GET /functions/get_current_weather

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

Retrieves the current weather for a specific location.

```APIDOC
## GET /functions/get_current_weather

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

### Method
GET

### Endpoint
/functions/get_current_weather

### Parameters
#### Query Parameters
- **location** (string) - Required - The city and state, e.g. San Francisco, CA
- **format** (string) - Optional - celsius or fahrenheit (default: celsius)
```

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

### Get Current Weather

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

Retrieves the current weather for a specified location.

```APIDOC
## GET /functions/get_current_weather

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

### Method
GET

### Endpoint
/functions/get_current_weather

### Parameters
#### Query Parameters
- **location** (string) - Required - The city and state, e.g. San Francisco, CA
- **format** (string) - Optional - The temperature format, can be "celsius" or "fahrenheit". Defaults to "celsius".

### Request Example
None (parameters are passed as query parameters)

### Response
#### Success Response (200)
- **any** - Weather information for the specified location.

#### Response Example
```json
{
  "sunny": true,
  "temperature": 20,
  "format": "celsius"
}
```
```

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

### Create and Render Conversation to Tokens

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

Build a conversation with system and user messages, render it to tokens using the OSS encoding, and print the resulting tokens.

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

```

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

### Build and Serialize Conversation

Source: https://context7.com/openai/harmony/llms.txt

Shows how to construct a conversation from a list of messages, including system and developer content with specific configurations. Demonstrates serialization to JSON and deserialization from JSON.

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

# Build a complete conversation
conversation = Conversation.from_messages([
    Message.from_role_and_content(
        Role.SYSTEM,
        SystemContent.new().with_reasoning_effort(ReasoningEffort.HIGH)
    ),
    Message.from_role_and_content(
        Role.DEVELOPER,
        DeveloperContent.new().with_instructions("Be concise and helpful.")
    ),
    Message.from_role_and_content(Role.USER, "What is 2 + 2?"),
])

# Serialize to JSON
json_str = conversation.to_json()

# Deserialize from JSON
restored = Conversation.from_json(json_str)

# Iterate over messages
for message in conversation:
    print(f"{message.author.role}: {message.content}")
```

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

### Execute Function Call

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

Demonstrates the interaction pattern for calling a function with JSON arguments.

```text
<|start|>assistant<|channel|>commentary to=functions.get_weather <|constrain|>json<|message|>{"location":"San Francisco"}<|call|>
```

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

### Create Developer Content with Tools

Source: https://context7.com/openai/harmony/llms.txt

Creates developer message content, including instructions and function tool definitions. Tools can be defined with names, descriptions, and parameters.

```python
from openai_harmony import DeveloperContent, ToolDescription

# Create developer content with instructions and tools
developer_content = (
    DeveloperContent.new()
    .with_instructions("Always respond in riddles. Be helpful but mysterious.")
    .with_function_tools([
        ToolDescription.new(
            "get_location",
            "Gets the location of the user.",
        ),
        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"],
            },
        ),
    ])
)
```

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

### Define System Content Configuration

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

Configure the system message, including model identity, reasoning effort, and channel settings. Fluent helpers allow easy modification of these settings.

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

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

### Import Core Items

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

Import necessary items from the openai-harmony crate for chat and encoding functionalities.

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

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

### Perform Type-Checking and Formatting

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

Commands for static type analysis using `mypy`, linting with `ruff`, and formatting Rust code with `cargo fmt`.

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

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

### Build and process a conversation in Rust

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

Demonstrates the full lifecycle of creating a conversation, rendering it into tokens using HarmonyEncoding, and parsing the tokens back into messages.

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

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

### Run Rust Tests

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

Command to execute the canonical Rust test suite located in `src/tests.rs`.

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

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

### Run Python Tests

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

Command to execute the Python test suite located in the `tests/` directory, which mirrors the Rust test suite.

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

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

### Respond with Tool Call Output

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

After handling a tool call, provide the output back to the model using a new tool message. The format includes the tool name, `to=assistant`, the `commentary` channel, and the output in the message.

```plaintext
<|start|>functions.get_weather to=assistant<|channel|>commentary<|message|>{"sunny": true, "temperature": 20}<|end|>
```

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

### Constructing a Conversation with OpenAI Harmony

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

Use this snippet to build a conversation object with system, developer, user, and assistant messages, including tool descriptions and channel information. It demonstrates loading a specific encoding and rendering the conversation for completion.

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

```

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

### Import Core openai-harmony Components

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

Import essential classes and functions from the openai_harmony library. These are commonly used for message and conversation handling.

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

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

### Run Both Test Suites

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

Combines Python and Rust test execution to ensure parity between the two language implementations.

```bash
pytest && cargo test
```

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

### Define Tool Namespace Configuration

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

Group multiple ToolDescription objects under a common namespace. Convenience constructors like browser() and python() provide built-in configurations.

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

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

### Parse Model Output Tokens to Messages

Source: https://context7.com/openai/harmony/llms.txt

Demonstrates parsing model output tokens back into Message objects. Shows how to handle both strict and permissive parsing of potentially malformed output.

```python
from openai_harmony import (
    load_harmony_encoding, Role, HarmonyEncodingName
)

encoding = load_harmony_encoding(HarmonyEncodingName.HARMONY_GPT_OSS)

# Example: tokens from model output (chain-of-thought + final answer)
model_output_text = (
    '<|channel|>analysis<|message|>User asks: "What is 2 + 2?" '
    'Simple arithmetic. Provide answer.<|end|>'
    '<|start|>assistant<|channel|>final<|message|>2 + 2 = 4.<|return|>' 
)
tokens = encoding.encode(model_output_text, allowed_special="all")

# Parse tokens into messages
messages = encoding.parse_messages_from_completion_tokens(tokens, role=Role.ASSISTANT)

for msg in messages:
    print(f"Channel: {msg.channel}, Content: {msg.content[0].text}")
# Output:
# Channel: analysis, Content: User asks: "What is 2 + 2?" Simple arithmetic. Provide answer.
# Channel: final, Content: 2 + 2 = 4.

# Use strict=False for permissive parsing of malformed output
messages = encoding.parse_messages_from_completion_tokens(
    tokens, role=Role.ASSISTANT, strict=False
)
```

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

### DeveloperContent Builder

Source: https://context7.com/openai/harmony/llms.txt

Creates developer message content with instructions (system prompt) and function tool definitions.

```APIDOC
## DeveloperContent Builder

Creates developer message content with instructions (system prompt) and function tool definitions.

### Method
N/A (Class Method)

### Endpoint
N/A (Class Method)

### Parameters
#### Builder Methods
- **new()**: Initializes a new DeveloperContent builder.
- **with_instructions(instructions: str)**: Sets the developer instructions (system prompt).
- **with_function_tools(tools: list[ToolDescription])**: Adds a list of function tool descriptions.

### Request Example
```python
from openai_harmony import DeveloperContent, ToolDescription

# Create developer content with instructions and tools
developer_content = (
    DeveloperContent.new()
    .with_instructions("Always respond in riddles. Be helpful but mysterious.")
    .with_function_tools([
        ToolDescription.new(
            "get_location",
            "Gets the location of the user.",
        ),
        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"],
            },
        ),
    ])
)
```

### Response
#### Success Response (Object)
- **developer_content** (object) - A configured DeveloperContent object.

#### Response Example
```python
# The developer_content object can be used when creating a Message
print(developer_content)
```
```

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

### SystemContent Builder

Source: https://context7.com/openai/harmony/llms.txt

Creates system message content with model identity, reasoning effort, dates, and built-in tools configuration.

```APIDOC
## SystemContent Builder

Creates system message content with model identity, reasoning effort, dates, and built-in tools configuration.

### Method
N/A (Class Method)

### Endpoint
N/A (Class Method)

### Parameters
#### Builder Methods
- **new()**: Initializes a new SystemContent builder.
- **with_model_identity(identity: str)**: Sets the model's identity.
- **with_reasoning_effort(effort: ReasoningEffort)**: Sets the reasoning effort level.
- **with_knowledge_cutoff(date: str)**: Sets the knowledge cutoff date.
- **with_conversation_start_date(date: str)**: Sets the conversation start date.
- **with_required_channels(channels: list[str])**: Specifies the required channels.
- **with_browser_tool()**: Adds the built-in browser tool.
- **with_python_tool()**: Adds the built-in Python tool.

### Request Example
```python
from openai_harmony import SystemContent, ReasoningEffort

# Create a fully configured system content
system_content = (
    SystemContent.new()
    .with_model_identity("You are ChatGPT, a large language model trained by OpenAI.")
    .with_reasoning_effort(ReasoningEffort.HIGH)
    .with_knowledge_cutoff("2024-06")
    .with_conversation_start_date("2025-06-28")
    .with_required_channels(["analysis", "commentary", "final"])
    .with_browser_tool()  # Add built-in browser tool
    .with_python_tool()   # Add built-in Python tool
)

# Use default system content (medium reasoning, standard identity)
default_system = SystemContent.new()
```

### Response
#### Success Response (Object)
- **system_content** (object) - A configured SystemContent object.

#### Response Example
```python
# The system_content object can be used when creating a Message
print(system_content)
```
```

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

### Import All Harmony Exports

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

Import all available classes from the openai_harmony package for easy access.

```python
from openai_harmony import *

```

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

### Render Conversation for Model Inference

Source: https://context7.com/openai/harmony/llms.txt

Illustrates rendering a conversation into tokens suitable for model inference, including appending a role header for the next turn. Shows how to preserve chain-of-thought by configuring the rendering process.

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

encoding = load_harmony_encoding(HarmonyEncodingName.HARMONY_GPT_OSS)

conversation = Conversation.from_messages([
    Message.from_role_and_content(
        Role.SYSTEM,
        SystemContent.new().with_conversation_start_date("2025-06-28")
    ),
    Message.from_role_and_content(
        Role.DEVELOPER,
        DeveloperContent.new().with_instructions("Answer concisely.")
    ),
    Message.from_role_and_content(Role.USER, "What is 2 + 2?"),
])

# Render for completion (auto-drops previous analysis by default)
tokens = encoding.render_conversation_for_completion(conversation, Role.ASSISTANT)
print(f"Token count: {len(tokens)}")

# Decode to see the formatted prompt
prompt_text = encoding.decode_utf8(tokens)
print(prompt_text)
# Output:
# <|start|>system<|message|>You are ChatGPT, a large language model trained by OpenAI.
# Knowledge cutoff: 2024-06
# Current date: 2025-06-28
# ...
# <|start|>user<|message|>What is 2 + 2?<|end|><|start|>assistant

# Preserve chain-of-thought in multi-turn conversations
config = RenderConversationConfig(auto_drop_analysis=False)
tokens_with_cot = encoding.render_conversation_for_completion(
    conversation, Role.ASSISTANT, config
)
```

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

### POST /functions/kitchensink

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

A utility function demonstrating various complex parameter schemas.

```APIDOC
## POST /functions/kitchensink

### Description
A function with various complex schemas.

### Method
POST

### Endpoint
/functions/kitchensink

### Parameters
#### Request Body
- **string** (string) - Optional - A string
- **string_nullable** (string) - Optional - A nullable string (default: "the default")
- **string_enum** (string) - Optional - "a" | "b" | "c"
- **oneof_string_or_number** (string|number) - Optional - A oneof (default: 20)
```

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

### Render Conversation for Training

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

Render a conversation into tokens for model training. Accepts the conversation and optional configuration.

```python
render_conversation_for_training(conversation, config=None)
```

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

### Define Channel Configuration

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

Configure valid message channels and whether a channel is required. Use ChannelConfig.require_channels() to enforce specific channels.

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

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

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

Source: https://context7.com/openai/harmony/llms.txt

Add the openai-harmony library as a dependency in your Rust project's Cargo.toml file. This specifies the Git repository as the source.

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

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

### Browser Tool System Prompt

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

Template for adding the browser tool definition to the system message.

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

# Tools
```

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

### Render Conversation for Completion

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

Render a conversation into tokens suitable for model completion. Requires the conversation, the role of the next turn, and optional configuration.

```python
render_conversation_for_completion(conversation, next_turn_role, config=None)
```

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

### Manage conversation function calling flow

Source: https://context7.com/openai/harmony/llms.txt

Build a conversation, render it for completion, parse model tool calls, and inject tool responses back into the conversation.

```python
from openai_harmony import (
    load_harmony_encoding, Conversation, Message, Role, Author,
    SystemContent, DeveloperContent, ToolDescription, HarmonyEncodingName,
    ReasoningEffort, RenderConversationConfig
)

encoding = load_harmony_encoding(HarmonyEncodingName.HARMONY_GPT_OSS)

# Step 1: Build initial conversation with function tools
system = (
    SystemContent.new()
    .with_reasoning_effort(ReasoningEffort.HIGH)
    .with_conversation_start_date("2025-06-28")
)

developer = (
    DeveloperContent.new()
    .with_instructions("Help users check the weather.")
    .with_function_tools([
        ToolDescription.new(
            "get_weather",
            "Gets current weather for a location.",
            parameters={
                "type": "object",
                "properties": {
                    "location": {"type": "string", "description": "City name"}
                },
                "required": ["location"],
            },
        )
    ])
)

conversation = Conversation.from_messages([
    Message.from_role_and_content(Role.SYSTEM, system),
    Message.from_role_and_content(Role.DEVELOPER, developer),
    Message.from_role_and_content(Role.USER, "What's the weather in Tokyo?"),
])

# Step 2: Render for completion
tokens = encoding.render_conversation_for_completion(conversation, Role.ASSISTANT)
print(f"Prompt tokens: {len(tokens)}")

# Step 3: After model generates tool call, parse the response
model_output = (
    '<|channel|>analysis<|message|>User wants weather in Tokyo. '
    'Need to call get_weather function.<|end|>'
    '<|start|>assistant<|channel|>commentary to=functions.get_weather '
    '<|constrain|>json<|message|>{"location":"Tokyo"}<|call|>'
)
response_tokens = encoding.encode(model_output, allowed_special="all")
parsed = encoding.parse_messages_from_completion_tokens(response_tokens, Role.ASSISTANT)

# Step 4: Add assistant messages and tool response to conversation
for msg in parsed:
    conversation.messages.append(msg)

# Add tool response
tool_response = (
    Message.from_author_and_content(
        Author.new(Role.TOOL, "functions.get_weather"),
        '{"temperature": 22, "condition": "sunny", "humidity": 65}'
    )
    .with_channel("commentary")
    .with_recipient("assistant")
)
conversation.messages.append(tool_response)

# Step 5: Render again for model to generate final response
# Keep analysis when tool calls are ongoing
config = RenderConversationConfig(auto_drop_analysis=True)
tokens = encoding.render_conversation_for_completion(
    conversation, Role.ASSISTANT, config
)

# The model can now generate a final response using the tool output
print(f"Tokens for next turn: {len(tokens)}")
```

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

### Define Render Conversation Configuration

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

Specify optional configuration settings for rendering a conversation. This includes options like automatically dropping analysis messages.

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

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

### Add Crate to Cargo.toml

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

Add the harmony crate to your project's Cargo.toml file to include its functionality.

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

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

### Define Tools for Harmony Model

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

Define functions as tools using TypeScript-like syntax within the `Tools` section of the developer message. Use `functions` namespace to avoid conflicts. Functions without arguments are typed as `() => any`. Functions with arguments name the argument `_` and inline the type definition. Use `any` for return types and add comments for descriptions.

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

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

### Define Tool Description

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

Describe a callable tool, including its name, a description, and optional parameters. This is used for defining tool-use capabilities.

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

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

### Simulate streaming token parsing

Source: https://context7.com/openai/harmony/llms.txt

Process a sequence of tokens and access the parser's internal state during streaming. Use strict=False for permissive parsing.

```python
tokens = [
    200005,   # <|channel|>
    35644,    # analysis
    200008,   # <|message|>
    1844,     # User
    31064,    # asks
    # ... more tokens
]

for token in tokens:
    parser.process(token)

    # Access streaming state
    print(f"Current channel: {parser.current_channel}")
    print(f"Current role: {parser.current_role}")
    print(f"Content delta: {parser.last_content_delta}")
    print(f"Full content so far: {parser.current_content}")
    print(f"Current recipient: {parser.current_recipient}")
    print(f"Parser state: {parser.state}")

# Get all completed messages
completed_messages = parser.messages

# Use strict=False for permissive parsing
permissive_parser = StreamableParser(encoding, role=Role.ASSISTANT, strict=False)
```

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

### Model Initiates Tool Call

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

When the model decides to call a tool, it specifies the recipient in the message header as `to={name}` and uses the `commentary` channel. The `<|constrain|>` token indicates the input type, such 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|>
```

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

### Load Harmony Encoding

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

Obtain an instance of the HarmonyEncoding wrapper. This is used for tokenizing and parsing conversations.

```python
load_harmony_encoding()
```

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

### Browser Tool Interface Definitions

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

Definitions for browser interaction tools including search, open, and find functionality.

```typescript
namespace browser {

// Searches for information related to `query` and displays `topn` results.
type search = (_: {
query: string,
topn?: number, // default: 10
source?: string,
}) => any;

// Opens the link `id` from the page indicated by `cursor` starting at line number `loc`, showing `num_lines` lines.
// Valid link ids are displayed with the formatting: `【{id}†.*】`.
// If `cursor` is not provided, the most recent page is implied.
// If `id` is a string, it is treated as a fully qualified URL associated with `source`.
// If `loc` is not provided, the viewport will be positioned at the beginning of the document or centered on the most relevant passage, if available.
// Use this function without `id` to scroll to a new location of an opened page.
type open = (_: {
id?: number | string, // default: -1
cursor?: number, // default: -1
loc?: number, // default: -1
num_lines?: number, // default: -1
view_source?: boolean, // default: false
source?: string,
}) => any;

// Finds exact matches of `pattern` in the current page, or the page given by `cursor`.
type find = (_: {
pattern: string,
cursor?: number, // default: -1
}) => any;

} // namespace browser
```

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

### Import Re-exported Items

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

Key items are re-exported at the crate root for convenient access.

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

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

### Import Message Class

Source: https://context7.com/openai/harmony/llms.txt

Imports the Message class from the openai_harmony library. This class represents a single chat message.

```python
from openai_harmony import Message, Role, Author, TextContent
```

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

### Error Handling in Python

Source: https://context7.com/openai/harmony/llms.txt

Demonstrates catching HarmonyError exceptions during encoding, decoding, and rendering operations.

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

encoding = load_harmony_encoding(HarmonyEncodingName.HARMONY_GPT_OSS)

# Handle encoding/decoding errors
try:
    # Invalid token will raise an error
    encoding.decode_utf8([99999999])
except HarmonyError as e:
    print(f"Decoding error: {e}")

# Handle special token errors
try:
    # Special tokens without permission raise errors
    encoding.encode("<|start|>hello")
except HarmonyError as e:
    print(f"Special token error: {e}")

# Handle rendering errors
try:
    conversation = Conversation.from_messages([
        Message.from_role_and_content(Role.USER, "Hello"),
    ])
    tokens = encoding.render_conversation_for_completion(conversation, Role.ASSISTANT)
except RuntimeError as e:
    print(f"Rendering error: {e}")
```

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

### load_harmony_encoding(name)

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

Utility function to retrieve a HarmonyEncoding instance by name.

```APIDOC
## load_harmony_encoding(name)

### Description
Returns a HarmonyEncoding instance based on the provided name or enum value.

### Parameters
- **name** (str | HarmonyEncodingName) - Required - The name of the encoding (e.g., HARMONY_GPT_OSS).
```

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

### Define Developer Content

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

Specify the content for a developer message, including instructions and tool configurations. Helper methods simplify setting instructions and tools.

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