Repository Public
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