SPB Git

Repository Public

LabStore.swift 17.2 KB 339 lines swift

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

Theme