Repository Public
1// Author: Simon-Pierre Boucher — contact@spboucher.ai2// File: App/ResearchStore.swift3// Description: Conversations with the research agent and the analyses running on the server; a run keeps streaming whatever window is showing it. Backend 6: routing, usage, provenance and the research study of each conversation (the kit's store, fed by the stream and by REST).4import AppKit5import SwiftUI6import UserNotifications7import VQuantCore8import VQuantKit910/// One analysis being followed by this Mac. The job itself runs on the server: closing every window does not stop it.11@Observable final class RunController: Identifiable {12 let id = UUID()13 private(set) var state = RunState()14 private(set) var phase: GenerationRunner.Phase = .connecting15 let question: String16 let mode: String17 /// The model asked for (`auto` = the server routes); nil for a job this Mac did not start.18 let requestedModel: String?19 let budget: ChatBudget?20 let startedAt = Date()21 /// Backend 6 — the router's decision (only when `auto` was requested), the usage of the `done` event, provenance22 /// and budget events, exactly as the stream stated them.23 private(set) var route: VQRouteDecision?24 private(set) var usage: VQUsage?25 private(set) var provenance: [VQProvenanceSource] = []26 private(set) var budgetHits: [VQBudgetEvent] = []27 /// The research study of the conversation: this run's events on top of what the workspace already held.28 let study: VQResearchSessionStore29 @ObservationIgnored fileprivate var task: Task<Void, Never>?3031 init(question: String, mode: String, requestedModel: String? = nil, budget: ChatBudget? = nil, study: VQResearchSessionStore) {32 self.question = question; self.mode = mode; self.requestedModel = requestedModel; self.budget = budget; self.study = study33 }3435 var isActive: Bool { switch phase { case .connecting, .streaming, .reconnecting: true; default: false } }36 var isResearch: Bool { mode == ResearchMode.research.rawValue }37 fileprivate func update(_ u: GenerationRunner.Update) { state = u.state; phase = u.phase }3839 /// Applies one raw stream frame to what backend 6 added. Returns an approval the agent has just asked for.40 @discardableResult41 func ingest(_ json: VQJSON, index: Int?) -> VQResearchApproval? {42 let type = json["type"]?.stringValue ?? ""43 // the answer and the reasoning are followed by RunState; the study does not need a publish per chunk of text44 if type == "text" || type == "thinking" { return nil }45 study.apply(json, index: index)46 switch VQGenerationEvent(json: json) {47 case .modelRouted(let d): route = d48 case .budget(let b): if !budgetHits.contains(b) { budgetHits.append(b) }49 case .provenance(let p): provenance = p50 case .done(_, let u): if let u { usage = u }51 case .quantJob, .other: break52 }53 if type == "approval_request", let a = json["approval"].map(VQResearchApproval.init(json:)), a.status == .pending { return a }54 return nil55 }56}5758/// What backend 6 stores with each message of a conversation (CONTRACT §2.4, §9.3).59struct TurnMeta: Equatable {60 var extras: VQMessageExtras61 var research: VQMessageResearch?62 static let none = TurnMeta(extras: VQMessageExtras(json: .null), research: nil)63}6465/// Where the study of a conversation stands on this Mac.66enum StudyLoad: Equatable {67 case loading68 /// the workspace was read; `cachedAt` is set when it comes from this Mac's cache (server unreachable)69 case loaded(cachedAt: Date?)70 /// the conversation has no research workspace71 case absent72 case failed(String)73}7475@Observable final class ResearchStore {76 private(set) var sessions: [SessionSummary] = []77 private(set) var sessionsFromCache = false78 private(set) var sessionsError: String?79 private(set) var conversations: [String: Cached<Conversation>] = [:]80 /// Per message of a conversation, what backend 6 stored with it (usage, model, provenance, research summary).81 private(set) var turnMeta: [String: [TurnMeta]] = [:]82 /// Runs followed by this Mac, by conversation id (a conversation takes one question at a time, as on the server).83 private(set) var runs: [String: RunController] = [:]84 /// A run whose conversation id is not known yet (new conversation, before the server's first frame).85 private(set) var pending: [UUID: RunController] = [:]86 private(set) var generations: [GenerationSummary] = []87 private(set) var generationsError: String?88 private(set) var generationsFetched: Date?89 /// Research studies by reference (`session:<conversation id>` or a workspace id).90 private(set) var studies: [String: VQResearchSessionStore] = [:]91 private(set) var studyLoads: [String: StudyLoad] = [:]92 /// Approvals the agent is waiting for (from streams and from `GET /api/v2/research/approvals`), oldest first.93 private(set) var pendingApprovals: [VQResearchApproval] = []94 /// The approval a window should present now (set when a request arrives; cleared when answered or dismissed).95 var presentedApproval: VQResearchApproval?9697 @ObservationIgnored private let api: VQuantAPI98 @ObservationIgnored private let cache: DiskCache99 @ObservationIgnored private let settings: SettingsStore100 @ObservationIgnored var toasts: ToastCenter?101 /// The kit's clients (set by AppEnvironment right after init).102 @ObservationIgnored var vq: VQNextAPI?103 @ObservationIgnored private var poll: Task<Void, Never>?104 @ObservationIgnored private var rawConversations: [String: VQJSON] = [:]105 @ObservationIgnored private var approvalStudy: [String: String] = [:]106107 init(api: VQuantAPI, cache: DiskCache, settings: SettingsStore) { self.api = api; self.cache = cache; self.settings = settings }108109 func reset() {110 for r in runs.values { r.task?.cancel() }; for r in pending.values { r.task?.cancel() }111 sessions = []; conversations = [:]; runs = [:]; pending = [:]; generations = []; sessionsError = nil; generationsError = nil112 turnMeta = [:]; rawConversations = [:]; studies = [:]; studyLoads = [:]; pendingApprovals = []; presentedApproval = nil; approvalStudy = [:]113 }114115 // MARK: Conversations116117 func refreshSessions(search: String? = nil) async {118 do {119 if let search, !search.isEmpty { sessions = try await api.sessions(search: search); sessionsFromCache = false }120 else {121 let r = try await cache.fetch("sessions") { [api] in try await api.sessions() }122 sessions = r.value; sessionsFromCache = r.fromCache123 }124 sessionsError = nil125 } catch { if !(error is CancellationError) { sessionsError = error.localizedDescription } }126 }127128 @discardableResult func loadConversation(_ id: String, force: Bool = false) async -> Cached<Conversation>? {129 if !force, let c = conversations[id], !c.fromCache { return c }130 do {131 // the stored conversation is read once, as JSON: the 1.x turns are decoded from it and backend 6's additions132 // (usage, model, provenance, research summary, tool results for the study) are kept beside them133 let r = try await cache.fetch("conversation-v6-\(id)") { [api] in134 Self.slim(try VQJSON.parse(try await api.client.data(.get, "/api/sessions/\(APIClient.segment(id))")))135 }136 let conversation = try JSONDecoder().decode(Conversation.self, from: r.value.data())137 let c = Cached(value: conversation, fetchedAt: r.fetchedAt, fromCache: r.fromCache)138 conversations[id] = c; rawConversations[id] = r.value139 let extras = VQMessageExtras.ofSession(r.value), research = VQMessageResearch.ofSession(r.value)140 turnMeta[id] = extras.enumerated().map { TurnMeta(extras: $1, research: research.indices.contains($0) ? research[$0] : nil) }141 return c142 } catch let e as APIError where e.kind == .notFound { conversations[id] = nil; turnMeta[id] = nil; rawConversations[id] = nil; return nil }143 catch let e as APIError where e.kind == .network {144 // a conversation cached by 1.x (before the raw form existed) stays readable offline145 if let old = cache.read(Conversation.self, for: "conversation-\(id)") { let c = Cached(value: old.value, fetchedAt: old.fetchedAt, fromCache: true); conversations[id] = c; return c }146 toasts?.error(e); return conversations[id]147 }148 catch { toasts?.error(error); return conversations[id] }149 }150151 /// The stored conversation without the base64 copies of its figures (they are fetched by address when shown).152 nonisolated static func slim(_ session: VQJSON) -> VQJSON {153 guard var o = session.objectValue else { return session }154 let messages = VQMessageExtras.messages(of: session).map { m -> VQJSON in155 guard var mo = m.objectValue, let figs = mo["customPythonFigures"]?.arrayValue else { return m }156 mo["customPythonFigures"] = .array(figs.map { f in157 guard var fo = f.objectValue else { return f }158 fo["figures"] = nil159 return .object(fo)160 })161 return .object(mo)162 }163 o["messages"] = .array(messages)164 return .object(o)165 }166167 func meta(_ sessionId: String, turn index: Int) -> TurnMeta { turnMeta[sessionId].flatMap { $0.indices.contains(index) ? $0[index] : nil } ?? .none }168169 func rename(_ id: String, _ title: String) async { await change { try await $0.renameSession(id, title: title) } }170 func pin(_ id: String, _ pinned: Bool) async { await change { try await $0.pinSession(id, pinned: pinned) } }171 func delete(_ id: String) async {172 await change { try await $0.deleteSession(id) }173 conversations[id] = nil; cache.remove("conversation-\(id)"); cache.remove("conversation-v6-\(id)")174 turnMeta[id] = nil; rawConversations[id] = nil175 }176 private func change(_ op: @escaping (VQuantAPI) async throws -> Void) async {177 do { try await op(api); await refreshSessions() } catch { toasts?.error(error) }178 }179180 // MARK: Studies (CONTRACT §9)181182 static func studyRef(sessionId: String) -> String { VQResearchSession.reference(sessionId: sessionId) }183184 /// The study store of a reference, created empty the first time.185 func study(ref: String) -> VQResearchSessionStore {186 if let s = studies[ref] { return s }187 let s = VQResearchSessionStore(client: vq?.researchAgent)188 studies[ref] = s189 return s190 }191 func study(sessionId: String) -> VQResearchSessionStore { study(ref: Self.studyRef(sessionId: sessionId)) }192193 /// Reads the workspace of a study by REST (network first; this Mac's encrypted cache when the server cannot be194 /// reached). A conversation without a workspace is `absent`, not an error.195 func loadStudy(ref: String, sessionId: String? = nil, force: Bool = false) async {196 if !force, case .loaded(nil)? = studyLoads[ref] { return }197 guard let vq else { return }198 if studyLoads[ref] == nil { studyLoads[ref] = .loading }199 do {200 let detail = try await cachedJSON("study-\(ref)") { try await vq.client.json(.get("/api/v2/research/sessions/\(VQRequest.segment(ref))", timeout: 60)) }201 let sandbox = try? await cachedJSON("study-sandbox") { try await vq.client.json(.get("/api/v2/research/sandbox")) }202 let d = VQResearchSessionDetail(json: detail.value)203 study(ref: ref).install(detail: d, conversation: sessionId.flatMap { rawConversations[$0] }, sandbox: sandbox.map { VQSandboxStatus(json: $0.value) })204 studyLoads[ref] = .loaded(cachedAt: detail.fromCache ? detail.fetchedAt : nil)205 for a in d.approvals where a.status == .pending { noteApproval(a, ref: ref, present: false) }206 } catch let e as VQError where e.kind == .notFound { studyLoads[ref] = .absent }207 catch is CancellationError {}208 catch { if studies[ref]?.detail == nil { studyLoads[ref] = .failed(error.localizedDescription) } }209 }210211 /// Network first, then the encrypted cache on a network failure — the rule of `DiskCache.fetch`, for kit requests.212 func cachedJSON(_ key: String, _ load: @escaping @Sendable () async throws -> VQJSON) async throws -> Cached<VQJSON> {213 try await cache.fetch(key) {214 do { return try await load() }215 catch let e as VQError where e.kind == .network { throw APIError(.network, e.message) }216 }217 }218 func cachedData(_ key: String, _ load: @escaping @Sendable () async throws -> Data) async throws -> Cached<Data> {219 try await cache.fetch(key) {220 do { return try await load() }221 catch let e as VQError where e.kind == .network { throw APIError(.network, e.message) }222 }223 }224225 // MARK: Approvals (CONTRACT §9.7)226227 /// Requests waiting at launch or when a window reopens (a study started on another device may be waiting).228 func refreshApprovals() async {229 guard let vq else { return }230 guard let list = try? await vq.researchAgent.approvals(pendingOnly: true) else { return }231 let now = Date()232 let known = Set(pendingApprovals.map(\.id))233 pendingApprovals = list.filter { $0.isAnswerable(now: now) }.sorted { ($0.createdAt ?? .distantPast) < ($1.createdAt ?? .distantPast) }234 if presentedApproval == nil, let fresh = pendingApprovals.first(where: { !known.contains($0.id) }) { presentedApproval = fresh }235 }236237 func noteApproval(_ a: VQResearchApproval, ref: String?, present: Bool, sessionId: String? = nil) {238 guard a.status == .pending else { return }239 if let ref { approvalStudy[a.id] = ref }240 if !pendingApprovals.contains(where: { $0.id == a.id }) { pendingApprovals.append(a) }241 guard present else { return }242 if presentedApproval == nil { presentedApproval = a }243 if let sessionId { Notifier.approvalNeeded(title: a.title(.en), body: a.reason ?? a.scope(.en), sessionId: sessionId) }244 }245246 /// Answers a request. False when the server no longer takes an answer (expired, or answered on another device).247 @discardableResult func answer(_ a: VQResearchApproval, _ decision: VQResearchApproval.Decision) async -> Bool {248 var ok = false249 if let ref = approvalStudy[a.id], let s = studies[ref] {250 ok = await s.answer(a, decision)251 if !ok, let e = s.lastError, e.kind != .notFound { toasts?.show(e.userMessage, error: true); return false }252 } else if let vq {253 do { _ = try await vq.researchAgent.answer(approval: a.id, decision); ok = true }254 catch let e as VQError where e.kind == .notFound { ok = false }255 catch { toasts?.error(error); return false }256 }257 pendingApprovals.removeAll { $0.id == a.id }258 if presentedApproval?.id == a.id { presentedApproval = pendingApprovals.first }259 if !ok { toasts?.show("This request is no longer waiting for an answer (it expired or was answered on another device).", error: true) }260 return ok261 }262263 func approvalResolved(_ id: String) {264 pendingApprovals.removeAll { $0.id == id }265 if presentedApproval?.id == id { presentedApproval = nil }266 }267268 // MARK: Runs269270 func run(for sessionId: String?) -> RunController? { sessionId.flatMap { runs[$0] } }271272 /// Starts an analysis. `key` identifies a new conversation until the server names it. `preparedSession` = the273 /// conversation id was created beforehand with its research workspace (a dataset was attached): the run is274 /// reachable by that id at once.275 @discardableResult276 func ask(_ question: String, sessionId: String?, key: UUID, mode: ResearchMode, model: String, image: (data: Data, mime: String)? = nil,277 budget: ChatBudget? = nil, projectId: String? = nil, preparedSession: Bool = false) -> RunController {278 let history = sessionId.flatMap { conversations[$0]?.value.turns.map { (question: $0.question, answer: $0.answer) } } ?? []279 let req = ChatRequest(query: question, sessionId: sessionId, history: history, mode: mode, model: model, imageBase64: image?.data.base64EncodedString(), imageMimeType: image?.mime,280 budget: budget, projectId: projectId)281 let study = sessionId.map { self.study(sessionId: $0) } ?? VQResearchSessionStore(client: vq?.researchAgent)282 study.beginGeneration()283 let run = RunController(question: question, mode: mode.rawValue, requestedModel: model, budget: budget, study: study)284 if let sessionId { runs[sessionId] = run } else { pending[key] = run }285 _ = preparedSession286 follow(run, GenerationRunner(api: api), pendingKey: sessionId == nil ? key : nil) { $0.start(req) }287 return run288 }289290 /// Follows a job that is already running on the server (started from another device, or before this app was reopened).291 @discardableResult func attach(_ g: GenerationSummary) -> RunController {292 if let r = runs[g.sessionId], r.state.jobId == g.id { return r }293 let study = self.study(sessionId: g.sessionId)294 study.beginGeneration()295 let run = RunController(question: g.query, mode: g.mode, study: study)296 runs[g.sessionId] = run297 follow(run, GenerationRunner(api: api), pendingKey: nil) { $0.attach(jobId: g.id) }298 return run299 }300301 func pendingRun(_ key: UUID) -> RunController? { pending[key] }302 /// The window that composed the draft now shows the named conversation.303 func adopt(_ key: UUID) { pending[key] = nil }304305 private func follow(_ run: RunController, _ base: GenerationRunner, pendingKey: UUID?, _ open: (GenerationRunner) -> AsyncStream<GenerationRunner.Update>) {306 // the raw frames, in order, for what backend 6 added (the 1.x state keeps coming through `Update`)307 let (frames, feed) = AsyncStream<SSEFrame>.makeStream()308 var runner = base309 runner.onFrame = { feed.yield($0) }310 let stream = open(runner)311 let tap = Task { [weak self] in312 for await f in frames {313 let type = f.json["type"]?.stringValue ?? ""314 if type == "text" || type == "thinking" { continue }315 let json = VQJSON(f.json)316 let asked = run.ingest(json, index: f.id)317 guard let self else { continue }318 if type == "job", let sid = f.json["sessionId"]?.stringValue, !sid.isEmpty { self.studies[Self.studyRef(sessionId: sid)] = run.study }319 if let asked { self.noteApproval(asked, ref: run.state.sessionId.map(Self.studyRef(sessionId:)), present: true, sessionId: run.state.sessionId ?? f.json["sessionId"]?.stringValue) }320 if type == "approval_resolved", let id = json["approval"]?["id"]?.stringValue { self.approvalResolved(id) }321 }322 }323 run.task = Task { [weak self] in324 var moved = pendingKey == nil325 for await u in stream {326 run.update(u)327 if !moved, let sid = u.state.sessionId, pendingKey != nil, let self {328 // the server has named the conversation: the run is now reachable by its id. It also stays reachable329 // by the draft key until the window that started it has switched to the conversation (adopt).330 self.runs[sid] = run; moved = true331 self.studies[Self.studyRef(sessionId: sid)] = run.study332 }333 }334 feed.finish()335 await tap.value336 guard let self, !Task.isCancelled else { return }337 await self.finished(run)338 }339 }340341 private func finished(_ run: RunController) async {342 if let sid = run.state.sessionId {343 await loadConversation(sid, force: true)344 await refreshSessions()345 // what the stream does not carry (notes, environment, files) and what stays after it: the workspace by REST346 if run.study.workspaceId != nil || run.isResearch { await loadStudy(ref: Self.studyRef(sessionId: sid), sessionId: sid, force: true) }347 }348 await refreshGenerations()349 if run.state.finished, settings.notifyOnCompletion, !NSApp.isActive {350 Notifier.post(title: run.state.error == nil ? "Analysis finished" : "Analysis interrupted", body: run.question, id: run.id.uuidString, route: .conversation(run.state.sessionId))351 }352 }353354 /// Removes a finished run from view (its answer is in the conversation).355 func dismiss(_ sessionId: String) { if let r = runs[sessionId], !r.isActive { runs[sessionId] = nil } }356357 func stop(_ run: RunController) async {358 guard let id = run.state.jobId else { return }359 do { try await api.cancelGeneration(id) } catch { toasts?.error(error) }360 }361362 func cancelGeneration(_ id: String) async {363 do { try await api.cancelGeneration(id); await refreshGenerations() } catch { toasts?.error(error) }364 }365366 #if DEBUG367 /// Visual checks and UI tests: a recorded conversation, installed as if it had been read from the server.368 func debugInstall(conversation raw: VQJSON) {369 let slim = Self.slim(raw)370 guard let c = try? JSONDecoder().decode(Conversation.self, from: slim.data()) else { return }371 conversations[c.sessionId] = Cached(value: c, fetchedAt: Date(), fromCache: false); rawConversations[c.sessionId] = slim372 let extras = VQMessageExtras.ofSession(slim), research = VQMessageResearch.ofSession(slim)373 turnMeta[c.sessionId] = extras.enumerated().map { TurnMeta(extras: $1, research: research.indices.contains($0) ? research[$0] : nil) }374 }375 func debugMark(ref: String, _ load: StudyLoad) { studyLoads[ref] = load }376 /// Visual checks and UI tests: a run fed by recorded events, with no request to the server (and no model call).377 @discardableResult func debugRun(sessionId: String, question: String, mode: String, events: [VQJSON], study: VQResearchSessionStore? = nil) -> RunController {378 let s = study ?? self.study(sessionId: sessionId)379 let run = RunController(question: question, mode: mode, requestedModel: "auto", study: s)380 var state = RunState(); state.jobId = "fixture"; state.sessionId = sessionId381 for (i, e) in events.enumerated() {382 if let v = try? JSONValue.parse(e.data()) { state.apply(SSEFrame(id: i, json: v)) }383 if let a = run.ingest(e, index: i) { noteApproval(a, ref: Self.studyRef(sessionId: sessionId), present: true, sessionId: sessionId) }384 }385 run.update(.init(state: state, phase: state.finished ? .finished : .streaming))386 runs[sessionId] = run; studies[Self.studyRef(sessionId: sessionId)] = s387 return run388 }389 #endif390391 // MARK: Server job list392393 func refreshGenerations() async {394 do { let l = try await api.generations(); generations = l.generations; generationsFetched = Date(); generationsError = nil }395 catch { if !(error is CancellationError) { generationsError = error.localizedDescription } }396 }397398 var runningCount: Int { generations.filter { $0.status == .running }.count }399400 func startPolling() {401 poll?.cancel()402 poll = Task { [weak self] in403 while !Task.isCancelled {404 guard let self else { return }405 if NSApp.isActive || self.runningCount > 0 { await self.refreshGenerations() }406 // jobs are polled at the configured pace while something runs, slowly otherwise407 try? await Task.sleep(for: .seconds(self.runningCount > 0 ? max(2, self.settings.jobPoll) : 30))408 }409 }410 }411 func stopPolling() { poll?.cancel(); poll = nil }412}413414extension VQJSON {415 /// The core's JSON value as the kit's (the conversion itself is `init(core:)` in App/LabStore.swift).416 init(_ v: JSONValue) { self.init(core: v) }417}418