Repository Public
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