@dvai-bridge/android-mediapipe-core 4.0.0

package/android/src/main/java/co/deepvoiceai/bridge/mediapipe/core/MediaPipeBridge.kt

@@ -0,0 +1,203 @@
+package co.deepvoiceai.bridge.mediapipe.core
+
+import android.content.Context
+import com.google.ai.edge.litertlm.Backend
+import com.google.ai.edge.litertlm.Content
+import com.google.ai.edge.litertlm.Contents
+import com.google.ai.edge.litertlm.Conversation
+import com.google.ai.edge.litertlm.Engine
+import com.google.ai.edge.litertlm.EngineConfig
+import com.google.ai.edge.litertlm.Message
+import com.google.ai.edge.litertlm.MessageCallback
+
+/**
+ * Test seam over Google's LiteRT-LM Engine. Concrete [MediaPipeBridge]
+ * implements this; [MediaPipeHandlers] takes the interface so unit tests can
+ * substitute a canned-response fake without loading a real `.litertlm` model.
+ *
+ * Concurrency: implementations need NOT be thread-safe — [MediaPipeHandlers]
+ * serializes all calls behind its own mutex.
+ */
+interface MediaPipeBridgeApi {
+    /**
+     * Synchronous prompt completion. If [images] is non-empty the engine must
+     * have been built with `visionEnabled = true`; otherwise LiteRT-LM will
+     * throw at conversation creation or message-send time. Images are supplied
+     * as raw encoded bytes (PNG/JPEG/etc.).
+     */
+    fun completePrompt(prompt: String, images: List<ByteArray> = emptyList()): String
+
+    /**
+     * Asynchronous prompt completion. The supplied callback fires per partial
+     * chunk; the second arg is `true` on the final fragment. Returns a handle
+     * the caller can [AutoCloseable.close] to release the per-call conversation
+     * once the stream finishes (or is cancelled). Images are supplied as raw
+     * encoded bytes (PNG/JPEG/etc.).
+     */
+    fun completePromptAsync(
+        prompt: String,
+        images: List<ByteArray> = emptyList(),
+        onPartial: (partial: String, done: Boolean) -> Unit,
+    ): AutoCloseable
+}
+
+/**
+ * Kotlin wrapper around the LiteRT-LM `litertlm-android:0.10.2` Engine API.
+ * Replaces the deprecated `com.google.mediapipe:tasks-genai` MediaPipe bridge
+ * (Phase 3B, Tasks 18-19).
+ *
+ * Architecture:
+ *
+ *  - One long-lived [Engine] per bridge instance (lazy-initialized so JVM unit
+ *    tests using the [MediaPipeBridgeApi] fake never trigger native loading).
+ *    [engine.initialize()] is called inside the lazy block; this is the heavy
+ *    model-load step (~10 s) and must be called off the main thread.
+ *  - One [Conversation] per request — LiteRT-LM Conversations are stateful and
+ *    multi-turn, so we create a fresh one per call and close it after to
+ *    maintain the same stateless-request semantics as the old session model.
+ *  - Vision is enabled at the engine level via [EngineConfig.visionBackend].
+ *    There is no per-conversation vision flag (unlike the old
+ *    `GraphOptions.setEnableVisionModality`).
+ *
+ * API deviations from the migration doc (§3) based on actual bytecode inspection:
+ *  - [Message] has no `.text` property — text is accessed through
+ *    `message.contents.contents`, which is a `List<Content>`. Text parts are
+ *    `Content.Text` items; their text fields are joined to form the response.
+ *  - [EngineConfig] DOES have `maxNumImages: Int?` and `maxNumTokens: Int?`
+ *    fields in the actual 0.10.2 artifact — the migration doc §5 risk for
+ *    setMaxNumImages is not applicable; the field exists and is used here.
+ *  - [Engine] does not accept Android `Context` — per migration doc §4, Context
+ *    is only needed for optional path derivation. The constructor keeps `context`
+ *    for API compatibility and future use (e.g. `context.cacheDir.path`).
+ *
+ * Model file format: LiteRT-LM uses `.litertlm` bundles, not `.task`. Existing
+ * `.task` models must be re-converted; see the migration notes for details.
+ */
+class MediaPipeBridge(
+    @Suppress("UNUSED_PARAMETER") private val context: Context,
+    private val modelPath: String,
+    private val maxTokens: Int = 2048,
+    private val visionEnabled: Boolean = false,
+    private val maxImages: Int = 1,
+) : MediaPipeBridgeApi, AutoCloseable {
+
+    private val engine: Engine by lazy {
+        val cfg = EngineConfig(
+            modelPath = modelPath,
+            // Vision is enabled at the engine level by supplying a visionBackend.
+            // GPU() is the standard choice; null disables vision modality.
+            visionBackend = if (visionEnabled) Backend.GPU() else null,
+            // maxNumImages: EngineConfig does have this field in 0.10.2
+            // (migration doc §5 TBD is resolved — field exists in actual artifact).
+            maxNumImages = if (visionEnabled) maxImages else null,
+            // maxNumTokens maps to the old setMaxTokens(int) option.
+            maxNumTokens = maxTokens,
+        )
+        val e = Engine(cfg)
+        e.initialize()
+        e
+    }
+
+    @Volatile private var engineInitialized: Boolean = false
+
+    private fun engine(): Engine {
+        val ref = engine
+        engineInitialized = true
+        return ref
+    }
+
+    private fun newConversation(): Conversation =
+        engine().createConversation()
+
+    /**
+     * Build a [Contents] value combining the text prompt with any image bytes.
+     * [Content.ImageBytes] accepts raw PNG/JPEG bytes directly — no MPImage
+     * wrapping required (migration doc §2). The vararg [Contents.of] overload
+     * is used to avoid a spurious unchecked-cast warning from the list overload.
+     */
+    private fun buildContents(prompt: String, images: List<ByteArray>): Contents {
+        val parts = mutableListOf<Content>(Content.Text(prompt))
+        for (bytes in images) {
+            parts.add(Content.ImageBytes(bytes))
+        }
+        return Contents.of(parts)
+    }
+
+    /**
+     * Extract text from a [Message] response.
+     *
+     * [Message] has no `.text` shortcut in the 0.10.2 public API. Text is
+     * accessed via `message.contents.contents` (a `List<Content>`). All
+     * `Content.Text` items are joined; non-text parts (images, audio, tool
+     * responses) are silently ignored, matching the expected LLM response shape.
+     */
+    private fun Message.extractText(): String =
+        contents.contents
+            .filterIsInstance<Content.Text>()
+            .joinToString("") { it.text }
+
+    override fun completePrompt(prompt: String, images: List<ByteArray>): String {
+        val msgContents = buildContents(prompt, images)
+        val conversation = newConversation()
+        try {
+            // sendMessage is the single-call replacement for the old
+            // addQueryChunk + addImage + generateResponse triple (migration doc §3).
+            val message = conversation.sendMessage(msgContents)
+            return message.extractText()
+        } finally {
+            try {
+                conversation.close()
+            } catch (_: Throwable) { /* idempotent */ }
+        }
+    }
+
+    override fun completePromptAsync(
+        prompt: String,
+        images: List<ByteArray>,
+        onPartial: (String, Boolean) -> Unit,
+    ): AutoCloseable {
+        val msgContents = buildContents(prompt, images)
+        val conversation = newConversation()
+        try {
+            // MessageCallback replaces the old ProgressListener<String> callback.
+            // onMessage fires per partial token; onDone signals completion.
+            // (migration doc §3 streaming: callback form maps 1:1 to our contract)
+            conversation.sendMessageAsync(
+                msgContents,
+                object : MessageCallback {
+                    override fun onMessage(message: Message) {
+                        onPartial(message.extractText(), false)
+                    }
+
+                    override fun onDone() {
+                        onPartial("", true)
+                    }
+
+                    override fun onError(throwable: Throwable) {
+                        // Surface the error: re-throw on the callback thread so
+                        // that the engine's internal executor propagates it.
+                        throw RuntimeException("LiteRT-LM streaming error", throwable)
+                    }
+                },
+            )
+        } catch (t: Throwable) {
+            try {
+                conversation.close()
+            } catch (_: Throwable) { /* idempotent */ }
+            throw t
+        }
+        return AutoCloseable {
+            try {
+                conversation.close()
+            } catch (_: Throwable) { /* idempotent — best-effort cleanup */ }
+        }
+    }
+
+    override fun close() {
+        if (engineInitialized) {
+            try {
+                engine.close()
+            } catch (_: Throwable) { /* idempotent */ }
+        }
+    }
+}

package/android/src/main/java/co/deepvoiceai/bridge/mediapipe/core/MediaPipeHandlers.kt

@@ -0,0 +1,482 @@
+package co.deepvoiceai.bridge.mediapipe.core
+
+import co.deepvoiceai.bridge.shared.core.DvaiHandlers
+import co.deepvoiceai.bridge.shared.core.HandlerContext
+import co.deepvoiceai.bridge.shared.core.HandlerResponse
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.channels.awaitClose
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.callbackFlow
+import kotlinx.coroutines.flow.flow
+import kotlinx.coroutines.sync.Mutex
+import kotlinx.coroutines.sync.withLock
+import kotlinx.coroutines.withContext
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonArray
+import kotlinx.serialization.json.JsonNull
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.JsonPrimitive
+import kotlinx.serialization.json.addJsonObject
+import kotlinx.serialization.json.booleanOrNull
+import kotlinx.serialization.json.buildJsonObject
+import kotlinx.serialization.json.contentOrNull
+import kotlinx.serialization.json.intOrNull
+import kotlinx.serialization.json.put
+import kotlinx.serialization.json.putJsonArray
+import kotlinx.serialization.json.putJsonObject
+import java.util.UUID
+
+/**
+ * OpenAI-compatible handler set for the MediaPipe LLM backend on Android.
+ * Wires `openAIMessagesToPrompt` -> `bridge.completePrompt` (sync) or
+ * `bridge.completePromptAsync` (streaming) -> OpenAI response shape.
+ *
+ * Phase 1 scope (Task 46): text + optional image input on vision-capable
+ * Gemma tasks (e.g. Gemma 3n vision variants). Audio (`input_audio`) is
+ * permanently rejected — MediaPipe `tasks-genai` has no audio path. Image
+ * support is gated behind [visionCapable]: when `false`, `image_url` parts
+ * return a 400 pointing at the model's lack of vision capability rather than
+ * silently ignoring them. PluginState (Task 48) toggles the flag from the
+ * caller-supplied `visionEnabled` start option.
+ *
+ * ## Streaming envelope
+ *
+ * Emits one role-only delta frame, then one content delta frame per MediaPipe
+ * progress callback (with `finish_reason: "stop"` on the final frame), then a
+ * literal `[DONE]` terminator. Frame count therefore varies with the number of
+ * tokens generated — there is no fixed envelope size. Server-side buffering in
+ * [HandlerDispatch] still collects everything before flush in Phase 1, so
+ * clients see all frames together; per-token streaming lands when dispatch
+ * grows a flush-per-chunk path.
+ *
+ * ## Streaming envelope parity (with [LlamaHandlers])
+ *
+ * The two backends emit slightly different shapes — both valid per OpenAI's
+ * spec, but worth documenting so readers don't assume identical behavior:
+ *
+ *  - [LlamaHandlers] emits: role / content / **separate empty-delta finish
+ *    frame with `finish_reason: "stop"`** / `[DONE]` (fixed 4-frame shape).
+ *  - [MediaPipeHandlers] emits: role / content₁ … content_N (last frame
+ *    carries `finish_reason: "stop"` alongside its content) / `[DONE]`
+ *    (variable frame count).
+ *
+ * Clients that accumulate `delta.content` see the full text in both cases.
+ * Clients that gate on `finish_reason` see it on the trailing chunk in both
+ * cases — just empty-delta in Llama, content-bearing in MediaPipe. The
+ * asymmetry is intentional: LlamaHandlers wraps a single completePrompt call
+ * with no intra-token signal, while MediaPipe's progress callback already
+ * surfaces the `done` flag inline with the final content chunk.
+ *
+ * All bridge-touching paths are serialized via [bridgeMutex] because
+ * `LlmInferenceSession` is not safe to use from multiple concurrent callers.
+ */
+class MediaPipeHandlers(
+    private val bridge: MediaPipeBridgeApi,
+    private val modelId: String,
+    /**
+     * `true` when the loaded MediaPipe `.task` bundle is a vision-capable
+     * Gemma variant AND PluginState has wired the bridge with
+     * `visionEnabled = true`. Defaults to `false` so non-vision deployments
+     * (the common case) reject image parts with a clear 400.
+     */
+    private val visionCapable: Boolean = false,
+) : DvaiHandlers {
+    private val bridgeMutex = Mutex()
+
+    override suspend fun handleChatCompletion(body: JsonObject, ctx: HandlerContext): HandlerResponse {
+        val messages = body["messages"] as? JsonArray
+            ?: return HandlerResponse.Error(400, "Missing 'messages' field")
+
+        // Walk content parts up-front: collect images for vision-capable
+        // models, reject audio (always unsupported), and reject image_url for
+        // non-vision models. Mirrors LlamaHandlers/FoundationHandlers ordering.
+        // Images are collected as raw bytes; ByteArray → MPImage conversion
+        // happens inside the bridge implementation.
+        val images = mutableListOf<ByteArray>()
+        for (msg in messages) {
+            val msgObj = msg as? JsonObject ?: continue
+            val content = msgObj["content"] as? JsonArray ?: continue
+            for (part in content) {
+                val partObj = part as? JsonObject ?: continue
+                val type = (partObj["type"] as? JsonPrimitive)?.contentOrNull
+                if (type == "image_url") {
+                    if (!visionCapable) {
+                        return HandlerResponse.Error(
+                            400,
+                            "Image input requires a vision-capable MediaPipe model. " +
+                                "Loaded model has no vision capability — pass " +
+                                "`visionEnabled: true` to start() with a Gemma 3n " +
+                                "vision-capable .task bundle to enable image input.",
+                        )
+                    }
+                    val urlStr = (partObj["image_url"] as? JsonObject)
+                        ?.get("url")
+                        ?.let { it as? JsonPrimitive }
+                        ?.contentOrNull
+                    if (urlStr.isNullOrEmpty()) {
+                        return HandlerResponse.Error(
+                            400,
+                            "image_url part missing 'url' field",
+                        )
+                    }
+                    val bytes = try {
+                        withContext(Dispatchers.IO) { ImageDecoder.resolve(urlStr) }
+                    } catch (e: Exception) {
+                        // Fetch / decode failure — 502 per spec §8.5 wording.
+                        return HandlerResponse.Error(
+                            502,
+                            "Failed to fetch image: ${e.message ?: "unknown error"}",
+                        )
+                    }
+                    images.add(bytes)
+                }
+                if (type == "input_audio") {
+                    return HandlerResponse.Error(
+                        400,
+                        "Audio input not supported on MediaPipe LLM " +
+                            "(no audio-capable tasks-genai task).",
+                    )
+                }
+            }
+        }
+
+        if (messages.isEmpty()) {
+            return HandlerResponse.Error(400, "Empty 'messages' array")
+        }
+
+        val prompt = openAIMessagesToPrompt(messages)
+        val isStream = (body["stream"] as? JsonPrimitive)?.booleanOrNull ?: false
+
+        val id = "chatcmpl-mp-" + UUID.randomUUID().toString().take(20).lowercase()
+        val created = System.currentTimeMillis() / 1000L
+
+        if (isStream) {
+            return HandlerResponse.Sse(
+                buildChatStreamFrames(id = id, created = created, prompt = prompt, images = images),
+            )
+        }
+
+        val text = try {
+            bridgeMutex.withLock {
+                withContext(Dispatchers.IO) { bridge.completePrompt(prompt, images) }
+            }
+        } catch (e: Exception) {
+            return HandlerResponse.Error(500, e.message ?: "Inference failed")
+        }
+
+        val response = buildJsonObject {
+            put("id", id)
+            put("object", "chat.completion")
+            put("created", created)
+            put("model", modelId)
+            putJsonArray("choices") {
+                addJsonObject {
+                    put("index", 0)
+                    putJsonObject("message") {
+                        put("role", "assistant")
+                        put("content", text)
+                    }
+                    put("finish_reason", "stop")
+                }
+            }
+            putJsonObject("usage") {
+                put("prompt_tokens", 0)
+                put("completion_tokens", 0)
+                put("total_tokens", 0)
+            }
+        }
+        return HandlerResponse.Json(200, response)
+    }
+
+    override suspend fun handleCompletion(body: JsonObject, ctx: HandlerContext): HandlerResponse {
+        val promptField = body["prompt"]
+        val prompt: String = when {
+            promptField == null || promptField is JsonNull -> ""
+            promptField is JsonPrimitive && promptField.contentOrNull != null -> promptField.content
+            promptField is JsonArray -> promptField.joinToString("\n") {
+                (it as? JsonPrimitive)?.contentOrNull ?: ""
+            }
+            else -> return HandlerResponse.Error(400, "'prompt' must be a string or array of strings")
+        }
+
+        val chatBody = buildJsonObject {
+            for ((k, v) in body) {
+                if (k == "prompt") continue
+                put(k, v)
+            }
+            putJsonArray("messages") {
+                addJsonObject {
+                    put("role", "user")
+                    put("content", prompt)
+                }
+            }
+        }
+
+        val chatResp = handleChatCompletion(chatBody, ctx)
+        return when (chatResp) {
+            is HandlerResponse.Json -> {
+                // Smart cast across the shared-core module boundary doesn't work;
+                // bind to a local val and cast once. See LlamaHandlers.kt for the
+                // same fix.
+                val respBody = chatResp.body
+                if (chatResp.status != 200 || respBody !is JsonObject) {
+                    chatResp
+                } else {
+                    HandlerResponse.Json(200, chatToLegacyCompletion(respBody))
+                }
+            }
+            is HandlerResponse.Sse -> {
+                val model = (body["model"] as? JsonPrimitive)?.contentOrNull ?: modelId
+                HandlerResponse.Sse(
+                    flow {
+                        chatResp.flow.collect { chunk ->
+                            emit(adaptChunkToLegacy(chunk, model))
+                        }
+                    },
+                )
+            }
+            is HandlerResponse.Error -> chatResp
+        }
+    }
+
+    override suspend fun handleEmbeddings(body: JsonObject, ctx: HandlerContext): HandlerResponse =
+        HandlerResponse.Error(
+            400,
+            "Embeddings not supported on MediaPipe LLM. " +
+                "Use capacitorBackend: \"llama\" with nativeEmbeddingMode: true.",
+        )
+
+    override suspend fun handleModels(ctx: HandlerContext): HandlerResponse =
+        HandlerResponse.Json(
+            200,
+            buildJsonObject {
+                put("object", "list")
+                putJsonArray("data") {
+                    addJsonObject {
+                        put("id", ctx.modelId)
+                        put("object", "model")
+                        put("owned_by", "google-mediapipe")
+                    }
+                }
+            },
+        )
+
+    // ----- Streaming -----
+
+    /**
+     * Build the SSE envelope: role frame + N content frames (last carries
+     * `finish_reason: "stop"`) + `[DONE]` terminator. Frame count varies with
+     * token count — see the "Streaming envelope parity" note in this class's
+     * KDoc for the documented divergence from [LlamaHandlers].
+     *
+     * Acquires [bridgeMutex] for the lifetime of the stream and releases it
+     * in [awaitClose] — guarantees serialization with non-streaming requests
+     * AND mutex release on either successful completion or coroutine
+     * cancellation.
+     */
+    private fun buildChatStreamFrames(
+        id: String,
+        created: Long,
+        prompt: String,
+        images: List<ByteArray>,
+    ): Flow<String> = callbackFlow {
+        // Serialize against any other bridge use for the entire stream lifetime.
+        // Track ownership explicitly via a local flag so we never depend on the
+        // racy `Mutex.isLocked` snapshot read for unlock decisions.
+        var unlocked = false
+        bridgeMutex.lock()
+        fun safeUnlock() {
+            if (!unlocked) {
+                unlocked = true
+                bridgeMutex.unlock()
+            }
+        }
+
+        // Role chunk (first frame of the envelope).
+        val roleChunk = buildJsonObject {
+            put("id", id); put("object", "chat.completion.chunk")
+            put("created", created); put("model", modelId)
+            putJsonArray("choices") {
+                addJsonObject {
+                    put("index", 0)
+                    putJsonObject("delta") { put("role", "assistant") }
+                }
+            }
+        }
+        trySend("data: $roleChunk\n\n")
+
+        val handle: AutoCloseable = try {
+            bridge.completePromptAsync(prompt, images) { partial, done ->
+                // Content-delta chunk for every (partial, done) pair. When `done`
+                // is true the final frame carries finish_reason="stop"; otherwise
+                // finish_reason is null.
+                val chunk = buildJsonObject {
+                    put("id", id); put("object", "chat.completion.chunk")
+                    put("created", created); put("model", modelId)
+                    putJsonArray("choices") {
+                        addJsonObject {
+                            put("index", 0)
+                            putJsonObject("delta") { put("content", partial) }
+                            if (done) {
+                                put("finish_reason", "stop")
+                            } else {
+                                put("finish_reason", JsonNull)
+                            }
+                        }
+                    }
+                }
+                trySend("data: $chunk\n\n")
+                if (done) {
+                    trySend("data: [DONE]\n\n")
+                    close()
+                }
+            }
+        } catch (e: Exception) {
+            // Generation failed to start. Emit an error chunk + [DONE] so the
+            // client sees a well-formed SSE close, then complete the flow with
+            // the exception (collector receives it).
+            //
+            // finish_reason uses the OpenAI-standard "stop" value; the failure
+            // signal is conveyed via the sibling `error` field. (OpenAI's spec
+            // restricts finish_reason to stop|length|tool_calls|content_filter|
+            // function_call|null, so we don't invent an "error" value.)
+            val errChunk = buildJsonObject {
+                put("id", id); put("object", "chat.completion.chunk")
+                put("created", created); put("model", modelId)
+                putJsonArray("choices") {
+                    addJsonObject {
+                        put("index", 0)
+                        putJsonObject("delta") { /* empty */ }
+                        put("finish_reason", "stop")
+                    }
+                }
+                putJsonObject("error") { put("message", e.message ?: "Inference failed") }
+            }
+            trySend("data: $errChunk\n\n")
+            trySend("data: [DONE]\n\n")
+            close(e)
+            // Release the mutex synchronously — awaitClose still runs but
+            // there is no AutoCloseable handle to call close() on.
+            safeUnlock()
+            return@callbackFlow
+        }
+
+        awaitClose {
+            try {
+                handle.close()
+            } catch (_: Throwable) { /* best-effort */ }
+            safeUnlock()
+        }
+    }
+
+    // ----- Helpers -----
+
+    /**
+     * Flatten OpenAI chat messages into a single `role: content` newline-joined
+     * prompt string. Multimodal content arrays are reduced to their `text`
+     * parts (image / audio parts are rejected before this method is reached).
+     */
+    private fun openAIMessagesToPrompt(messages: JsonArray): String =
+        messages.mapNotNull { msg ->
+            val msgObj = msg as? JsonObject ?: return@mapNotNull null
+            val role = (msgObj["role"] as? JsonPrimitive)?.contentOrNull ?: "user"
+            val content = msgObj["content"]
+            when (content) {
+                is JsonPrimitive -> "$role: ${content.contentOrNull ?: ""}"
+                is JsonArray -> {
+                    val texts = content.mapNotNull inner@{ part ->
+                        val partObj = part as? JsonObject ?: return@inner null
+                        if ((partObj["type"] as? JsonPrimitive)?.contentOrNull == "text") {
+                            (partObj["text"] as? JsonPrimitive)?.contentOrNull
+                        } else {
+                            null
+                        }
+                    }
+                    if (texts.isNotEmpty()) "$role: ${texts.joinToString(" ")}" else null
+                }
+                else -> null
+            }
+        }.joinToString("\n")
+
+    /** Mirrors `chatToLegacyCompletion()` from `packages/dvai-bridge-core`. */
+    private fun chatToLegacyCompletion(chat: JsonObject): JsonObject = buildJsonObject {
+        val chatId = (chat["id"] as? JsonPrimitive)?.contentOrNull ?: ""
+        val cmplId = if (chatId.isEmpty()) {
+            "cmpl-${System.currentTimeMillis() / 1000L}"
+        } else {
+            chatId.replace("chatcmpl-", "cmpl-")
+        }
+        put("id", cmplId)
+        put("object", "text_completion")
+        chat["created"]?.let { put("created", it) }
+            ?: put("created", System.currentTimeMillis() / 1000L)
+        put("model", (chat["model"] as? JsonPrimitive)?.contentOrNull ?: modelId)
+        putJsonArray("choices") {
+            val chatChoices = chat["choices"] as? JsonArray ?: JsonArray(emptyList())
+            for (c in chatChoices) {
+                val co = c as? JsonObject ?: continue
+                addJsonObject {
+                    val msg = co["message"] as? JsonObject
+                    put("text", (msg?.get("content") as? JsonPrimitive)?.contentOrNull ?: "")
+                    put("index", (co["index"] as? JsonPrimitive)?.intOrNull ?: 0)
+                    put(
+                        "finish_reason",
+                        (co["finish_reason"] as? JsonPrimitive)?.contentOrNull ?: "stop",
+                    )
+                    put("logprobs", JsonNull)
+                }
+            }
+        }
+        val usage = chat["usage"] as? JsonObject
+        if (usage != null) {
+            put("usage", usage)
+        } else {
+            putJsonObject("usage") {
+                put("prompt_tokens", 0)
+                put("completion_tokens", 0)
+                put("total_tokens", 0)
+            }
+        }
+    }
+
+    /** Adapt a single SSE frame from chat.completion.chunk -> text_completion.chunk. */
+    private fun adaptChunkToLegacy(chunk: String, model: String): String {
+        val trimmed = chunk.trim()
+        if (!trimmed.startsWith("data:")) return chunk
+        val payload = trimmed.removePrefix("data:").trim()
+        if (payload == "[DONE]") return "data: [DONE]\n\n"
+        val parsed = try {
+            Json.parseToJsonElement(payload) as? JsonObject ?: return chunk
+        } catch (_: Exception) {
+            return chunk
+        }
+        val chatId = (parsed["id"] as? JsonPrimitive)?.contentOrNull ?: ""
+        val id = chatId.replace("chatcmpl-", "cmpl-")
+        val legacy = buildJsonObject {
+            put("id", id)
+            put("object", "text_completion.chunk")
+            parsed["created"]?.let { put("created", it) }
+                ?: put("created", System.currentTimeMillis() / 1000L)
+            put("model", (parsed["model"] as? JsonPrimitive)?.contentOrNull ?: model)
+            putJsonArray("choices") {
+                val chatChoices = parsed["choices"] as? JsonArray ?: JsonArray(emptyList())
+                for (c in chatChoices) {
+                    val co = c as? JsonObject ?: continue
+                    addJsonObject {
+                        val delta = co["delta"] as? JsonObject
+                        put("text", (delta?.get("content") as? JsonPrimitive)?.contentOrNull ?: "")
+                        put("index", (co["index"] as? JsonPrimitive)?.intOrNull ?: 0)
+                        val fr = co["finish_reason"]
+                        if (fr is JsonPrimitive && fr.contentOrNull != null) {
+                            put("finish_reason", fr.content)
+                        } else {
+                            put("finish_reason", JsonNull)
+                        }
+                        put("logprobs", JsonNull)
+                    }
+                }
+            }
+        }
+        return "data: $legacy\n\n"
+    }
+}