Repository Public
1// Author: Simon-Pierre Boucher — contact@spboucher.ai2// File: Core/Lab/LabSupport.swift3// Description: Pure logic of the Quant Lab screens (no UI, no network): reading a JSON parameter's schema hint and checking a value against it, the row editor's conversions, comparing two results, the integrity statement of a backtest, the modes of the options engine, slices of a result, catalogue search and remembered parameters.4import Foundation56// MARK: - JSON parameters78/// A `json` parameter comes with a `schemaHint`: an example of the expected value, sometimes several9/// (`{"SPY": -0.2} or {"Crash": {"SPY": -0.2}}`, or one per strategy: `ma_cross {"fast": 50} · donchian {…}`).10/// The hint is an example, not a schema: what it lets the client say is advisory, and the server stays the authority.11public enum LabJSONHint {12 public struct Column: Sendable, Equatable, Identifiable {13 public enum Kind: Sendable, Equatable { case number, text, bool, choice([String]), other }14 public var name: String15 public var kind: Kind16 /// The value the hint shows for this key.17 public var example: JSONValue18 public var id: String { name }19 }2021 public enum Shape: Sendable, Equatable {22 /// An array of objects: editable as rows with these columns (in the hint's order).23 case rows([Column])24 /// An object (keys in the hint's order).25 case object([String])26 /// An array of scalars or of arrays.27 case list28 }2930 public struct Alternative: Sendable, Equatable {31 /// The word written before the example when the hint names its alternatives (`ma_cross {…}`).32 public var label: String?33 public var shape: Shape34 public var example: JSONValue35 public var isArray: Bool { if case .object = shape { false } else { true } }36 }3738 /// Every example found in the hint, in order. Empty when the hint has none that can be read.39 public static func alternatives(_ hint: String?) -> [Alternative] {40 guard let hint, !hint.isEmpty else { return [] }41 var out: [Alternative] = []42 let chars = Array(hint)43 var i = 0, lastEnd = 044 while i < chars.count {45 guard chars[i] == "{" || chars[i] == "[" else { i += 1; continue }46 guard let end = matchingEnd(chars, from: i) else { break }47 let fragment = String(chars[i...end])48 let before = String(chars[lastEnd..<i])49 if let value = parseLoose(fragment) {50 let shape: Shape51 switch value {52 case .array(let a):53 if let first = a.first, let o = first.objectValue, a.allSatisfy({ $0.objectValue != nil }) {54 shape = .rows(orderedKeys(o, in: fragment).map { Column(name: $0, kind: kind(o[$0]!), example: o[$0]!) })55 } else { shape = .list }56 case .object(let o): shape = .object(orderedKeys(o, in: fragment))57 default: i = end + 1; lastEnd = i; continue58 }59 out.append(Alternative(label: label(before), shape: shape, example: value))60 }61 i = end + 1; lastEnd = i62 }63 return out64 }6566 /// The columns of the row editor, when the hint describes an array of objects.67 public static func rowColumns(_ hint: String?) -> [Column]? {68 for a in alternatives(hint) { if case .rows(let c) = a.shape, !c.isEmpty { return c } }69 return nil70 }7172 /// The example of one named alternative (`strategy_params` by strategy).73 public static func example(_ hint: String?, labelled label: String) -> JSONValue? { alternatives(hint).first { $0.label == label }?.example }7475 private static func kind(_ v: JSONValue) -> Column.Kind {76 switch v {77 case .number: return .number78 case .bool: return .bool79 case .string(let s):80 let parts = s.split(separator: "|").map(String.init)81 return parts.count > 1 && parts.allSatisfy({ !$0.isEmpty && !$0.contains(" ") }) ? .choice(parts) : .text82 default: return .other83 }84 }8586 /// Index of the bracket closing the one at `start` (strings respected); nil when unbalanced.87 private static func matchingEnd(_ c: [Character], from start: Int) -> Int? {88 var depth = 0, inString = false, escaped = false89 for i in start..<c.count {90 let ch = c[i]91 if inString {92 if escaped { escaped = false } else if ch == "\\" { escaped = true } else if ch == "\"" { inString = false }93 continue94 }95 if ch == "\"" { inString = true }96 else if ch == "{" || ch == "[" { depth += 1 }97 else if ch == "}" || ch == "]" { depth -= 1; if depth == 0 { return i } }98 }99 return nil100 }101102 /// Hints end lists with an ellipsis (`[{…}, …]`): it is dropped before parsing.103 private static func parseLoose(_ fragment: String) -> JSONValue? {104 var s = fragment105 for e in [", …", ",…", ", ...", ",...", "…"] { s = s.replacingOccurrences(of: e, with: "") }106 return try? JSONValue.parse(Data(s.utf8))107 }108109 private static func orderedKeys(_ o: [String: JSONValue], in fragment: String) -> [String] {110 o.keys.sorted { a, b in111 let ia = fragment.range(of: "\"\(a)\"")?.lowerBound ?? fragment.endIndex, ib = fragment.range(of: "\"\(b)\"")?.lowerBound ?? fragment.endIndex112 return ia == ib ? a < b : ia < ib113 }114 }115116 /// `… · ma_cross ` → "ma_cross"; connective text ("or", "with one symbol") gives nil.117 private static func label(_ before: String) -> String? {118 let t = before.trimmingCharacters(in: CharacterSet(charactersIn: " ·\n\t"))119 guard let word = t.split(whereSeparator: { $0 == " " || $0 == "·" }).last.map(String.init), word == t else { return nil }120 guard word != "or", word.unicodeScalars.allSatisfy({ CharacterSet.lowercaseLetters.contains($0) || CharacterSet.decimalDigits.contains($0) || $0 == "_" }) else { return nil }121 return word122 }123124 // MARK: checking a value125126 public struct Check: Sendable, Equatable {127 /// The value cannot be sent as it is (not JSON, or neither an object nor an array).128 public var error: String?129 /// Differences from the hint's example. Advisory: the engine decides.130 public var notes: [String] = []131 /// What the text is: "array of 2 objects", "object with 3 keys", "empty".132 public var summary: String = ""133 public var isEmpty = false134 public var isValid: Bool { error == nil }135 }136137 public static func check(_ text: String, hint: String?, selected label: String? = nil) -> Check {138 let trimmed = text.trimmingCharacters(in: .whitespacesAndNewlines)139 if trimmed.isEmpty { return Check(summary: "empty", isEmpty: true) }140 let value: JSONValue141 do { value = try JSONValue.parse(Data(trimmed.utf8)) }142 catch {143 let detail = jsonSerializationReason(trimmed) ?? ""144 return Check(error: "Not valid JSON" + (detail.isEmpty ? "." : ": \(detail)"), summary: "invalid")145 }146 var c = Check()147 switch value {148 case .array(let a):149 let objects = a.filter { $0.objectValue != nil }.count150 c.summary = a.isEmpty ? "empty array" : objects == a.count ? "array of \(a.count) object\(a.count == 1 ? "" : "s")" : "array of \(a.count) value\(a.count == 1 ? "" : "s")"151 case .object(let o): c.summary = o.isEmpty ? "empty object" : "object with \(o.count) key\(o.count == 1 ? "" : "s")"152 default:153 c.error = "A JSON object or array is expected."; c.summary = "a single value"154 return c155 }156 var alts = alternatives(hint)157 if let label, let named = alts.first(where: { $0.label == label }) { alts = [named] }158 guard !alts.isEmpty else { return c }159 let isArray = value.arrayValue != nil160 guard let match = alts.first(where: { $0.isArray == isArray }) else {161 c.notes.append("The hint shows \(alts[0].isArray ? "an array" : "an object"); this is \(isArray ? "an array" : "an object").")162 return c163 }164 if case .rows(let columns) = match.shape, let rows = value.arrayValue, alts.allSatisfy({ $0.isArray == false || $0.shape == match.shape }) {165 let names = columns.map(\.name)166 for (i, row) in rows.enumerated() {167 guard let o = row.objectValue else { c.notes.append("Item \(i + 1) is not an object."); continue }168 for k in o.keys.sorted() where !names.contains(k) { c.notes.append("Item \(i + 1): “\(k)” is not in the hint (\(names.joined(separator: ", "))).") }169 for col in columns {170 guard let v = o[col.name], v != .null else { continue }171 switch (col.kind, v) {172 case (.number, .number), (.text, .string), (.bool, .bool), (.other, _): break173 case (.choice(let list), .string(let s)): if !list.contains(s) { c.notes.append("Item \(i + 1): \(col.name) “\(s)” is not one of \(list.joined(separator: ", ")).") }174 case (.number, _): c.notes.append("Item \(i + 1): \(col.name) is a number in the hint.")175 case (.text, _), (.choice, _): c.notes.append("Item \(i + 1): \(col.name) is text in the hint.")176 case (.bool, _): c.notes.append("Item \(i + 1): \(col.name) is true or false in the hint.")177 }178 if c.notes.count >= 6 { c.notes.append("…"); return c }179 }180 }181 }182 if case .object(let keys) = match.shape, label != nil, let o = value.objectValue {183 for k in o.keys.sorted() where !keys.contains(k) { c.notes.append("“\(k)” is not in the hint for \(label!) (\(keys.isEmpty ? "no parameter" : keys.joined(separator: ", "))).") }184 }185 return c186 }187188 private static func jsonSerializationReason(_ text: String) -> String? {189 do { _ = try JSONSerialization.jsonObject(with: Data(text.utf8), options: [.fragmentsAllowed]); return nil }190 catch { return ((error as NSError).userInfo[NSDebugDescriptionErrorKey] as? String).map { $0.hasSuffix(".") ? String($0.dropLast()) + "." : $0 } }191 }192193 /// The same value, indented with sorted keys; nil when the text is not JSON.194 public static func pretty(_ text: String) -> String? {195 guard let v = try? JSONValue.parse(Data(text.utf8)) else { return nil }196 return String(decoding: v.data(pretty: true), as: UTF8.self)197 }198199 // MARK: row editor200201 /// The rows of an array of objects as cell texts by column name; nil when the text is not such an array202 /// (an empty text is an empty table).203 public static func rows(_ text: String) -> [[String: String]]? {204 let trimmed = text.trimmingCharacters(in: .whitespacesAndNewlines)205 if trimmed.isEmpty { return [] }206 guard let a = (try? JSONValue.parse(Data(trimmed.utf8)))?.arrayValue else { return nil }207 var out: [[String: String]] = []208 for item in a {209 guard let o = item.objectValue else { return nil }210 out.append(o.mapValues(cellText))211 }212 return out213 }214215 public static func cellText(_ v: JSONValue) -> String {216 switch v {217 case .string(let s): return s218 case .number(let n): return n.rounded() == n && abs(n) < 9e15 ? String(Int64(n)) : String(n)219 case .bool(let b): return b ? "true" : "false"220 case .null: return ""221 default: return String(decoding: v.data(), as: UTF8.self)222 }223 }224225 /// One cell back to JSON: numbers where the column is numeric (a decimal comma is accepted), otherwise text.226 /// An empty cell is left out of the object (the engine applies its default).227 public static func cellValue(_ text: String, kind: Column.Kind?) -> JSONValue? {228 let t = text.trimmingCharacters(in: .whitespaces)229 if t.isEmpty { return nil }230 switch kind {231 case .number?: if let n = Double(t.replacingOccurrences(of: ",", with: ".")), n.isFinite { return .number(n) } else { return .string(t) }232 case .bool?: return t == "true" ? .bool(true) : t == "false" ? .bool(false) : .string(t)233 case .other?, nil:234 if let v = try? JSONValue.parse(Data(t.utf8)), v.stringValue == nil { return v }235 return .string(t)236 default: return .string(t)237 }238 }239240 /// The JSON text of a table of rows (keys not in the columns are kept).241 public static func text(rows: [[String: String]], columns: [Column]) -> String {242 if rows.isEmpty { return "" }243 let kinds = Dictionary(uniqueKeysWithValues: columns.map { ($0.name, $0.kind) })244 let items = rows.map { row in JSONValue.object(row.reduce(into: [String: JSONValue]()) { o, kv in if let v = cellValue(kv.value, kind: kinds[kv.key]) { o[kv.key] = v } }) }245 return String(decoding: JSONValue.array(items).data(pretty: true), as: UTF8.self)246 }247248 /// A new row: choices take their first value, every other cell is empty (the hint's numbers are examples —249 /// a strike of 100 means nothing for the instrument at hand — and are shown as placeholders instead).250 public static func newRow(_ columns: [Column]) -> [String: String] {251 columns.reduce(into: [:]) { o, c in if case .choice(let list) = c.kind { o[c.name] = list.first ?? "" } else { o[c.name] = "" } }252 }253}254255// MARK: - Comparing two results256257public enum LabCompare {258 public struct Metric: Sendable, Equatable {259 public var label: String260 public var value: Double?261 public var unit: String?262 public init(label: String, value: Double?, unit: String? = nil) { self.label = label; self.value = value; self.unit = unit }263 }264 public struct Row: Sendable, Equatable, Identifiable {265 public var label: String266 public var a: Double?, b: Double?267 public var unit: String?268 public var inA: Bool, inB: Bool269 /// b − a, in the metric's own unit; nil when either side has no number.270 public var delta: Double? { if let a, let b { b - a } else { nil } }271 /// (b − a) / |a|; nil when a is zero or either side is missing.272 public var relative: Double? { if let a, let b, a != 0 { (b - a) / abs(a) } else { nil } }273 public var id: String { label }274 }275276 /// Metrics of A in A's order, each with its counterpart of B by label, then the metrics only B has.277 public static func rows(a: [Metric], b: [Metric]) -> [Row] {278 var out: [Row] = [], seen = Set<String>()279 for m in a where seen.insert(m.label).inserted {280 let other = b.first { $0.label == m.label }281 out.append(Row(label: m.label, a: m.value, b: other?.value, unit: m.unit ?? other?.unit, inA: true, inB: other != nil))282 }283 for m in b where seen.insert(m.label).inserted { out.append(Row(label: m.label, a: nil, b: m.value, unit: m.unit, inA: false, inB: true)) }284 return out285 }286287 public struct ParamDifference: Sendable, Equatable, Identifiable {288 public var name: String289 public var a: String, b: String290 public var id: String { name }291 }292293 /// Parameters whose recorded values differ ("—" = not recorded on that side).294 public static func paramDifferences(a: [String: JSONValue], b: [String: JSONValue]) -> [ParamDifference] {295 Set(a.keys).union(b.keys).sorted().compactMap { k in296 a[k] == b[k] ? nil : ParamDifference(name: k, a: a[k].map(paramText) ?? "—", b: b[k].map(paramText) ?? "—")297 }298 }299300 /// A parameter value on one line (lists joined, structures as compact JSON).301 public static func paramText(_ v: JSONValue) -> String {302 switch v {303 case .array(let a) where a.allSatisfy({ $0.objectValue == nil && $0.arrayValue == nil }): return a.map(LabJSONHint.cellText).joined(separator: ", ")304 case .array, .object: return String(decoding: v.data(), as: UTF8.self)305 case .null: return "—"306 default: return LabJSONHint.cellText(v)307 }308 }309}310311// MARK: - Backtest integrity312313/// What can be said about look-ahead and survivorship for one backtest: the engine's own flags when it reported314/// them, and otherwise a plain statement of what was and was not checked. Never more than that.315public enum LabIntegrity {316 public enum State: String, Sendable, Equatable { case passed, failed, warning, informational, notReported }317 public struct Line: Sendable, Equatable, Identifiable {318 public var title: String319 public var state: State320 public var detail: String321 /// True when the sentence is the engine's; false when it is this app stating that the engine reported nothing.322 public var fromEngine: Bool323 public var id: String { title + detail }324 }325 public struct Diagnostic: Sendable, Equatable {326 public var name: String327 public var passed: Bool?328 public var conclusion: String329 public init(name: String, passed: Bool?, conclusion: String) { self.name = name; self.passed = passed; self.conclusion = conclusion }330 }331 public struct Statement: Sendable, Equatable {332 public var lookAhead: [Line]333 public var survivorship: Line334 }335336 static func isLookAhead(_ name: String) -> Bool {337 let n = name.lowercased()338 return n.contains("look-ahead") || n.contains("lookahead") || n.contains("look ahead") || n.contains("truncation") || n.contains("one bar later") || n.contains("lagged")339 }340341 public static func backtest(diagnostics: [Diagnostic], warnings: [String], assumptions: [String], symbols: Int) -> Statement {342 var look = diagnostics.filter { isLookAhead($0.name) }.map {343 Line(title: $0.name, state: $0.passed == true ? .passed : $0.passed == false ? .failed : .informational, detail: $0.conclusion, fromEngine: true)344 }345 if look.isEmpty {346 look = [Line(title: "Look-ahead", state: .notReported,347 detail: "The engine reported no look-ahead test for this run. By its construction the signal of bar t is traded one bar later; no truncation test result is available here, and nothing else was checked.",348 fromEngine: false)]349 }350 let mentions: (String) -> Bool = { let s = $0.lowercased(); return s.contains("survivorship") || s.contains("delisted") }351 let survivorship: Line352 if let w = warnings.first(where: mentions) {353 survivorship = Line(title: "Survivorship", state: .warning, detail: w, fromEngine: true)354 } else if let a = assumptions.first(where: mentions) {355 survivorship = Line(title: "Survivorship", state: .informational, detail: a, fromEngine: true)356 } else if let d = diagnostics.first(where: { mentions($0.name) || mentions($0.conclusion) }) {357 survivorship = Line(title: d.name, state: d.passed == true ? .passed : d.passed == false ? .failed : .informational, detail: d.conclusion, fromEngine: true)358 } else {359 survivorship = Line(title: "Survivorship", state: .notReported,360 detail: "Not checked. The engine reported no survivorship warning for this run, and it does not test for it: the universe is the \(symbols == 1 ? "symbol" : "\(symbols) symbols") you entered, as \(symbols == 1 ? "it exists" : "they exist") in the data today. Choosing \(symbols == 1 ? "an instrument that still trades" : "instruments that still trade") is itself a selection.",361 fromEngine: false)362 }363 return Statement(lookAhead: look, survivorship: survivorship)364 }365}366367// MARK: - Options engine modes368369/// The options engine is one tool with a `mode` parameter; the Quant Lab presents it as three workbenches (plus370/// implied volatility). A mode only chooses which parameters are put forward and how the result is read: every371/// parameter is still sent, and "All parameters" shows the whole form.372public enum LabOptionsMode: String, Sendable, CaseIterable, Identifiable {373 case price, implied, strategy, chain374 public var id: String { rawValue }375 public var title: String {376 switch self { case .price: "Pricer"; case .implied: "Implied volatility"; case .strategy: "Strategy builder"; case .chain: "Chain analytics" }377 }378 public var blurb: String {379 switch self {380 case .price: "Inputs → price by three models and Greeks."381 case .implied: "The volatility that reproduces a market price."382 case .strategy: "Legs → P&L at expiry and today, break-evens, maximum gain and loss."383 case .chain: "Listed chain → smile, term structure, surface, exposure estimates."384 }385 }386 /// Whether a parameter belongs to the form of this mode.387 public func shows(param name: String, group: String?) -> Bool {388 if name == "symbol" { return true }389 if name == "mode" { return false } // the mode is the segmented control itself390 let g = group ?? ""391 switch self {392 case .price: return ["Contract", "Market", "Numerics"].contains(g)393 case .implied: return ["Contract", "Market", "Implied volatility"].contains(g) || name == "steps"394 case .strategy: return g == "Strategy" || g == "Market" || ["expiry_days", "multiplier"].contains(name)395 case .chain: return g == "Chain" || ["rate", "dividend_yield", "spot", "multiplier"].contains(name)396 }397 }398}399400// MARK: - Slices of a result401402/// A named subset of a result's figures and tables (by their ids), so a long result can be read one question at a403/// time. "All" is always offered; a slice with nothing in it is not.404public struct LabSlice: Sendable, Equatable, Identifiable {405 public var id: String406 public var title: String407 var chartPrefixes: [String]408 var tableIds: [String]409 /// The complement of these slices (the "Overview" of a backtest).410 var excluding: [LabSlice] = []411412 public func includesChart(_ chartId: String) -> Bool {413 if !excluding.isEmpty { return !excluding.contains { $0.includesChart(chartId) } }414 return chartPrefixes.contains { chartId.hasPrefix($0) }415 }416 public func includesTable(_ tableId: String) -> Bool {417 if !excluding.isEmpty { return !excluding.contains { $0.includesTable(tableId) } }418 return tableIds.contains(tableId)419 }420421 /// The slices that make sense for an engine (and mode), limited to those with content in this result.422 public static func available(engine: String, mode: String?, chartIds: [String], tableIds: [String]) -> [LabSlice] {423 let all: [LabSlice]424 switch (engine, mode) {425 case ("options_lab", "chain"?):426 all = [LabSlice(id: "smile", title: "Smile", chartPrefixes: ["smile", "vendor_iv"], tableIds: ["quotes"]),427 LabSlice(id: "term", title: "Term structure", chartPrefixes: ["term_structure"], tableIds: ["expiries"]),428 LabSlice(id: "surface", title: "Surface", chartPrefixes: ["surface"], tableIds: []),429 LabSlice(id: "exposure", title: "Exposure", chartPrefixes: ["gex", "dex", "open_interest"], tableIds: ["exposure"])]430 case ("backtest", _):431 let wf = LabSlice(id: "walk_forward", title: "Walk-forward", chartPrefixes: ["walk_forward"], tableIds: ["walk_forward"])432 let se = LabSlice(id: "sensitivity", title: "Sensitivity", chartPrefixes: ["sensitivity"], tableIds: ["sensitivity"])433 all = [LabSlice(id: "overview", title: "Performance", chartPrefixes: [], tableIds: [], excluding: [wf, se]), wf, se]434 default: all = []435 }436 let kept = all.filter { s in chartIds.contains(where: s.includesChart) || tableIds.contains(where: s.includesTable) }437 return kept.count >= 2 ? kept : []438 }439}440441// MARK: - Catalogue search and remembered parameters442443public enum LabCatalogueSearch {444 /// Every word of the query must appear in one of the fields (case- and accent-insensitive). An empty query matches.445 public static func matches(_ query: String, fields: [String]) -> Bool {446 let fold: (String) -> String = { $0.folding(options: [.caseInsensitive, .diacriticInsensitive], locale: nil).replacingOccurrences(of: "_", with: " ") }447 let words = fold(query).split(whereSeparator: { $0 == " " || $0 == "," }).map(String.init)448 if words.isEmpty { return true }449 let hay = fields.map(fold)450 return words.allSatisfy { w in hay.contains { $0.contains(w) } }451 }452}453454/// The parameters last used with a tool on this Mac (not synced: a convenience of the form, not a document).455public enum LabParamMemory {456 public static func key(_ tool: String) -> String { "lab.lastParams.\(tool)" }457458 public static func encode(_ params: [String: JSONValue]) -> Data { JSONValue.object(params).data() }459460 /// The stored values that still name a parameter of the tool (an engine update may have renamed or removed some).461 public static func decode(_ data: Data?, known: [String]) -> [String: JSONValue] {462 guard let data, let o = (try? JSONValue.parse(data))?.objectValue else { return [:] }463 return o.filter { known.contains($0.key) && $0.value != .null }464 }465}466