SPB Git

Repository Public

LabSupport.swift 24.9 KB 466 lines swift

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

Theme