SPB Git

Repository Public

StudyStore.swift 14.5 KB 285 lines swift

1// Author: Simon-Pierre Boucher — contact@spboucher.ai2// File: App/Next/StudyStore.swift3// Description: Autonomous research (CONTRACT §9) beside the conversations: the server's model registry, the list of research workspaces, and every read of a workspace (files, text pages, datasets, run logs) — network first, then this Mac's encrypted cache, so a study read once stays readable offline.4import AppKit5import CryptoKit6import SwiftUI7import UniformTypeIdentifiers8import VQuantCore9import VQuantKit10import VQuantUI1112extension AppEnvironment {13    var studies: StudyStore { store { StudyStore(app: self) } }14}1516/// A dataset attached in the composer: uploaded into `data/` of the workspace, then profiled by the server.17struct AttachedDataset: Identifiable, Equatable {18    enum Phase: Equatable { case uploading, inspecting, ready, failed(String) }19    let id = UUID()20    var name: String21    var bytes: Int22    var phase: Phase = .uploading23    var uploaded: VQUploadedFile?24    var inspection: VQDatasetInspection?25    /// The profile could not be read (the file is in the workspace all the same).26    var inspectionError: String?27}2829@Observable final class StudyStore: SessionScoped {30    @ObservationIgnored unowned let app: AppEnvironment3132    // the model registry (CONTRACT §2.1)33    private(set) var catalog: VQModelCatalog?34    /// Why the registry could not be read (the composer then falls back to the 1.x list and says so).35    private(set) var catalogError: String?36    private(set) var catalogCachedAt: Date?37    private(set) var catalogLoading = false38    /// The Research mode exists on this server (its sandbox route answers); nil while unknown. `/api/config` does not list it.39    private(set) var researchAvailable: Bool?4041    // research workspaces (CONTRACT §9.6)42    private(set) var workspaces: [VQResearchSession] = []43    private(set) var workspacesError: String?44    private(set) var workspacesCachedAt: Date?45    private(set) var workspacesLoaded = false4647    /// Paths read from this Mac's cache because the server could not be reached, by study reference.48    private(set) var cachedReads: [String: Set<String>] = [:]4950    @ObservationIgnored private var temp: URL51    #if DEBUG52    @ObservationIgnored var fixture: StudyFixture?53    #endif5455    init(app: AppEnvironment) {56        self.app = app57        temp = FileManager.default.temporaryDirectory.appendingPathComponent("vquant-research-\(ProcessInfo.processInfo.processIdentifier)", isDirectory: true)58        app.hintObservers.append { [weak self] hint in59            // a conversation or an analysis changed on another device: the list of studies may have too60            if hint.topic.known == .sessions || hint.topic.known == .generations { Task { await self?.refreshWorkspaces() } }61        }62    }6364    func reset() {65        catalog = nil; catalogError = nil; workspaces = []; workspacesError = nil; workspacesLoaded = false; cachedReads = [:]66        try? FileManager.default.removeItem(at: temp)67    }6869    private var agent: VQResearchAgentClient { app.vq.researchAgent }7071    // MARK: models7273    func loadCatalog(force: Bool = false) async {74        if researchAvailable != true { Task { researchAvailable = await agent.researchModeAvailability() != nil } }75        if catalogLoading || (!force && catalog != nil && catalogCachedAt == nil) { return }76        catalogLoading = true; defer { catalogLoading = false }77        do {78            let vq = app.vq79            let r = try await app.research.cachedJSON("models-catalog") { try await vq.client.json(.get("/api/v2/models")) }80            let c = VQModelCatalog(json: r.value)81            guard !c.providers.isEmpty else { throw VQError(.decoding, message: "The server's model registry is empty.") }82            catalog = c; catalogCachedAt = r.fromCache ? r.fetchedAt : nil; catalogError = nil83        } catch is CancellationError {}84        catch { if catalog == nil { catalogError = error.localizedDescription } }85    }8687    /// A name for a model id: the registry's label, the 1.x table otherwise, the id as a last resort.88    func modelLabel(_ id: String?) -> String {89        guard let id, !id.isEmpty else { return "—" }90        if id == "auto" { return catalog?.auto.label ?? "Auto" }91        return catalog?.model(id)?.label ?? ResearchModel.name(id)92    }93    func provider(of id: String) -> String? {94        if let p = catalog?.model(id)?.provider { return p }95        if id.hasPrefix("claude") { return "anthropic" }; if id.hasPrefix("gpt") { return "openai" }; if id.hasPrefix("gemini") { return "google" }96        if id.hasPrefix("openrouter:") { return "openrouter" }; if id.hasPrefix("local:") { return "local" }97        return nil98    }99100    // MARK: workspaces101102    func refreshWorkspaces() async {103        #if DEBUG104        if let f = fixture { workspaces = f.sessions; workspacesLoaded = true; return }105        #endif106        do {107            let vq = app.vq108            let r = try await app.research.cachedJSON("research-sessions") { try await vq.client.json(.get("/api/v2/research/sessions")) }109            let list: [VQResearchSession] = r.value.models("sessions")110            workspaces = list; workspacesCachedAt = r.fromCache ? r.fetchedAt : nil; workspacesError = nil111        } catch is CancellationError {}112        catch { workspacesError = error.localizedDescription }113        workspacesLoaded = true114    }115116    func workspace(ofSession id: String) -> VQResearchSession? { workspaces.first { $0.sessionIds.contains(id) || ($0.kind == .session && $0.ref == id) } }117118    // MARK: reads of a workspace119120    private func key(_ ref: String, _ what: String, _ path: String) -> String { "study-\(what)-\(ref)-\(path)" }121    private func note(_ ref: String, _ path: String, cached: Bool) {122        if cached { cachedReads[ref, default: []].insert(path) } else if cachedReads[ref]?.contains(path) == true { cachedReads[ref]?.remove(path) }123    }124125    func files(_ ref: String) async throws -> [VQResearchFile] {126        #if DEBUG127        if let f = fixture { return f.files }128        #endif129        let agent = agent130        let r = try await app.research.cachedJSON(key(ref, "files", "")) { try await agent.client.json(.get("/api/v2/research/sessions/\(VQRequest.segment(ref))/files", [VQQueryItem("path", ""), VQQueryItem("recursive", "1")])) }131        note(ref, "", cached: r.fromCache)132        return r.value.models("files")133    }134135    /// Lines `from…` of a text file (1-based, as the server counts them).136    func text(_ ref: String, path: String, from: Int = 1, limit: Int = 400) async throws -> VQResearchFilePreview {137        #if DEBUG138        if let f = fixture { return try f.text(path) }139        #endif140        let agent = agent141        let r = try await app.research.cachedJSON(key(ref, "text-\(from)-\(limit)", path)) {142            try await agent.client.json(.get("/api/v2/research/sessions/\(VQRequest.segment(ref))/file", [VQQueryItem("path", path), VQQueryItem("offset", String(from)), VQQueryItem("limit", String(limit))], timeout: 60))143        }144        note(ref, path, cached: r.fromCache)145        return VQResearchFilePreview(json: r.value)146    }147148    /// The bytes of a file. Files up to 12 MB are kept in the encrypted cache (figures, tables, code); larger ones149    /// are fetched each time.150    func data(_ ref: String, path: String, bytes: Int? = nil) async throws -> Data {151        #if DEBUG152        if let f = fixture { return try f.data(path) }153        #endif154        let agent = agent155        if let bytes, bytes > 12_000_000 { return try await agent.fileData(ref, path: path) }156        let r = try await app.research.cachedData(key(ref, "data", path)) { try await agent.fileData(ref, path: path) }157        note(ref, path, cached: r.fromCache)158        if r.value.count > 12_000_000 { app.cache.remove(key(ref, "data", path)) }159        return r.value160    }161162    func inspect(_ ref: String, path: String) async throws -> VQDatasetInspection {163        #if DEBUG164        if let f = fixture { return f.inspection }165        #endif166        let agent = agent167        let r = try await app.research.cachedJSON(key(ref, "inspect", path)) { try await agent.client.json(.get("/api/v2/research/sessions/\(VQRequest.segment(ref))/inspect", [VQQueryItem("path", path)], timeout: 120)) }168        return VQDatasetInspection(json: r.value)169    }170171    func runLogs(_ runId: String, tail: Int = 8000) async throws -> VQRunLogs {172        #if DEBUG173        if let f = fixture { return f.runLogs }174        #endif175        let agent = agent176        let r = try await app.research.cachedJSON("study-run-\(runId)") { try await agent.client.json(.get("/api/v2/research/runs/\(VQRequest.segment(runId))", [VQQueryItem("tail", String(tail))])) }177        return VQRunLogs(json: r.value)178    }179180    /// The seam the kit's research views read through: every read goes by the cache rules above.181    func source(_ ref: String) -> ResearchDataSource {182        ResearchDataSource(textFile: { [weak self] path in guard let self else { throw CancellationError() }; return try await self.text(ref, path: path) },183                           fileData: { [weak self] path in guard let self else { throw CancellationError() }; return try await self.data(ref, path: path) },184                           runLogs: { [weak self] id in guard let self else { throw CancellationError() }; return try await self.runLogs(id) },185                           inspect: { [weak self] path in guard let self else { throw CancellationError() }; return try await self.inspect(ref, path: path) })186    }187188    /// A file of the workspace as a file of this Mac (Quick Look, drag to the Finder, sharing). Kept in the temporary189    /// directory of this launch under its own name.190    func download(_ ref: String, path: String, bytes: Int? = nil) async throws -> URL {191        let dir = temp.appendingPathComponent(SHA256.hash(data: Data("\(ref)/\(path)".utf8)).prefix(8).map { String(format: "%02x", $0) }.joined(), isDirectory: true)192        let url = dir.appendingPathComponent((path as NSString).lastPathComponent)193        let d = try await data(ref, path: path, bytes: bytes)194        try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)195        try d.write(to: url, options: .atomic)196        return url197    }198199    // MARK: dataset upload (CONTRACT §9.1)200201    /// Creates the workspace of a conversation before its first message (or returns the one it has).202    func prepareWorkspace(sessionId: String?, title: String?, projectId: String?) async throws -> String {203        let r = try await agent.createSession(title: title, projectId: projectId, sessionId: sessionId)204        guard !r.sessionId.isEmpty else { throw VQError(.decoding, message: "The server did not name the research workspace.") }205        Task { await refreshWorkspaces() }206        return r.sessionId207    }208209    /// Uploads a file into `data/` and returns where it landed. Refusals are stated in the server's own sentence.210    func upload(sessionId: String, name: String, data: Data) async throws -> VQUploadedFile {211        let limit = app.research.study(sessionId: sessionId).sandbox?.uploadMaxBytes ?? VQDatasetUpload.defaultMaxBytes212        return try await agent.upload(ResearchStore.studyRef(sessionId: sessionId), name: name, data: data, maxBytes: limit)213    }214215    /// The sentence shown for a refused upload: the server's own (413, 415), the client-side check otherwise.216    static func uploadMessage(_ error: Error) -> String {217        if let r = error as? VQDatasetUpload.Refusal { return r.message(.en) }218        if let e = error as? VQError {219            if [413, 415].contains(e.status), !e.message.isEmpty, !e.message.hasPrefix("HTTP ") { return e.message }220            return VQDatasetUpload.message(for: e, .en)221        }222        return error.localizedDescription223    }224}225226extension VQTokens.Typography.Role {227    /// Shorthand: `.font(VQTokens.Typography.caption.font)` reads long at call sites.228    var f: Font { font }229}230231#if DEBUG232/// Recorded payloads of a real study (the kit's fixtures: `Tests/VQuantKitTests/Fixtures/research`), for visual233/// checks and UI tests of the cockpit with no request and no model call. `-VQXStudyFixture <directory>`.234struct StudyFixture {235    let directory: URL236    let detail: VQJSON237    let conversation: VQJSON238    let sandbox: VQJSON239    let events: [VQJSON]240    let sessions: [VQResearchSession]241    let files: [VQResearchFile]242    let inspection: VQDatasetInspection243    let runLogs: VQRunLogs244    let trace: VQJSON245    var sessionId: String { conversation["sessionId"]?.stringValue ?? "fixture" }246247    init?(directory: URL) {248        func json(_ name: String) -> VQJSON? { (try? Data(contentsOf: directory.appendingPathComponent(name))).flatMap { try? VQJSON.parse($0) } }249        guard let detail = json("session.json"), let conversation = json("conversation.json") else { return nil }250        self.directory = directory; self.detail = detail; self.conversation = conversation251        sandbox = json("sandbox.json") ?? .null252        events = json("stream_study.json")?.arrayValue ?? []253        sessions = (json("sessions.json") ?? .null).models("sessions")254        files = (json("files.json") ?? detail).models("files")255        inspection = VQDatasetInspection(json: json("inspect.json") ?? .null)256        runLogs = VQRunLogs(json: json("run_detail.json") ?? .null)257        trace = json("trace.json") ?? .null258    }259260    func text(_ path: String) throws -> VQResearchFilePreview {261        let name: String262        if path.hasPrefix("logs/cells/") { name = "file_cell.json" }263        else if path.hasSuffix(".jsonl") { name = "file_jsonl.json" }264        else if path.hasSuffix(".csv") { name = "file_csv.json" }265        else if path.hasSuffix("lock.txt") { name = "file_lock.json" }266        else if path.hasSuffix("common.py") { name = "file_common.json" }267        else { name = "file_code.json" }268        guard let d = try? Data(contentsOf: directory.appendingPathComponent(name)), let j = try? VQJSON.parse(d) else { throw VQError(.notFound, status: 404, message: "No such file.") }269        var p = VQResearchFilePreview(json: j); p.path = path270        return p271    }272273    func data(_ path: String) throws -> Data {274        if path.lowercased().hasSuffix(".png") {275            // the recorded figures, in the order of the workspace's figure files276            let pngs = files.map(\.path).filter { $0.hasPrefix("artifacts/figures/") && $0.hasSuffix(".png") }.sorted()277            let i = (pngs.firstIndex(of: path) ?? 0) % 6 + 1278            if let d = try? Data(contentsOf: directory.appendingPathComponent(String(format: "figure_%02d.png", i))) { return d }279        }280        if let t = try? text(path) { return Data(t.text.utf8) }281        throw VQError(.notFound, status: 404, message: "No such file.")282    }283}284#endif285
Files main
Menu

Theme