Repository Public
1// Author: Simon-Pierre Boucher — contact@spboucher.ai2// File: App/LabStore.swift3// Description: Observable state of the Quant Lab (backend 6) on the shared kit's tolerant models: the 19-tool catalogue, the forms being edited, jobs with progress, cancellation, results kept for offline reading, automated reviews. The list refreshes on the sync hint `quant_jobs`; a slow poll is the fallback.4import AppKit5import SwiftUI6import VQuantCore7import VQuantKit89extension AppEnvironment {10 /// The Quant Lab store (created on first use, emptied at sign-out and lock).11 var lab: LabStore { store { LabStore(app: self) } }12}1314// The legacy result views of 1.x read the core's `JSONValue`; the kit speaks `VQJSON`. Same six cases.15extension VQJSON {16 var core: JSONValue {17 switch self {18 case .null: .null19 case .bool(let b): .bool(b)20 case .number(let n): .number(n)21 case .string(let s): .string(s)22 case .array(let a): .array(a.map(\.core))23 case .object(let o): .object(o.mapValues(\.core))24 }25 }26 init(core v: JSONValue) {27 switch v {28 case .null: self = .null29 case .bool(let b): self = .bool(b)30 case .number(let n): self = .number(n)31 case .string(let s): self = .string(s)32 case .array(let a): self = .array(a.map(VQJSON.init(core:)))33 case .object(let o): self = .object(o.mapValues(VQJSON.init(core:)))34 }35 }36}3738extension VQQuantJob {39 /// "AAPL" or "SPY, QQQ, TLT": what the job is about, for lists.40 var subject: String {41 if let s = params["symbol"]?.stringValue { return s }42 if let a = params["symbols"]?.arrayValue, !a.isEmpty {43 let names = a.compactMap(\.stringValue)44 return names.count > 4 ? names.prefix(3).joined(separator: ", ") + " +\(names.count - 3)" : names.joined(separator: ", ")45 }46 if let p = params["positions"]?.arrayValue, !p.isEmpty { return "\(p.count) position\(p.count == 1 ? "" : "s")" }47 if let e = params["events"]?.arrayValue, !e.isEmpty { return "\(e.count) event\(e.count == 1 ? "" : "s")" }48 return ""49 }50 /// Wall-clock duration: the server's `durationMs` once finished, the elapsed time while running.51 func duration(now: Date = Date()) -> TimeInterval? {52 if let durationMs { return durationMs / 1000 }53 if let startedAt, let finishedAt { return finishedAt.timeIntervalSince(startedAt) }54 if isRunning, let startedAt { return max(0, now.timeIntervalSince(startedAt)) }55 return nil56 }57 /// The mode of an options job, the strategy of a backtest: the second line of a job row.58 var variant: String? {59 if tool == "options_lab" { return params["mode"]?.stringValue.flatMap(LabOptionsMode.init(rawValue:))?.title }60 if tool == "backtest" { return params["strategy"]?.stringValue?.replacingOccurrences(of: "_", with: " ") }61 return nil62 }63}6465/// Why a computation could not be started, in words the form shows.66struct LabStartFailure: Error, Equatable {67 var message: String68 /// The server refused because the person already runs the maximum number of computations.69 var isLimit = false70}7172@Observable final class LabStore: SessionScoped {73 private(set) var catalog: VQLabCatalog?74 private(set) var jobs: [VQQuantJob] = []75 private(set) var jobsLoaded = false76 private(set) var fromCache = false77 private(set) var error: String?78 private(set) var fetchedAt: Date?79 /// Jobs with their result (finished), by id.80 private(set) var details: [String: VQQuantJob] = [:]81 /// What the cancel route last answered for a job, explained (shown next to the job until it is dismissed).82 var cancelNotes: [String: String] = [:]83 /// The form of each tool as the person left it (kept while the app runs; the last submitted values are also84 /// remembered on this Mac).85 var forms: [String: VQLabForm] = [:]86 /// Review ids started from this Mac that have not arrived through sync yet, by job id.87 var pendingReviews: [String: String] = [:]8889 @ObservationIgnored private unowned let app: AppEnvironment90 @ObservationIgnored private var followers: [String: Task<Void, Never>] = [:]91 @ObservationIgnored private var poll: Task<Void, Never>?92 @ObservationIgnored private var lastHint: Date?93 @ObservationIgnored private var refreshing = false94 @ObservationIgnored private var refreshAgain = false9596 init(app: AppEnvironment) {97 self.app = app98 app.hintObservers.append { [weak self] hint in99 guard hint.topic == .quantJobs else { return }100 self?.lastHint = Date()101 self?.app.quant.hintHeard()102 Task { await self?.refresh() }103 }104 }105106 func reset() {107 poll?.cancel(); poll = nil108 followers.values.forEach { $0.cancel() }; followers = [:]109 catalog = nil; jobs = []; jobsLoaded = false; details = [:]; cancelNotes = [:]; forms = [:]; pendingReviews = [:]; error = nil; fromCache = false; lastHint = nil110 }111112 // MARK: reading113114 var maxRunning: Int { catalog?.maxRunning ?? 3 }115 var runningCount: Int { jobs.filter(\.isRunning).count }116 var atLimit: Bool { runningCount >= maxRunning }117 func tool(_ id: String) -> VQLabTool? { catalog?.tool(id) }118 func title(_ toolId: String) -> String { tool(toolId)?.title ?? toolId.replacingOccurrences(of: "_", with: " ") }119 /// The freshest state known for a job: its full record when finished, its summary otherwise.120 func job(_ id: String) -> VQQuantJob? { details[id] ?? jobs.first { $0.id == id } }121122 /// The sentence shown when the limit of simultaneous computations is reached.123 var limitExplanation: String {124 "\(maxRunning) computations are already running for your account, which is the server's limit per person. Wait for one to finish, or cancel one, then run this again."125 }126127 // MARK: loading128129 /// Network first; on a network failure the last copy this Mac received (sealed in the cache).130 private func cached(_ key: String, _ request: VQRequest) async throws -> (json: VQJSON, fromCache: Bool) {131 do {132 let j = try await app.vq.client.json(request)133 app.cache.write(j, for: key)134 return (j, false)135 } catch let e as VQError where e.kind == .network {136 if let hit = app.cache.read(VQJSON.self, for: key) { return (hit.value, true) }137 throw e138 }139 }140141 /// Catalogue (once) and job list. Called when the section appears, on every `quant_jobs` hint, and by the fallback poll.142 func refresh() async {143 if refreshing { refreshAgain = true; return }144 refreshing = true; defer { refreshing = false }145 repeat {146 refreshAgain = false147 do {148 if catalog == nil {149 var c = VQLabCatalog(json: try await cached("lab-tools", .get("/api/quant/tools")).json)150 #if DEBUG151 // visual check of the "unavailable engines" block, which the test backend never produces: `-VQXLabUnavailable "id=reason"`152 if let demo = app.options.extra["LabUnavailable"], let eq = demo.firstIndex(of: "=") { c.unavailable[String(demo[..<eq])] = String(demo[demo.index(after: eq)...]) }153 #endif154 catalog = c155 }156 let r = try await cached("lab-jobs", .get("/api/quant/jobs"))157 let list = VQQuantJobList(json: r.json).jobs158 jobs = list; fromCache = r.fromCache; fetchedAt = Date(); error = nil; jobsLoaded = true159 reconcile()160 } catch let e as VQError { if jobs.isEmpty || e.kind != .network { error = e.userMessage }; jobsLoaded = true }161 catch { if !(error is CancellationError) { self.error = error.localizedDescription } }162 } while refreshAgain163 ensurePolling()164 }165166 /// Follows every running job (progress), forgets what is gone.167 private func reconcile() {168 let ids = Set(jobs.map(\.id))169 for j in jobs where j.isRunning && followers[j.id] == nil { follow(j.id) }170 // deleted on another device: the kept record goes too171 for id in details.keys where !ids.contains(id) { details[id] = nil; app.cache.remove("lab-job-\(id)") }172 cancelNotes = cancelNotes.filter { ids.contains($0.key) }173 }174175 /// The watched job is polled once a second by the kit (`follow`): that is where progress comes from. The list176 /// itself is not polled while hints arrive.177 private func follow(_ id: String) {178 guard followers[id] == nil else { return }179 let lab = app.vq.lab180 followers[id] = Task { [weak self] in181 do {182 for try await state in lab.follow(id, every: 1) {183 guard let self, !Task.isCancelled else { return }184 self.apply(state)185 }186 } catch {}187 guard let self, !Task.isCancelled else { return }188 self.followers[id] = nil189 await self.refresh()190 }191 }192193 private func apply(_ state: VQQuantJob) {194 var summary = state; summary.result = nil; summary.code = nil195 if let i = jobs.firstIndex(where: { $0.id == state.id }) { if jobs[i] != summary { jobs[i] = summary } } else { jobs.insert(summary, at: 0) }196 if state.isFinished { keep(state) }197 }198199 private func keep(_ job: VQQuantJob) {200 details[job.id] = job201 app.cache.write(Self.json(job), for: "lab-job-\(job.id)")202 }203204 /// The record as the detail route returns it (so a kept job is read back by the same initialiser).205 private static func json(_ j: VQQuantJob) -> VQJSON {206 var o: VQJSONObject = ["id": .string(j.id), "tool": .string(j.tool), "params": .object(j.params), "status": .string(j.status.rawValue), "cancellable": .bool(j.cancellable)]207 o["startedAt"] = VQJSON(j.startedAt.map { ($0.timeIntervalSince1970 * 1000).rounded() }); o["finishedAt"] = VQJSON(j.finishedAt.map { ($0.timeIntervalSince1970 * 1000).rounded() })208 o["error"] = VQJSON(j.error); o["progress"] = VQJSON(j.progress); o["engineVersion"] = VQJSON(j.engineVersion); o["durationMs"] = VQJSON(j.durationMs)209 o["projectId"] = VQJSON(j.projectId); o["sessionId"] = VQJSON(j.sessionId); o["code"] = VQJSON(j.code); o["result"] = j.result ?? .null210 return .object(o)211 }212213 /// The full record of a job. Finished jobs are immutable: they are kept (memory, then the sealed cache) and stay214 /// readable offline. A running job starts being followed.215 @discardableResult func detail(_ id: String) async -> VQQuantJob? {216 if let d = details[id] { return d }217 if let hit = app.cache.read(VQJSON.self, for: "lab-job-\(id)").map({ VQQuantJob(json: $0.value) }), hit.id == id, hit.isFinished { details[id] = hit; return hit }218 do {219 let j = try await app.vq.lab.job(id)220 if j.isFinished { keep(j) } else { apply(j); follow(id) }221 return j222 } catch let e as VQError {223 if e.kind != .network { app.toasts.show(e.kind == .notFound ? "This computation no longer exists on the server." : e.userMessage, error: true) }224 return jobs.first { $0.id == id }225 } catch { return jobs.first { $0.id == id } }226 }227228 // MARK: fallback poll229230 /// Hints make polling unnecessary while the sync stream is up. The fallback covers a stream that is down:231 /// every 60 s when idle and the app is in front, every 20 s while something runs (5 s when no hint was ever heard).232 private func ensurePolling() {233 guard poll == nil else { return }234 poll = Task { [weak self] in235 while !Task.isCancelled {236 guard let self else { return }237 let running = self.runningCount > 0238 let hintsAlive = self.lastHint.map { Date().timeIntervalSince($0) < 180 } ?? false239 try? await Task.sleep(for: .seconds(running ? (hintsAlive ? 20 : 5) : 60))240 if Task.isCancelled { return }241 if self.app.session.account != nil, NSApp.isActive || self.runningCount > 0 { await self.refresh() }242 }243 }244 }245246 // MARK: forms247248 /// The form of a tool: as it was left in this run of the app, else the last submitted values on this Mac, else249 /// the server's defaults. Pure (called while views render): the view stores the form when it appears.250 func form(_ tool: VQLabTool) -> VQLabForm {251 if let f = forms[tool.id], f.tool == tool { return f }252 let stored = LabParamMemory.decode(app.settings.defaults.data(forKey: LabParamMemory.key(tool.id)), known: tool.params.map(\.name))253 return VQLabForm(tool: tool, values: stored.mapValues(VQJSON.init(core:)))254 }255256 func hasRemembered(_ toolId: String) -> Bool { app.settings.defaults.data(forKey: LabParamMemory.key(toolId)) != nil }257 func forget(_ tool: VQLabTool) { app.settings.defaults.removeObject(forKey: LabParamMemory.key(tool.id)); forms[tool.id] = VQLabForm(tool: tool) }258259 private func remember(_ tool: String, _ params: VQJSONObject) {260 app.settings.defaults.set(LabParamMemory.encode(params.mapValues(\.core)), forKey: LabParamMemory.key(tool))261 }262263 // MARK: actions264265 /// Starts a computation with validated input. The server validates again and applies the limit per person.266 func start(tool: VQLabTool, params: VQJSONObject, projectId: String? = nil) async throws -> VQQuantJob {267 do {268 let j = try await app.vq.lab.start(tool: tool.id, params: params, projectId: projectId)269 remember(tool.id, params)270 apply(j)271 if j.isRunning { follow(j.id) }272 return j273 } catch let e as VQError {274 switch e.kind {275 case .rateLimited: throw LabStartFailure(message: limitExplanation, isLimit: true)276 case .network: throw LabStartFailure(message: "The VQuant server cannot be reached: nothing was started.")277 default: throw LabStartFailure(message: e.userMessage)278 }279 }280 }281282 /// Asks the server to stop a job and explains what it answered.283 func cancel(_ id: String) async {284 do {285 switch try await app.vq.lab.cancel(id) {286 case .cancelled(let j):287 apply(j)288 cancelNotes[id] = "Cancelled: the engine's process was stopped on the server. A cancelled computation keeps no result."289 case .notCancellable:290 cancelNotes[id] = "This is one of the six legacy tools: they run to completion on the server and cannot be stopped. They usually finish within seconds; the result will appear here."291 case .notRunning(let status):292 cancelNotes[id] = "Nothing to cancel: the computation had already finished\(status.isEmpty ? "" : " (\(Self.word(status)))") when the request arrived."293 await refresh()294 }295 } catch let e as VQError {296 cancelNotes[id] = e.kind == .notFound ? "This computation no longer exists on the server." : "The cancel request failed: \(e.userMessage)"297 } catch {}298 }299300 static func word(_ status: String) -> String {301 switch status { case "done": "done"; case "error": "failed"; case "cancelled": "cancelled"; case "interrupted": "interrupted"; default: status }302 }303304 func delete(_ id: String) async {305 do {306 try await app.vq.lab.delete(id)307 followers[id]?.cancel(); followers[id] = nil308 jobs.removeAll { $0.id == id }; details[id] = nil; cancelNotes[id] = nil309 app.cache.remove("lab-job-\(id)"); app.cache.remove("quant-job-\(id)")310 } catch let e as VQError { app.toasts.show(e.kind == .conflict ? "A running computation cannot be deleted: cancel it first." : e.userMessage, error: true) }311 catch {}312 }313314 // MARK: projects and reviews315316 /// Appends `{type: "quant_job", ref: jobId}` to a synced project (once). The write is queued durably by the sync engine.317 @discardableResult func addToProject(_ job: VQQuantJob, projectId: String) async -> Bool {318 guard let projects = app.sync.active?.projects, let project = projects[projectId] else { return false }319 if project.data.items.contains(where: { $0.type == .quantJob && $0.ref == job.id }) { return false }320 let title = [title(job.tool), job.subject].filter { !$0.isEmpty }.joined(separator: " · ")321 await projects.update(projectId) { p in p.items.append(VQProject.Item(type: .quantJob, ref: job.id, title: title, addedAt: Date())) }322 return true323 }324325 /// The automated reviews of a job, newest first (server-written `review` objects, read from sync).326 func reviews(of jobId: String) -> [VQObject<VQReview>] {327 (app.sync.active?.reviews.items ?? []).filter { $0.data.target?.type == .quantJob && $0.data.target?.id == jobId }328 .sorted { ($0.data.startedAt ?? $0.createdAt) > ($1.data.startedAt ?? $1.createdAt) }329 }330331 /// Starts an automated review (`POST /api/v2/reviews`): deterministic checks, then a reviewer model. It costs332 /// model usage, so it only ever runs on the person's explicit request.333 func startReview(of job: VQQuantJob) async throws {334 let id = try await app.vq.research.startReview(of: VQReview.Target(type: .quantJob, id: job.id), projectId: job.projectId)335 pendingReviews[job.id] = id336 await app.sync.active?.reviews.refresh()337 }338}339