SPB Git

Repository Public

VQLabTools.swift 19.7 KB 357 lines swift

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
Files main
Menu

Theme