SPB Git

Repository Public

ResearchStore.swift 23.5 KB 418 lines swift

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

Theme