SwiftHarmony

A Swift port of OpenAI's harmony for encoding conversations as tokens for language model inference.

---

This library is a complete Swift implementation of the harmony response format used by OpenAI's gpt-oss model series. It uses the same test data as the original to validate correctness.

• Full feature parity – rendering and parsing matches the reference implementation.
• Native Swift – no bridging or FFI, pure Swift with Sendable types throughout.
• All Apple platforms – macOS, iOS, tvOS, watchOS, and visionOS.

Installation

Add SwiftHarmony to your Package.swift:

dependencies: [
    .package(url: "https://github.com/6over3/SwiftHarmony.git", from: "1.0.0")
]

Then add it to your target:

.target(
    name: "YourTarget",
    dependencies: ["SwiftHarmony"]
)

Usage

Encoding Conversations

import SwiftHarmony

let encoder = try HarmonyEncoder(.harmonyGptOss)

let messages = [
    ChatMessage(role: .system, text: "You are a helpful assistant."),
    ChatMessage(role: .user, text: "Hello!")
]

let tokens = try encoder.renderConversationForCompletion(
    messages,
    nextTurnRole: .assistant
)

Parsing Streaming Responses

let parser = try StreamableParser(encoder: encoder, role: .assistant)

for token in responseTokens {
    try parser.process(token)
    if let delta = parser.currentContentDelta {
        print(delta, terminator: "")
    }
}

let messages = parser.allMessages

Text Tokenization

let tokens = encoder.encode("Hello, world!")
let text = try encoder.decode(tokens)

Documentation

Generate documentation locally:

swift package generate-documentation

License

MIT – 6OVER3 INSTITUTE