Repository Public
1// Author: Simon-Pierre Boucher — contact@spboucher.ai2// File: Sources/VQuantKit/Lab/VQLabTools.swift3// Description: The Quant Lab tool catalogue (`GET /api/quant/tools`) and a form that validates input the way the4// server does (`buildInput` in server/routes/quant.ts).5import Foundation67/// `GET /api/quant/tools` — with a 2.x client header the six legacy tools plus every lab engine.8public struct VQLabCatalog: Sendable, Equatable, VQJSONDecodable {9 public var tools: [VQLabTool]10 /// Computations one person may run at once.11 public var maxRunning: Int?12 /// Engines that could not be offered: `[engineId: reason]`.13 public var unavailable: [String: String]14 public init(json j: VQJSON) {15 tools = j.models("tools"); maxRunning = j.int("maxRunning"); unavailable = j.dict("unavailable").compactMapValues(\.stringValue)16 }17 public func tool(_ id: String) -> VQLabTool? { tools.first { $0.id == id } }18 public var labEngines: [VQLabTool] { tools.filter(\.isLab) }19 /// Tools grouped by category, in catalogue order.20 public var byCategory: [(category: String, tools: [VQLabTool])] {21 var order: [String] = [], groups: [String: [VQLabTool]] = [:]22 for t in tools {23 let c = t.category?.rawValue ?? "other"24 if groups[c] == nil { order.append(c) }25 groups[c, default: []].append(t)26 }27 return order.map { ($0, groups[$0]!) }28 }29}3031public struct VQLabTool: Sendable, Equatable, Identifiable, VQJSONDecodable {32 public enum Category: String, Sendable, Hashable, CaseIterable { case volatility, risk, econometrics, options, backtest, portfolio, simulation }33 public var id: String34 public var title: String35 public var summary: String36 public var category: VQOpen<Category>?37 public var version: String?38 /// "legacy" or "lab/1".39 public var resultSchema: String40 public var params: [VQLabParam]41 public init(json j: VQJSON) {42 id = j.str("id"); title = j.str("title", id); summary = j.str("summary"); category = j.optOpen("category"); version = j.optStr("version")43 resultSchema = j.str("resultSchema", "legacy"); params = j.models("params")44 }45 public var isLab: Bool { resultSchema.hasPrefix(VQLabResult.schemaPrefix) }46 /// Parameters grouped by their `group` hint, in declaration order ("" = no group).47 public var groups: [(name: String, params: [VQLabParam])] {48 var order: [String] = [], groups: [String: [VQLabParam]] = [:]49 var current = ""50 for p in params {51 if p.type == .group { current = p.label; continue } // a layout heading52 let g = p.group ?? current53 if groups[g] == nil { order.append(g) }54 groups[g, default: []].append(p)55 }56 return order.map { ($0, groups[$0]!) }57 }58}5960public struct VQLabParam: Sendable, Equatable, Identifiable, VQJSONDecodable {61 public enum ParamType: String, Sendable, Hashable, CaseIterable {62 case symbol, symbols, int, number, numbers, choice, bool, date, text, json63 /// A layout heading (no value).64 case group65 }66 public var name: String67 public var label: String68 /// A type added later decodes as `.unknown`: the form shows a text field and sends the text.69 public var type: VQOpen<ParamType>70 public var required: Bool71 public var group: String?72 public var help: String?73 public var defaultValue: VQJSON?74 /// Numeric bounds (`int`, `number`, each of `numbers`); for `symbols` the count of distinct symbols.75 public var min: Double?, max: Double?76 /// ISO bounds of a `date`.77 public var minDate: String?, maxDate: String?78 public var choices: [String]79 /// `numbers`: 10 when absent (the legacy tools).80 public var maxItems: Int?81 /// `text`: 2 000 when absent.82 public var maxLength: Int?83 public var multiline: Bool84 /// `json`: what the value should look like.85 public var schemaHint: String?86 /// `json`: 64 KB when absent.87 public var maxBytes: Int?88 /// Required when every listed parameter has (one of) the value(s) — judged on the validated input, defaults89 /// included. The server enforces it (400); `VQLabForm.validate()` does too.90 public var requiredWhen: VQLabCondition?91 /// A display hint: hide the field unless the condition holds (`VQLabForm.isVisible`).92 public var visibleWhen: VQLabCondition?93 public var id: String { name }9495 public init(json j: VQJSON) {96 name = j.str("name"); label = j.str("label", name); type = j.open("type", .text); required = j.flag("required")97 group = j.optStr("group"); help = j.optStr("help"); defaultValue = j["default"].flatMap { $0.isNull ? nil : $0 }98 min = j.num("min"); max = j.num("max"); minDate = j.optStr("minDate"); maxDate = j.optStr("maxDate"); choices = j.strings("choices")99 maxItems = j.int("maxItems"); maxLength = j.int("maxLength"); multiline = j.flag("multiline"); schemaHint = j.optStr("schemaHint"); maxBytes = j.int("maxBytes")100 requiredWhen = VQLabCondition(json: j["requiredWhen"]); visibleWhen = VQLabCondition(json: j["visibleWhen"])101 }102}103104/// `{ param: value | [values] }` of `requiredWhen` / `visibleWhen`: met when every listed parameter has (one of) the105/// value(s). Values are strings, numbers or booleans.106public struct VQLabCondition: Sendable, Equatable {107 /// Parameter name → accepted values.108 public var accepted: [String: [VQJSON]]109110 public init?(json: VQJSON?) {111 guard let o = json?.objectValue, !o.isEmpty else { return nil }112 accepted = o.mapValues { $0.arrayValue ?? [$0] }113 }114 /// Whether the condition holds for these values (a parameter that is absent matches nothing).115 public func isMet(by values: VQJSONObject) -> Bool {116 accepted.allSatisfy { name, options in values[name].map { options.contains($0) } ?? false }117 }118 /// "Mode is strategy and Template is custom" — the wording of the server's refusal.119 public func sentence(labels: [String: String]) -> String { sentence(labels: labels, language: .preferred) }120 /// The same sentence in a given language (parameter labels and values stay as the server wrote them).121 public func sentence(labels: [String: String], language: VQLanguage) -> String {122 accepted.keys.sorted().map { key in123 VQL10n.string("%1$@ is %2$@", language, labels[key] ?? key, accepted[key]!.map { $0.displayString ?? $0.text() }.joined(separator: VQL10n.string(" or ", language)))124 }.joined(separator: VQL10n.string(" and ", language))125 }126}127128/// The input of a tool, edited by a form and validated like the server validates it. A value type: copy it freely.129///130/// ```swift131/// var form = VQLabForm(tool: tool)132/// form["symbol"] = "AAPL"133/// form["confidence_levels"] = "0.95, 0.99" // lists as the person types them, or as JSON arrays134/// switch form.validate() {135/// case .success(let params): let job = try await lab.start(tool: tool.id, params: params)136/// case .failure(let issues): show(issues) // [name: message], the server's own wording137/// }138/// ```139public struct VQLabForm: Sendable, Equatable {140 public let tool: VQLabTool141 /// Raw values by parameter name: what the person typed (strings) or structured values (numbers, booleans, arrays, objects).142 public private(set) var values: VQJSONObject143144 /// Starts from the tool's defaults.145 public init(tool: VQLabTool, values: VQJSONObject = [:]) {146 self.tool = tool147 var v: VQJSONObject = [:]148 for p in tool.params { if let d = p.defaultValue { v[p.name] = d } }149 for (k, x) in values { v[k] = x }150 self.values = v151 }152153 public subscript(name: String) -> VQJSON? {154 get { values[name] }155 set { values[name] = newValue }156 }157158 /// The value as text for a text field (lists joined with ", ", JSON pretty-printed).159 public func text(_ name: String) -> String {160 switch values[name] {161 case .string(let s)?: return s162 case .array(let a)? where a.allSatisfy({ $0.objectValue == nil && $0.arrayValue == nil }): return a.compactMap(\.displayString).joined(separator: ", ")163 case .array?, .object?: return values[name]!.text(pretty: true)164 case let v?: return v.displayString ?? ""165 case nil: return ""166 }167 }168 public func bool(_ name: String) -> Bool { values[name] == .bool(true) || values[name] == .string("true") }169170 public mutating func reset() { self = VQLabForm(tool: tool) }171172 public struct Issue: Sendable, Equatable, Identifiable {173 /// Parameter name ("" for a cross-field rule).174 public var name: String175 public var message: String176 public var id: String { name + message }177 }178 public struct Invalid: Error, Sendable, Equatable {179 public var issues: [Issue]180 public var message: String { issues.map(\.message).joined(separator: " ") }181 }182183 /// Validates every parameter (all issues, not only the first) and returns the explicit input: unknown keys are184 /// dropped and defaults written out, exactly what the server records with the job.185 public func validate() -> Result<VQJSONObject, Invalid> { validate(language: .preferred) }186187 /// `validate()` with the messages in a given language (by default the app's; the server's own wording is English).188 public func validate(language: VQLanguage) -> Result<VQJSONObject, Invalid> {189 var out: VQJSONObject = [:]190 var issues: [Issue] = []191 for p in tool.params where p.type != .group {192 do { if let v = try Self.check(p, values[p.name], language) { out[p.name] = v } }193 catch let e as ParamError { issues.append(Issue(name: p.name, message: e.message)) }194 catch { issues.append(Issue(name: p.name, message: String(describing: error))) }195 }196 if let lo = out["min_weight"]?.doubleValue, let hi = out["max_weight"]?.doubleValue, lo > hi {197 issues.append(Issue(name: "", message: VQL10n.string("Minimum weight is above maximum weight.", language)))198 }199 // Mode-dependent requirements, judged on the validated input (so a default mode counts) — like the server.200 let labels = Dictionary(tool.params.map { ($0.name, $0.label) }, uniquingKeysWith: { a, _ in a })201 for p in tool.params {202 guard let when = p.requiredWhen, out[p.name] == nil, !issues.contains(where: { $0.name == p.name }), when.isMet(by: out) else { continue }203 issues.append(Issue(name: p.name, message: VQL10n.string("%1$@ is required when %2$@.", language, p.label, when.sentence(labels: labels, language: language))))204 }205 return issues.isEmpty ? .success(out) : .failure(Invalid(issues: issues))206 }207208 public var isValid: Bool { if case .success = validate() { return true } else { return false } }209210 /// The values as the server will judge conditions on them: what was entered, converted where it parses, with211 /// defaults for the rest (an invalid entry counts as typed).212 public var effectiveValues: VQJSONObject {213 var out: VQJSONObject = [:]214 for p in tool.params where p.type != .group {215 if let v = try? Self.check(p, values[p.name]) { out[p.name] = v } else if let raw = values[p.name], !raw.isNull, raw != .string("") { out[p.name] = raw }216 }217 return out218 }219 /// Whether the field should be shown now (`visibleWhen`; a parameter without the hint is always shown).220 public func isVisible(_ param: VQLabParam) -> Bool { param.visibleWhen?.isMet(by: effectiveValues) ?? true }221 /// Whether the field is required now: always (`required`) or because of the other fields (`requiredWhen`).222 public func isRequired(_ param: VQLabParam) -> Bool { param.required || (param.requiredWhen?.isMet(by: effectiveValues) ?? false) }223 /// The parameters to show now, grouped like `VQLabTool.groups` (empty groups dropped).224 public var visibleGroups: [(name: String, params: [VQLabParam])] {225 let v = effectiveValues226 return tool.groups.map { ($0.name, $0.params.filter { $0.visibleWhen?.isMet(by: v) ?? true }) }.filter { !$0.1.isEmpty }227 }228 public func issue(for name: String) -> String? { issue(for: name, language: .preferred) }229 public func issue(for name: String, language: VQLanguage) -> String? {230 if case .failure(let invalid) = validate(language: language) { return invalid.issues.first { $0.name == name }?.message }231 return nil232 }233234 // MARK: rules (mirror of buildInput)235236 struct ParamError: Error { let message: String }237 static let textMaxLength = 2_000238 static let jsonMaxBytes = 64 * 1024239 static let jsonMaxDepth = 12240241 static func check(_ p: VQLabParam, _ raw: VQJSON?, _ language: VQLanguage = .en) throws -> VQJSON? {242 func msg(_ key: String, _ args: CVarArg...) -> ParamError { ParamError(message: VQL10n.string(key, language, arguments: args)) }243 let isMissing: Bool = { switch raw { case nil, .null?: return true; case .string(let s)?: return s.isEmpty; default: return false } }()244 if isMissing {245 if p.required { throw msg("%@ is required.", p.label) }246 return p.defaultValue247 }248 let v = raw!249 switch p.type {250 case .known(.symbol): return .string(try symbol(v, p.label, language))251 case .known(.symbols):252 var seen = Set<String>(), list: [String] = []253 for part in parts(v) { let s = try symbol(part, p.label, language); if seen.insert(s).inserted { list.append(s) } }254 let lo = Int(p.min ?? 1), hi = Int(p.max ?? 50)255 if list.count < lo || list.count > hi { throw msg("%1$@: between %2$@ and %3$@ distinct symbols.", p.label, "\(lo)", "\(hi)") }256 return VQJSON(list)257 case .known(.int), .known(.number): return .number(try number(v, p, integer: p.type == .int, language))258 case .known(.numbers):259 let list = try parts(v).map { try number($0, p, integer: false, language) }260 let maxItems = p.maxItems ?? 10261 if list.isEmpty || list.count > maxItems { throw msg("%1$@: 1 to %2$@ values.", p.label, "\(maxItems)") }262 return VQJSON(list)263 case .known(.choice):264 let s = v.displayString ?? ""265 if !p.choices.contains(s) { throw msg("%1$@: one of %2$@.", p.label, p.choices.joined(separator: ", ")) }266 return .string(s)267 case .known(.bool): return .bool(v == .bool(true) || v == .string("true"))268 case .known(.date):269 guard let d = v.stringValue?.trimmingCharacters(in: .whitespaces), isISODate(d) else { throw msg("%@: a date YYYY-MM-DD is expected.", p.label) }270 if let lo = p.minDate, d < lo { throw msg("%1$@: not before %2$@.", p.label, lo) }271 if let hi = p.maxDate, d > hi { throw msg("%1$@: not after %2$@.", p.label, hi) }272 return .string(d)273 case .known(.text), .unknown:274 guard let s = v.stringValue ?? v.doubleValue.flatMap({ _ in v.displayString }) else { throw msg("%@: text is expected.", p.label) }275 // control characters other than tab and newline are removed, like the server does276 let cleaned = String(String.UnicodeScalarView(s.unicodeScalars.filter { u in !(u.value <= 0x08 || u.value == 0x0B || u.value == 0x0C || (u.value >= 0x0E && u.value <= 0x1F) || u.value == 0x7F) }))277 .trimmingCharacters(in: .whitespacesAndNewlines)278 let limit = p.maxLength ?? textMaxLength279 if cleaned.utf16.count > limit { throw msg("%1$@: at most %2$@ characters.", p.label, "\(limit)") }280 if cleaned.isEmpty {281 if p.required { throw msg("%@ is required.", p.label) }282 return p.defaultValue283 }284 return .string(cleaned)285 case .known(.json):286 let limit = p.maxBytes ?? jsonMaxBytes287 var value = v288 if let s = v.stringValue {289 if s.utf16.count > limit { throw msg("%1$@: too large (limit %2$@ KB).", p.label, "\(Int((Double(limit) / 1024).rounded()))") }290 guard let parsed = try? VQJSON.parse(s) else { throw msg("%@: this is not valid JSON.", p.label) }291 value = parsed292 }293 guard value.objectValue != nil || value.arrayValue != nil else { throw msg("%@: a JSON object or array is expected.", p.label) }294 if value.data().count > limit { throw msg("%1$@: too large (limit %2$@ KB).", p.label, "\(Int((Double(limit) / 1024).rounded()))") }295 if depth(value, limit: jsonMaxDepth) > jsonMaxDepth { throw msg("%@: nested too deeply.", p.label) }296 return value297 case .known(.group): return nil298 }299 }300301 /// A list given as an array, or as text separated by spaces, commas or semicolons.302 static func parts(_ v: VQJSON) -> [VQJSON] {303 if let a = v.arrayValue { return a.filter { ($0.displayString ?? "x").trimmingCharacters(in: .whitespaces) != "" } }304 let text = v.displayString ?? ""305 return text.split(whereSeparator: { $0 == "," || $0 == ";" || $0.isWhitespace }).map { .string(String($0)) }306 }307308 /// `^[A-Z0-9^][A-Z0-9.\-=^]{0,14}$` after trimming and upper-casing.309 static func symbol(_ v: VQJSON, _ label: String, _ language: VQLanguage = .en) throws -> String {310 let shown = v.displayString ?? ""311 let s = shown.trimmingCharacters(in: .whitespacesAndNewlines).uppercased()312 let u = Array(s.utf8)313 func alnum(_ c: UInt8) -> Bool { (c >= 48 && c <= 57) || (c >= 65 && c <= 90) }314 let ok = !u.isEmpty && u.count <= 15 && (alnum(u[0]) || u[0] == 94) && u.dropFirst().allSatisfy { alnum($0) || $0 == 46 || $0 == 45 || $0 == 61 || $0 == 94 }315 if !ok { throw ParamError(message: VQL10n.string("%1$@: \"%2$@\" is not a ticker symbol.", language, label, String(shown.prefix(20)))) }316 return s317 }318319 static func number(_ v: VQJSON, _ p: VQLabParam, integer: Bool, _ language: VQLanguage = .en) throws -> Double {320 var n: Double?321 switch v {322 case .number(let x): n = x323 case .string(let s):324 // JS Number(): surrounding spaces allowed, "." decimal mark only; a decimal comma is accepted here too325 // because the fr-CA keyboard produces it (the server receives a number either way).326 let t = s.trimmingCharacters(in: .whitespaces).replacingOccurrences(of: ",", with: ".")327 n = t.isEmpty ? nil : Double(t)328 case .bool(let b): n = b ? 1 : 0329 default: n = nil330 }331 guard let n, n.isFinite, !integer || n.rounded() == n else { throw ParamError(message: VQL10n.string(integer ? "%@: an integer is expected." : "%@: a number is expected.", language, p.label)) }332 let lo = p.min ?? -Double.greatestFiniteMagnitude, hi = p.max ?? Double.greatestFiniteMagnitude333 if n < lo || n > hi { throw ParamError(message: VQL10n.string("%1$@: must be between %2$@ and %3$@.", language, p.label, plain(lo), plain(hi))) }334 return n335 }336337 /// A bound as JavaScript prints it (1e15 → "1000000000000000", 0.5 → "0.5").338 static func plain(_ x: Double) -> String { VQJSON.number(x).text() }339340 static func isISODate(_ s: String) -> Bool {341 let u = Array(s.utf8)342 guard u.count == 10, u[4] == 45, u[7] == 45 else { return false }343 for i in [0, 1, 2, 3, 5, 6, 8, 9] where !(u[i] >= 48 && u[i] <= 57) { return false }344 guard let date = VQISODate.parse(s) else { return false }345 return VQFormat.dateISO(date, timeZone: TimeZone(identifier: "UTC")!) == s // rejects 2026-02-31346 }347348 static func depth(_ v: VQJSON, limit: Int, current: Int = 1) -> Int {349 if current > limit { return current }350 switch v {351 case .array(let a): return a.map { depth($0, limit: limit, current: current + 1) }.max() ?? current352 case .object(let o): return o.values.map { depth($0, limit: limit, current: current + 1) }.max() ?? current353 default: return current354 }355 }356}357