@dvai-bridge/ios-llama-core 4.0.0

package/LICENSE

@@ -0,0 +1,51 @@
+# Deep Voice Ai Limited - Software License Agreement
+
+**Version 1.0.0**
+
+This License Agreement governs the use of the DVAI-Bridge software (the "Software"). By downloading, installing, or using the Software, you agree to be bound by the terms of this License.
+
+---
+
+## 1. LICENSE GRANTS
+
+### 1.1 Development and Personal Use (Free Tier)
+Deep Voice Ai Limited ("Licensor") grants you a non-exclusive, non-transferable, royalty-free license to use the Software solely for:
+- Internal development and testing purposes.
+- Non-commercial personal projects.
+- Academic and non-profit research.
+
+### 1.2 Commercial Use (Paid Tier)
+Any use of the Software for **Commercial Purposes** requires a separate, paid Commercial License from Licensor. "Commercial Purposes" include:
+- Use in production environments.
+- Integration into revenue-generating products or services.
+- Distribution to third-party customers for a fee.
+- Use by an entity with more than $100,000 USD in annual revenue.
+
+To obtain a Commercial License, contact `info@deepvoiceai.co` or visit `https://deepvoiceai.co/licensing`.
+
+---
+
+## 2. RESTRICTIONS
+Except as expressly permitted, you may not:
+- Sublicense, rent, lease, or resell the Software without express permission.
+- Remove any proprietary notices or branding from the Software.
+- Use the Software for any illegal or malicious purposes.
+
+---
+
+## 3. INTELLECTUAL PROPERTY
+The Software is owned by **Deep Voice Ai Limited** and is protected by copyright and intellectual property laws. This agreement does not transfer ownership of the Software.
+
+---
+
+## 4. NO WARRANTY
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. IN NO EVENT SHALL THE LICENSOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE.
+
+---
+
+## 5. GOVERNING LAW
+This License shall be governed by and construed in accordance with the laws of the jurisdiction where Deep Voice Ai Limited is registered.
+
+---
+
+© 2026 Deep Voice Ai Limited. All rights reserved.

package/Package.swift

@@ -0,0 +1,71 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+    name: "DVAILlamaCore",
+    // Platform floor bumped to iOS 17 / macOS 14 in v3.2.0 — DVAISharedCore
+    // moved to Hummingbird (swift-nio) which carries that floor. Earlier
+    // (Telegraph era) we shipped iOS 14 / macOS 12.
+    platforms: [.iOS(.v17), .macOS(.v14)],
+    products: [
+        .library(name: "DVAILlamaCore", targets: ["DVAILlamaCore"]),
+        .library(name: "DVAILlamaCoreObjC", targets: ["DVAILlamaCoreObjC"]),
+    ],
+    dependencies: [
+        // Shared HTTP-server / handler-dispatch types that all backend
+        // cores re-use. Path-dep identity = "dvai-bridge-ios-shared-core".
+        // DVAISharedCore brings in Hummingbird transitively as of
+        // v3.2.0 — the iOS HTTP server backbone is no longer Telegraph.
+        .package(path: "../dvai-bridge-ios-shared-core"),
+    ],
+    targets: [
+        // Prebuilt llama.xcframework — produced by upstream's
+        // build-xcframework.sh, materialized by `bash scripts/mac-side-prepare-xcframework.sh`.
+        // The xcframework is gitignored; CI must run the prepare step before
+        // iOS jobs. The submodule + xcframeworks live in
+        // dvai-bridge-android-llama-core (Phase 3A Task 9 relocation).
+        .binaryTarget(
+            name: "llama",
+            path: "../dvai-bridge-android-llama-core/android/src/main/cpp/native/llama.cpp/build-apple/llama.xcframework"
+        ),
+        .binaryTarget(
+            name: "mtmd",
+            path: "../dvai-bridge-android-llama-core/android/src/main/cpp/native/llama.cpp/build-apple/mtmd.xcframework"
+        ),
+        // Package.swift lives at the package root (not under `ios/`), so target
+        // paths include the `ios/` prefix. The root placement avoids an SPM
+        // identity-collision with sibling packages whose manifests also live at
+        // `<pkg>/ios/Package.swift` — SPM derives a path-dep's identity from
+        // the last directory component of the path, and "ios" would alias
+        // multiple packages and trigger a false cyclic-dependency error.
+        .target(
+            name: "DVAILlamaCoreObjC",
+            dependencies: ["llama", "mtmd"],
+            path: "ios/Sources/DVAILlamaCoreObjC",
+            publicHeadersPath: "include",
+            linkerSettings: [
+                .linkedFramework("Foundation"),
+            ]
+        ),
+        // Swift target — depends on the ObjC++ target and the extracted
+        // shared HTTP types in DVAISharedCore.
+        .target(
+            name: "DVAILlamaCore",
+            dependencies: [
+                "DVAILlamaCoreObjC",
+                .product(name: "DVAISharedCore", package: "dvai-bridge-ios-shared-core"),
+            ],
+            path: "ios/Sources/DVAILlamaCore"
+        ),
+        .testTarget(
+            name: "DVAILlamaCoreTests",
+            dependencies: [
+                "DVAILlamaCore",
+                "DVAILlamaCoreObjC",
+                .product(name: "DVAISharedCore", package: "dvai-bridge-ios-shared-core"),
+            ],
+            path: "ios/Tests/DVAILlamaCoreTests"
+        ),
+    ],
+    cxxLanguageStandard: .cxx17
+)

package/README.md

@@ -0,0 +1,199 @@
+![DVAI-Bridge](/assets/banner.png)
+
+# DVAI-Bridge
+
+<!-- [![Smoke — real models](https://github.com/Westenets/dvai-bridge/actions/workflows/smoke-real-models.yml/badge.svg?branch=main)](https://github.com/Westenets/dvai-bridge/actions/workflows/smoke-real-models.yml) -->
+
+[![License](https://img.shields.io/badge/License-Commercial-blue.svg)](LICENSE) ![Node.js](https://img.shields.io/badge/Node.js-22+-green?logo=node.js) ![TypeScript](https://img.shields.io/badge/TypeScript-5.6+-blue?logo=typescript) ![Swift](https://img.shields.io/badge/Swift-5.9+-F05138?logo=swift) ![Kotlin](https://img.shields.io/badge/Kotlin-2.0+-7F52FF?logo=kotlin) ![Flutter](https://img.shields.io/badge/Flutter-3.39+-02569B?logo=flutter) ![.NET](https://img.shields.io/badge/.NET-10.0_LTS-512BD4?logo=dotnet)
+
+> **The local OpenAI server you embed inside your app.**
+> One library. One HTTP wire. Every platform. Zero install for your users.
+
+**Docs:** [dvai-bridge.deepvoiceai.co](https://dvai-bridge.deepvoiceai.co)
+
+```ts
+import { DVAI } from "@dvai-bridge/core";
+import OpenAI from "openai";
+
+const dvai = new DVAI({ backend: "transformers" });
+await dvai.initialize();
+
+const openai = new OpenAI({ baseURL: dvai.baseUrl, apiKey: "ignored" });
+await openai.chat.completions.create({
+  model: dvai.transformersModelId,
+  messages: [{ role: "user", content: "Hello!" }],
+});
+```
+
+That's it. A real OpenAI-compatible server is now running inside your app's
+own process. Point any OpenAI client — LangChain, the OpenAI SDK, the Vercel
+AI SDK, anything — at `dvai.baseUrl` and your agent code keeps working.
+
+Built by **[Deep Voice AI](https://deepvoiceai.co)**.
+
+---
+
+## Why it exists
+
+Local AI works beautifully on a laptop with **Ollama + LangChain**. Then you
+try to ship the app and your users don't have Ollama. Mobile can't run it.
+Corporate IT won't add another daemon. So you reinvent the same plumbing —
+spawn an inference engine, bind a port, translate to OpenAI HTTP, handle
+CORS, manage lifecycle, wrap the accelerator of the day per platform — and
+do it all over again for every target OS.
+
+DVAI-Bridge is that plumbing, packaged as a library, for every client
+platform.
+
+---
+
+## What you get
+
+- **One OpenAI HTTP surface.** Bound on `127.0.0.1` (or `0.0.0.0` for
+  device-to-device). Streaming, embeddings, models, recovery — all built in.
+- **Six SDKs.** `@dvai-bridge/core` + `react` + `vanilla` + `capacitor`,
+  `DVAIBridge` (Swift / iOS), `co.deepvoiceai:dvai-bridge` (Kotlin / Android),
+  `@dvai-bridge/react-native`, `dvai_bridge` (Flutter), `co.deepvoiceai.dvai-bridge` (.NET).
+- **Nine backends.** WebLLM, Transformers.js, llama.cpp, Apple Foundation
+  Models, MLX, CoreML / ANE, MediaPipe LLM, LiteRT, ONNX Runtime GenAI —
+  selected per-platform, invisible to your agent code.
+- **Native acceleration** wherever it runs: WebGPU in browsers, CUDA / Metal
+  / Vulkan / DirectML on desktop, ANE / Metal / MLX on iOS, NNAPI / QNN
+  Hexagon / GPU delegate on Android.
+- **Multimodal.** Text, image, audio, video — declarative loader for
+  cutting-edge models (Gemma 4, LLaVA, Idefics) without waiting for library
+  updates.
+- **Distributed inference (v3.0+).** Phone too slow? Offload to your laptop
+  on the same Wi-Fi via mDNS pairing — same OpenAI wire, transparent to
+  your code. Internet path via a self-hostable rendezvous server.
+- **DVAI Hub (v3.1+).** A first-party desktop utility that turns any device
+  into a strong-peer for the rest of your fleet. Brand-neutral install via
+  Homebrew / winget / GitHub Releases, OR fork it for your own branded
+  companion. Routes through Ollama / LM Studio / vLLM / llama-server /
+  llamafile if you've already got those running.
+- **Zero user install.** It's a library, not a daemon. `npm install`,
+  `cocoapods`, gradle — your CI already has the muscle for it.
+
+---
+
+## Supported platforms
+
+| Stack | Package | Backends |
+| --- | --- | --- |
+| Browser (React, Vue, Svelte, vanilla JS) | `@dvai-bridge/core` + `react` / `vanilla` | WebLLM (WebGPU), Transformers.js (WebGPU / WASM SIMD) |
+| Node / Bun / Electron | `@dvai-bridge/core` | Transformers.js, native llama.cpp |
+| Capacitor hybrid mobile | `@dvai-bridge/capacitor` + backend slice | Native llama.cpp (Metal iOS, Vulkan / CPU Android) |
+| iOS native (Swift) | `DVAIBridge` (SPM / CocoaPods) | llama.cpp (Metal), CoreML / ANE, Apple Foundation Models, MLX |
+| Android native (Kotlin / Java) | `co.deepvoiceai:dvai-bridge` (AAR) | llama.cpp, MediaPipe LLM, LiteRT, NNAPI / QNN |
+| React Native (≥0.77, TurboModule) | `@dvai-bridge/react-native` | All iOS + Android backends (delegates) |
+| Flutter (≥3.39) | `dvai_bridge` (pub.dev) | All iOS + Android backends (Pigeon channels) |
+| .NET 10 LTS (MAUI / Avalonia / WinUI / Catalyst / desktop) | `co.deepvoiceai.dvai-bridge*` (NuGet) | iOS / Android delegate to native; desktop = llama.cpp + ONNX Runtime GenAI + ML.NET |
+
+Full quickstart per platform: [dvai-bridge.deepvoiceai.co/guide/getting-started](https://dvai-bridge.deepvoiceai.co/guide/getting-started)
+
+---
+
+## Examples
+
+```ts
+// React
+import { DVAIProvider, useDVAI } from "@dvai-bridge/react";
+<DVAIProvider config={{ backend: "transformers" }}>
+  <Chat />
+</DVAIProvider>;
+function Chat() {
+  const { isReady, baseUrl } = useDVAI();
+  return isReady ? <div>Local AI live at {baseUrl}</div> : <Loading />;
+}
+```
+
+```swift
+// iOS
+let server = try await DVAIBridge.shared.start()
+// server.baseUrl = "http://127.0.0.1:38883/v1"
+```
+
+```kotlin
+// Android
+val server = DVAIBridge.start(context)
+// server.baseUrl = "http://127.0.0.1:38883/v1"
+```
+
+```dart
+// Flutter
+final state = await DVAIBridge.instance.start(
+  backend: BackendKind.auto,
+  modelPath: '/path/to/model.gguf',
+);
+// state.baseUrl = "http://127.0.0.1:38883/v1"
+```
+
+```csharp
+// .NET
+var server = await DVAIBridge.Shared.StartAsync(new StartOptions {
+    Backend = BackendKind.Auto,
+    ModelPath = "/path/to/model.gguf",
+});
+// server.BaseUrl = "http://127.0.0.1:38883/v1"
+```
+
+Multimodal, streaming, embeddings, distributed offload, the Hub —
+everything's at the [docs site](https://dvai-bridge.deepvoiceai.co).
+
+---
+
+## What's new in v3.1
+
+- **DVAI Hub** — Tauri desktop utility that's the strong-peer side of v3
+  distributed inference. `brew install deepvoiceai/dvai-hub/dvai-hub` (or
+  `winget install DeepVoiceAI.DVAIHub`) → mobile apps on the same Wi-Fi
+  pair with it and offload heavy inference. [Guide →](https://dvai-bridge.deepvoiceai.co/guide/dvai-hub)
+- **External-engine bridge.** Hub surfaces Ollama / LM Studio / vLLM /
+  llama-server / llamafile as additional backend pools so paired apps
+  serve from whatever's already cached. Opt-in per engine.
+- **Strict substitution policy.** Models with mismatched family / version /
+  size / type are refused by default; quant-only mismatches gated behind a
+  per-pairing `preferBetterQuant` flag. No silent mis-routing.
+- **HMAC-signed identity** on `/v1/chat/completions`. Per-app audit logs
+  surface who served what, with structured `(appId, peerDeviceId,
+  engine, requestedModel, servedModel, outcome)` rows.
+- **Library finalization.** `httpBindHost` (LAN bind), `chatCompletionInterceptor`
+  (extension point), HMAC primitives re-exported, `/v1/dvai/*` routes
+  actually dispatched, TransformersBackend Node-mode device fix.
+  [Migration v3.0 → v3.1 →](https://dvai-bridge.deepvoiceai.co/migration/v3.0-to-v3.1)
+
+---
+
+## Robustness
+
+Streaming-correct (SSE passthrough + blank-chunk detection), generation
+timeout, automatic engine-state recovery on fatal errors, port fallback,
+worker offloading, Private Network Access ready, CORS configured. The
+boring substrate so your agent code never has to think about it.
+
+---
+
+## Licensing
+
+Dual: **free for development & personal use** on `localhost` (verified at
+runtime). **Commercial use** requires a license key — `info@deepvoiceai.co`.
+
+---
+
+## Contributing
+
+PRs welcome.
+
+```bash
+pnpm install
+pnpm build
+bash scripts/build-all.sh   # full matrix (auto-skips per-host)
+```
+
+[`CONTRIBUTING.md`](./CONTRIBUTING.md) for the PR flow. Per-platform
+contributor docs (iOS / Android / RN / Flutter / .NET) under
+[`docs/development/`](./docs/development/).
+
+---
+
+© Deep Voice AI Limited. All rights reserved.

package/ios/Sources/DVAILlamaCore/AudioDecoder.swift

@@ -0,0 +1,112 @@
+import Foundation
+import AVFoundation
+
+/// Supported audio encodings accepted by `AudioDecoder.decode(data:format:)`.
+///
+/// `pcm16` is treated as already-decoded raw little-endian 16 kHz mono PCM16
+/// and returned unchanged. All other formats are decoded via
+/// `AVAudioFile` + `AVAudioConverter` to that same target format.
+enum AudioFormat: String {
+    case pcm16, wav, mp3, m4a, aac, flac
+}
+
+/// Decodes supported audio formats to 16 kHz mono PCM16 little-endian samples
+/// suitable for feeding into a multimodal projector.
+struct AudioDecoder {
+    /// Decode `data` (encoded in `format`) to 16 kHz mono PCM16 LE samples.
+    /// Pass-through for `.pcm16`.
+    static func decode(data: Data, format: AudioFormat) async throws -> Data {
+        switch format {
+        case .pcm16:
+            return data
+        case .wav, .mp3, .m4a, .aac, .flac:
+            return try await decodeViaAVAudioFile(data: data)
+        }
+    }
+
+    private static func decodeViaAVAudioFile(data: Data) async throws -> Data {
+        // AVAudioFile requires a file URL, so write to a temp file first.
+        let tmpURL = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)
+        try data.write(to: tmpURL)
+        defer { try? FileManager.default.removeItem(at: tmpURL) }
+
+        let inputFile = try AVAudioFile(forReading: tmpURL)
+        guard let outputFormat = AVAudioFormat(
+            commonFormat: .pcmFormatInt16,
+            sampleRate: 16000,
+            channels: 1,
+            interleaved: true
+        ) else {
+            throw NSError(
+                domain: "AudioDecoder",
+                code: 1,
+                userInfo: [NSLocalizedDescriptionKey: "Unable to create output format"]
+            )
+        }
+        guard let converter = AVAudioConverter(from: inputFile.processingFormat, to: outputFormat) else {
+            throw NSError(
+                domain: "AudioDecoder",
+                code: 2,
+                userInfo: [NSLocalizedDescriptionKey: "Unable to create converter"]
+            )
+        }
+        guard
+            let inputBuf = AVAudioPCMBuffer(pcmFormat: inputFile.processingFormat, frameCapacity: 4096),
+            let outputBuf = AVAudioPCMBuffer(pcmFormat: outputFormat, frameCapacity: 4096)
+        else {
+            throw NSError(
+                domain: "AudioDecoder",
+                code: 3,
+                userInfo: [NSLocalizedDescriptionKey: "Unable to allocate buffers"]
+            )
+        }
+
+        var result = Data()
+        while inputFile.framePosition < inputFile.length {
+            try inputFile.read(into: inputBuf)
+
+            // The input callback may be invoked multiple times per
+            // `convert(to:error:withInputFrom:)` call. Without this guard the
+            // same `inputBuf` would be re-emitted to the converter and we'd
+            // double-count samples / corrupt output.
+            var consumed = false
+            var error: NSError?
+            converter.convert(to: outputBuf, error: &error) { _, status in
+                if consumed {
+                    status.pointee = .endOfStream
+                    return nil
+                }
+                consumed = true
+                status.pointee = .haveData
+                return inputBuf
+            }
+            if let error = error { throw error }
+
+            if let int16Data = outputBuf.int16ChannelData {
+                let frameLength = Int(outputBuf.frameLength)
+                if frameLength > 0 {
+                    let bytes = UnsafeRawPointer(int16Data[0])
+                    result.append(Data(bytes: bytes, count: frameLength * 2))
+                }
+            }
+        }
+
+        // Drain: tell the converter we're done so any buffered tail samples
+        // (e.g. AAC priming / codec lookahead) are flushed to outputBuf.
+        var drainError: NSError?
+        let drainStatus = converter.convert(to: outputBuf, error: &drainError) { _, status in
+            status.pointee = .endOfStream
+            return nil
+        }
+        if drainStatus == .haveData, drainError == nil, let int16Data = outputBuf.int16ChannelData {
+            let frameLength = Int(outputBuf.frameLength)
+            if frameLength > 0 {
+                let bytes = UnsafeRawPointer(int16Data[0])
+                result.append(Data(bytes: bytes, count: frameLength * 2))
+            }
+        }
+        // drainError on flush is acceptable — some codecs return an error when there's nothing left.
+
+        return result
+    }
+}

package/ios/Sources/DVAILlamaCore/ContentPartsTranslator.swift

@@ -0,0 +1,232 @@
+import Foundation
+
+/// The canonical media-marker token mtmd uses for image/audio splice points.
+/// Mirrors `mtmd_default_marker()` from `tools/mtmd/mtmd.h`. Substituting this
+/// literal lets us avoid an FFI call from this translation unit.
+public let MTMD_MEDIA_MARKER = "<__media__>"
+
+/// One rendered chat message ready for `bridge.applyChatTemplate(...)`.
+/// Content has had image_url / input_audio parts replaced with the
+/// `<__media__>` marker; the corresponding raw bytes live in
+/// `LlamaPromptInput.media` in the same declaration order as the markers.
+struct LlamaTranslatedMessage: Equatable {
+    let role: String
+    let content: String
+}
+
+/// Output of `ContentPartsTranslator.translate(messages:)` — the inputs
+/// the llama.cpp handler will hand to `bridge.applyChatTemplate(...)` and
+/// `bridge.completeMultimodalPrompt(...)`.
+struct LlamaPromptInput: Equatable {
+    /// Per-message rendered content with media replaced by `<__media__>`
+    /// markers, in source order. Pass directly to `applyChatTemplate`.
+    let messagesWithMarkers: [LlamaTranslatedMessage]
+    /// All media bytes (images + decoded audio) in declaration order across
+    /// all messages, matching the order the markers appear in the rendered
+    /// content. mtmd's `tokenize` matches markers to bitmaps by position;
+    /// it auto-detects image vs audio by magic bytes, so a single ordered
+    /// list is sufficient.
+    let media: [Data]
+    /// Legacy: concatenation of all `text` parts for diagnostics. The handler
+    /// no longer feeds this to the model directly — `messagesWithMarkers` +
+    /// `media` is the source of truth — but it stays available for logging.
+    let prompt: String
+}
+
+/// Errors raised by `ContentPartsTranslator.translate(messages:)`. The HTTP
+/// status mappings (per spec §8.5) are owned by the handler layer; the
+/// translator just throws the typed case.
+enum TranslatorError: Error, Equatable {
+    /// 400 — `Request includes an image but no mmproj was loaded. Set nativeMmprojPath when starting.`
+    case noMmprojForImage
+    /// 400 — `Loaded model has no native audio encoder. Use a multimodal model like Gemma 4 or Phi-4 Multimodal.`
+    case audioWithoutAudioEncoder
+    /// 400 — `Unsupported audio format: <fmt>. Supported on this platform: <list>.`
+    case unsupportedAudioFormat(String, supported: [String])
+    /// 400 — `Audio decode failed: <reason>`.
+    case audioDecodeFailed(String)
+    /// 502 — `Failed to fetch image: <reason>`.
+    case imageFetchFailed(String)
+    /// 400 — `<reason>`. Used for shape errors (missing role, unknown part type, etc.).
+    case malformedRequest(String)
+}
+
+/// Test seam for the image-decode collaborator. The default implementation
+/// just delegates to `ImageDecoder.resolve(url:)`; tests can substitute a
+/// canned-bytes mock so they don't have to round-trip through the real
+/// data-URL / file / HTTP pipelines (those are covered in `ImageDecoderTest`).
+protocol ImageDecoderProtocol {
+    func resolve(url: String) async throws -> Data
+}
+
+struct DefaultImageDecoder: ImageDecoderProtocol {
+    func resolve(url: String) async throws -> Data {
+        try await ImageDecoder.resolve(url: url)
+    }
+}
+
+/// Walks an OpenAI-style `messages` array and produces a `LlamaPromptInput`
+/// bundle. Each message's content is rendered into a string with media parts
+/// replaced by `<__media__>` markers; the corresponding bytes (image bytes
+/// from `ImageDecoder` and the raw base64-decoded audio bytes — still in
+/// their WAV/MP3/FLAC envelope) are appended to `media` in declaration order.
+///
+/// mtmd does its own format detection (via miniaudio) inside
+/// `mtmd_helper_bitmap_init_from_buf` by inspecting magic bytes, so the
+/// translator must hand it the original encoded audio rather than headerless
+/// PCM samples — `mtmd_helper_bitmap_init_from_buf` only recognizes
+/// WAV/MP3/FLAC and would fail silently on raw PCM.
+///
+/// Audio data contract: `input_audio.data` must be standard base64 (RFC 4648
+/// §4); URL-safe base64 (`-` / `_` chars) is rejected. This matches OpenAI's
+/// documented input format.
+///
+/// Spec reference: §8.1 (content-part shape), §8.2 (image translation), §8.3
+/// (audio translation), §8.5 (error mapping).
+final class ContentPartsTranslator {
+    /// Audio formats this platform can decode. Anything outside the set
+    /// throws `unsupportedAudioFormat`. iOS has flac (via `AVAudioFile`);
+    /// Android has ogg instead.
+    static let supportedAudioFormats: [String] = ["pcm16", "wav", "mp3", "m4a", "aac", "flac"]
+
+    private let mmprojLoaded: Bool
+    private let modelHasAudioEncoder: Bool
+    private let imageDecoder: ImageDecoderProtocol
+    /// Currently unused on the production path — mtmd handles audio decoding
+    /// internally via miniaudio, so we pass the raw base64-decoded bytes (in
+    /// their WAV/MP3/FLAC envelope) straight through. Kept as an init
+    /// parameter for backward compatibility with existing tests and as a
+    /// possible future fallback for formats mtmd cannot decode itself.
+    private let audioDecoder: (Data, AudioFormat) async throws -> Data
+
+    init(
+        mmprojLoaded: Bool,
+        modelHasAudioEncoder: Bool,
+        imageDecoder: ImageDecoderProtocol = DefaultImageDecoder(),
+        audioDecoder: @escaping (Data, AudioFormat) async throws -> Data = { try await AudioDecoder.decode(data: $0, format: $1) }
+    ) {
+        self.mmprojLoaded = mmprojLoaded
+        self.modelHasAudioEncoder = modelHasAudioEncoder
+        self.imageDecoder = imageDecoder
+        self.audioDecoder = audioDecoder
+    }
+
+    /// Translate an OpenAI `messages` array (as decoded JSON: `[String: Any]`
+    /// per message) into a `LlamaPromptInput`. Walks each message's `content`
+    /// in order; legacy string content is treated as a single text part.
+    func translate(messages: [[String: Any]]) async throws -> LlamaPromptInput {
+        var translatedMessages: [LlamaTranslatedMessage] = []
+        var media: [Data] = []
+        var promptParts: [String] = []
+
+        for (msgIdx, msg) in messages.enumerated() {
+            guard let role = msg["role"] as? String else {
+                throw TranslatorError.malformedRequest("messages[\(msgIdx)] missing string 'role'")
+            }
+            let content = msg["content"]
+            // Per-message rendered string (text segments + markers in order).
+            var renderedSegments: [String] = []
+
+            if let text = content as? String {
+                promptParts.append(text)
+                renderedSegments.append(text)
+                translatedMessages.append(LlamaTranslatedMessage(role: role, content: renderedSegments.joined(separator: " ")))
+                continue
+            }
+            guard let parts = content as? [[String: Any]] else {
+                throw TranslatorError.malformedRequest(
+                    "messages[\(msgIdx)].content must be a string or array of content parts"
+                )
+            }
+            for (partIdx, part) in parts.enumerated() {
+                let path = "messages[\(msgIdx)].content[\(partIdx)]"
+                guard let type = part["type"] as? String else {
+                    throw TranslatorError.malformedRequest("\(path) missing string 'type'")
+                }
+                switch type {
+                case "text":
+                    guard let text = part["text"] as? String else {
+                        throw TranslatorError.malformedRequest("\(path) text part missing string 'text'")
+                    }
+                    promptParts.append(text)
+                    renderedSegments.append(text)
+                case "image_url":
+                    if !mmprojLoaded {
+                        throw TranslatorError.noMmprojForImage
+                    }
+                    guard let imgObj = part["image_url"] as? [String: Any],
+                          let url = imgObj["url"] as? String else {
+                        throw TranslatorError.malformedRequest("\(path) image_url part missing image_url.url")
+                    }
+                    do {
+                        let bytes = try await imageDecoder.resolve(url: url)
+                        media.append(bytes)
+                    } catch {
+                        throw TranslatorError.imageFetchFailed(String(describing: error))
+                    }
+                    renderedSegments.append(MTMD_MEDIA_MARKER)
+                case "input_audio":
+                    if !modelHasAudioEncoder {
+                        throw TranslatorError.audioWithoutAudioEncoder
+                    }
+                    guard let audioObj = part["input_audio"] as? [String: Any],
+                          let dataB64 = audioObj["data"] as? String,
+                          let formatStr = audioObj["format"] as? String else {
+                        throw TranslatorError.malformedRequest(
+                            "\(path) input_audio part missing input_audio.data or input_audio.format"
+                        )
+                    }
+                    if !Self.supportedAudioFormats.contains(formatStr) {
+                        throw TranslatorError.unsupportedAudioFormat(
+                            formatStr,
+                            supported: Self.supportedAudioFormats
+                        )
+                    }
+                    // Validate the format string against `AudioFormat` to keep
+                    // the supported-format gate honest, but the production
+                    // path no longer calls into AudioDecoder — mtmd does its
+                    // own format detection by magic bytes.
+                    guard AudioFormat(rawValue: formatStr) != nil else {
+                        // The supportedAudioFormats list is the source of truth;
+                        // this branch only fires if the raw-value enum diverges
+                        // from that list.
+                        throw TranslatorError.unsupportedAudioFormat(
+                            formatStr,
+                            supported: Self.supportedAudioFormats
+                        )
+                    }
+                    guard !dataB64.isEmpty else {
+                        throw TranslatorError.malformedRequest("input_audio.data is empty")
+                    }
+                    // Standard base64 only (RFC 4648 §4). URL-safe base64 (-/_ chars) is rejected.
+                    // Matches OpenAI's documented input format.
+                    guard let encodedBytes = Data(base64Encoded: dataB64) else {
+                        throw TranslatorError.malformedRequest("input_audio.data is not valid base64")
+                    }
+                    // Pass the raw base64-decoded bytes (still in their
+                    // original WAV/MP3/FLAC envelope) straight through to
+                    // mtmd. `mtmd_helper_bitmap_init_from_buf` only accepts
+                    // WAV/MP3/FLAC by magic-byte detection — feeding it
+                    // headerless PCM (e.g. via `AudioDecoder.decode`) makes
+                    // bitmap-init fail silently with mtmd error 52.
+                    media.append(encodedBytes)
+                    renderedSegments.append(MTMD_MEDIA_MARKER)
+                default:
+                    throw TranslatorError.malformedRequest("unsupported content part type: \(type)")
+                }
+            }
+            // Join the rendered segments with spaces so adjacent text+marker
+            // pairs become "before <__media__> after". A single space matches
+            // the canonical mtmd-cli prompt shape.
+            translatedMessages.append(
+                LlamaTranslatedMessage(role: role, content: renderedSegments.joined(separator: " "))
+            )
+        }
+
+        return LlamaPromptInput(
+            messagesWithMarkers: translatedMessages,
+            media: media,
+            prompt: promptParts.joined(separator: "\n")
+        )
+    }
+}