DVAI-Bridge

Appearance

Migrating from v1.6 to v2.0 ​

v2.0 is the first release after v1.6. The [1.7.0] and [1.8.0] sections that previously sat in CHANGELOG.md were CHANGELOG-only — never tagged on GitHub — and are now folded into v2.0. v2.0 covers Phase 3A (the *-core extraction across the iOS + Android Capacitor plugins), Phase 3B (Android-mediapipe-core's tasks-genai → LiteRT-LM runtime swap), and Phase 3C (the standalone iOS Native SDK with the new MLX, CoreML, and Apple Foundation Models backends).

Almost every v2.0 change is additive — new iOS native SDK, new MLX backend, new Capacitor MLX plugin, new shared-core extraction. A few breaking changes hit direct consumers of the lower-level Swift packages. The OpenAI-compatible HTTP surface, the JS Capacitor shim, and the published web/transport API are all unchanged.

Already on v2.0 and looking for v2.1 (Android Native SDK) or v2.2 (React Native)? See v2.0 → v2.1 and v2.1 → v2.2.

Quick decision matrix ​

If you are using…Migration
@dvai-bridge/core (web)None.
@dvai-bridge/transformers (web)None.
@dvai-bridge/capacitor + capacitor-llama / capacitor-foundation / capacitor-mediapipeNone.
@dvai-bridge/ios-llama-core directly (Swift)Add import DVAISharedCore for HandlerContext / DVAIHandlers / HttpServer / CORSConfig.
@dvai-bridge/ios-foundation-core directly (Swift)Rename internal PluginState → FoundationPluginState. Add import DVAISharedCore for shared types.

Most apps fit the first three rows and need no changes.

What's new (additive — no migration needed) ​

  • @dvai-bridge/ios — standalone iOS SwiftPM/CocoaPods SDK. Drop it into a SwiftUI / UIKit app, call DVAIBridge.shared.start(...), point your OpenAI client at the returned baseUrl. See iOS Native SDK guide.
  • MLX backend (@dvai-bridge/ios-mlx-core + @dvai-bridge/capacitor-mlx). Apple-Silicon GPU + Neural Engine LLM inference via mlx-swift-lm. Pass modelPath: "mlx-community/Llama-3.2-1B-Instruct-4bit" — that's an HF model id, not a local path. See MLX Backend guide.
  • CoreML backend (@dvai-bridge/ios's DVAICoreMLCore target) — full stateful MLState-based inference for .mlmodelc checkpoints.
  • DVAISharedCore package — shared HTTP-server / handler-dispatch types extracted out of DVAILlamaCore so non-llama backends don't transitively pull llama.xcframework. Internal refactor — if you only use DVAIBridge.shared you won't notice.
  • Apple Foundation Models backend — the BackendKind.foundation case wraps LanguageModelSession for zero-download text on iOS 26+. SwiftPM-only — a CocoaPods limitation. See iOS Native SDK guide.
  • Phase 3A *-core extraction (iOS + Android) — each Capacitor plugin's portable native code now lives in a separate *-core package (@dvai-bridge/ios-llama-core, @dvai-bridge/ios-foundation-core, @dvai-bridge/android-llama-core, @dvai-bridge/android-mediapipe-core) so the same source feeds both the Capacitor wrapper and the upcoming standalone native SDKs. Capacitor-side users see no change — the wrapper packages now declare the cores as peerDependencies.
  • Phase 3B Android-mediapipe-core runtime swap — @dvai-bridge/android-mediapipe-core migrated from the deprecated com.google.mediapipe:tasks-genai:0.10.33 SDK to a single artifact com.google.ai.edge.litertlm:litertlm-android:0.10.2. Same handler behaviour, same Capacitor JS contract — the migration is transparent to JS callers.

Breaking changes (only affect direct Swift package consumers) ​

1. HandlerContext / DVAIHandlers / HandlerResponse / HttpServer / CORSConfig moved ​

Previously these public types lived in DVAILlamaCore. v2.0 pulls them out into a new DVAISharedCore package — so non-llama backends don't inherit llama.xcframework.

Before (v1.6) ​

swift
import DVAILlamaCore

let handlers: DVAIHandlers = MyHandlers()
let ctx = HandlerContext(modelId: "x", backendName: "y")
let server = HttpServer()

After (v2.0) ​

swift
import DVAISharedCore   // ← new
import DVAILlamaCore    // still need this if you also use PluginState / ModelDownloader / LlamaHandlers

let handlers: DVAIHandlers = MyHandlers()
let ctx = HandlerContext(modelId: "x", backendName: "y")
let server = HttpServer()

SwiftPM consumers also need to add DVAISharedCore to their target's dependencies in Package.swift:

swift
.package(path: "path/to/dvai-bridge-ios-shared-core"),
// ...
dependencies: [
    .product(name: "DVAISharedCore", package: "dvai-bridge-ios-shared-core"),
]

CocoaPods consumers using the umbrella DVAIBridge.podspec don't need to change anything — the pod imports everything in a single Swift module.

2. DVAIFoundationCore.PluginState renamed to FoundationPluginState ​

The Foundation Models core's PluginState actor was renamed to FoundationPluginState — to disambiguate it from DVAILlamaCore.PluginState when both cores are bundled into the same Swift module (e.g. under CocoaPods).

Before ​

swift
import DVAIFoundationCore
let state = PluginState()

After ​

swift
import DVAIFoundationCore
let state = FoundationPluginState()

Same applies to internal-only FoundationHttpServer (was HttpServer until v1.8) — it's been removed entirely in favour of DVAISharedCore.HttpServer.

3. BackendKind enum gained .mlx ​

The Swift BackendKind enum (in @dvai-bridge/ios) and the JS CapacitorBackend type (in @dvai-bridge/capacitor) now include .mlx / "mlx".

If you exhaustively switch on these enums, add a case .mlx: branch — or a default:.

That's the only Swift-source breaking change visible to apps using DVAIBridge.shared. Exhaustive switches were the only public API that could be affected by the new case.

4. BackendSelector.resolve(.auto, …) now errors on HF-id-shaped paths ​

Before: passing modelPath: "owner/repo" (no file extension) to .auto resolution returned a generic configurationInvalid("auto backend can't infer …") error. v2.0 treats that pattern as an explicit hint that the consumer might mean MLX — and emits a clearer error: "if this is an MLX-converted checkpoint, set DVAIBridgeConfig.backend = .mlx explicitly".

If you were matching on the previous error string, update it.

CocoaPods asymmetries (worth knowing) ​

The single-pod CocoaPods build collapses every Swift module into one DVAIBridge Swift module. That's incompatible with three SwiftPM-only patterns — so CocoaPods consumers see slightly less of the SDK:

  • DVAIBridgeReactiveState doesn't conform to ObservableObject. Subscribe to the stateChanges: AnyPublisher<Void, Never> instead.
  • The .foundation backend is unavailable — private-framework autolink. Selecting it throws DVAIBridgeError.backendUnavailable.
  • The .mlx backend is unavailable — mlx-swift-lm's transitive deps don't publish CocoaPods specs. Selecting it throws the same.

CocoaPods consumers can pair .llama and .coreml — together they cover the broad on-device-LLM case. For full backend coverage, use SwiftPM.

See the full iOS Native SDK guide § CocoaPods asymmetries for the reasons.

Versioning policy going forward ​

From v2.0 onward:

  • Version bumps and git tags happen at whole-phase boundaries (Phase 3 = 3A + 3B + 3C + 3D combined) — not per sub-phase.
  • Tag-first, then CHANGELOG entry. Untagged versions are placeholders.
  • Breaking-change releases (major bumps) ship with a migration guide in docs/migration/.

Pre-existing migration ​

Still on v1.5.x? See v1.5 → v1.6 migration first.

Newer migration guides ​

  • v2.0 → v2.1 (Android Native SDK + LiteRT backend) — see v2.0 → v2.1 migration.
  • v2.1 → v2.2 (React Native module) — see v2.1 → v2.2 migration.
  • v2.2 → v2.3 (Flutter plugin + Android AAR republish) — see v2.2 → v2.3 migration. Flutter is the first family member published to pub.dev (public); existing iOS / Android / React Native consumers see no behaviour changes.