@dvai-bridge/ios 4.0.0

package/ios/Sources/DVAIBridge/Capability/CapabilityPrecheck.swift

@@ -0,0 +1,193 @@
+import Foundation
+#if canImport(UIKit)
+import UIKit
+#endif
+
+/// v3.2 — pre-init capability gate (Swift port of the Kotlin
+/// `CapabilityPrecheck` and the TS `assessCapability`).
+///
+/// Mirrors the Android + TS heuristic 1:1 — same hint shapes, same
+/// threshold defaults (3 tok/s hardware floor, 10 tok/s comfort
+/// threshold), same three modes. Guarantees that a given device
+/// classifies the same way regardless of which platform's SDK is
+/// asking.
+///
+/// Heuristic-only: no model is loaded, no probe runs. The cold-run
+/// probe (`probeCapability`) refines the estimate AFTER the model is
+/// loaded and a request has actually completed; that path is unchanged
+/// from v3.0.
+public enum CapabilityPrecheck {
+
+    /// Result of `assess(...)`. `Codable` so it can serialize cleanly
+    /// to JSON for cross-language Pigeon / Capacitor bridges.
+    public struct Result: Sendable, Codable, Equatable {
+        public let mode: PrecheckMode
+        /// Estimated decode tok/s for any 1–3B-class model.
+        public let tokPerSec: Double
+        public let hints: DeviceCapabilityHints
+        /// Human-readable explanation; safe to log + display.
+        public let reason: String
+    }
+
+    /// Tunable thresholds. Defaults match `OffloadConfig` / the Kotlin
+    /// `CapabilityPrecheck.Thresholds` / the TS defaults.
+    public struct Thresholds: Sendable {
+        /// Below this, the device is too weak to run inference at all.
+        /// Default 3.0 tok/s.
+        public var hardwareMinimum: Double
+        /// Below this, run in offload-only mode. Default 10.0.
+        public var minLocalCapability: Double
+
+        public init(hardwareMinimum: Double = 3.0, minLocalCapability: Double = 10.0) {
+            self.hardwareMinimum = hardwareMinimum
+            self.minLocalCapability = minLocalCapability
+        }
+    }
+
+    /// Run the precheck. Pass `hints` to override the auto-detect (used
+    /// by tests + cross-platform parity checks).
+    public static func assess(
+        thresholds: Thresholds = Thresholds(),
+        hints: DeviceCapabilityHints? = nil
+    ) -> Result {
+        let resolvedHints = hints ?? detectDeviceHints()
+        let tokPerSec = heuristicTokPerSec(hints: resolvedHints)
+
+        if tokPerSec < thresholds.hardwareMinimum {
+            return Result(
+                mode: .tooWeak,
+                tokPerSec: tokPerSec,
+                hints: resolvedHints,
+                reason: "estimated \(tokPerSec) tok/s, below the " +
+                    "\(thresholds.hardwareMinimum) tok/s hardware floor — " +
+                    "local inference would be unusable."
+            )
+        }
+
+        if tokPerSec < thresholds.minLocalCapability {
+            return Result(
+                mode: .offloadOnly,
+                tokPerSec: tokPerSec,
+                hints: resolvedHints,
+                reason: "estimated \(tokPerSec) tok/s, below the " +
+                    "\(thresholds.minLocalCapability) tok/s comfort threshold — " +
+                    "model will not be loaded locally; every request will be " +
+                    "forwarded to a paired peer."
+            )
+        }
+
+        return Result(
+            mode: .ok,
+            tokPerSec: tokPerSec,
+            hints: resolvedHints,
+            reason: "estimated \(tokPerSec) tok/s, above the " +
+                "\(thresholds.minLocalCapability) tok/s threshold — running normally."
+        )
+    }
+
+    /// Pure heuristic — mirrors the TS `heuristicTokPerSec` and
+    /// Kotlin's `CapabilityPrecheck.heuristicTokPerSec`.
+    public static func heuristicTokPerSec(hints: DeviceCapabilityHints) -> Double {
+        // Base score by GPU class — observed floors for 1–3B q4 GGUFs.
+        let gpuBase: Double
+        switch hints.gpuClass {
+        case .none: gpuBase = 3.0
+        case .integrated: gpuBase = 8.0
+        case .discrete: gpuBase = 35.0
+        case .appleSilicon: gpuBase = 40.0
+        }
+
+        let cpuMul: Double
+        switch hints.cpuClass {
+        case .low: cpuMul = 0.6
+        case .mid: cpuMul = 1.0
+        case .high: cpuMul = 1.3
+        }
+
+        let ramMul: Double
+        if hints.ramGb < 4 { ramMul = 0.3 }
+        else if hints.ramGb < 8 { ramMul = 0.7 }
+        else { ramMul = 1.0 }
+
+        let npuBonus: Double = hints.hasNpu ? 1.4 : 1.0
+
+        let raw = gpuBase * cpuMul * ramMul * npuBonus
+        return (raw * 10).rounded() / 10
+    }
+
+    /// Best-effort introspection on iOS / macOS via sysctl + ProcessInfo.
+    public static func detectDeviceHints() -> DeviceCapabilityHints {
+        let physicalMemoryBytes = ProcessInfo.processInfo.physicalMemory
+        let ramGb = Int(Double(physicalMemoryBytes) / (1024.0 * 1024.0 * 1024.0))
+        let cores = ProcessInfo.processInfo.activeProcessorCount
+
+        let cpuClass: CpuClass
+        if cores >= 8 { cpuClass = .high }
+        else if cores >= 4 { cpuClass = .mid }
+        else { cpuClass = .low }
+
+        // Apple Silicon Macs + iPhones with M-series / A-series chips
+        // have unified-memory architectures. We treat them as the
+        // `appleSilicon` class — the heuristic uses gpuBase = 40.
+        // Older Intel Macs report `appleSilicon` if the runtime is on
+        // arm64; we rely on `arch == arm64` as the signal.
+        let gpuClass: GpuClass = isAppleSilicon() ? .appleSilicon : .integrated
+
+        // NPU detection: every Apple Silicon device since A11 has the
+        // Neural Engine, and every Intel Mac since 2020 has none. Use
+        // arch as a proxy.
+        let hasNpu = isAppleSilicon()
+
+        return DeviceCapabilityHints(
+            hasNpu: hasNpu,
+            ramGb: ramGb,
+            gpuClass: gpuClass,
+            cpuClass: cpuClass
+        )
+    }
+
+    private static func isAppleSilicon() -> Bool {
+        #if arch(arm64)
+        return true
+        #else
+        return false
+        #endif
+    }
+}
+
+/// Lifecycle mode the SDK enters on `start()`. JSON-serialized as a
+/// lower-cased dash string for cross-platform parity (`ok` /
+/// `offload-only` / `too-weak`).
+public enum PrecheckMode: String, Sendable, Codable, Equatable {
+    case ok
+    case offloadOnly = "offload-only"
+    case tooWeak = "too-weak"
+}
+
+/// Mirrors the Kotlin `DeviceCapabilityHints` and TS interface.
+public struct DeviceCapabilityHints: Sendable, Codable, Equatable {
+    public let hasNpu: Bool
+    public let ramGb: Int
+    public let gpuClass: GpuClass
+    public let cpuClass: CpuClass
+
+    public init(hasNpu: Bool, ramGb: Int, gpuClass: GpuClass, cpuClass: CpuClass) {
+        self.hasNpu = hasNpu
+        self.ramGb = ramGb
+        self.gpuClass = gpuClass
+        self.cpuClass = cpuClass
+    }
+}
+
+public enum GpuClass: String, Sendable, Codable, Equatable {
+    case none
+    case integrated
+    case discrete
+    case appleSilicon = "apple-silicon"
+}
+
+public enum CpuClass: String, Sendable, Codable, Equatable {
+    case low
+    case mid
+    case high
+}

package/ios/Sources/DVAIBridge/Capability/CapabilityScore.swift

@@ -0,0 +1,51 @@
+import Foundation
+
+/// Swift-side `CapabilityScore` mirroring the TypeScript shape in
+/// `packages/dvai-bridge-core/src/capability/types.ts`. Persisted by
+/// `CapabilityCache`.
+public struct CapabilityScore: Sendable, Equatable, Codable, Hashable {
+    /// Source of the estimate.
+    public enum Source: String, Sendable, Codable, Hashable {
+        case probe
+        case heuristic
+    }
+
+    /// Model identifier this score applies to.
+    public let modelId: String
+    /// Stable per-install device identifier.
+    public let deviceId: String
+    /// Library SemVer at the time the score was measured.
+    public let libraryVersion: String
+    /// Estimated decode rate, tokens-per-second.
+    public let tokPerSec: Double
+    /// Source of the estimate.
+    public let source: Source
+    /// Unix milliseconds the score was measured / computed.
+    public let measuredAt: Int64
+
+    public init(
+        modelId: String,
+        deviceId: String,
+        libraryVersion: String,
+        tokPerSec: Double,
+        source: Source = .heuristic,
+        measuredAt: Int64 = Int64(Date().timeIntervalSince1970 * 1000)
+    ) {
+        self.modelId = modelId
+        self.deviceId = deviceId
+        self.libraryVersion = libraryVersion
+        self.tokPerSec = tokPerSec
+        self.source = source
+        self.measuredAt = measuredAt
+    }
+}
+
+public struct CapabilityCacheKey: Sendable, Hashable {
+    public let modelId: String
+    public let libraryVersion: String
+
+    public init(modelId: String, libraryVersion: String) {
+        self.modelId = modelId
+        self.libraryVersion = libraryVersion
+    }
+}

package/ios/Sources/DVAIBridge/Capability/DeviceID.swift

@@ -0,0 +1,70 @@
+import Foundation
+
+/// Stable per-install device identifier. Generated once on first call,
+/// persisted alongside the capability cache under the same Application
+/// Support directory. Used for:
+///   - identifying THIS device in mDNS TXT records (LAN discovery).
+///   - identifying THIS device in rendezvous-server pairing payloads.
+///   - keying the capability cache.
+///
+/// NOT a privacy hazard: the ID is per-install and per-device-storage,
+/// never tied to user identity. Reinstalling the app or wiping app
+/// storage produces a fresh ID — that's the right behaviour and matches
+/// the TS-side `generateDeviceId` semantics in
+/// `packages/dvai-bridge-core/src/capability/deviceId.ts`.
+public final class DeviceIDStore: @unchecked Sendable {
+    private let fileURL: URL
+    private let lock = NSLock()
+    private var cached: String?
+
+    public init(directory: URL) {
+        self.fileURL = directory.appendingPathComponent("device-id.txt", isDirectory: false)
+    }
+
+    /// Return the device ID, generating + persisting it on first call.
+    public func get() throws -> String {
+        lock.lock()
+        defer { lock.unlock() }
+        if let cached = cached { return cached }
+
+        // Try to load existing
+        if let data = try? Data(contentsOf: fileURL),
+           let raw = String(data: data, encoding: .utf8)?.trimmingCharacters(in: .whitespacesAndNewlines),
+           !raw.isEmpty {
+            cached = raw
+            return raw
+        }
+
+        // Generate fresh
+        let id = Self.generate()
+        try FileManager.default.createDirectory(
+            at: fileURL.deletingLastPathComponent(),
+            withIntermediateDirectories: true
+        )
+        try id.write(to: fileURL, atomically: true, encoding: .utf8)
+        cached = id
+        return id
+    }
+
+    /// Generate a 22-char URL-safe base64 random ID. Mirrors the TS
+    /// `generateDeviceId()` shape (16 random bytes, base64url, no
+    /// padding) so device IDs round-trip across platforms.
+    public static func generate() -> String {
+        var bytes = [UInt8](repeating: 0, count: 16)
+        let status = SecRandomCopyBytes(kSecRandomDefault, bytes.count, &bytes)
+        if status != errSecSuccess {
+            // Fall back to UUID — still random, just not from SecRandom.
+            return UUID().uuidString.replacingOccurrences(of: "-", with: "")
+                .lowercased().prefix(22).description
+        }
+        return base64UrlEncode(Data(bytes))
+    }
+
+    private static func base64UrlEncode(_ data: Data) -> String {
+        let b64 = data.base64EncodedString()
+        return b64
+            .replacingOccurrences(of: "+", with: "-")
+            .replacingOccurrences(of: "/", with: "_")
+            .replacingOccurrences(of: "=", with: "")
+    }
+}

package/ios/Sources/DVAIBridge/Capability/HardwareAssessment.swift

@@ -0,0 +1,41 @@
+import Foundation
+
+/// v3.2 — JSON-serializable result of `DVAIBridge.shared.assessHardware()`.
+///
+/// Returned to consumer code so the app developer can decide whether
+/// to call `DVAIBridge.shared.start(...)` and what (if anything) to
+/// surface in the UI. The SDK itself never shows UI for hardware
+/// decisions — consumer apps make those choices.
+///
+/// `Codable` so it round-trips cleanly through Capacitor / React
+/// Native / Pigeon bridges as JSON without any custom converter.
+public struct HardwareAssessment: Sendable, Codable, Equatable {
+    /// Lifecycle mode the SDK would enter on `start()`. See
+    /// `PrecheckMode` for the three values.
+    public let mode: PrecheckMode
+    /// Estimated decode tok/s for any 1–3B-class model on this device.
+    public let tokPerSec: Double
+    /// Human-readable explanation; safe to log + display.
+    public let reason: String
+    /// Underlying hints used to compute the estimate.
+    public let hints: DeviceCapabilityHints
+
+    public init(
+        mode: PrecheckMode,
+        tokPerSec: Double,
+        reason: String,
+        hints: DeviceCapabilityHints
+    ) {
+        self.mode = mode
+        self.tokPerSec = tokPerSec
+        self.reason = reason
+        self.hints = hints
+    }
+
+    init(from result: CapabilityPrecheck.Result) {
+        self.mode = result.mode
+        self.tokPerSec = result.tokPerSec
+        self.reason = result.reason
+        self.hints = result.hints
+    }
+}