Repository Public
1// Author: Simon-Pierre Boucher — contact@spboucher.ai2// File: Packages/LocalChatModelHub/Sources/HuggingFaceAPI.swift3// Description: Hugging Face Hub client (search, repository detail with file sizes and LFS hashes, model card) over URLSession.4import Foundation5import LocalChatCore67public enum HubError: LocalizedError, Sendable, Equatable {8 case invalidRepository(String)9 case notFound(String)10 case gated(String)11 case unauthorized(String)12 case rateLimited13 case http(Int)14 case network(String)15 case invalidResponse(String)16 case integrityFailure(file: String, detail: String)17 case insufficientStorage(needed: Int64, available: Int64)18 case nothingToDownload19 case importFailed(String)20 case cancelled2122 public var errorDescription: String? {23 switch self {24 case .invalidRepository(let r): "“\(r)” is not a valid Hugging Face repository."25 case .notFound(let r): "\(r) was not found on Hugging Face (or it is private and needs a token)."26 case .gated(let r): "\(r) is gated: it requires accepting the license on huggingface.co and a Hugging Face token."27 case .unauthorized(let r): "Hugging Face refused access to \(r). Check the token in Settings."28 case .rateLimited: "Hugging Face is rate limiting requests. Try again in a moment."29 case .http(let code): "Hugging Face answered with HTTP \(code)."30 case .network(let m): "Network error: \(m)"31 case .invalidResponse(let m): "Unexpected answer from Hugging Face: \(m)"32 case .integrityFailure(let file, let detail): "\(file) failed its integrity check (\(detail)). The partial file was removed; resume to download it again."33 case .insufficientStorage(let needed, let available): "Not enough free storage: needs \(ByteFormat.string(needed)), \(ByteFormat.string(available)) free."34 case .nothingToDownload: "This repository has no file this app can use."35 case .importFailed(let m): "Import failed: \(m)"36 case .cancelled: "Cancelled."37 }38 }3940 /// Worth retrying after a pause.41 public var isTransient: Bool {42 switch self {43 case .rateLimited, .network: true44 case .http(let code): code >= 500 || code == 40845 default: false46 }47 }48}4950public enum HubFormat: String, Sendable, Codable, CaseIterable { case mlx, gguf }5152public enum HubSort: String, Sendable, CaseIterable {53 case trending = "trendingScore", downloads, likes, lastModified, created = "createdAt"54 public var title: String {55 switch self { case .trending: "Trending"; case .downloads: "Most downloaded"; case .likes: "Most liked"; case .lastModified: "Recently updated"; case .created: "Newest" }56 }57}5859public struct HubFile: Codable, Sendable, Hashable, Identifiable {60 public var path: String // "rfilename"61 public var size: Int64? // nil in search results (only repository detail with blobs carries sizes)62 public var sha256: String? // LFS files only63 public var id: String { path }64 public init(path: String, size: Int64? = nil, sha256: String? = nil) { self.path = path; self.size = size; self.sha256 = sha256 }65 public var isLFS: Bool { sha256 != nil }66 public var fileName: String { (path as NSString).lastPathComponent }67}6869/// A repository as the Hub describes it. Search results carry a subset of the fields (no sizes, no card data).70public struct HubModel: Sendable, Hashable, Identifiable {71 public enum Gating: String, Sendable, Codable { case open, auto, manual }72 public var id: String // "org/name"73 public var author: String?74 public var commit: String? // "sha"75 public var pipelineTag: String?76 public var libraryName: String?77 public var tags: [String]78 public var downloads: Int?79 public var likes: Int?80 public var lastModified: Date?81 public var createdAt: Date?82 public var gating: Gating83 public var isPrivate: Bool84 public var files: [HubFile]85 public var safetensorsParameters: Int64? // safetensors.total86 public var config: JSONValue? // subset of config.json + tokenizer_config the Hub exposes87 public var cardData: JSONValue?88 public var gguf: JSONValue? // GGUF metadata the Hub parsed (architecture, context_length, total, chat_template)89 public var usedStorage: Int64?9091 public var name: String { id.split(separator: "/").last.map(String.init) ?? id }92 public var organization: String { author ?? id.split(separator: "/").first.map(String.init) ?? "" }93 public var isGated: Bool { gating != .open }94 public var license: String? {95 if let l = cardData?["license"]?.stringValue { return l }96 return tags.first { $0.hasPrefix("license:") }.map { String($0.dropFirst("license:".count)) }97 }98 public var modelType: String? { config?["model_type"]?.stringValue ?? gguf?["architecture"]?.stringValue }99 public var baseModel: String? {100 cardData?["base_model"]?.stringValue ?? cardData?["base_model"]?.arrayValue?.first?.stringValue101 ?? tags.first { $0.hasPrefix("base_model:") && !$0.contains(":quantized:") && !$0.contains(":finetune:") }.map { String($0.dropFirst("base_model:".count)) }102 }103 public var chatTemplate: String? {104 if let t = gguf?["chat_template"]?.stringValue { return t }105 let raw = config?["tokenizer_config"]?["chat_template"]106 if let s = raw?.stringValue { return s }107 return raw?.arrayValue?.compactMap { $0["template"]?.stringValue }.joined(separator: "\n")108 }109 public var webURL: URL? { URL(string: "https://huggingface.co/\(id)") }110}111112extension HubModel: Decodable {113 private enum Keys: String, CodingKey {114 case id, modelId, author, sha, pipeline_tag, library_name, tags, downloads, likes, lastModified, createdAt, gated115 case isPrivate = "private", siblings, safetensors, config, cardData, gguf, usedStorage116 }117 private struct Sibling: Decodable {118 struct LFS: Decodable { var sha256: String?; var size: Int64? }119 var rfilename: String; var size: Int64?; var lfs: LFS?120 }121 private struct Safetensors: Decodable { var total: Int64? }122123 public init(from decoder: Decoder) throws {124 let c = try decoder.container(keyedBy: Keys.self)125 guard let id = try c.decodeIfPresent(String.self, forKey: .id) ?? c.decodeIfPresent(String.self, forKey: .modelId) else {126 throw DecodingError.dataCorrupted(.init(codingPath: c.codingPath, debugDescription: "model without id"))127 }128 self.id = id129 author = try? c.decodeIfPresent(String.self, forKey: .author)130 commit = try? c.decodeIfPresent(String.self, forKey: .sha)131 pipelineTag = try? c.decodeIfPresent(String.self, forKey: .pipeline_tag)132 libraryName = try? c.decodeIfPresent(String.self, forKey: .library_name)133 tags = (try? c.decodeIfPresent([String].self, forKey: .tags)) ?? []134 downloads = try? c.decodeIfPresent(Int.self, forKey: .downloads)135 likes = try? c.decodeIfPresent(Int.self, forKey: .likes)136 lastModified = (try? c.decodeIfPresent(String.self, forKey: .lastModified)).flatMap(HubDate.parse)137 createdAt = (try? c.decodeIfPresent(String.self, forKey: .createdAt)).flatMap(HubDate.parse)138 // "gated" is false, "auto" or "manual"139 if let s = try? c.decodeIfPresent(String.self, forKey: .gated) { gating = Gating(rawValue: s) ?? .manual }140 else if (try? c.decodeIfPresent(Bool.self, forKey: .gated)) == true { gating = .manual }141 else { gating = .open }142 isPrivate = (try? c.decodeIfPresent(Bool.self, forKey: .isPrivate)) ?? false143 let siblings = (try? c.decodeIfPresent([Sibling].self, forKey: .siblings)) ?? []144 files = siblings.map { HubFile(path: $0.rfilename, size: $0.lfs?.size ?? $0.size, sha256: $0.lfs?.sha256) }145 safetensorsParameters = (try? c.decodeIfPresent(Safetensors.self, forKey: .safetensors))?.total146 config = try? c.decodeIfPresent(JSONValue.self, forKey: .config)147 cardData = try? c.decodeIfPresent(JSONValue.self, forKey: .cardData)148 gguf = try? c.decodeIfPresent(JSONValue.self, forKey: .gguf)149 usedStorage = try? c.decodeIfPresent(Int64.self, forKey: .usedStorage)150 }151}152153enum HubDate {154 static func parse(_ text: String) -> Date? {155 let f = ISO8601DateFormatter(); f.formatOptions = [.withInternetDateTime, .withFractionalSeconds]156 if let d = f.date(from: text) { return d }157 f.formatOptions = [.withInternetDateTime]158 return f.date(from: text)159 }160}161162public struct HubSearchQuery: Sendable, Hashable {163 public var text: String164 public var format: HubFormat? // nil = any repository165 public var pipelineTag: String? // "text-generation", "image-text-to-text", "sentence-similarity", …166 public var author: String?167 public var sort: HubSort168 public var limit: Int169 public init(text: String = "", format: HubFormat? = .mlx, pipelineTag: String? = nil, author: String? = nil, sort: HubSort = .downloads, limit: Int = 30) {170 self.text = text; self.format = format; self.pipelineTag = pipelineTag; self.author = author; self.sort = sort; self.limit = limit171 }172}173174public struct HubSearchPage: Sendable {175 public var models: [HubModel]176 public var next: URL? // cursor for the following page, from the Link header177}178179public struct HuggingFaceAPI: Sendable {180 public typealias TokenProvider = @Sendable () async -> String?181 public let baseURL: URL182 let session: URLSession183 let tokenProvider: TokenProvider184185 /// - Parameters:186 /// - session: inject a session with stub `protocolClasses` in tests.187 /// - tokenProvider: returns the user's Hugging Face token (read from the Keychain by the app), or nil.188 public init(baseURL: URL = URL(string: "https://huggingface.co")!, session: URLSession? = nil, tokenProvider: @escaping TokenProvider = { nil }) {189 self.baseURL = baseURL; self.tokenProvider = tokenProvider190 if let session { self.session = session } else {191 let c = URLSessionConfiguration.ephemeral192 c.timeoutIntervalForRequest = 30; c.waitsForConnectivity = false; c.httpAdditionalHeaders = ["User-Agent": "LocalChat"]193 self.session = URLSession(configuration: c)194 }195 }196197 public static func isValidRepositoryID(_ id: String) -> Bool {198 let parts = id.split(separator: "/", omittingEmptySubsequences: false)199 guard parts.count == 2 else { return false }200 let allowed = CharacterSet(charactersIn: "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_.")201 return parts.allSatisfy { !$0.isEmpty && $0.unicodeScalars.allSatisfy(allowed.contains) && !$0.hasPrefix(".") && !$0.contains("..") }202 }203204 public func searchURL(_ query: HubSearchQuery) -> URL {205 var c = URLComponents(url: baseURL.appendingPathComponent("api/models"), resolvingAgainstBaseURL: false)!206 var items: [URLQueryItem] = []207 let text = query.text.trimmingCharacters(in: .whitespacesAndNewlines)208 if !text.isEmpty { items.append(.init(name: "search", value: text)) }209 // the "mlx" / "gguf" tags are more reliable than library_name (many MLX conversions keep library_name=transformers)210 if let format = query.format { items.append(.init(name: "filter", value: format.rawValue)) }211 if let tag = query.pipelineTag, !tag.isEmpty { items.append(.init(name: "pipeline_tag", value: tag)) }212 if let author = query.author, !author.isEmpty { items.append(.init(name: "author", value: author)) }213 items += [.init(name: "sort", value: query.sort.rawValue), .init(name: "direction", value: "-1"),214 .init(name: "limit", value: String(max(1, min(100, query.limit)))), .init(name: "full", value: "true"), .init(name: "config", value: "true")]215 c.queryItems = items216 return c.url!217 }218219 public func search(_ query: HubSearchQuery) async throws -> HubSearchPage { try await page(at: searchURL(query)) }220221 /// Follows the cursor returned by a previous page.222 public func page(at url: URL) async throws -> HubSearchPage {223 let (data, response) = try await get(url, repo: nil)224 do {225 let models = try JSONDecoder().decode([FailableModel].self, from: data).compactMap(\.model)226 return HubSearchPage(models: models, next: Self.nextLink(response.value(forHTTPHeaderField: "Link")))227 } catch { throw HubError.invalidResponse(String(describing: error).prefix(200).description) }228 }229230 /// Repository detail with every file's size and, for LFS files, its SHA-256.231 public func model(_ repoID: String, revision: String? = nil) async throws -> HubModel {232 guard Self.isValidRepositoryID(repoID) else { throw HubError.invalidRepository(repoID) }233 var path = "api/models/\(repoID)"234 if let revision, !revision.isEmpty { path += "/revision/\(revision)" }235 var c = URLComponents(url: baseURL.appendingPathComponent(path), resolvingAgainstBaseURL: false)!236 c.queryItems = [.init(name: "blobs", value: "true")]237 let (data, _) = try await get(c.url!, repo: repoID)238 do { return try JSONDecoder().decode(HubModel.self, from: data) }239 catch { throw HubError.invalidResponse(String(describing: error).prefix(200).description) }240 }241242 /// The raw model card (README.md), without its YAML front matter. Nil when the repository has none.243 public func readme(_ repoID: String, revision: String = "main") async throws -> String? {244 guard Self.isValidRepositoryID(repoID) else { throw HubError.invalidRepository(repoID) }245 do {246 let (data, _) = try await get(Self.resolveURL(base: baseURL, repoID: repoID, revision: revision, path: "README.md"), repo: repoID)247 var text = String(decoding: data, as: UTF8.self)248 if text.hasPrefix("---"), let end = text.range(of: "\n---", range: text.index(text.startIndex, offsetBy: 3)..<text.endIndex) {249 text = String(text[end.upperBound...]).trimmingCharacters(in: .whitespacesAndNewlines)250 }251 return text252 } catch HubError.notFound { return nil }253 }254255 public static func resolveURL(base: URL, repoID: String, revision: String, path: String) -> URL {256 var url = base.appendingPathComponent(repoID).appendingPathComponent("resolve").appendingPathComponent(revision)257 for part in path.split(separator: "/") { url.appendPathComponent(String(part)) }258 return url259 }260261 private struct FailableModel: Decodable {262 var model: HubModel?263 init(from decoder: Decoder) throws { model = try? HubModel(from: decoder) }264 }265266 static func nextLink(_ header: String?) -> URL? {267 guard let header else { return nil }268 for part in header.components(separatedBy: ",") where part.contains("rel=\"next\"") {269 if let open = part.firstIndex(of: "<"), let close = part.firstIndex(of: ">"), open < close {270 return URL(string: String(part[part.index(after: open)..<close]))271 }272 }273 return nil274 }275276 private func get(_ url: URL, repo: String?) async throws -> (Data, HTTPURLResponse) {277 var request = URLRequest(url: url)278 request.setValue("application/json", forHTTPHeaderField: "Accept")279 let token = await tokenProvider()280 if let token, !token.isEmpty { request.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization") }281 let data: Data, response: URLResponse282 do { (data, response) = try await session.data(for: request) }283 catch is CancellationError { throw HubError.cancelled }284 catch let e as URLError where e.code == .cancelled { throw HubError.cancelled }285 catch { throw HubError.network(error.localizedDescription) }286 guard let http = response as? HTTPURLResponse else { throw HubError.invalidResponse("not HTTP") }287 if let error = Self.error(status: http.statusCode, repo: repo ?? url.host ?? "", hasToken: token?.isEmpty == false,288 errorCode: http.value(forHTTPHeaderField: "X-Error-Code")) { throw error }289 return (data, http)290 }291292 /// Maps a Hub status to an error. Without a token the Hub answers 401 both for gated files and for repositories that do not exist.293 static func error(status: Int, repo: String, hasToken: Bool, errorCode: String?) -> HubError? {294 switch status {295 case 200..<300: return nil296 case 401, 403:297 if errorCode == "GatedRepo" { return .gated(repo) }298 if errorCode == "RepoNotFound" { return hasToken ? .unauthorized(repo) : .notFound(repo) }299 return status == 403 ? .gated(repo) : (hasToken ? .unauthorized(repo) : .notFound(repo))300 case 404: return .notFound(repo)301 case 429: return .rateLimited302 default: return .http(status)303 }304 }305}306