SPB Git

Repository Public

VQResearchModels.swift 31.0 KB 561 lines swift

1// Author: Simon-Pierre Boucher — contact@spboucher.ai2// File: Sources/VQuantKit/ResearchAgent/VQResearchModels.swift3// Description: The autonomous research agent (CONTRACT §9): the payloads of `/api/v2/research/*`. Tolerant decoders.4import Foundation56/// The modes of `POST /api/chat`. `research` (§9.3) is the autonomous quantitative study; a mode added later decodes7/// as `.unknown` through `VQOpen<VQAnalysisMode>`.8public enum VQAnalysisMode: String, Sendable, Hashable, CaseIterable {9    case fast, standard, deep, ultra, research10    /// The modes the server announces in `GET /api/config` (`modes`), unknown ones kept.11    public static func modes(ofConfig config: VQJSON) -> [VQOpen<VQAnalysisMode>] { config.strings("modes").map(VQOpen.init) }12    public var isAutonomousResearch: Bool { self == .research }13}1415/// A research workspace: `p-<projectId>` (shared by the conversations of a project) or `s-<sessionId>`.16public struct VQResearchSession: Sendable, Hashable, Identifiable, VQJSONDecodable {17    public enum Kind: String, Sendable, Hashable, CaseIterable { case session, project }18    public var id: String19    public var kind: VQOpen<Kind>20    /// The project id or the session id.21    public var ref: String22    public var title: String?23    public var createdAt: Date?24    public var updatedAt: Date?25    /// Conversations that work in this workspace.26    public var sessionIds: [String]27    public init(json j: VQJSON) {28        id = j.str("id"); kind = j.open("kind", .session); ref = j.str("ref"); title = j.optStr("title")29        createdAt = j.date("createdAt"); updatedAt = j.date("updatedAt"); sessionIds = j.strings("sessionIds")30    }31    /// The `:id` of the research routes for a conversation whose workspace id is not known yet.32    public static func reference(sessionId: String) -> String { "session:\(sessionId)" }33}3435public struct VQResearchFile: Sendable, Hashable, Identifiable, VQJSONDecodable {36    public var path: String37    public var isDirectory: Bool38    public var bytes: Int39    public var modifiedAt: Date?40    public var id: String { path }41    public var name: String { path.split(separator: "/").last.map(String.init) ?? path }42    public init(path: String, isDirectory: Bool, bytes: Int, modifiedAt: Date?) { self.path = path; self.isDirectory = isDirectory; self.bytes = bytes; self.modifiedAt = modifiedAt }43    public init(json j: VQJSON) { path = j.str("path"); isDirectory = j.str("type") == "dir"; bytes = j.int("bytes") ?? 0; modifiedAt = j.date("modifiedAt") }44}4546/// Status of a ledger entry. Failed, inconclusive and abandoned experiments are regular entries: list them with the others.47public enum VQLedgerStatus: String, Sendable, Hashable, CaseIterable {48    case running, ok, failed, timeout, killed, interrupted, inconclusive, abandoned49    public var isFailure: Bool { self == .failed || self == .timeout || self == .killed || self == .interrupted }50}5152/// An entry of the experiment ledger: an `execution` written by the runtime for every cell and run, or an53/// `experiment` declared by the agent.54public struct VQLedgerEntry: Sendable, Hashable, Identifiable, VQJSONDecodable {55    public enum Kind: String, Sendable, Hashable, CaseIterable { case experiment, execution }56    public var id: String57    public var workspaceId: String?58    public var sessionId: String?59    public var generationId: String?60    public var seq: Int?61    public var kind: VQOpen<Kind>62    public var title: String?63    public var hypothesis: String?64    public var method: String?65    /// `notebook:<agent>` or the script path.66    public var codeRef: String?67    /// First 16 hex of the SHA-256 of the code; a cell's code is at `logs/cells/<codeHash>.py`.68    public var codeHash: String?69    public var envHash: String?70    public var runId: String?71    public var status: VQOpen<VQLedgerStatus>72    public var metrics: VQJSONObject?73    public var diagnostics: VQJSON?74    public var artifacts: [String]75    public var notes: String?76    public var error: String?77    public var startedAt: Date?78    public var finishedAt: Date?79    public var durationMs: Double?80    public init(json j: VQJSON) {81        id = j.str("id"); workspaceId = j.optStr("workspaceId"); sessionId = j.optStr("sessionId"); generationId = j.optStr("generationId"); seq = j.int("seq")82        kind = j.open("kind", .experiment); title = j.optStr("title"); hypothesis = j.optStr("hypothesis"); method = j.optStr("method")83        codeRef = j.optStr("codeRef"); codeHash = j.optStr("codeHash"); envHash = j.optStr("envHash"); runId = j.optStr("runId")84        status = j.open("status", .ok); metrics = j["metrics"]?.objectValue; diagnostics = j["diagnostics"].flatMap { $0.isNull ? nil : $0 }85        artifacts = j.strings("artifacts"); notes = j.optStr("notes"); error = j.optStr("error")86        startedAt = j.date("startedAt"); finishedAt = j.date("finishedAt"); durationMs = j.num("durationMs")87    }88}8990/// A run: a Python program of the workspace executed as its own sandboxed process (§9.5).91public struct VQResearchRun: Sendable, Hashable, Identifiable, VQJSONDecodable {92    public enum Status: String, Sendable, Hashable, CaseIterable {93        case running, done, failed, timeout, killed, cancelled, interrupted94        public var isTerminal: Bool { self != .running }95    }96    public enum Network: String, Sendable, Hashable, CaseIterable { case `default`, open }97    public var id: String98    public var generationId: String?99    public var label: String?100    /// Workspace path of the script.101    public var code: String?102    public var codeHash: String?103    public var args: [String]104    /// `open` = this run was authorised to reach any public host.105    public var network: Network106    public var status: VQOpen<Status>107    /// 0–1, nil until the program reports (`@@progress`).108    public var progress: Double?109    public var exitCode: Int?110    public var error: String?111    public var startedAt: Date?112    public var finishedAt: Date?113    public init(id: String) { self.id = id; args = []; network = .default; status = .known(.running) }114    public init(json j: VQJSON) {115        id = j.str("id"); generationId = j.optStr("generationId"); label = j.optStr("label"); code = j.optStr("code") ?? j.optStr("codeRef"); codeHash = j.optStr("codeHash")116        args = j.list("args").compactMap(\.displayString); network = j.str("network") == "open" ? .open : .default; status = j.open("status", .running)117        progress = j.num("progress"); exitCode = j.int("exitCode"); error = j.optStr("error"); startedAt = j.date("startedAt"); finishedAt = j.date("finishedAt")118    }119    public var isRunning: Bool { status == .running }120    public var duration: TimeInterval? { startedAt.flatMap { s in finishedAt.map { $0.timeIntervalSince(s) } } }121}122123/// `GET /api/v2/research/runs/:runId?tail=` — the ends of the logs, secrets masked.124public struct VQRunLogs: Sendable, Hashable, VQJSONDecodable {125    public var run: VQResearchRun126    public var stdout: String127    public var stderr: String128    public init(json j: VQJSON) { run = VQResearchRun(json: j["run"] ?? .null); stdout = j.str("stdout"); stderr = j.str("stderr") }129}130131/// A note of the research memory (per workspace; not the person's `agent_memories`).132public struct VQResearchNote: Sendable, Hashable, Identifiable, VQJSONDecodable {133    public enum Kind: String, Sendable, Hashable, CaseIterable { case dataset, model, decision, implementation, failure, hypothesis, finding, workflow }134    public var id: String135    public var kind: VQOpen<Kind>136    public var title: String137    /// The stream carries the first 600 characters; REST the whole body.138    public var body: String139    public var createdAt: Date?140    public init(json j: VQJSON) { id = j["id"]?.displayString ?? ""; kind = j.open("kind", .finding); title = j.str("title", "Note"); body = j.str("body"); createdAt = j.date("createdAt") }141}142143/// A module of the person's code library (`from vqlib.<name> import …`).144public struct VQLibraryEntry: Sendable, Hashable, Identifiable, VQJSONDecodable {145    public var name: String146    public var description: String?147    public var savedAt: Date?148    public var sha256: String?149    public var bytes: Int?150    public var exports: [String]151    public var id: String { name }152    public init(json j: VQJSON) { name = j.str("name"); description = j.optStr("description"); savedAt = j.date("savedAt"); sha256 = j.optStr("sha256"); bytes = j.int("bytes"); exports = j.strings("exports") }153}154155public struct VQResearchEnvironment: Sendable, Hashable, VQJSONDecodable {156    /// Hash of `environment.lock.txt`; stored on each ledger entry as `envHash`.157    public var hash: String?158    /// Number of distributions installed (base + overlay).159    public var packages: Int?160    /// What this workspace installed on top of the shared base (`name==version`).161    public var overlay: [String]162    /// Workspace path of the lockfile.163    public var lockfile: String?164    public init(json j: VQJSON) { hash = j.optStr("hash"); packages = j.int("packages"); overlay = j.strings("overlay"); lockfile = j.optStr("lockfile") }165}166167/// An authorisation the agent asks for (§9.7). Unanswered for 15 minutes, it is a refusal.168public struct VQResearchApproval: Sendable, Hashable, Identifiable, VQJSONDecodable {169    public enum Action: String, Sendable, Hashable, CaseIterable { case openNetwork = "open_network", sendData = "send_data", raiseBudget = "raise_budget", other }170    public enum Status: String, Sendable, Hashable, CaseIterable { case pending, approved, denied, expired }171    public enum Decision: String, Sendable, Hashable { case approve, deny }172    public static let timeToLive: TimeInterval = 15 * 60173174    public var id: String175    public var action: VQOpen<Action>176    public var reason: String?177    public var detail: VQJSONObject?178    public var status: VQOpen<Status>179    public var createdAt: Date?180    public var resolvedAt: Date?181    /// The workspace and generation that asked (REST only; nil on stream events).182    public var workspaceId: String?183    public var generationId: String?184    public init(json j: VQJSON) {185        id = j.str("id"); action = j.open("action", .other); reason = j.optStr("reason"); detail = j["detail"]?.objectValue186        status = j.open("status", .pending); createdAt = j.date("createdAt"); resolvedAt = j.date("resolvedAt")187        workspaceId = j.optStr("workspaceId"); generationId = j.optStr("generationId")188    }189190    public var deadline: Date? { createdAt?.addingTimeInterval(Self.timeToLive) }191192    public struct Countdown: Sendable, Equatable {193        /// Seconds left before silence counts as a refusal; 0 once expired; nil when the request has no creation time.194        public var remaining: TimeInterval?195        public var expired: Bool196        /// `mm:ss`197        public var label: String198        /// Share of the 15 minutes already spent, 0–1.199        public var elapsedShare: Double200        /// Under two minutes.201        public var urgent: Bool202    }203    public func countdown(now: Date) -> Countdown {204        guard let deadline else { return Countdown(remaining: nil, expired: status == .expired, label: VQFormat.nullText, elapsedShare: 0, urgent: false) }205        let remaining = max(0, deadline.timeIntervalSince(now))206        let s = Int(remaining.rounded(.up))207        return Countdown(remaining: remaining, expired: status == .expired || (status == .pending && remaining == 0), label: String(format: "%02d:%02d", s / 60, s % 60),208                         elapsedShare: min(1, max(0, 1 - remaining / Self.timeToLive)), urgent: remaining > 0 && remaining <= 120)209    }210    /// Pending on the server and inside its 15 minutes on this clock.211    public func isAnswerable(now: Date) -> Bool { status == .pending && !countdown(now: now).expired }212213    /// The status in words ("en attente", "autorisée", "refusée", "expirée").214    public func statusLabel(_ language: VQLanguage = .preferred) -> String {215        switch status.known {216        case .pending?: return VQL10n.string("waiting for your answer", language)217        case .approved?: return VQL10n.string("approved", language)218        case .denied?: return VQL10n.string("refused", language)219        case .expired?: return VQL10n.string("expired unanswered", language)220        case nil: return status.rawValue221        }222    }223224    public func title(_ language: VQLanguage = .preferred) -> String {225        switch action.known {226        case .openNetwork?: return VQL10n.string("Open the network for one run", language)227        case .sendData?: return VQL10n.string("Send data to an external service", language)228        case .raiseBudget?: return VQL10n.string("Exceed the budget of this study", language)229        default: return VQL10n.string("Authorisation requested by the agent", language)230        }231    }232    /// What saying yes authorises, in one or two sentences.233    public func scope(_ language: VQLanguage = .preferred) -> String {234        switch action.known {235        case .openNetwork?: return VQL10n.string("One run will be able to reach any public host (private and local addresses stay refused). Every destination is written to logs/network.log.", language)236        case .sendData?: return VQL10n.string("Data of the research workspace will leave the server for the service named. The transfer is recorded in the audit trail.", language)237        case .raiseBudget?: return VQL10n.string("The cost or time limits of this analysis will be raised to the values requested.", language)238        default: return VQL10n.string("The agent considers that this step needs your consent.", language)239        }240    }241    /// The `detail` object as label/value pairs a person can read.242    public func details(_ language: VQLanguage = .preferred, locale: VQNumberLocale = .frCA) -> [(label: String, value: String)] {243        var out: [(String, String)] = []244        for key in (detail ?? [:]).keys.sorted() {245            guard let v = detail?[key], !v.isNull, v != .string("") else { continue }246            switch key {247            case "maxCostUsd": out.append((VQL10n.string("New cost ceiling", language), VQFormat.cost(v.doubleValue, locale: locale)))248            case "maxMinutes": out.append((VQL10n.string("New maximum duration", language), "\(VQFormat.number(v.doubleValue, decimals: 0, locale: locale)) min"))249            case "host", "hosts", "destination", "url": out.append(("Destination", v.arrayValue.map { $0.compactMap(\.displayString).joined(separator: ", ") } ?? v.displayString ?? v.text()))250            case "purpose": out.append((VQL10n.string("Purpose", language), v.displayString ?? v.text()))251            case "path", "script": out.append(("Script", v.displayString ?? v.text()))252            case "label": out.append((VQL10n.string("Run", language), v.displayString ?? v.text()))253            case "code": out.append(("Code", v.displayString ?? v.text()))254            default: out.append((key, v.displayString ?? v.text()))255            }256        }257        return out258    }259}260261/// `GET /api/v2/research/sessions/:id`262public struct VQResearchSessionDetail: Sendable, Hashable, VQJSONDecodable {263    public var session: VQResearchSession264    public var files: [VQResearchFile]265    /// Declared by the agent (`kind: experiment`), oldest first.266    public var experiments: [VQLedgerEntry]267    /// Written by the runtime for every cell and run.268    public var executions: [VQLedgerEntry]269    public var runs: [VQResearchRun]270    public var notes: [VQResearchNote]271    public var library: [VQLibraryEntry]272    public var environment: VQResearchEnvironment273    public var approvals: [VQResearchApproval]274    /// The analyses run in the workspace, oldest first, each with the final state of its plan (empty from a server275    /// that predates it).276    public var generations: [VQResearchGeneration]277    /// The plan of the most recent generation that has one.278    public var plan: [VQResearchState.PlanStep]279    /// The figures with their linter verdict, oldest first (empty for studies recorded before the server kept them).280    public var figures: [VQResearchFigureRecord]281    public init(json j: VQJSON) {282        session = VQResearchSession(json: j["session"] ?? .null); files = j.models("files"); experiments = j.models("experiments"); executions = j.models("executions")283        runs = j.models("runs"); notes = j.models("notes"); library = j.models("library"); environment = VQResearchEnvironment(json: j["environment"] ?? .null); approvals = j.models("approvals")284        generations = j.models("generations"); plan = VQResearchState.PlanStep.list(j["plan"]); figures = j.models("figures")285    }286}287288/// One analysis run in a workspace (`generations` of the session detail).289public struct VQResearchGeneration: Sendable, Hashable, Identifiable, VQJSONDecodable {290    public enum Status: String, Sendable, Hashable, CaseIterable {291        case running, done, error, cancelled292        /// Cut by a server restart: the workspace, files and logs are kept; the person continues from there.293        case interrupted294    }295    public var generationId: String296    public var sessionId: String?297    public var status: VQOpen<Status>298    public var startedAt: Date?299    public var finishedAt: Date?300    public var mode: String?301    public var model: String?302    /// The final state of its plan.303    public var plan: [VQResearchState.PlanStep]304    public var budgetApplied: VQBudgetApplied?305    /// Limits that were hit.306    public var budget: [VQBudgetEvent]307    public var id: String { generationId }308    public init(json j: VQJSON) {309        generationId = j.str("generationId"); sessionId = j.optStr("sessionId"); status = j.open("status", .done); startedAt = j.date("startedAt"); finishedAt = j.date("finishedAt")310        mode = j.optStr("mode"); model = j.optStr("model"); plan = VQResearchState.PlanStep.list(j["plan"]); budgetApplied = j.model("budgetApplied"); budget = j.models("budget")311    }312}313314/// A figure as the server keeps it (`figures` of the session detail; the same fields as the `figure_lint` event).315public struct VQResearchFigureRecord: Sendable, Hashable, Identifiable, VQJSONDecodable {316    public var id: String317    public var generationId: String?318    public var toolId: String?319    public var at: Date?320    public var title: String?321    /// The title drawn on the figure: the text a report puts under it.322    public var caption: String?323    /// The address used in the conversation (`/figures/…`), kept while the build keeps it.324    public var url: String?325    /// The durable copies in the workspace: read them with the file route.326    public var files: VQResearchState.FigureFiles?327    public var status: VQOpen<VQResearchState.LintStatus>?328    /// Repaired automatically.329    public var fixes: [VQResearchState.LintIssue]330    /// Left as they are (information-level ones included).331    public var findings: [VQResearchState.LintIssue]332    public var codeHash: String?333    public init(json j: VQJSON) {334        id = j.str("id"); generationId = j.optStr("generationId"); toolId = j.optStr("toolId"); at = j.date("at"); title = j.optStr("title"); caption = j.optStr("caption"); url = j.optStr("url")335        files = j["files"].flatMap { $0.objectValue == nil ? nil : VQResearchState.FigureFiles(json: $0) }; status = j.optOpen("status"); fixes = j.models("fixes"); findings = j.models("findings"); codeHash = j.optStr("codeHash")336    }337}338339/// `GET …/file?path=&offset=&limit=` for a text file.340public struct VQResearchFilePreview: Sendable, Hashable, VQJSONDecodable {341    public var path: String342    public var bytes: Int343    public var totalLines: Int344    /// 1-based, inclusive.345    public var from: Int346    public var to: Int347    public var text: String348    /// More lines exist beyond `to`.349    public var truncated: Bool350    public init(json j: VQJSON) {351        path = j.str("path"); bytes = j.int("bytes") ?? 0; totalLines = j.int("totalLines") ?? 0; from = j.int("from") ?? 1; to = j.int("to") ?? 0; text = j.str("text"); truncated = j.flag("truncated")352    }353}354355/// `GET …/inspect?path=` — the profile of a dataset.356public struct VQDatasetInspection: Sendable, Hashable, VQJSONDecodable {357    public var path: String358    public var format: String359    public var bytes: Int?360    public var rows: Int?361    /// Rows the profile was computed on (fewer than `rows` when `truncated`).362    public var rowsProfiled: Int?363    public var truncated: Bool364    public var columnCount: Int?365    public var columns: [Column]366    public var duplicatedRows: Int?367    public var timeColumns: [String]368    public var memoryMb: Double?369    /// The first rows, one object per row.370    public var head: [VQJSONObject]371    /// Excel workbooks.372    public var sheets: [String]373374    public struct Column: Sendable, Hashable, Identifiable, VQJSONDecodable {375        public var name: String376        public var dtype: String377        public var missing: Int378        /// Fraction (0.05 = 5 %).379        public var missingShare: Double380        public var distinct: Int?381        public var examples: [VQJSON]382        /// `mean, std, min, 25%, 50%, 75%, max` for numeric columns.383        public var summary: [String: Double]384        public var range: [String]385        public var parsesAsDate: Bool386        public var zeros: Int?387        public var id: String { name }388        public init(json j: VQJSON) {389            name = j.str("name"); dtype = j.str("dtype"); missing = j.int("missing") ?? 0; missingShare = j.num("missingShare") ?? 0; distinct = j.int("distinct")390            examples = j.list("examples"); summary = j.dict("summary").compactMapValues(\.doubleValue); range = j.list("range").compactMap(\.displayString)391            parsesAsDate = j.flag("parsesAsDate"); zeros = j.int("zeros")392        }393    }394    public init(json j: VQJSON) {395        let d = j["dataset"] ?? j396        path = d.str("path"); format = d.str("format"); bytes = d.int("bytes"); rows = d.int("rows"); rowsProfiled = d.int("rowsProfiled"); truncated = d.flag("truncated")397        columns = d.models("columns"); columnCount = d.int("columnCount") ?? d.int("columns"); duplicatedRows = d.int("duplicatedRows"); timeColumns = d.strings("timeColumns")398        memoryMb = d.num("memoryMb"); sheets = d.strings("sheets")399        head = d.list("head").compactMap { row in400            if let o = row.objectValue { return o }401            // rows given as arrays: key them by column name402            guard let a = row.arrayValue else { return nil }403            return Dictionary(zip(d.models("columns", as: Column.self).map(\.name), a), uniquingKeysWith: { a, _ in a })404        }405    }406}407408/// `GET /api/v2/research/sandbox`409public struct VQSandboxStatus: Sendable, Hashable, VQJSONDecodable {410    /// false: this host cannot isolate the agent's code. Say so plainly in the interface.411    public var enforced: Bool412    public var mechanism: String?413    public var note: String?414    /// `cpuSeconds, memoryMb, wallMs, maxProcesses, fileMb, diskMb` (and whatever is added later).415    public var limits: [String: Double]416    /// What the sandbox reaches without asking.417    public var defaultNetwork: [String]418    /// What an approved `open` run reaches.419    public var openNetwork: String?420    public var uploadMaxBytes: Int421    public init(json j: VQJSON) {422        let s = j["sandbox"] ?? .null423        enforced = s.flag("enforced"); mechanism = s.optStr("mechanism"); note = s.optStr("note")424        limits = j.dict("limits").compactMapValues(\.doubleValue)425        defaultNetwork = (j["network"] ?? .null).strings("default"); openNetwork = (j["network"] ?? .null).optStr("open")426        uploadMaxBytes = j.int("uploadMaxBytes") ?? VQDatasetUpload.defaultMaxBytes427    }428}429430public struct VQUploadedFile: Sendable, Hashable, VQJSONDecodable {431    public var path: String432    public var bytes: Int433    public var sha256: String434    public init(json j: VQJSON) { let f = j["file"] ?? j; path = f.str("path"); bytes = f.int("bytes") ?? 0; sha256 = f.str("sha256") }435}436437/// What backend 6 adds (§9.3) to a stored conversation message of a generation that used the workspace.438public struct VQMessageResearch: Sendable, Hashable, VQJSONDecodable {439    public var workspaceId: String440    public var experiments: [VQLedgerEntry]441    public var executionsTotal: Int442    public var executionsFailed: Int443    /// nil when the gate did not run (not research mode).444    public var qualityGate: [VQQualityGateFinding]?445    public init(json j: VQJSON) {446        workspaceId = j.str("workspaceId"); experiments = j.models("experiments")447        executionsTotal = (j["executions"] ?? .null).int("total") ?? 0; executionsFailed = (j["executions"] ?? .null).int("failed") ?? 0448        qualityGate = j["qualityGate"]?.arrayValue.map { $0.map(VQQualityGateFinding.init(json:)) }449    }450    /// The `research` object of each message of a session payload (nil where a message has none).451    public static func ofSession(_ session: VQJSON) -> [VQMessageResearch?] {452        VQMessageExtras.messages(of: session).map { m in m["research"].flatMap { $0.objectValue == nil ? nil : VQMessageResearch(json: $0) } }453    }454}455456public struct VQQualityGateFinding: Sendable, Hashable, Identifiable, VQJSONDecodable {457    public enum Severity: String, Sendable, Hashable, CaseIterable { case info, warning, error }458    /// `numbers`, `sample`, `significance…`, `figures`, `failed_experiments`, `still_running`, `ledger_empty` (open list).459    public var id: String460    public var severity: VQOpen<Severity>461    public var finding: String462    public var evidence: String?463    public init(json j: VQJSON) { id = j.str("id"); severity = j.open("severity", .info); finding = j.str("finding"); evidence = j.optStr("evidence") }464    public var isOpen: Bool { severity != .info }465}466467// MARK: dataset upload — the checks a client can make before sending (the server checks the bytes again)468469public enum VQDatasetUpload {470    public static let extensions = [".csv", ".tsv", ".txt", ".json", ".jsonl", ".parquet", ".xlsx", ".xls", ".feather"]471    public static let defaultMaxBytes = 200 * 1024 * 1024472473    public enum Refusal: Error, Sendable, Equatable {474        case noExtension475        case unsupported(String)476        case empty477        case tooLarge(bytes: Int, limit: Int)478        /// The first bytes do not match the extension (or the text file holds NUL bytes, or is an archive, PDF or executable).479        case contentMismatch(String)480481        public func message(_ language: VQLanguage = .preferred) -> String {482            switch self {483            case .noExtension: return VQL10n.string("This file has no extension: there is no telling how to read it. Accepted: CSV, TSV, JSON, Parquet, Excel, Feather.", language)484            case .unsupported(let e): return VQL10n.string("The format %1$@ is not accepted. Accepted: CSV, TSV, TXT, JSON, JSONL, Parquet, XLSX, XLS, Feather.", language, "\(e)")485            case .empty: return VQL10n.string("This file is empty.", language)486            case .tooLarge(let b, let l): return VQL10n.string("This file is %1$@; the limit is %2$@.", language, VQFormat.bytes(b, language: language), VQFormat.bytes(l, language: language))487            case .contentMismatch(let e): return VQL10n.string("The content of the file does not match its extension %1$@ (or it is an archive, a PDF or an executable).", language, "\(e)")488            }489        }490    }491492    public static func fileExtension(_ name: String) -> String {493        guard let i = name.lastIndex(of: "."), i != name.startIndex else { return "" }494        return name[i...].lowercased()495    }496497    /// Extension, emptiness and size. `maxBytes` comes from `VQSandboxStatus.uploadMaxBytes`.498    public static func validate(name: String, size: Int, maxBytes: Int = defaultMaxBytes) -> Refusal? {499        let e = fileExtension(name)500        if e.isEmpty { return .noExtension }501        if !extensions.contains(e) { return .unsupported(e) }502        if size == 0 { return .empty }503        if size > maxBytes { return .tooLarge(bytes: size, limit: maxBytes) }504        return nil505    }506507    /// The same, plus the signature of the first bytes (pass at least the first 4 KB).508    public static func validate(name: String, size: Int, head: Data, maxBytes: Int = defaultMaxBytes) -> Refusal? {509        if let r = validate(name: name, size: size, maxBytes: maxBytes) { return r }510        let e = fileExtension(name)511        let b = [UInt8](head.prefix(4096))512        func starts(_ sig: [UInt8]) -> Bool { b.count >= sig.count && Array(b.prefix(sig.count)) == sig }513        let zip: [UInt8] = [0x50, 0x4B, 0x03, 0x04]514        switch e {515        case ".parquet": return starts(Array("PAR1".utf8)) ? nil : .contentMismatch(e)516        case ".xlsx": return starts(zip) ? nil : .contentMismatch(e)517        case ".xls": return starts([0xD0, 0xCF, 0x11, 0xE0]) ? nil : .contentMismatch(e)518        case ".feather": return starts(Array("ARROW1".utf8)) || starts(Array("FEA1".utf8)) ? nil : .contentMismatch(e)519        default:520            let binary = b.contains(0) || starts(zip) || starts(Array("%PDF".utf8)) || starts([0x7F, 0x45, 0x4C, 0x46]) || starts([0xCF, 0xFA, 0xED, 0xFE]) || starts([0x4D, 0x5A]) && b.count > 64 && b.contains(where: { $0 < 9 })521                || starts([0x1F, 0x8B])522            return binary ? .contentMismatch(e) : nil523        }524    }525526    /// What the server answered, in words.527    public static func message(for error: VQError, _ language: VQLanguage = .preferred) -> String {528        switch error.status {529        case 413: return VQL10n.string("The server refuses this file: it is over the maximum size.", language)530        case 415: return VQL10n.string("The content of the file does not match its extension (or it is an archive, a PDF or an executable).", language)531        case 401: return VQL10n.string("Session locked: open VQuant again, then retry.", language)532        case 404: return VQL10n.string("The research workspace of this conversation cannot be found.", language)533        case 0: return VQL10n.string("The connection dropped during the upload.", language)534        default: return (VQL10n.string("Upload refused: ", language)) + error.message535        }536    }537538    /// The multipart body of the upload route (field `file`) and its content type.539    public static func multipart(name: String, data: Data, boundary: String = "vq-\(UUID().uuidString)") -> (body: Data, contentType: String) {540        let safe = name.replacingOccurrences(of: "\"", with: "_").replacingOccurrences(of: "\r", with: "").replacingOccurrences(of: "\n", with: "")541        var body = Data("--\(boundary)\r\nContent-Disposition: form-data; name=\"file\"; filename=\"\(safe)\"\r\nContent-Type: application/octet-stream\r\n\r\n".utf8)542        body.append(data)543        body.append(Data("\r\n--\(boundary)--\r\n".utf8))544        return (body, "multipart/form-data; boundary=\(boundary)")545    }546}547548public extension VQFormat {549    /// 1 536 → "1,5 ko" (fr: o, ko, Mo, Go) / "1.5 KB".550    static func bytes(_ bytes: Int?, language: VQLanguage = .fr) -> String {551        guard let bytes else { return nullText }552        let locale: VQNumberLocale = language == .fr ? .frCA : .enCA553        let units = language == .fr ? ["o", "ko", "Mo", "Go"] : ["B", "KB", "MB", "GB"]554        let b = Double(bytes)555        if b < 1024 { return "\(number(b, decimals: 0, locale: locale))\u{00A0}\(units[0])" }556        if b < 1_048_576 { return "\(number(b / 1024, decimals: b < 10_240 ? 1 : 0, locale: locale))\u{00A0}\(units[1])" }557        if b < 1_073_741_824 { return "\(number(b / 1_048_576, decimals: 1, locale: locale))\u{00A0}\(units[2])" }558        return "\(number(b / 1_073_741_824, decimals: 2, locale: locale))\u{00A0}\(units[3])"559    }560}561
Files main
Menu

Theme