Repository Public
1// Author: Simon-Pierre Boucher — contact@spboucher.ai2// File: Packages/LocalChatCore/Sources/Models.swift3// Description: Model descriptors shared by the hub, the engine and both apps: backend, format, quantization, capabilities, sizes.4import Foundation56public enum BackendKind: String, Codable, Sendable, CaseIterable, Hashable {7 case mlx // MLX Swift, on-device (macOS + iOS devices)8 case gguf // llama.cpp, on-device (macOS in this build)9 case appleFoundation // Apple Foundation Models (system model)10 case remote // an OpenAI-compatible node the user trusts (another Mac running Local Chat, MacLustr…)1112 public var displayName: String {13 switch self {14 case .mlx: "MLX"15 case .gguf: "llama.cpp"16 case .appleFoundation: "Apple Intelligence"17 case .remote: "Remote"18 }19 }20 public var isOnDevice: Bool { self != .remote }21}2223public enum ModelFormat: String, Codable, Sendable, Hashable { case mlx, gguf, system, remote }2425public enum ModelCapability: String, Codable, Sendable, CaseIterable, Hashable {26 case chat, vision, tools, reasoning, embeddings, code, structuredOutput, audio27 public var label: String {28 switch self {29 case .chat: "Chat"; case .vision: "Vision"; case .tools: "Tools"; case .reasoning: "Reasoning"30 case .embeddings: "Embeddings"; case .code: "Code"; case .structuredOutput: "Structured output"; case .audio: "Audio"31 }32 }33 public var symbol: String {34 switch self {35 case .chat: "bubble.left.and.bubble.right"; case .vision: "eye"; case .tools: "wrench.and.screwdriver"36 case .reasoning: "brain"; case .embeddings: "point.3.connected.trianglepath.dotted"; case .code: "chevron.left.forwardslash.chevron.right"37 case .structuredOutput: "curlybraces"; case .audio: "waveform"38 }39 }40}4142/// Where a figure comes from. The UI never shows an inferred number as a measured one.43public enum Provenance: String, Codable, Sendable, Hashable { case declared, inferred, measured, unknown }4445public struct ModelDescriptor: Codable, Sendable, Hashable, Identifiable {46 public var id: String // stable key: "<backend>:<repo>[:<file>]" or "remote:<node>:<model>"47 public var name: String // display name48 public var repoID: String? // Hugging Face repository49 public var revision: String? // commit the local copy was downloaded at50 public var fileName: String? // GGUF file inside the repository51 public var backend: BackendKind52 public var format: ModelFormat53 public var architecture: String? // config.json model_type or GGUF general.architecture54 public var parameterCount: Int64?55 public var parameterProvenance: Provenance56 public var quantization: String? // "4bit", "Q4_K_M", …57 public var bitsPerWeight: Double?58 public var contextLength: Int?59 public var capabilities: Set<ModelCapability>60 public var license: String?61 public var sizeBytes: Int64? // bytes on disk (local) or to download62 public var localPath: String? // path relative to the models root, nil when not downloaded63 public var remoteNodeID: UUID?64 public var addedAt: Date?65 public var lastUsedAt: Date?66 public var imported: Bool // user-imported from disk (not downloaded by the hub)6768 public init(id: String, name: String, repoID: String? = nil, revision: String? = nil, fileName: String? = nil, backend: BackendKind,69 format: ModelFormat, architecture: String? = nil, parameterCount: Int64? = nil, parameterProvenance: Provenance = .unknown,70 quantization: String? = nil, bitsPerWeight: Double? = nil, contextLength: Int? = nil,71 capabilities: Set<ModelCapability> = [.chat], license: String? = nil, sizeBytes: Int64? = nil, localPath: String? = nil,72 remoteNodeID: UUID? = nil, addedAt: Date? = nil, lastUsedAt: Date? = nil, imported: Bool = false) {73 self.id = id; self.name = name; self.repoID = repoID; self.revision = revision; self.fileName = fileName; self.backend = backend74 self.format = format; self.architecture = architecture; self.parameterCount = parameterCount75 self.parameterProvenance = parameterProvenance; self.quantization = quantization; self.bitsPerWeight = bitsPerWeight76 self.contextLength = contextLength; self.capabilities = capabilities; self.license = license; self.sizeBytes = sizeBytes77 self.localPath = localPath; self.remoteNodeID = remoteNodeID; self.addedAt = addedAt; self.lastUsedAt = lastUsedAt; self.imported = imported78 }7980 public var isLocal: Bool { localPath != nil || backend == .appleFoundation }81 public var isEmbeddingOnly: Bool { capabilities.contains(.embeddings) && !capabilities.contains(.chat) }8283 public var parameterLabel: String? {84 guard let p = parameterCount else { return nil }85 let v = Double(p)86 if v >= 1e9 { return String(format: v >= 1e10 ? "%.0fB" : "%.1fB", v / 1e9) }87 if v >= 1e6 { return String(format: "%.0fM", v / 1e6) }88 return "\(p)"89 }9091 /// Estimated resident memory to run the model: weights + KV cache at `context` tokens + runtime overhead.92 /// It is an estimate (weights dominate); the Observatory reports the measured value once the model is loaded.93 public func estimatedMemoryBytes(context: Int = 4096) -> Int64? {94 guard let size = sizeBytes else { return nil }95 let kv = Int64(Double(context) * Self.kvBytesPerToken(parameters: parameterCount))96 return size + kv + 350 * 1_048_57697 }9899 /// Rough KV-cache cost per token (fp16 keys+values over all layers), from the parameter count when the config is unknown.100 static func kvBytesPerToken(parameters: Int64?) -> Double {101 guard let p = parameters else { return 120_000 }102 let b = Double(p) / 1e9103 return max(20_000, min(900_000, 55_000 * b.squareRoot() * max(1, b.squareRoot())))104 }105}106107public enum ModelFit: String, Codable, Sendable, Hashable {108 case comfortable, tight, tooLarge, unsupported, unknown109 public var label: String {110 switch self {111 case .comfortable: "Runs well"; case .tight: "Tight fit"; case .tooLarge: "Too large"112 case .unsupported: "Not supported"; case .unknown: "Unknown"113 }114 }115}116117public struct CompatibilityVerdict: Codable, Sendable, Hashable {118 public var fit: ModelFit119 public var reasons: [String]120 public var estimatedMemoryBytes: Int64?121 public init(fit: ModelFit, reasons: [String] = [], estimatedMemoryBytes: Int64? = nil) {122 self.fit = fit; self.reasons = reasons; self.estimatedMemoryBytes = estimatedMemoryBytes123 }124 public var canAttemptLoad: Bool { fit == .comfortable || fit == .tight || fit == .unknown }125}126127public enum ByteFormat {128 public static func string(_ bytes: Int64) -> String {129 let f = ByteCountFormatter(); f.countStyle = .file; f.allowedUnits = [.useMB, .useGB, .useKB]130 return f.string(fromByteCount: bytes)131 }132 public static func memory(_ bytes: Int64) -> String {133 let gb = Double(bytes) / 1_073_741_824134 return gb >= 1 ? String(format: "%.1f GB", gb) : String(format: "%.0f MB", Double(bytes) / 1_048_576)135 }136}137