Repository Public
1// Author: Simon-Pierre Boucher — contact@spboucher.ai2// File: Packages/LocalChatModelHub/Sources/ModelLibrary.swift3// Description: The installed-model index (library.json in the models folder): register, import from disk, reconcile, delete, disk usage.4import Foundation5import LocalChatCore67public struct ReconcileReport: Sendable, Hashable {8 public var removed: [String] // ids whose files disappeared9 public var adopted: [String] // ids found on disk and added to the index10 public init(removed: [String] = [], adopted: [String] = []) { self.removed = removed; self.adopted = adopted }11}1213public enum ImportMode: Sendable { case copy, move }1415/// Reads what the files on disk say about a model. Everything returned here is read from the files, not guessed from names, unless noted.16public enum LocalModelInspector {17 public static func directorySize(_ url: URL) -> Int64 {18 var isDir: ObjCBool = false19 guard FileManager.default.fileExists(atPath: url.path, isDirectory: &isDir) else { return 0 }20 if !isDir.boolValue { return fileSize(url) }21 var total: Int64 = 022 if let e = FileManager.default.enumerator(at: url, includingPropertiesForKeys: [.fileSizeKey, .isRegularFileKey]) {23 for case let file as URL in e {24 if let v = try? file.resourceValues(forKeys: [.fileSizeKey, .isRegularFileKey]), v.isRegularFile == true { total += Int64(v.fileSize ?? 0) }25 }26 }27 return total28 }2930 public static func fileSize(_ url: URL) -> Int64 {31 ((try? FileManager.default.attributesOfItem(atPath: url.path))?[.size] as? NSNumber)?.int64Value ?? 032 }3334 public static func isMLXModelDirectory(_ url: URL) -> Bool {35 let fm = FileManager.default36 guard fm.fileExists(atPath: url.appendingPathComponent("config.json").path) else { return false }37 return ((try? fm.contentsOfDirectory(atPath: url.path)) ?? []).contains { $0.hasSuffix(".safetensors") }38 }3940 static func json(_ url: URL) -> JSONValue? {41 (try? Data(contentsOf: url)).flatMap { try? JSONDecoder().decode(JSONValue.self, from: $0) }42 }4344 /// Fills a descriptor from an MLX model folder: config.json, tokenizer_config.json / chat_template files and the weight sizes.45 public static func inspectMLX(directory: URL, base: ModelDescriptor) -> ModelDescriptor {46 var d = base47 let config = json(directory.appendingPathComponent("config.json"))48 if let type = config?["model_type"]?.stringValue { d.architecture = type }49 let bits = config?["quantization"]?["bits"]?.intValue ?? config?["quantization_config"]?["bits"]?.intValue50 if let q = ModelNaming.mlxQuantization(fromName: d.name, configBits: bits) { d.quantization = q.label; d.bitsPerWeight = q.bitsPerWeight }51 let text = config?["text_config"]52 if let n = config?["max_position_embeddings"]?.intValue ?? text?["max_position_embeddings"]?.intValue { d.contextLength = n }53 else if let n = json(directory.appendingPathComponent("tokenizer_config.json"))?["model_max_length"]?.numberValue, n > 0, n < 1e7 { d.contextLength = Int(n) }54 let hasVision = config?["vision_config"] != nil || config?["vision_tower"] != nil55 var template: String?56 for name in ["chat_template.jinja", "chat_template.json"] {57 if let data = try? Data(contentsOf: directory.appendingPathComponent(name)) { template = String(decoding: data, as: UTF8.self); break }58 }59 if template == nil { template = json(directory.appendingPathComponent("tokenizer_config.json"))?["chat_template"]?.stringValue }60 let isEmbedder = d.capabilities == [.embeddings]61 || FileManager.default.fileExists(atPath: directory.appendingPathComponent("1_Pooling").path)62 || FileManager.default.fileExists(atPath: directory.appendingPathComponent("modules.json").path)63 if isEmbedder { d.capabilities = [.embeddings] } else {64 var caps = ModelNaming.capabilities(name: d.repoID ?? d.name, pipelineTag: nil, tags: [], chatTemplate: template, hasVisionConfig: hasVision)65 // keep what the Hub declared at download time (e.g. vision from the pipeline tag) when the files do not contradict it66 caps.formUnion(d.capabilities.subtracting([.embeddings]))67 if !hasVision && d.imported { caps.remove(.vision) }68 d.capabilities = caps69 }70 d.sizeBytes = directorySize(directory)71 if d.parameterCount == nil, let p = ModelNaming.parameterCount(fromName: d.name) { d.parameterCount = p; d.parameterProvenance = .inferred }72 return d73 }7475 /// Fills a descriptor from a GGUF file header. `projectorPresent` tells whether an mmproj file sits next to it.76 public static func inspectGGUF(file: URL, base: ModelDescriptor, projectorPresent: Bool = false) throws -> ModelDescriptor {77 let header = try GGUFReader.readHeader(at: file)78 var d = base79 if let a = header.architecture { d.architecture = a }80 if let n = header.contextLength { d.contextLength = n }81 if let l = header.license, d.license == nil { d.license = l }82 if let q = ModelNaming.ggufQuantization(fromName: file.lastPathComponent) ?? header.fileType.flatMap(ModelNaming.ggufQuantization(fileType:)) {83 d.quantization = q.label; d.bitsPerWeight = q.bitsPerWeight84 }85 if let p = header.declaredParameterCount { d.parameterCount = p; d.parameterProvenance = .declared }86 else if d.parameterCount == nil, let p = header.sizeLabel.flatMap(ModelNaming.parameterCount(fromName:)) ?? ModelNaming.parameterCount(fromName: file.lastPathComponent) {87 d.parameterCount = p; d.parameterProvenance = .inferred88 }89 if header.isProjector { d.capabilities = [.vision] }90 else if !header.hasChatTemplate && header.poolingType != nil && (header.poolingType ?? 0) != 0 { d.capabilities = [.embeddings] }91 else {92 var caps = ModelNaming.capabilities(name: d.repoID ?? header.name ?? d.name, pipelineTag: nil, tags: [], chatTemplate: header.chatTemplate,93 hasVisionConfig: false, hasProjector: projectorPresent)94 if d.capabilities == [.embeddings] { caps = [.embeddings] }95 d.capabilities = caps96 }97 return d98 }99}100101public actor ModelLibrary {102 public let paths: AppPaths103 private var models: [String: ModelDescriptor] = [:]104 private var loaded = false105 private var observers: [UUID: AsyncStream<[ModelDescriptor]>.Continuation] = [:]106107 public init(paths: AppPaths) { self.paths = paths }108109 private var indexURL: URL { paths.models.appendingPathComponent("library.json") }110111 private func loadIfNeeded() {112 guard !loaded else { return }113 loaded = true114 guard let data = try? Data(contentsOf: indexURL), let list = try? CoreCoding.decoder.decode([ModelDescriptor].self, from: data) else { return }115 models = Dictionary(list.map { ($0.id, $0) }, uniquingKeysWith: { $1 })116 }117118 private func save() {119 let list = sorted()120 if let data = try? CoreCoding.encoder.encode(list) { try? data.write(to: indexURL, options: .atomic) }121 for o in observers.values { o.yield(list) }122 }123124 private func sorted() -> [ModelDescriptor] {125 models.values.sorted { ($0.lastUsedAt ?? $0.addedAt ?? .distantPast, $1.name) > ($1.lastUsedAt ?? $1.addedAt ?? .distantPast, $0.name) }126 }127128 public func all() -> [ModelDescriptor] { loadIfNeeded(); return sorted() }129 public func model(id: String) -> ModelDescriptor? { loadIfNeeded(); return models[id] }130 public func contains(id: String) -> Bool { loadIfNeeded(); return models[id] != nil }131132 /// Emits the full list now and after every change.133 public func changes() -> AsyncStream<[ModelDescriptor]> {134 loadIfNeeded()135 let (stream, continuation) = AsyncStream<[ModelDescriptor]>.makeStream(bufferingPolicy: .bufferingNewest(1))136 let key = UUID()137 observers[key] = continuation138 continuation.onTermination = { [weak self] _ in Task { await self?.removeObserver(key) } }139 continuation.yield(sorted())140 return stream141 }142 private func removeObserver(_ key: UUID) { observers[key] = nil }143144 public func url(for descriptor: ModelDescriptor) -> URL? {145 guard let path = descriptor.localPath else { return nil }146 return path.hasPrefix("/") ? URL(fileURLWithPath: path) : paths.models.appendingPathComponent(path)147 }148149 /// Adds (or replaces) a model whose files are already in the models folder; metadata is completed from the files.150 @discardableResult151 public func register(_ descriptor: ModelDescriptor) throws -> ModelDescriptor {152 loadIfNeeded()153 guard let url = url(for: descriptor), FileManager.default.fileExists(atPath: url.path) else {154 throw HubError.importFailed("the files of \(descriptor.name) are missing")155 }156 var d = descriptor157 switch d.format {158 case .mlx: d = LocalModelInspector.inspectMLX(directory: url, base: d)159 case .gguf:160 let siblings = (try? FileManager.default.contentsOfDirectory(atPath: url.deletingLastPathComponent().path)) ?? []161 let projector = siblings.contains { $0.lowercased().contains("mmproj") && $0 != url.lastPathComponent }162 d = (try? LocalModelInspector.inspectGGUF(file: url, base: d, projectorPresent: projector)) ?? d163 d.sizeBytes = Self.ggufGroupSize(first: url)164 default: break165 }166 if d.addedAt == nil { d.addedAt = Date() }167 if let old = models[d.id] { d.lastUsedAt = d.lastUsedAt ?? old.lastUsedAt }168 models[d.id] = d169 save()170 return d171 }172173 /// Size of a GGUF model including the other parts of a split file.174 static func ggufGroupSize(first url: URL) -> Int64 {175 guard let part = ModelMetadataResolver.splitPart(url.lastPathComponent) else { return LocalModelInspector.fileSize(url) }176 let dir = url.deletingLastPathComponent()177 return ((try? FileManager.default.contentsOfDirectory(atPath: dir.path)) ?? [])178 .filter { ModelMetadataResolver.splitPart($0)?.stem == part.stem }179 .reduce(Int64(0)) { $0 + LocalModelInspector.fileSize(dir.appendingPathComponent($1)) }180 }181182 /// Imports an MLX model folder or a `.gguf` file chosen by the user. The caller holds security-scoped access for the duration of the call.183 @discardableResult184 public func importModel(from source: URL, mode: ImportMode = .copy) throws -> ModelDescriptor {185 loadIfNeeded()186 let fm = FileManager.default187 var isDir: ObjCBool = false188 guard fm.fileExists(atPath: source.path, isDirectory: &isDir) else { throw HubError.importFailed("\(source.lastPathComponent) does not exist") }189 let importRoot = paths.models.appendingPathComponent("imported", isDirectory: true)190 try fm.createDirectory(at: importRoot, withIntermediateDirectories: true)191 let name = source.lastPathComponent192 let id: String, format: ModelFormat, backend: BackendKind193194 if isDir.boolValue {195 guard LocalModelInspector.isMLXModelDirectory(source) else {196 throw HubError.importFailed("\(name) is not an MLX model folder (it needs config.json and .safetensors weights)")197 }198 id = "mlx:local/\(name)"; format = .mlx; backend = .mlx199 } else {200 guard source.pathExtension.lowercased() == "gguf" else { throw HubError.importFailed("only MLX folders and .gguf files can be imported") }201 do { _ = try GGUFReader.readHeader(at: source) } catch { throw HubError.importFailed((error as? LocalizedError)?.errorDescription ?? "invalid GGUF file") }202 id = "gguf:local:\(name)"; format = .gguf; backend = .gguf203 }204 let destination = importRoot.appendingPathComponent(name)205 if destination.standardizedFileURL != source.standardizedFileURL {206 let needed = LocalModelInspector.directorySize(source)207 if mode == .copy, let free = try? importRoot.resourceValues(forKeys: [.volumeAvailableCapacityForImportantUsageKey]).volumeAvailableCapacityForImportantUsage,208 free < needed + 256 * 1_048_576 { throw HubError.insufficientStorage(needed: needed, available: free) }209 if fm.fileExists(atPath: destination.path) { try fm.removeItem(at: destination) }210 do {211 switch mode {212 case .copy: try fm.copyItem(at: source, to: destination)213 case .move: try fm.moveItem(at: source, to: destination)214 }215 } catch { throw HubError.importFailed(error.localizedDescription) }216 }217 let display = format == .gguf ? (name as NSString).deletingPathExtension : name218 let base = ModelDescriptor(id: id, name: display, backend: backend, format: format, localPath: "imported/\(name)", addedAt: Date(), imported: true)219 do { return try register(base) }220 catch { try? fm.removeItem(at: destination); throw error }221 }222223 /// Removes the model from the index and deletes its files.224 public func delete(id: String) throws {225 loadIfNeeded()226 guard let d = models[id] else { return }227 if let url = url(for: d), !(d.localPath ?? "").hasPrefix("/") {228 let fm = FileManager.default229 if d.format == .gguf, let part = ModelMetadataResolver.splitPart(url.lastPathComponent) {230 let dir = url.deletingLastPathComponent()231 for f in (try? fm.contentsOfDirectory(atPath: dir.path)) ?? [] where ModelMetadataResolver.splitPart(f)?.stem == part.stem {232 try? fm.removeItem(at: dir.appendingPathComponent(f))233 }234 } else if fm.fileExists(atPath: url.path) { try fm.removeItem(at: url) }235 // a projector is removed with the last GGUF model of its folder; empty parent folders are pruned up to the models root236 var parent = url.deletingLastPathComponent()237 if d.format == .gguf {238 let rest = (try? fm.contentsOfDirectory(atPath: parent.path)) ?? []239 if !rest.contains(where: { $0.lowercased().hasSuffix(".gguf") && !$0.lowercased().contains("mmproj") }) {240 for f in rest where f.lowercased().contains("mmproj") { try? fm.removeItem(at: parent.appendingPathComponent(f)) }241 }242 }243 let root = paths.models.standardizedFileURL.path244 while parent.standardizedFileURL.path != root, parent.standardizedFileURL.path.hasPrefix(root),245 ((try? fm.contentsOfDirectory(atPath: parent.path)) ?? ["x"]).filter({ $0 != ".DS_Store" }).isEmpty {246 try? fm.removeItem(at: parent); parent = parent.deletingLastPathComponent()247 }248 }249 models[id] = nil250 save()251 }252253 public func touch(id: String, at date: Date = Date()) {254 loadIfNeeded()255 guard models[id] != nil else { return }256 models[id]?.lastUsedAt = date257 save()258 }259260 /// Replaces the stored descriptor (e.g. after the engine measured the real context length).261 public func update(_ descriptor: ModelDescriptor) {262 loadIfNeeded()263 guard models[descriptor.id] != nil else { return }264 models[descriptor.id] = descriptor265 save()266 }267268 /// Bytes used by installed models (measured on disk).269 public func diskUsage() -> Int64 {270 loadIfNeeded()271 return models.values.reduce(Int64(0)) { total, d in272 guard let url = url(for: d) else { return total }273 return total + (d.format == .gguf ? Self.ggufGroupSize(first: url) : LocalModelInspector.directorySize(url))274 }275 }276277 /// Drops entries whose files are gone and adopts MLX folders / GGUF files present on disk but missing from the index.278 @discardableResult279 public func reconcile() -> ReconcileReport {280 loadIfNeeded()281 let fm = FileManager.default282 var report = ReconcileReport()283 for (id, d) in models where d.backend == .mlx || d.backend == .gguf {284 if let url = url(for: d), fm.fileExists(atPath: url.path) { continue }285 models[id] = nil; report.removed.append(id)286 }287 let known = Set(models.values.compactMap(\.localPath))288 let root = paths.models289 // layout: <org>/<repo>/… and imported/<name>290 for org in ((try? fm.contentsOfDirectory(atPath: root.path)) ?? []).sorted() where !org.hasPrefix(".") {291 let orgURL = root.appendingPathComponent(org)292 var isDir: ObjCBool = false293 guard fm.fileExists(atPath: orgURL.path, isDirectory: &isDir), isDir.boolValue else { continue }294 for entry in ((try? fm.contentsOfDirectory(atPath: orgURL.path)) ?? []).sorted() where !entry.hasPrefix(".") {295 let url = orgURL.appendingPathComponent(entry)296 let relative = "\(org)/\(entry)"297 let imported = org == "imported"298 var candidates: [ModelDescriptor] = []299 if LocalModelInspector.isMLXModelDirectory(url) {300 if !known.contains(relative) {301 candidates.append(ModelDescriptor(id: imported ? "mlx:local/\(entry)" : "mlx:\(relative)", name: entry, repoID: imported ? nil : relative,302 backend: .mlx, format: .mlx, localPath: relative, imported: imported))303 }304 } else if entry.lowercased().hasSuffix(".gguf") {305 if !known.contains(relative), !entry.lowercased().contains("mmproj") {306 candidates.append(ModelDescriptor(id: "gguf:local:\(entry)", name: (entry as NSString).deletingPathExtension, backend: .gguf,307 format: .gguf, localPath: relative, imported: true))308 }309 } else {310 for file in ((try? fm.contentsOfDirectory(atPath: url.path)) ?? []).sorted() where file.lowercased().hasSuffix(".gguf") {311 let path = "\(relative)/\(file)"312 if known.contains(path) || file.lowercased().contains("mmproj") { continue }313 if let part = ModelMetadataResolver.splitPart(file), part.index != 1 { continue }314 candidates.append(ModelDescriptor(id: "gguf:\(relative):\(file)", name: (file as NSString).deletingPathExtension, repoID: relative,315 fileName: file, backend: .gguf, format: .gguf, localPath: path))316 }317 }318 for c in candidates where models[c.id] == nil {319 if let d = try? register(c) { report.adopted.append(d.id) }320 }321 }322 }323 if !report.removed.isEmpty { save() }324 return report325 }326}327