SPB Git

Repository Public

ModelLibrary.swift 18.7 KB 327 lines swift

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
Files main
Menu

Theme