@dvai-bridge/android 4.0.0 → 4.0.2

package/android/src/main/java/co/deepvoiceai/bridge/DVAIBridgeConfig.kt

@@ -1,119 +1,119 @@
-package co.deepvoiceai.bridge
-
-import co.deepvoiceai.bridge.shared.core.CorsConfig
-import co.deepvoiceai.bridge.shared.core.offload.OffloadConfig
-
-/**
- * Options accepted by [DVAIBridge.start]. Mirrors the iOS DVAIBridge
- * `StartOptions` struct + the Capacitor JS shim's StartOptions.
- *
- * @param backend             Which backend to use. [BackendKind.Auto] resolves
- *                            via [BackendSelector] at start-time.
- * @param modelPath           Filesystem path to the model checkpoint. Required
- *                            for Llama (.gguf), MediaPipe (.task), and LiteRT
- *                            (.tflite / .litertlm) backends.
- * @param tokenizerPath       Filesystem path to a directory containing
- *                            tokenizer.json (and optional tokenizer_config.json).
- *                            Required for the LiteRT backend; ignored otherwise.
- * @param mmprojPath          Optional multimodal projector path for Llama
- *                            (vision/audio LLMs).
- * @param chatTemplate        Optional Jinja chat template override (Llama backend
- *                            only). Falls back to the model's bundled template.
- * @param gpuLayers           Llama backend: number of transformer layers to
- *                            offload to GPU (Vulkan / OpenCL on supported
- *                            devices). 99 = all layers, 0 = CPU only. Ignored
- *                            by other backends.
- * @param contextSize         Context window in tokens. Defaults to 2048.
- * @param threads             CPU thread count for the inference loop. Llama
- *                            uses this directly; LiteRT/MediaPipe pick their
- *                            own threading by default.
- * @param embeddingMode       Llama backend: open the model in
- *                            embedding-extraction mode rather than completion
- *                            mode. Mutually exclusive with chat completion.
- * @param visionEnabled       MediaPipe backend: open the LiteRT-LM EngineConfig
- *                            with `visionBackend` enabled.
- * @param temperature         LiteRT backend: sampling temperature (0 = greedy).
- * @param topP                LiteRT backend: nucleus sampling cutoff (1 = disabled).
- * @param topK                LiteRT backend: top-K truncation (0 = disabled).
- * @param maxNewTokens        LiteRT backend: hard cap on tokens generated per request.
- * @param httpBasePort        First port the HTTP server tries to bind. Defaults
- *                            to 38883 (matches the rest of the dvai-bridge family).
- * @param httpMaxPortAttempts Number of consecutive ports to try before giving
- *                            up. Defaults to 16.
- * @param corsOrigin          CORS allow-origin policy. See [CorsConfig].
- *                            Defaults to wildcard.
- * @param modelId             Optional override for the model id surfaced via
- *                            `/v1/models`. Defaults to the file name minus
- *                            extension when null.
- */
-data class StartOptions(
-    val backend: BackendKind = BackendKind.Auto,
-    val modelPath: String? = null,
-    val tokenizerPath: String? = null,
-    val mmprojPath: String? = null,
-    val chatTemplate: String? = null,
-    val gpuLayers: Int = 99,
-    val contextSize: Int = 2048,
-    val threads: Int = 4,
-    val embeddingMode: Boolean = false,
-    val visionEnabled: Boolean = false,
-    val temperature: Float = 0f,
-    val topP: Float = 1f,
-    val topK: Int = 0,
-    val maxNewTokens: Int = 512,
-    val httpBasePort: Int = 38883,
-    val httpMaxPortAttempts: Int = 16,
-    val corsOrigin: CorsConfig = CorsConfig.Wildcard,
-    val modelId: String? = null,
-    /**
-     * Phase 3 — opt-in distributed inference / device offload. When
-     * `enabled = true`, [DVAIBridge] spins up an [NsdDiscovery] +
-     * [NsdAdvertiser], a [CapabilityCache], and a [PairingPolicy]
-     * whose `requests` Flow is exposed via `DVAIBridge.pairingRequests`
-     * for the host UI. Default null = behave exactly like v2.x.
-     */
-    val offload: OffloadConfig? = null,
-    /**
-     * v3.3 — offline JWT license validator config. When non-null, the
-     * SDK loads the JWT from this filesystem path and verifies it at
-     * startup. Auto-discovery (assets/, res/raw/, filesDir/) runs when
-     * BOTH this AND [licenseToken] are null.
-     *
-     * Production Android builds without a valid license throw
-     * [co.deepvoiceai.bridge.license.LicenseRequiredError] from
-     * [DVAIBridge.start]. Debug builds (`hostBuildConfigDebug = true`
-     * or `ApplicationInfo.FLAG_DEBUGGABLE`) skip validation entirely.
-     */
-    val licenseKeyPath: String? = null,
-    /**
-     * v3.3 — inline JWT license token. Overrides every other discovery
-     * source. Useful for CI / test contexts where reading a file isn't
-     * practical and operators inject via env var or build config.
-     */
-    val licenseToken: String? = null,
-    /**
-     * v3.3 — the host app's `BuildConfig.DEBUG` value, passed through to
-     * the license validator's dev-mode bypass. When true the validator
-     * returns `FreeDev` without trying to verify anything; when false (or
-     * null) the validator falls back to `ApplicationInfo.FLAG_DEBUGGABLE`.
-     *
-     * Pass `BuildConfig.DEBUG` from your app module here — the validator
-     * lives in this library module whose own `BuildConfig.DEBUG` never
-     * reflects the host app's state.
-     */
-    val hostBuildConfigDebug: Boolean? = null,
-)
-
-/** Options for [DVAIBridge.downloadModel]. */
-data class DownloadOptions(
-    val url: String,
-    val sha256: String,
-    val destFilename: String,
-)
-
-/** Result of a successful [DVAIBridge.downloadModel] call. */
-data class DownloadResult(
-    val path: String,
-    val sha256: String,
-    val sizeBytes: Long,
-)
+package co.deepvoiceai.bridge
+
+import co.deepvoiceai.bridge.shared.core.CorsConfig
+import co.deepvoiceai.bridge.shared.core.offload.OffloadConfig
+
+/**
+ * Options accepted by [DVAIBridge.start]. Mirrors the iOS DVAIBridge
+ * `StartOptions` struct + the Capacitor JS shim's StartOptions.
+ *
+ * @param backend             Which backend to use. [BackendKind.Auto] resolves
+ *                            via [BackendSelector] at start-time.
+ * @param modelPath           Filesystem path to the model checkpoint. Required
+ *                            for Llama (.gguf), MediaPipe (.task), and LiteRT
+ *                            (.tflite / .litertlm) backends.
+ * @param tokenizerPath       Filesystem path to a directory containing
+ *                            tokenizer.json (and optional tokenizer_config.json).
+ *                            Required for the LiteRT backend; ignored otherwise.
+ * @param mmprojPath          Optional multimodal projector path for Llama
+ *                            (vision/audio LLMs).
+ * @param chatTemplate        Optional Jinja chat template override (Llama backend
+ *                            only). Falls back to the model's bundled template.
+ * @param gpuLayers           Llama backend: number of transformer layers to
+ *                            offload to GPU (Vulkan / OpenCL on supported
+ *                            devices). 99 = all layers, 0 = CPU only. Ignored
+ *                            by other backends.
+ * @param contextSize         Context window in tokens. Defaults to 2048.
+ * @param threads             CPU thread count for the inference loop. Llama
+ *                            uses this directly; LiteRT/MediaPipe pick their
+ *                            own threading by default.
+ * @param embeddingMode       Llama backend: open the model in
+ *                            embedding-extraction mode rather than completion
+ *                            mode. Mutually exclusive with chat completion.
+ * @param visionEnabled       MediaPipe backend: open the LiteRT-LM EngineConfig
+ *                            with `visionBackend` enabled.
+ * @param temperature         LiteRT backend: sampling temperature (0 = greedy).
+ * @param topP                LiteRT backend: nucleus sampling cutoff (1 = disabled).
+ * @param topK                LiteRT backend: top-K truncation (0 = disabled).
+ * @param maxNewTokens        LiteRT backend: hard cap on tokens generated per request.
+ * @param httpBasePort        First port the HTTP server tries to bind. Defaults
+ *                            to 38883 (matches the rest of the dvai-bridge family).
+ * @param httpMaxPortAttempts Number of consecutive ports to try before giving
+ *                            up. Defaults to 16.
+ * @param corsOrigin          CORS allow-origin policy. See [CorsConfig].
+ *                            Defaults to wildcard.
+ * @param modelId             Optional override for the model id surfaced via
+ *                            `/v1/models`. Defaults to the file name minus
+ *                            extension when null.
+ */
+data class StartOptions(
+    val backend: BackendKind = BackendKind.Auto,
+    val modelPath: String? = null,
+    val tokenizerPath: String? = null,
+    val mmprojPath: String? = null,
+    val chatTemplate: String? = null,
+    val gpuLayers: Int = 99,
+    val contextSize: Int = 2048,
+    val threads: Int = 4,
+    val embeddingMode: Boolean = false,
+    val visionEnabled: Boolean = false,
+    val temperature: Float = 0f,
+    val topP: Float = 1f,
+    val topK: Int = 0,
+    val maxNewTokens: Int = 512,
+    val httpBasePort: Int = 38883,
+    val httpMaxPortAttempts: Int = 16,
+    val corsOrigin: CorsConfig = CorsConfig.Wildcard,
+    val modelId: String? = null,
+    /**
+     * Phase 3 — opt-in distributed inference / device offload. When
+     * `enabled = true`, [DVAIBridge] spins up an [NsdDiscovery] +
+     * [NsdAdvertiser], a [CapabilityCache], and a [PairingPolicy]
+     * whose `requests` Flow is exposed via `DVAIBridge.pairingRequests`
+     * for the host UI. Default null = behave exactly like v2.x.
+     */
+    val offload: OffloadConfig? = null,
+    /**
+     * v3.3 — offline JWT license validator config. When non-null, the
+     * SDK loads the JWT from this filesystem path and verifies it at
+     * startup. Auto-discovery (assets/, res/raw/, filesDir/) runs when
+     * BOTH this AND [licenseToken] are null.
+     *
+     * Production Android builds without a valid license throw
+     * [co.deepvoiceai.bridge.license.LicenseRequiredError] from
+     * [DVAIBridge.start]. Debug builds (`hostBuildConfigDebug = true`
+     * or `ApplicationInfo.FLAG_DEBUGGABLE`) skip validation entirely.
+     */
+    val licenseKeyPath: String? = null,
+    /**
+     * v3.3 — inline JWT license token. Overrides every other discovery
+     * source. Useful for CI / test contexts where reading a file isn't
+     * practical and operators inject via env var or build config.
+     */
+    val licenseToken: String? = null,
+    /**
+     * v3.3 — the host app's `BuildConfig.DEBUG` value, passed through to
+     * the license validator's dev-mode bypass. When true the validator
+     * returns `FreeDev` without trying to verify anything; when false (or
+     * null) the validator falls back to `ApplicationInfo.FLAG_DEBUGGABLE`.
+     *
+     * Pass `BuildConfig.DEBUG` from your app module here — the validator
+     * lives in this library module whose own `BuildConfig.DEBUG` never
+     * reflects the host app's state.
+     */
+    val hostBuildConfigDebug: Boolean? = null,
+)
+
+/** Options for [DVAIBridge.downloadModel]. */
+data class DownloadOptions(
+    val url: String,
+    val sha256: String,
+    val destFilename: String,
+)
+
+/** Result of a successful [DVAIBridge.downloadModel] call. */
+data class DownloadResult(
+    val path: String,
+    val sha256: String,
+    val sizeBytes: Long,
+)

package/android/src/main/java/co/deepvoiceai/bridge/license/Audience.kt

@@ -1,134 +1,134 @@
-package co.deepvoiceai.bridge.license
-
-import android.content.Context
-import android.content.pm.ApplicationInfo
-
-/**
- * Runtime audience + platform + dev-mode detection for the Android SDK.
- *
- * Kotlin port of `packages/dvai-bridge-core/src/license/audience.ts`.
- * The semantics are identical to the JS side but the platform APIs
- * differ — audience is read from [Context.getPackageName] rather than
- * `window.location.hostname`, and dev-mode is detected via
- * `BuildConfig.DEBUG` + `ApplicationInfo.FLAG_DEBUGGABLE` rather than
- * hostname heuristics.
- *
- * "Audience" on Android = the host app's package name (e.g.
- * `"com.acme.app"`). License JWTs bind to package names exactly like
- * iOS bundle ids; subdomain-style `*.acme.com` wildcards work for
- * domain-tail matching too.
- *
- * "Dev mode" detection bypasses license enforcement entirely so
- * developers don't need a license to run the SDK on a debug build.
- * This matches the JS-side `detectDevMode()` behaviour.
- */
-
-/** Detect the current SDK platform identifier. Always [DvaiPlatform.ANDROID]. */
-fun detectPlatform(): DvaiPlatform = DvaiPlatform.ANDROID
-
-/**
- * Detect the current audience string the license must bind. Returns
- * the host app's package name from [Context.getPackageName].
- *
- * Returns null only if [context] is null — in practice this never
- * happens because [LicenseValidator] requires a non-null context at
- * construction.
- */
-fun detectAudience(context: Context?): String? = context?.packageName
-
-/**
- * Detect whether the SDK is running in a developer environment where
- * license enforcement should be bypassed. The bypass list is
- * intentionally generous: blocking a developer mid-`./gradlew installDebug`
- * with a license-not-found error would be hostile.
- *
- * Precedence (highest first):
- *   1. `DVAI_FORCE_PROD=1` env var — production mode forced, overrides DEBUG.
- *   2. `DVAI_FORCE_DEV=1` env var — dev mode forced.
- *   3. [hostBuildConfigDebug] (a `BuildConfig.DEBUG` value passed in by the
- *      host app via [co.deepvoiceai.bridge.StartOptions]) — dev mode.
- *   4. [ApplicationInfo.FLAG_DEBUGGABLE] on the host app — dev mode.
- *   5. Otherwise production, license required.
- *
- * @param context              Application context — used to read
- *                             `ApplicationInfo.FLAG_DEBUGGABLE`.
- * @param hostBuildConfigDebug The host app's `BuildConfig.DEBUG`, passed in
- *                             explicitly because the validator lives in a
- *                             library module whose own `BuildConfig.DEBUG`
- *                             never reflects the host app's state. Pass null
- *                             to skip this check.
- */
-fun detectDevMode(
-    context: Context?,
-    hostBuildConfigDebug: Boolean? = null,
-): DevModeResult {
-    // 1. Explicit env-var overrides win — these mirror the JS side so the
-    //    same DVAI_FORCE_PROD / DVAI_FORCE_DEV semantics work in CI/test
-    //    contexts on any platform.
-    val forceProd = System.getenv("DVAI_FORCE_PROD")
-    if (forceProd == "1" || forceProd == "true") {
-        return DevModeResult(isDev = false, reason = "DVAI_FORCE_PROD set")
-    }
-    val forceDev = System.getenv("DVAI_FORCE_DEV")
-    if (forceDev == "1" || forceDev == "true") {
-        return DevModeResult(isDev = true, reason = "DVAI_FORCE_DEV set")
-    }
-
-    // 2. Host app's BuildConfig.DEBUG (explicit, preferred). When the host
-    //    passes a non-null value we treat it as authoritative — the host
-    //    knows whether they're a debug build better than we do. When null,
-    //    we fall through to the manifest-flag heuristic.
-    when (hostBuildConfigDebug) {
-        true -> return DevModeResult(isDev = true, reason = "BuildConfig.DEBUG=true")
-        false -> return DevModeResult(isDev = false, reason = "BuildConfig.DEBUG=false (host-supplied)")
-        null -> { /* fall through */ }
-    }
-
-    // 3. ApplicationInfo.FLAG_DEBUGGABLE — set on debug builds and on apps
-    //    with `android:debuggable="true"` in the manifest. Fallback when the
-    //    host hasn't wired their BuildConfig.DEBUG through to StartOptions.
-    if (context != null) {
-        val flags = context.applicationInfo.flags
-        if ((flags and ApplicationInfo.FLAG_DEBUGGABLE) != 0) {
-            return DevModeResult(isDev = true, reason = "ApplicationInfo.FLAG_DEBUGGABLE set")
-        }
-    }
-
-    return DevModeResult(isDev = false, reason = "production-class environment")
-}
-
-/** Outcome of [detectDevMode]. */
-data class DevModeResult(val isDev: Boolean, val reason: String)
-
-/**
- * Decide whether a license-payload `aud` entry matches the current
- * runtime audience. Supports exact match and `*.example.com` wildcard
- * matching for subdomain binding. Returns the matched `aud` pattern
- * on success so it can be recorded for audit, or null on miss.
- *
- * Match rules (identical to the JS side):
- *   - `"foo"` matches `"foo"` exactly
- *   - `"*.example.com"` matches `"example.com"` AND any `"<sub>.example.com"`
- *   - `"*"` matches any non-empty audience (intentionally permissive; use
- *     for trial/site licenses that span all of a customer's deployments)
- *
- * Runtime audience of `null` matches `"*"` only.
- */
-fun matchAudience(runtimeAudience: String?, audClaim: List<String>): String? {
-    if (runtimeAudience == null) {
-        return if (audClaim.contains("*")) "*" else null
-    }
-    val runtime = runtimeAudience.lowercase()
-    for (pattern in audClaim) {
-        val p = pattern.lowercase()
-        if (p == "*") return pattern // permissive wildcard
-        if (p == runtime) return pattern // exact match
-        if (p.startsWith("*.")) {
-            val suffix = p.substring(2)
-            if (runtime == suffix || runtime.endsWith(".$suffix")) {
-                return pattern
-            }
-        }
-    }
-    return null
-}
+package co.deepvoiceai.bridge.license
+
+import android.content.Context
+import android.content.pm.ApplicationInfo
+
+/**
+ * Runtime audience + platform + dev-mode detection for the Android SDK.
+ *
+ * Kotlin port of `packages/dvai-bridge-core/src/license/audience.ts`.
+ * The semantics are identical to the JS side but the platform APIs
+ * differ — audience is read from [Context.getPackageName] rather than
+ * `window.location.hostname`, and dev-mode is detected via
+ * `BuildConfig.DEBUG` + `ApplicationInfo.FLAG_DEBUGGABLE` rather than
+ * hostname heuristics.
+ *
+ * "Audience" on Android = the host app's package name (e.g.
+ * `"com.acme.app"`). License JWTs bind to package names exactly like
+ * iOS bundle ids; subdomain-style `*.acme.com` wildcards work for
+ * domain-tail matching too.
+ *
+ * "Dev mode" detection bypasses license enforcement entirely so
+ * developers don't need a license to run the SDK on a debug build.
+ * This matches the JS-side `detectDevMode()` behaviour.
+ */
+
+/** Detect the current SDK platform identifier. Always [DvaiPlatform.ANDROID]. */
+fun detectPlatform(): DvaiPlatform = DvaiPlatform.ANDROID
+
+/**
+ * Detect the current audience string the license must bind. Returns
+ * the host app's package name from [Context.getPackageName].
+ *
+ * Returns null only if [context] is null — in practice this never
+ * happens because [LicenseValidator] requires a non-null context at
+ * construction.
+ */
+fun detectAudience(context: Context?): String? = context?.packageName
+
+/**
+ * Detect whether the SDK is running in a developer environment where
+ * license enforcement should be bypassed. The bypass list is
+ * intentionally generous: blocking a developer mid-`./gradlew installDebug`
+ * with a license-not-found error would be hostile.
+ *
+ * Precedence (highest first):
+ *   1. `DVAI_FORCE_PROD=1` env var — production mode forced, overrides DEBUG.
+ *   2. `DVAI_FORCE_DEV=1` env var — dev mode forced.
+ *   3. [hostBuildConfigDebug] (a `BuildConfig.DEBUG` value passed in by the
+ *      host app via [co.deepvoiceai.bridge.StartOptions]) — dev mode.
+ *   4. [ApplicationInfo.FLAG_DEBUGGABLE] on the host app — dev mode.
+ *   5. Otherwise production, license required.
+ *
+ * @param context              Application context — used to read
+ *                             `ApplicationInfo.FLAG_DEBUGGABLE`.
+ * @param hostBuildConfigDebug The host app's `BuildConfig.DEBUG`, passed in
+ *                             explicitly because the validator lives in a
+ *                             library module whose own `BuildConfig.DEBUG`
+ *                             never reflects the host app's state. Pass null
+ *                             to skip this check.
+ */
+fun detectDevMode(
+    context: Context?,
+    hostBuildConfigDebug: Boolean? = null,
+): DevModeResult {
+    // 1. Explicit env-var overrides win — these mirror the JS side so the
+    //    same DVAI_FORCE_PROD / DVAI_FORCE_DEV semantics work in CI/test
+    //    contexts on any platform.
+    val forceProd = System.getenv("DVAI_FORCE_PROD")
+    if (forceProd == "1" || forceProd == "true") {
+        return DevModeResult(isDev = false, reason = "DVAI_FORCE_PROD set")
+    }
+    val forceDev = System.getenv("DVAI_FORCE_DEV")
+    if (forceDev == "1" || forceDev == "true") {
+        return DevModeResult(isDev = true, reason = "DVAI_FORCE_DEV set")
+    }
+
+    // 2. Host app's BuildConfig.DEBUG (explicit, preferred). When the host
+    //    passes a non-null value we treat it as authoritative — the host
+    //    knows whether they're a debug build better than we do. When null,
+    //    we fall through to the manifest-flag heuristic.
+    when (hostBuildConfigDebug) {
+        true -> return DevModeResult(isDev = true, reason = "BuildConfig.DEBUG=true")
+        false -> return DevModeResult(isDev = false, reason = "BuildConfig.DEBUG=false (host-supplied)")
+        null -> { /* fall through */ }
+    }
+
+    // 3. ApplicationInfo.FLAG_DEBUGGABLE — set on debug builds and on apps
+    //    with `android:debuggable="true"` in the manifest. Fallback when the
+    //    host hasn't wired their BuildConfig.DEBUG through to StartOptions.
+    if (context != null) {
+        val flags = context.applicationInfo.flags
+        if ((flags and ApplicationInfo.FLAG_DEBUGGABLE) != 0) {
+            return DevModeResult(isDev = true, reason = "ApplicationInfo.FLAG_DEBUGGABLE set")
+        }
+    }
+
+    return DevModeResult(isDev = false, reason = "production-class environment")
+}
+
+/** Outcome of [detectDevMode]. */
+data class DevModeResult(val isDev: Boolean, val reason: String)
+
+/**
+ * Decide whether a license-payload `aud` entry matches the current
+ * runtime audience. Supports exact match and `*.example.com` wildcard
+ * matching for subdomain binding. Returns the matched `aud` pattern
+ * on success so it can be recorded for audit, or null on miss.
+ *
+ * Match rules (identical to the JS side):
+ *   - `"foo"` matches `"foo"` exactly
+ *   - `"*.example.com"` matches `"example.com"` AND any `"<sub>.example.com"`
+ *   - `"*"` matches any non-empty audience (intentionally permissive; use
+ *     for trial/site licenses that span all of a customer's deployments)
+ *
+ * Runtime audience of `null` matches `"*"` only.
+ */
+fun matchAudience(runtimeAudience: String?, audClaim: List<String>): String? {
+    if (runtimeAudience == null) {
+        return if (audClaim.contains("*")) "*" else null
+    }
+    val runtime = runtimeAudience.lowercase()
+    for (pattern in audClaim) {
+        val p = pattern.lowercase()
+        if (p == "*") return pattern // permissive wildcard
+        if (p == runtime) return pattern // exact match
+        if (p.startsWith("*.")) {
+            val suffix = p.substring(2)
+            if (runtime == suffix || runtime.endsWith(".$suffix")) {
+                return pattern
+            }
+        }
+    }
+    return null
+}