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