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