SPB Git

Repository Public MIT

ModelCatalog.swift 21.0 KB 407 lines swift

1// =============================================================================2//                  SP BOUCHER | SOFTWARE & RESEARCH3//             ARTIFICIAL INTELLIGENCE • FINANCE • ENGINEERING4// =============================================================================5//6// PROJECT METADATA7// -----------------------------------------------------------------------------8// Project          : ORIX Astra9// File             : Packages/AstraLocal/Sources/ModelCatalog.swift10// Module           : Packages11// Repository       : https://git.spboucher.ai/orix-astra12// Created          : 2026-11-2113// Last Modified    : 2026-11-2114//15// =============================================================================16// AUTHOR & PROFESSIONAL AFFILIATION17// =============================================================================18//19// Author           : Simon-Pierre Boucher20// Position         : Professor of Finance21// Institution      : Université du Québec en Outaouais (UQO)22// Department       : Département des sciences administratives23// Organization     : SP Boucher24//25// Website          : https://spboucher.ai26// Git              : https://git.spboucher.ai27//28// =============================================================================29// OFFICIAL CONTACT DIRECTORY30// =============================================================================31//32// General          : info@spboucher.ai33// Professional     : contact@spboucher.ai34// Direct           : simon@spboucher.ai35// Research         : research@spboucher.ai36// Development      : dev@spboucher.ai37// Support          : support@spboucher.ai38// Security/Admin   : admin@spboucher.ai39// Notifications    : notifications@spboucher.ai40//41// Preferred Contact: support@spboucher.ai42//43// =============================================================================44// COPYRIGHT & INTELLECTUAL PROPERTY45// =============================================================================46//47// Copyright (c) 202648// Simon-Pierre Boucher49//50// All rights reserved where applicable.51//52// This file is governed by the applicable project license,53// copyright notices, institutional agreements and relevant law.54//55// Unless expressly authorized by the applicable license or56// rights holder, copying, redistribution, sublicensing,57// publication and commercial exploitation are not permitted.58//59// Existing third-party rights and notices remain unaffected.60//61// =============================================================================62// CONFIDENTIALITY & SECURITY63// =============================================================================64//65// Classification   : Public66// Distribution     : Public repository; use is governed by the project license67// Security Contact : admin@spboucher.ai68//69// Access to this source does not independently grant permission70// to redistribute or disclose confidential materials.71//72// Do not embed credentials, private keys, access tokens,73// certificates or confidential personal information.74//75// =============================================================================76// LICENSE & MAINTENANCE77// =============================================================================78//79// License          : Proprietary, all rights reserved (see license file)80// License File     : LICENSE81// Maintainer       : Simon-Pierre Boucher82// Technical Contact: dev@spboucher.ai83//84// =============================================================================85// END OF SP BOUCHER SOURCE HEADER86// =============================================================================8788import AstraCore89import Foundation9091// MARK: - Card9293public struct LocalModelFile: Codable, Sendable, Hashable {94    /// Path relative to the model directory, forward slashes.95    public var path: String96    public var size: Int6497    /// Lowercase hexadecimal SHA-256 of the whole file.98    public var sha256: String99    public init(path: String, size: Int64, sha256: String) { self.path = path; self.size = size; self.sha256 = sha256 }100}101102/// A measurement taken by really loading and running the model. Absent when nobody ran it.103public struct VerifiedRecord: Codable, Sendable, Hashable {104    /// ISO date of the run (yyyy-MM-dd).105    public var date: String106    /// Hardware the run happened on ("Mac17,6 (Apple M5 Max, 48 GB)"). A Mac measurement says nothing about an iPhone.107    public var machine: String108    /// "macOS" or "iOS": never inferred, always the platform the run happened on.109    public var platform: String110    public var osVersion: String111    public var tokensPerSecond: Double112    /// Seconds from request to first token, warm (model already loaded).113    public var timeToFirstToken: Double114    public var peakMemoryBytes: Int64?115    public var runtime: String?116    public init(date: String, machine: String, platform: String, osVersion: String, tokensPerSecond: Double, timeToFirstToken: Double,117                peakMemoryBytes: Int64? = nil, runtime: String? = nil) {118        self.date = date; self.machine = machine; self.platform = platform; self.osVersion = osVersion119        self.tokensPerSecond = tokensPerSecond; self.timeToFirstToken = timeToFirstToken; self.peakMemoryBytes = peakMemoryBytes; self.runtime = runtime120    }121}122123/// Everything the app knows about one downloadable model. Also the shape of one entry of `catalog.json`.124public struct LocalModelCard: Codable, Sendable, Hashable, Identifiable {125    public var id: String126    public var displayName: String127    public var family: String128    public var publisher: String129    /// Hugging Face repository ("mlx-community/Qwen3-0.6B-4bit").130    public var repo: String131    /// Exact commit of the repository the file list and hashes were taken from (40 hex characters).132    public var revision: String133    /// `model_type` from the model's config.json.134    public var architecture: String135    public var quantization: String136    public var parameterCount: Int64?137    public var licenseID: String138    public var licenseURL: String139    /// True only when the license lets the owner re-host the weights without further conditions. False = served from Hugging Face only.140    public var redistributable: Bool141    public var totalBytes: Int64142    public var files: [LocalModelFile]143    public var contextLength: Int144    public var capabilities: [Capability]145    public var minimumDeviceMemoryGB: Double146    public var estimatedRuntimeMemoryBytes: Int64147    public var supportedTasks: [String]148    public var verified: VerifiedRecord?149    public var notes: String?150    /// Mirror on the owner's site, ending in "/". nil when the weights are not re-hosted.151    public var baseURL: String?152    /// `https://huggingface.co/<repo>/resolve/<sha>/`.153    public var fallbackBaseURL: String?154155    public init(id: String, displayName: String, family: String, publisher: String, repo: String, revision: String, architecture: String,156                quantization: String, parameterCount: Int64? = nil, licenseID: String, licenseURL: String, redistributable: Bool,157                totalBytes: Int64, files: [LocalModelFile], contextLength: Int, capabilities: [Capability] = [.text],158                minimumDeviceMemoryGB: Double, estimatedRuntimeMemoryBytes: Int64, supportedTasks: [String] = ["chat"],159                verified: VerifiedRecord? = nil, notes: String? = nil, baseURL: String? = nil, fallbackBaseURL: String? = nil) {160        self.id = id; self.displayName = displayName; self.family = family; self.publisher = publisher; self.repo = repo; self.revision = revision161        self.architecture = architecture; self.quantization = quantization; self.parameterCount = parameterCount162        self.licenseID = licenseID; self.licenseURL = licenseURL; self.redistributable = redistributable163        self.totalBytes = totalBytes; self.files = files; self.contextLength = contextLength; self.capabilities = capabilities164        self.minimumDeviceMemoryGB = minimumDeviceMemoryGB; self.estimatedRuntimeMemoryBytes = estimatedRuntimeMemoryBytes165        self.supportedTasks = supportedTasks; self.verified = verified; self.notes = notes; self.baseURL = baseURL; self.fallbackBaseURL = fallbackBaseURL166    }167168    public static func huggingFaceBase(repo: String, revision: String) -> String { "https://huggingface.co/\(repo)/resolve/\(revision)/" }169170    /// Bytes of the weight files only (what MLX maps into memory).171    public var weightsBytes: Int64 { files.filter { $0.path.hasSuffix(".safetensors") }.reduce(0) { $0 + $1.size } }172173    public var memoryProfile: ModelMemoryProfile {174        ModelMemoryProfile(weightsBytes: weightsBytes, parameterCount: parameterCount, modelContextLength: contextLength)175    }176177    /// Download sources in order: the owner's mirror when the weights are re-hosted there, then Hugging Face.178    public var sourceURLs: [URL] {179        var out: [URL] = []180        if redistributable, let baseURL, let u = URL(string: baseURL) { out.append(u) }181        if let u = URL(string: fallbackBaseURL ?? Self.huggingFaceBase(repo: repo, revision: revision)), !out.contains(u) { out.append(u) }182        return out183    }184185    public func modelInfo(source: MetadataSource = .runtime) -> ModelInfo {186        ModelInfo(ref: ModelRef(provider: .mlx, modelID: id), displayName: displayName,187                  summary: "\(family) · \(quantization) · \(MemoryGovernor.format(totalBytes))", contextLength: contextLength,188                  capabilities: Set(capabilities), source: source, vendor: publisher)189    }190}191192// MARK: - Path and field validation193194public enum CatalogError: Error, Sendable, Hashable, LocalizedError {195    case unreadable(String)196    case unsupportedSchema(Int)197    case invalidCard(id: String, reason: String)198    case duplicateID(String)199    public var errorDescription: String? {200        switch self {201        case .unreadable(let m): "The model catalog could not be read: \(m)"202        case .unsupportedSchema(let n): "The model catalog uses schema \(n), which this version does not understand."203        case .invalidCard(let id, let reason): "The catalog entry “\(id)” is invalid: \(reason)"204        case .duplicateID(let id): "The catalog lists “\(id)” twice."205        }206    }207}208209public enum ModelPath {210    /// Largest single file the app accepts from any manifest.211    public static let maxFileBytes: Int64 = 24 << 30212    public static let maxFiles = 256213214    /// True for a relative path made of plain components: no "..", no ".", no empty component, no backslash, no control character, no leading "/" or "~".215    public static func isSafe(_ path: String) -> Bool {216        guard !path.isEmpty, path.utf8.count <= 512, !path.hasPrefix("/"), !path.hasPrefix("~"), !path.contains("\\") else { return false }217        guard !path.unicodeScalars.contains(where: { $0.value < 0x20 || $0.value == 0x7F }) else { return false }218        let parts = path.split(separator: "/", omittingEmptySubsequences: false)219        return parts.allSatisfy { !$0.isEmpty && $0 != "." && $0 != ".." && !$0.hasPrefix(".astra") }220    }221222    public static func isSafeID(_ id: String) -> Bool {223        guard !id.isEmpty, id.utf8.count <= 128, id != ".", id != "..", !id.hasPrefix(".") else { return false }224        return id.unicodeScalars.allSatisfy { ("a"..."z").contains($0) || ("A"..."Z").contains($0) || ("0"..."9").contains($0) || $0 == "-" || $0 == "_" || $0 == "." }225    }226227    static func isHex(_ s: String, count: Int) -> Bool {228        s.utf8.count == count && s.utf8.allSatisfy { ($0 >= 48 && $0 <= 57) || ($0 >= 97 && $0 <= 102) }229    }230}231232extension LocalModelCard {233    /// Throws when the card could not be downloaded safely or is internally inconsistent.234    public func validate() throws {235        func fail(_ reason: String) -> CatalogError { .invalidCard(id: id, reason: reason) }236        guard ModelPath.isSafeID(id) else { throw fail("the id contains characters that are not allowed") }237        guard ModelPath.isHex(revision, count: 40) else { throw fail("the revision is not a full commit hash") }238        guard repo.split(separator: "/").count == 2, !repo.contains("..") else { throw fail("the repository name is malformed") }239        guard !files.isEmpty, files.count <= ModelPath.maxFiles else { throw fail("the file list is empty or too long") }240        var seen = Set<String>()241        for f in files {242            guard ModelPath.isSafe(f.path) else { throw fail("unsafe file path “\(f.path)”") }243            guard seen.insert(f.path.lowercased()).inserted else { throw fail("file “\(f.path)” is listed twice") }244            guard f.size >= 0, f.size <= ModelPath.maxFileBytes else { throw fail("file “\(f.path)” has an unacceptable size") }245            guard ModelPath.isHex(f.sha256, count: 64) else { throw fail("file “\(f.path)” has no valid SHA-256") }246        }247        guard seen.contains("config.json") else { throw fail("config.json is missing from the file list") }248        guard files.contains(where: { $0.path.hasSuffix(".safetensors") }) else { throw fail("no weight file is listed") }249        guard totalBytes == files.reduce(0, { $0 + $1.size }) else { throw fail("totalBytes does not equal the sum of the file sizes") }250        guard contextLength > 0 else { throw fail("the context length is missing") }251        for (name, value) in [("baseURL", baseURL), ("fallbackBaseURL", fallbackBaseURL)] {252            guard let value else { continue }253            guard let u = URL(string: value), u.scheme == "https", u.host?.isEmpty == false, value.hasSuffix("/"), u.user == nil else {254                throw fail("\(name) must be an https URL ending in “/”")255            }256        }257        guard let license = URL(string: licenseURL), license.scheme == "https" else { throw fail("the license URL is not https") }258        if let v = verified {259            guard v.tokensPerSecond > 0, v.timeToFirstToken >= 0, !v.machine.isEmpty, ["macOS", "iOS"].contains(v.platform) else {260                throw fail("the verification record is incomplete")261            }262        }263    }264265    /// The part of a card that identifies the bytes: repository commit and every file's size and hash.266    public var contentFingerprint: [String] {267        [revision] + files.sorted { $0.path < $1.path }.map { "\($0.path)|\($0.size)|\($0.sha256)" }268    }269}270271// MARK: - Catalog272273public struct ModelCatalog: Sendable, Hashable {274    public enum Origin: String, Sendable, Codable, Hashable {275        /// Shipped inside the app.276        case bundled277        /// Known to the app, refreshed from the site with identical file hashes.278        case bundledRefreshed279        /// Not in the bundled catalog: comes from the online catalog only.280        case onlineCatalog281        public var label: String {282            switch self {283            case .bundled, .bundledRefreshed: "Included with the app"284            case .onlineCatalog: "From the online catalog"285            }286        }287    }288    public struct Entry: Sendable, Hashable, Identifiable {289        public var card: LocalModelCard290        public var origin: Origin291        public var id: String { card.id }292    }293    public struct Rejection: Sendable, Hashable {294        public var id: String295        public var reason: String296    }297298    public static let schema = 1299    public static let defaultBase = URL(string: "https://www.orixlab.dev/astra/models/v1")!300    static let maxCatalogBytes = 4 << 20301302    public var generatedAt: Date303    public var entries: [Entry]304    public var models: [LocalModelCard] { entries.map(\.card) }305    public func card(id: String) -> LocalModelCard? { entries.first { $0.id == id }?.card }306307    public init(generatedAt: Date = Date(), entries: [Entry] = []) { self.generatedAt = generatedAt; self.entries = entries }308309    struct Wire: Codable { var schema: Int; var generatedAt: String; var models: [LocalModelCard] }310311    /// Decodes and validates a `catalog.json`. Every card must be valid; one bad card rejects the file.312    public static func decode(_ data: Data, origin: Origin = .bundled) throws -> ModelCatalog {313        guard data.count <= maxCatalogBytes else { throw CatalogError.unreadable("the file is larger than \(maxCatalogBytes >> 20) MB") }314        struct Probe: Decodable { var schema: Int }315        let wire: Wire316        do {317            let probe = try JSONDecoder().decode(Probe.self, from: data)318            guard probe.schema == schema else { throw CatalogError.unsupportedSchema(probe.schema) }319            wire = try JSONDecoder().decode(Wire.self, from: data)320        } catch let e as CatalogError { throw e } catch { throw CatalogError.unreadable(Self.describe(error)) }321        guard let date = parseDate(wire.generatedAt) else { throw CatalogError.unreadable("generatedAt is not an ISO 8601 date") }322        var ids = Set<String>()323        for card in wire.models {324            try card.validate()325            guard ids.insert(card.id).inserted else { throw CatalogError.duplicateID(card.id) }326        }327        return ModelCatalog(generatedAt: date, entries: wire.models.map { Entry(card: $0, origin: origin) })328    }329330    public func encoded() throws -> Data {331        let f = ISO8601DateFormatter(); f.formatOptions = [.withInternetDateTime]332        let e = JSONEncoder(); e.outputFormatting = [.prettyPrinted, .sortedKeys, .withoutEscapingSlashes]333        return try e.encode(Wire(schema: Self.schema, generatedAt: f.string(from: generatedAt), models: models))334    }335336    /// Applies the acceptance rule to a catalog fetched from the site.337    /// - A card whose id the app already knows is accepted only when its revision and every file hash and size equal the bundled ones;338    ///   it may then update the descriptive fields and the mirror URL (the hashes still pin the bytes).339    /// - A card with a new id is accepted and marked `.onlineCatalog`.340    /// - Bundled models missing from the online catalog stay available.341    public func merging(online: ModelCatalog) -> (catalog: ModelCatalog, rejected: [Rejection]) {342        var out = self; var rejected: [Rejection] = []343        for entry in online.entries {344            if let i = out.entries.firstIndex(where: { $0.id == entry.id }) {345                let known = out.entries[i]346                if known.origin == .onlineCatalog { out.entries[i] = Entry(card: entry.card, origin: .onlineCatalog); continue }347                guard known.card.contentFingerprint == entry.card.contentFingerprint else {348                    rejected.append(Rejection(id: entry.id, reason: "The online catalog lists different files or hashes than the version included with the app; the included version is kept."))349                    continue350                }351                out.entries[i] = Entry(card: entry.card, origin: .bundledRefreshed)352            } else {353                out.entries.append(Entry(card: entry.card, origin: .onlineCatalog))354            }355        }356        out.generatedAt = max(generatedAt, online.generatedAt)357        return (out, rejected)358    }359360    static func parseDate(_ text: String) -> Date? {361        let f = ISO8601DateFormatter(); f.formatOptions = [.withInternetDateTime]362        if let d = f.date(from: text) { return d }363        f.formatOptions = [.withInternetDateTime, .withFractionalSeconds]364        return f.date(from: text)365    }366367    static func describe(_ error: Error) -> String {368        guard let e = error as? DecodingError else { return String(describing: error) }369        switch e {370        case .keyNotFound(let key, let c): return "missing “\(key.stringValue)” at \(path(c))"371        case .typeMismatch(_, let c), .valueNotFound(_, let c), .dataCorrupted(let c): return "\(c.debugDescription) at \(path(c))"372        @unknown default: return "malformed JSON"373        }374    }375    private static func path(_ c: DecodingError.Context) -> String { c.codingPath.map(\.stringValue).joined(separator: ".").isEmpty ? "the top level" : c.codingPath.map(\.stringValue).joined(separator: ".") }376}377378/// Fetches the online catalog through the app's HTTP seam.379public struct CatalogClient: Sendable {380    public var base: URL381    let transport: any HTTPTransport382    public init(base: URL = ModelCatalog.defaultBase, transport: any HTTPTransport) { self.base = base; self.transport = transport }383384    public var catalogURL: URL { base.appendingPathComponent("catalog.json") }385386    public func fetch() async throws -> ModelCatalog {387        var request = URLRequest(url: catalogURL)388        request.cachePolicy = .reloadIgnoringLocalCacheData389        request.timeoutInterval = 20390        request.setValue("application/json", forHTTPHeaderField: "Accept")391        let (data, response) = try await transport.send(request)392        guard response.statusCode == 200 else {393            throw AstraError.server(status: response.statusCode, message: "The model catalog is not available right now (HTTP \(response.statusCode)).")394        }395        do { return try ModelCatalog.decode(data, origin: .onlineCatalog) }396        catch { throw AstraError.decoding((error as? LocalizedError)?.errorDescription ?? String(describing: error)) }397    }398399    /// Bundled catalog refreshed from the site; on any failure the bundled catalog is returned unchanged with the failure.400    public func refreshed(bundled: ModelCatalog) async -> (catalog: ModelCatalog, rejected: [ModelCatalog.Rejection], failure: AstraError?) {401        do {402            let merged = bundled.merging(online: try await fetch())403            return (merged.catalog, merged.rejected, nil)404        } catch { return (bundled, [], AstraError.wrap(error)) }405    }406}407
Files main
Menu

Theme