Repository Public
1// Author: Simon-Pierre Boucher — contact@spboucher.ai2// File: Packages/LocalChatModelHub/Sources/ModelMetadataResolver.swift3// Description: Turns a Hub repository into downloadable candidates (one MLX model, or one per GGUF file) with sizes, quantization and capability rules.4import Foundation5import LocalChatCore67/// Something the user can download: a descriptor, the exact files that will be fetched, and what is known to be a problem.8public struct ModelCandidate: Sendable, Hashable, Identifiable {9 public var descriptor: ModelDescriptor10 public var files: [HubFile]11 public var projector: HubFile? // GGUF vision projector (mmproj) found in the repository, downloaded with the model12 public var isGated: Bool13 public var unsupportedReason: String? // set when the architecture is known not to be implemented by the backend14 public var notes: [String]15 public var id: String { descriptor.id }16 public var downloadBytes: Int64 { files.reduce(0) { $0 + ($1.size ?? 0) } }17}1819public struct ModelMetadataResolver: Sendable {20 /// `config.json` model types the MLX backend implements (LLM, VLM and embedders). Nil = unknown, no verdict is given.21 public var supportedMLXArchitectures: Set<String>?22 /// GGUF `general.architecture` values the llama.cpp backend supports. Nil = unknown.23 public var supportedGGUFArchitectures: Set<String>?2425 public init(supportedMLXArchitectures: Set<String>? = MLXArchitectures.all, supportedGGUFArchitectures: Set<String>? = nil) {26 self.supportedMLXArchitectures = supportedMLXArchitectures; self.supportedGGUFArchitectures = supportedGGUFArchitectures27 }2829 public func candidates(for model: HubModel) -> [ModelCandidate] {30 var out: [ModelCandidate] = []31 if let mlx = mlxCandidate(for: model) { out.append(mlx) }32 out.append(contentsOf: ggufCandidates(for: model))33 return out34 }3536 public func unsupportedMLXReason(architecture: String?) -> String? {37 guard let supported = supportedMLXArchitectures, let architecture else { return nil }38 return supported.contains(architecture) ? nil : "The architecture “\(architecture)” is not implemented in MLX Swift."39 }4041 // MARK: MLX4243 static let weightExtensions: Set<String> = ["safetensors"]44 static let auxiliaryExtensions: Set<String> = ["json", "jinja", "txt", "model", "tiktoken"]45 static let allowedSubfolders: Set<String> = ["1_Pooling", "2_Dense", "2_Normalize"] // sentence-transformers modules the embedders read4647 /// Files of an MLX (or safetensors embedder) repository that are needed to run it.48 public static func mlxFiles(in model: HubModel) -> [HubFile] {49 model.files.filter { file in50 let parts = file.path.split(separator: "/")51 if parts.count > 2 || (parts.count == 2 && !allowedSubfolders.contains(String(parts[0]))) { return false }52 let name = file.fileName.lowercased(), ext = (name as NSString).pathExtension53 if name.hasPrefix(".") || name == "license.txt" || name == "notice.txt" || name == "requirements.txt" { return false }54 if ["training_args.json", "trainer_state.json", "all_results.json", "eval_results.json", "train_results.json"].contains(name) { return false }55 if weightExtensions.contains(ext) { return !name.contains("adapter") && !name.hasPrefix("optimizer") }56 return auxiliaryExtensions.contains(ext)57 }58 }5960 public func mlxCandidate(for model: HubModel) -> ModelCandidate? {61 let files = Self.mlxFiles(in: model)62 let hasWeights = files.contains { $0.path.hasSuffix(".safetensors") }63 let hasConfig = files.contains { $0.path == "config.json" }64 guard hasWeights, hasConfig else { return nil }65 let isMLX = model.tags.contains("mlx") || model.libraryName == "mlx"66 let hasVisionConfig = model.config?["vision_config"] != nil || ["image-text-to-text", "video-text-to-text"].contains(model.pipelineTag ?? "")67 let caps = ModelNaming.capabilities(name: model.id, pipelineTag: model.pipelineTag, tags: model.tags, chatTemplate: model.chatTemplate,68 hasVisionConfig: hasVisionConfig)69 // Plain safetensors repositories are only offered when they are embedders: MLX Swift loads those from the original weights.70 guard isMLX || caps == [.embeddings] else { return nil }7172 let configBits = model.config?["quantization_config"]?["bits"]?.intValue ?? model.config?["quantization"]?["bits"]?.intValue73 let quant = ModelNaming.mlxQuantization(fromName: model.name, configBits: configBits)74 var parameters = model.safetensorsParameters; var provenance: Provenance = parameters == nil ? .unknown : .declared75 if parameters == nil, let p = ModelNaming.parameterCount(fromName: model.name) { parameters = p; provenance = .inferred }76 let size = files.reduce(Int64(0)) { $0 + ($1.size ?? 0) }77 var notes: [String] = []78 if !isMLX { notes.append("Not an MLX conversion: the original safetensors weights are used.") }79 if files.contains(where: { $0.size == nil }) { notes.append("Some file sizes are unknown; the download size is a lower bound.") }80 if model.isGated { notes.append("Gated repository: accept its license on huggingface.co and add your token in Settings.") }81 let context = model.config?["max_position_embeddings"]?.intValue ?? model.config?["text_config"]?["max_position_embeddings"]?.intValue82 let descriptor = ModelDescriptor(83 id: "mlx:\(model.id)", name: model.name, repoID: model.id, revision: model.commit, backend: .mlx, format: .mlx,84 architecture: model.modelType, parameterCount: parameters, parameterProvenance: provenance, quantization: quant?.label,85 bitsPerWeight: quant?.bitsPerWeight, contextLength: context, capabilities: caps, license: model.license,86 sizeBytes: size > 0 ? size : nil)87 return ModelCandidate(descriptor: descriptor, files: files, projector: nil, isGated: model.isGated,88 unsupportedReason: unsupportedMLXReason(architecture: model.modelType), notes: notes)89 }9091 // MARK: GGUF9293 /// "name-00001-of-00003.gguf" → ("name", 1, 3)94 static func splitPart(_ fileName: String) -> (stem: String, index: Int, total: Int)? {95 guard let regex = try? NSRegularExpression(pattern: "^(.*)-([0-9]{5})-of-([0-9]{5})\\.gguf$", options: [.caseInsensitive]) else { return nil }96 guard let m = regex.firstMatch(in: fileName, range: NSRange(fileName.startIndex..., in: fileName)),97 let s = Range(m.range(at: 1), in: fileName), let i = Range(m.range(at: 2), in: fileName), let t = Range(m.range(at: 3), in: fileName),98 let index = Int(fileName[i]), let total = Int(fileName[t]) else { return nil }99 return (String(fileName[s]), index, total)100 }101102 public func ggufCandidates(for model: HubModel) -> [ModelCandidate] {103 let gguf = model.files.filter { $0.path.lowercased().hasSuffix(".gguf") }104 guard !gguf.isEmpty else { return [] }105 let projectors = gguf.filter { $0.fileName.lowercased().contains("mmproj") }106 let weights = gguf.filter { !$0.fileName.lowercased().contains("mmproj") }107 // prefer a half-precision projector: it is what llama.cpp examples ship by default108 let projector = projectors.first { $0.fileName.lowercased().contains("f16") } ?? projectors.first109110 // group split files; a group is only offered when every part is present111 var groups: [(first: HubFile, parts: [HubFile])] = []; var splits: [String: [(Int, Int, HubFile)]] = [:]; var order: [String] = []112 for file in weights {113 if let part = Self.splitPart(file.fileName) {114 let key = (file.path as NSString).deletingLastPathComponent + "/" + part.stem115 if splits[key] == nil { order.append(key) }116 splits[key, default: []].append((part.index, part.total, file))117 } else { groups.append((file, [file])) }118 }119 for key in order {120 let parts = splits[key]!.sorted { $0.0 < $1.0 }121 if let total = parts.first?.1, parts.count == total, parts.map(\.0) == Array(1...total) { groups.append((parts[0].2, parts.map(\.2))) }122 }123124 let architecture = model.gguf?["architecture"]?.stringValue ?? model.modelType125 let declared = Self.int64(model.gguf?["total"])126 let context = Self.int64(model.gguf?["context_length"]).map(Int.init)127 let template = model.chatTemplate128 var unsupported: String?129 if let supported = supportedGGUFArchitectures, let architecture, !supported.contains(architecture) {130 unsupported = "The architecture “\(architecture)” is not supported by this build of llama.cpp."131 }132 return groups.map { group in133 let name = group.first.fileName134 let quant = ModelNaming.ggufQuantization(fromName: name)135 var parameters = declared; var provenance: Provenance = declared == nil ? .unknown : .declared136 if parameters == nil, let p = ModelNaming.parameterCount(fromName: name) ?? ModelNaming.parameterCount(fromName: model.name) { parameters = p; provenance = .inferred }137 var caps = ModelNaming.capabilities(name: model.id, pipelineTag: model.pipelineTag, tags: model.tags, chatTemplate: template,138 hasVisionConfig: false, hasProjector: projector != nil)139 if projector == nil { caps.remove(.vision) } // a GGUF language model cannot see without its projector file140 var files = group.parts; var notes: [String] = []141 if let projector, caps.contains(.vision) { files.append(projector); notes.append("Includes the vision projector \(projector.fileName).") }142 if group.parts.count > 1 { notes.append("Split in \(group.parts.count) parts.") }143 if model.isGated { notes.append("Gated repository: accept its license on huggingface.co and add your token in Settings.") }144 let size = files.reduce(Int64(0)) { $0 + ($1.size ?? 0) }145 let display = (name as NSString).deletingPathExtension.replacingOccurrences(of: "-00001-of-\(String(format: "%05d", group.parts.count))", with: "")146 let descriptor = ModelDescriptor(147 id: "gguf:\(model.id):\(group.first.path)", name: display, repoID: model.id, revision: model.commit, fileName: group.first.path,148 backend: .gguf, format: .gguf, architecture: architecture, parameterCount: parameters, parameterProvenance: provenance,149 quantization: quant?.label, bitsPerWeight: quant?.bitsPerWeight, contextLength: context, capabilities: caps,150 license: model.license, sizeBytes: size > 0 ? size : nil)151 return ModelCandidate(descriptor: descriptor, files: files, projector: caps.contains(.vision) ? projector : nil,152 isGated: model.isGated, unsupportedReason: unsupported, notes: notes)153 }.sorted { ($0.descriptor.sizeBytes ?? 0) < ($1.descriptor.sizeBytes ?? 0) }154 }155156 /// The Hub sends GGUF numbers sometimes as numbers, sometimes as strings.157 static func int64(_ value: JSONValue?) -> Int64? {158 if let n = value?.numberValue { return Int64(n) }159 if let s = value?.stringValue { return Int64(s) }160 return nil161 }162}163