SPB Git

Repository Public

DeviceModelCatalog.swift 9.8 KB 152 lines swift

1// Author: Simon-Pierre Boucher — contact@spboucher.ai2// File: Packages/LocalChatModelHub/Sources/DeviceModelCatalog.swift3// Description: The live list of MLX models published by mlx-community on Hugging Face, with size and memory estimates, and which Apple device classes can run each.4import Foundation5import LocalChatCore67/// One MLX repository from the Hub listing. Sizes are estimates (parameters × nominal bits per weight) until the repository detail is fetched.8public struct CatalogModel: Sendable, Hashable, Identifiable, Codable {9    public enum Task: String, Sendable, Codable, CaseIterable, Identifiable {10        case chat, vision, embeddings11        public var id: String { rawValue }12        public var title: String { switch self { case .chat: "Chat"; case .vision: "Vision"; case .embeddings: "Embeddings" } }13        public var pipelineTags: [String] {14            switch self { case .chat: ["text-generation"]; case .vision: ["image-text-to-text"]; case .embeddings: ["sentence-similarity", "feature-extraction"] }15        }16    }17    public var repoID: String18    public var task: Task19    public var architecture: String?20    public var parameterCount: Int64?21    public var quantization: String?22    public var bitsPerWeight: Double?23    public var estimatedSizeBytes: Int64?24    public var downloads: Int25    public var likes: Int26    public var lastModified: Date?27    public var isGated: Bool28    public var license: String?29    public var capabilities: Set<ModelCapability>30    /// nil when mlx-swift-lm implements the architecture, otherwise why Local Chat cannot load it.31    public var unsupportedReason: String?32    /// True when the Hub published the parameter count; false when it was read from the repository name.33    public var parametersAreDeclared: Bool = true34    public var id: String { repoID }35    public var name: String { repoID.split(separator: "/").last.map(String.init) ?? repoID }36    public var isSupported: Bool { unsupportedReason == nil }3738    /// Weights + KV cache at `context` tokens + runtime overhead (same formula as `ModelDescriptor.estimatedMemoryBytes`).39    public func estimatedMemoryBytes(context: Int = 4096) -> Int64? { descriptor.estimatedMemoryBytes(context: context) }4041    public var descriptor: ModelDescriptor {42        ModelDescriptor(id: "mlx:\(repoID)", name: name, repoID: repoID, backend: .mlx, format: .mlx, architecture: architecture,43                        parameterCount: parameterCount, parameterProvenance: parameterCount == nil ? .unknown : (parametersAreDeclared ? .declared : .inferred), quantization: quantization,44                        bitsPerWeight: bitsPerWeight, capabilities: capabilities, license: license, sizeBytes: estimatedSizeBytes)45    }46}4748public struct DeviceCatalogEntry: Sendable, Hashable, Identifiable {49    public var model: CatalogModel50    public var fit: ModelFit51    public var estimatedMemoryBytes: Int64?52    public var id: String { model.id }53}5455public actor DeviceModelCatalog {56    public struct Snapshot: Sendable, Codable { public var fetchedAt: Date; public var models: [CatalogModel] }5758    private let api: HuggingFaceAPI59    private let cacheURL: URL?60    private let author: String61    private var snapshot: Snapshot?62    public static let maxAge: TimeInterval = 24 * 36006364    public init(api: HuggingFaceAPI, cacheURL: URL?, author: String = "mlx-community") { self.api = api; self.cacheURL = cacheURL; self.author = author }6566    /// Cached list when it is younger than a day, otherwise a fresh listing (most downloaded first). Falls back to the cache when offline.67    public func models(forceRefresh: Bool = false, pagesPerTask: Int = 2) async throws -> Snapshot {68        if snapshot == nil, let cacheURL, let data = try? Data(contentsOf: cacheURL) { snapshot = try? CoreCoding.decoder.decode(Snapshot.self, from: data) }69        if !forceRefresh, let snapshot, Date().timeIntervalSince(snapshot.fetchedAt) < Self.maxAge, !snapshot.models.isEmpty { return snapshot }70        do {71            var seen = Set<String>(); var out: [CatalogModel] = []72            for task in CatalogModel.Task.allCases {73                for tag in task.pipelineTags {74                    var next: URL? = Self.listingURL(base: api.baseURL, author: author, pipelineTag: tag)75                    var page = 076                    while let url = next, page < pagesPerTask {77                        let result = try await api.page(at: url)78                        for hub in result.models where seen.insert(hub.id).inserted { if let model = Self.catalogModel(hub, task: task) { out.append(model) } }79                        next = result.next; page += 180                    }81                }82            }83            let fresh = Snapshot(fetchedAt: Date(), models: out.sorted { $0.downloads > $1.downloads })84            snapshot = fresh85            if let cacheURL, let data = try? CoreCoding.encoder.encode(fresh) { try? data.write(to: cacheURL, options: .atomic) }86            return fresh87        } catch {88            if let snapshot, !snapshot.models.isEmpty { return snapshot }89            throw error90        }91    }9293    /// The listing only returns parameter counts when `safetensors` is requested explicitly (`full=true` leaves it out).94    static func listingURL(base: URL, author: String, pipelineTag: String) -> URL {95        var c = URLComponents(url: base.appendingPathComponent("api/models"), resolvingAgainstBaseURL: false)!96        c.queryItems = [.init(name: "filter", value: "mlx"), .init(name: "pipeline_tag", value: pipelineTag), .init(name: "author", value: author),97                        .init(name: "sort", value: "downloads"), .init(name: "direction", value: "-1"), .init(name: "limit", value: "100")]98            + ["safetensors", "config", "downloads", "likes", "pipeline_tag", "tags", "lastModified", "gated"].map { .init(name: "expand[]", value: $0) }99        return c.url!100    }101102    /// Builds a catalog entry from a Hub listing item. Returns nil for repositories that are not runnable models (adapters, datasets of weights without a config).103    public static func catalogModel(_ hub: HubModel, task: CatalogModel.Task) -> CatalogModel? {104        let name = hub.id105        let lower = name.lowercased()106        if lower.contains("lora") || lower.contains("adapter") { return nil }107        let architecture = hub.config?["model_type"]?.stringValue108        let quant = ModelNaming.mlxQuantization(fromName: name)109        let declared = hub.safetensorsParameters110        let parameters = declared ?? ModelNaming.parameterCount(fromName: name)111        var size: Int64?112        if let parameters, let bits = quant?.bitsPerWeight { size = Int64(Double(parameters) * bits / 8) }113        let hasVision = task == .vision114        var capabilities = ModelNaming.capabilities(name: name, pipelineTag: hub.pipelineTag, tags: hub.tags,115                                                    chatTemplate: hub.config?["tokenizer_config"]?["chat_template"]?.stringValue, hasVisionConfig: hasVision)116        if task == .embeddings { capabilities = [.embeddings] }117        var reason: String?118        if let architecture {119            let supported: Set<String> = switch task { case .chat: MLXArchitectures.text.union(MLXArchitectures.vision); case .vision: MLXArchitectures.vision; case .embeddings: MLXArchitectures.embedding }120            if !supported.contains(architecture) { reason = "Architecture “\(architecture)” is not implemented in MLX Swift \(MLXArchitectures.version)." }121        } else { reason = "The repository does not declare its architecture." }122        return CatalogModel(repoID: hub.id, task: task, architecture: architecture, parameterCount: parameters, quantization: quant?.label,123                            bitsPerWeight: quant?.bitsPerWeight, estimatedSizeBytes: size, downloads: hub.downloads ?? 0, likes: hub.likes ?? 0,124                            lastModified: hub.lastModified, isGated: hub.isGated, license: hub.license, capabilities: capabilities, unsupportedReason: reason, parametersAreDeclared: declared != nil)125    }126127    /// The models a device class can run: loadable architecture, known size, fits in memory. Most downloaded first.128    public static func entries(_ models: [CatalogModel], for device: AppleDeviceClass, task: CatalogModel.Task? = nil, includeTight: Bool = true,129                               context: Int = 4096) -> [DeviceCatalogEntry] {130        models.compactMap { model in131            guard model.isSupported, task == nil || model.task == task else { return nil }132            let need = model.estimatedMemoryBytes(context: context)133            let fit = device.fit(estimatedMemoryBytes: need)134            guard fit == .comfortable || (includeTight && fit == .tight) else { return nil }135            return DeviceCatalogEntry(model: model, fit: fit, estimatedMemoryBytes: need)136        }137    }138139    /// The largest (by parameters) well-downloaded models that fit comfortably: a short "best picks" list for a device class.140    public static func bestPicks(_ models: [CatalogModel], for device: AppleDeviceClass, task: CatalogModel.Task, count: Int = 5, minimumDownloads: Int = 500) -> [DeviceCatalogEntry] {141        let fitting = entries(models, for: device, task: task, includeTight: false).filter { $0.model.downloads >= minimumDownloads }142        // one entry per base model family and size: keep the most downloaded quantization of each143        var byFamily: [String: DeviceCatalogEntry] = [:]144        for entry in fitting {145            let key = entry.model.name.lowercased().replacingOccurrences(of: "-?(\\d)bit.*$|-?(bf16|fp16|dwq|qat).*$", with: "", options: .regularExpression)146            if let current = byFamily[key], current.model.downloads >= entry.model.downloads { continue }147            byFamily[key] = entry148        }149        return Array(byFamily.values.sorted { (($0.model.parameterCount ?? 0), $0.model.downloads) > (($1.model.parameterCount ?? 0), $1.model.downloads) }.prefix(count))150    }151}152
Files main
Menu

Theme