SPB Git

Repository Public

HuggingFaceAPI.swift 16.6 KB 306 lines swift

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

Theme