Repository Public
1//2// VQuant iOS3// File: Core/Models/Research.swift4// Description: Conversations, analyses (server jobs), the agent workspace and device sessions, as served by the backend.5//6// Author: Simon-Pierre Boucher7// Contact: contact@spboucher.ai8//910import Foundation1112// MARK: - Conversations1314/// A row of `GET /api/sessions`.15struct ConversationSummary: Codable, Hashable, Sendable, Identifiable {16 var sessionId: String17 var title: String18 var pinned: Bool19 var createdAt: Date?20 var updatedAt: Date?21 var id: String { sessionId }2223 private enum CodingKeys: String, CodingKey { case sessionId, title, pinned, createdAt, updatedAt }24 init(sessionId: String, title: String, pinned: Bool = false, createdAt: Date? = nil, updatedAt: Date? = nil) {25 self.sessionId = sessionId; self.title = title; self.pinned = pinned; self.createdAt = createdAt; self.updatedAt = updatedAt26 }27 init(from decoder: Decoder) throws {28 let c = try decoder.container(keyedBy: CodingKeys.self)29 sessionId = try c.decode(String.self, forKey: .sessionId)30 title = c.flexString(.title) ?? ""31 pinned = c.flexBool(.pinned) ?? ((c.flexInt(.pinned) ?? 0) != 0)32 createdAt = c.flexDate(.createdAt) ?? c.flexDouble(.createdAt).map { Date(timeIntervalSince1970: $0 / 1000) }33 updatedAt = c.flexDate(.updatedAt) ?? c.flexDouble(.updatedAt).map { Date(timeIntervalSince1970: $0 / 1000) }34 }35 func encode(to encoder: Encoder) throws {36 var c = encoder.container(keyedBy: CodingKeys.self)37 try c.encode(sessionId, forKey: .sessionId); try c.encode(title, forKey: .title); try c.encode(pinned, forKey: .pinned)38 try c.encodeIfPresent(createdAt.map(ISO8601.string), forKey: .createdAt); try c.encodeIfPresent(updatedAt.map(ISO8601.string), forKey: .updatedAt)39 }40}4142struct SourceLink: Codable, Hashable, Sendable, Identifiable {43 var title: String44 var url: String45 var snippet: String?46 var rank: Int?47 var id: String { url }48 private enum CodingKeys: String, CodingKey { case title, url, snippet, rank }49 init(title: String, url: String, snippet: String? = nil, rank: Int? = nil) { self.title = title; self.url = url; self.snippet = snippet; self.rank = rank }50 init(from decoder: Decoder) throws {51 let c = try decoder.container(keyedBy: CodingKeys.self)52 url = c.flexString(.url) ?? ""53 title = c.flexString(.title) ?? url54 snippet = c.flexString(.snippet); rank = c.flexInt(.rank)55 }56}5758/// One tool call kept with a report: the name of the tool and what it returned. This is the audit trail of the59/// data a report rests on.60struct ToolRecord: Codable, Hashable, Sendable {61 var tool: String62 var result: JSONValue63 private enum CodingKeys: String, CodingKey { case tool, result }64 init(tool: String, result: JSONValue) { self.tool = tool; self.result = result }65 init(from decoder: Decoder) throws {66 let c = try decoder.container(keyedBy: CodingKeys.self)67 tool = c.flexString(.tool) ?? "?"68 result = (try? c.decodeIfPresent(JSONValue.self, forKey: .result)) ?? .null69 }70}7172/// Figures produced by one Python notebook call. `figureUrls` are files on the server (`/figures/…`); `figures`73/// holds the same images as base64, kept with the conversation for when the files are gone.74struct FigureBatch: Codable, Hashable, Sendable, Identifiable {75 var id: String76 var figures: [String]77 var figureUrls: [String]78 var output: String?79 var description: String?80 private enum CodingKeys: String, CodingKey { case id, figureId, figures, figureUrls, output, description }81 init(id: String, figures: [String] = [], figureUrls: [String] = [], output: String? = nil, description: String? = nil) {82 self.id = id; self.figures = figures; self.figureUrls = figureUrls; self.output = output; self.description = description83 }84 init(from decoder: Decoder) throws {85 let c = try decoder.container(keyedBy: CodingKeys.self)86 id = c.flexString(.id) ?? c.flexString(.figureId) ?? UUID().uuidString87 figures = (try? c.decodeIfPresent([String].self, forKey: .figures)) ?? []88 figureUrls = (try? c.decodeIfPresent([String].self, forKey: .figureUrls)) ?? []89 output = c.flexString(.output); description = c.flexString(.description)90 }91 func encode(to encoder: Encoder) throws {92 var c = encoder.container(keyedBy: CodingKeys.self)93 try c.encode(id, forKey: .id); try c.encode(figures, forKey: .figures); try c.encode(figureUrls, forKey: .figureUrls)94 try c.encodeIfPresent(output, forKey: .output); try c.encodeIfPresent(description, forKey: .description)95 }96}9798/// A question and its report, with everything needed to audit or reproduce it.99struct Exchange: Codable, Hashable, Sendable {100 var question: String101 var answer: String102 var toolResults: [ToolRecord]103 var sources: [SourceLink]104 var pythonCode: String?105 var figures: [FigureBatch]106107 private enum CodingKeys: String, CodingKey { case question, answer, toolResults, sources, pythonCode, customPythonFigures }108 init(question: String, answer: String, toolResults: [ToolRecord] = [], sources: [SourceLink] = [], pythonCode: String? = nil, figures: [FigureBatch] = []) {109 self.question = question; self.answer = answer; self.toolResults = toolResults; self.sources = sources; self.pythonCode = pythonCode; self.figures = figures110 }111 init(from decoder: Decoder) throws {112 let c = try decoder.container(keyedBy: CodingKeys.self)113 question = c.flexString(.question) ?? ""114 answer = c.flexString(.answer) ?? ""115 toolResults = (try? c.decodeIfPresent([ToolRecord].self, forKey: .toolResults)) ?? []116 sources = (try? c.decodeIfPresent([SourceLink].self, forKey: .sources)) ?? []117 pythonCode = c.flexString(.pythonCode)118 figures = (try? c.decodeIfPresent([FigureBatch].self, forKey: .customPythonFigures)) ?? []119 }120 func encode(to encoder: Encoder) throws {121 var c = encoder.container(keyedBy: CodingKeys.self)122 try c.encode(question, forKey: .question); try c.encode(answer, forKey: .answer); try c.encode(toolResults, forKey: .toolResults)123 try c.encode(sources, forKey: .sources); try c.encodeIfPresent(pythonCode, forKey: .pythonCode); try c.encode(figures, forKey: .customPythonFigures)124 }125}126127/// `GET /api/sessions/:id`. The server stores `messages` as a JSON string; both forms are accepted.128struct Conversation: Codable, Hashable, Sendable, Identifiable {129 var sessionId: String130 var title: String131 var exchanges: [Exchange]132 var createdAt: Date?133 var updatedAt: Date?134 var id: String { sessionId }135136 private enum CodingKeys: String, CodingKey { case sessionId, title, messages, createdAt, updatedAt }137 init(sessionId: String, title: String, exchanges: [Exchange], createdAt: Date? = nil, updatedAt: Date? = nil) {138 self.sessionId = sessionId; self.title = title; self.exchanges = exchanges; self.createdAt = createdAt; self.updatedAt = updatedAt139 }140 init(from decoder: Decoder) throws {141 let c = try decoder.container(keyedBy: CodingKeys.self)142 sessionId = try c.decode(String.self, forKey: .sessionId)143 title = c.flexString(.title) ?? ""144 createdAt = c.flexDate(.createdAt); updatedAt = c.flexDate(.updatedAt)145 if let direct = try? c.decode([Exchange].self, forKey: .messages) { exchanges = direct }146 else if let text = c.flexString(.messages), let data = text.data(using: .utf8) { exchanges = (try? JSONDecoder().decode([Exchange].self, from: data)) ?? [] }147 else { exchanges = [] }148 }149 func encode(to encoder: Encoder) throws {150 var c = encoder.container(keyedBy: CodingKeys.self)151 try c.encode(sessionId, forKey: .sessionId); try c.encode(title, forKey: .title); try c.encode(exchanges, forKey: .messages)152 try c.encodeIfPresent(createdAt.map(ISO8601.string), forKey: .createdAt); try c.encodeIfPresent(updatedAt.map(ISO8601.string), forKey: .updatedAt)153 }154}155156/// A row of `GET /api/shared-reports` (the report library).157struct SharedReportSummary: Decodable, Hashable, Sendable, Identifiable {158 var id: String159 var shareId: String160 var question: String161 var answer: String162 var createdAt: Date?163 private enum CodingKeys: String, CodingKey { case id, shareId, question, answer, createdAt }164 init(from decoder: Decoder) throws {165 let c = try decoder.container(keyedBy: CodingKeys.self)166 shareId = try c.decode(String.self, forKey: .shareId)167 id = c.flexString(.id) ?? shareId168 question = c.flexString(.question) ?? ""; answer = c.flexString(.answer) ?? ""169 createdAt = c.flexDate(.createdAt) ?? c.flexDouble(.createdAt).map { Date(timeIntervalSince1970: $0 > 1e12 ? $0 / 1000 : $0) }170 }171}172173/// `GET /api/share/:shareId`.174struct SharedReport: Decodable, Hashable, Sendable {175 var question: String176 var answer: String177 var toolResults: [ToolRecord]178 var sources: [SourceLink]179 var figures: [FigureBatch]180 private enum CodingKeys: String, CodingKey { case question, answer, toolResults, sources, customPythonFigures }181 init(from decoder: Decoder) throws {182 let c = try decoder.container(keyedBy: CodingKeys.self)183 question = c.flexString(.question) ?? ""; answer = c.flexString(.answer) ?? ""184 toolResults = (try? c.decodeIfPresent([ToolRecord].self, forKey: .toolResults)) ?? []185 sources = (try? c.decodeIfPresent([SourceLink].self, forKey: .sources)) ?? []186 figures = (try? c.decodeIfPresent([FigureBatch].self, forKey: .customPythonFigures)) ?? []187 }188 var exchange: Exchange { Exchange(question: question, answer: answer, toolResults: toolResults, sources: sources, figures: figures) }189}190191// MARK: - Analyses (server jobs)192193enum AnalysisMode: String, CaseIterable, Codable, Sendable, Identifiable {194 case fast, standard, deep, ultra195 /// Autonomous research (backend 6, CONTRACT §9): persistent workspace, experiment ledger, quality gate.196 case research197 var id: String { rawValue }198 /// The four analysis modes of 1.0 (the research mode has its own entry point).199 static let classic: [AnalysisMode] = [.fast, .standard, .deep, .ultra]200}201202enum GenerationStatus: String, Codable, Sendable {203 case running, done, error, cancelled, unknown204 init(from decoder: Decoder) throws { self = GenerationStatus(rawValue: (try? decoder.singleValueContainer().decode(String.self)) ?? "") ?? .unknown }205}206207/// A row of `GET /api/generations`: an analysis running on the server, or finished in the last 24 hours.208struct Generation: Codable, Hashable, Sendable, Identifiable {209 var id: String210 var sessionId: String211 var query: String212 var mode: String213 var status: GenerationStatus214 var step: String215 var chars: Int216 var tools: Int217 var startedAt: Date218 var finishedAt: Date?219 var replayable: Bool220 var error: String?221222 private enum CodingKeys: String, CodingKey { case id, sessionId, query, mode, status, step, chars, tools, startedAt, finishedAt, replayable, error }223 init(id: String, sessionId: String, query: String, mode: String = "standard", status: GenerationStatus, step: String = "", chars: Int = 0, tools: Int = 0,224 startedAt: Date, finishedAt: Date? = nil, replayable: Bool = true, error: String? = nil) {225 self.id = id; self.sessionId = sessionId; self.query = query; self.mode = mode; self.status = status; self.step = step; self.chars = chars; self.tools = tools226 self.startedAt = startedAt; self.finishedAt = finishedAt; self.replayable = replayable; self.error = error227 }228 init(from decoder: Decoder) throws {229 let c = try decoder.container(keyedBy: CodingKeys.self)230 id = try c.decode(String.self, forKey: .id)231 sessionId = c.flexString(.sessionId) ?? ""232 query = c.flexString(.query) ?? ""; mode = c.flexString(.mode) ?? "standard"233 status = (try? c.decode(GenerationStatus.self, forKey: .status)) ?? .unknown234 step = c.flexString(.step) ?? ""; chars = c.flexInt(.chars) ?? 0; tools = c.flexInt(.tools) ?? 0235 startedAt = Date(timeIntervalSince1970: (c.flexDouble(.startedAt) ?? 0) / 1000)236 finishedAt = c.flexDouble(.finishedAt).map { Date(timeIntervalSince1970: $0 / 1000) }237 replayable = c.flexBool(.replayable) ?? false238 error = c.flexString(.error)239 }240 func encode(to encoder: Encoder) throws {241 var c = encoder.container(keyedBy: CodingKeys.self)242 try c.encode(id, forKey: .id); try c.encode(sessionId, forKey: .sessionId); try c.encode(query, forKey: .query); try c.encode(mode, forKey: .mode)243 try c.encode(status.rawValue, forKey: .status); try c.encode(step, forKey: .step); try c.encode(chars, forKey: .chars); try c.encode(tools, forKey: .tools)244 try c.encode(startedAt.timeIntervalSince1970 * 1000, forKey: .startedAt); try c.encodeIfPresent(finishedAt.map { $0.timeIntervalSince1970 * 1000 }, forKey: .finishedAt)245 try c.encode(replayable, forKey: .replayable); try c.encodeIfPresent(error, forKey: .error)246 }247}248249struct GenerationList: Codable, Sendable {250 var generations: [Generation]251 var running: Int252}253254/// Body of `POST /api/chat`.255struct ChatRequest: Encodable, Sendable {256 struct Turn: Encodable, Sendable { var question: String; var answer: String }257 var query: String258 var history: [Turn] = []259 var sessionId: String?260 var mode: String = AnalysisMode.standard.rawValue261 var model: String?262 var imageData: String?263 var imageMimeType: String?264 /// Per-generation limits (backend 6, CONTRACT §2.4). Omitted when nil: the server applies the preference.265 struct Budget: Encodable, Sendable, Equatable { var maxCostUsd: Double?; var maxMinutes: Double? }266 var budget: Budget?267 /// Files the conversation in a research project and gives the agent the project's context (CONTRACT §5.1).268 var projectId: String?269}270271// MARK: - Workspace272273struct Memory: Codable, Hashable, Sendable, Identifiable {274 var id: String275 var content: String276 var category: String277 var createdAt: Double278 var created: Date { Date(timeIntervalSince1970: createdAt / 1000) }279}280281/// A holding the user recorded (`/api/workspace/portfolio`). VQuant has no brokerage connection: positions are282/// declarative, and nothing here can place an order.283struct Position: Codable, Hashable, Sendable, Identifiable {284 var symbol: String285 var quantity: Double286 var costBasis: Double?287 var note: String?288 var updatedAt: Double289 var id: String { symbol }290}291292struct Watch: Codable, Hashable, Sendable, Identifiable {293 var id: String294 var title: String295 var prompt: String296 var model: String297 var deep: Bool298 /// `HH:mm`, server time.299 var time: String300 /// `weekdays` or `daily`.301 var days: String302 var enabled: Bool303 var lastRunAt: Double?304 var lastSessionId: String?305 var lastStatus: String?306 var createdAt: Double307}308309struct RecallStats: Codable, Hashable, Sendable {310 var passages: Int311 var conversations: Int312}313314struct Account: Codable, Hashable, Sendable {315 var id: String316 var name: String317}318319struct Workspace: Codable, Hashable, Sendable {320 var user: Account321 var memories: [Memory]322 var positions: [Position]323 var watches: [Watch]324 var recall: RecallStats?325}326327// MARK: - Devices and passkeys (`/api/native/*`)328329/// A native device session (this app on one device).330struct DeviceSession: Codable, Hashable, Sendable, Identifiable {331 var id: String332 var label: String?333 var platform: String?334 var createdAt: Double?335 var lastUsedAt: Double?336 var current: Bool?337 var created: Date? { createdAt.map { Date(timeIntervalSince1970: $0 / 1000) } }338 var lastUsed: Date? { lastUsedAt.map { Date(timeIntervalSince1970: $0 / 1000) } }339}340341/// A passkey of the account. The server never exposes the credential id, only an opaque `ref`.342struct PasskeyInfo: Codable, Hashable, Sendable, Identifiable {343 var ref: String344 var label: String?345 var deviceType: String?346 var backedUp: Bool?347 var createdAt: Double?348 var lastUsedAt: Double?349 var id: String { ref }350 private enum CodingKeys: String, CodingKey { case ref, label, deviceType, backedUp, createdAt, lastUsedAt }351 init(from decoder: Decoder) throws {352 let c = try decoder.container(keyedBy: CodingKeys.self)353 ref = try c.decode(String.self, forKey: .ref)354 label = c.flexString(.label); deviceType = c.flexString(.deviceType)355 backedUp = c.flexBool(.backedUp) ?? c.flexInt(.backedUp).map { $0 != 0 }356 createdAt = c.flexDouble(.createdAt); lastUsedAt = c.flexDouble(.lastUsedAt)357 }358 var created: Date? { createdAt.map { Date(timeIntervalSince1970: $0 / 1000) } }359 var lastUsed: Date? { lastUsedAt.map { Date(timeIntervalSince1970: $0 / 1000) } }360}361362/// `GET /api/native/devices`.363struct DeviceList: Codable, Hashable, Sendable {364 var sessions: [DeviceSession]365 var passkeys: [PasskeyInfo]366 var reauthFresh: Bool367}368369/// Answer of `login/verify` and `register/verify`: the device token is shown once and goes straight to the Keychain.370struct SignInResult: Codable, Sendable {371 var token: String372 var user: Account373 var device: DeviceSession374 var idleDays: Int?375}376377/// `GET /api/native/session`.378struct NativeSession: Codable, Hashable, Sendable {379 var user: Account380 var device: DeviceSession381 var reauthFresh: Bool382 var idleDays: Int?383}384385// MARK: - Quantitative computations (`/api/quant/*`)386387/// One parameter of a server engine, as described by `GET /api/quant/tools` (defaults and bounds come from the server).388struct QuantParam: Codable, Hashable, Sendable, Identifiable {389 var name: String390 var type: String391 var label: String392 var required: Bool?393 var `default`: JSONValue?394 var min: Double?395 var max: Double?396 var choices: [String]?397 var id: String { name }398}399400struct QuantTool: Codable, Hashable, Sendable, Identifiable {401 var id: String402 var title: String403 var summary: String404 var params: [QuantParam]405}406407struct QuantToolList: Codable, Hashable, Sendable {408 var tools: [QuantTool]409 var maxRunning: Int410}411412enum QuantStatus: String, Codable, Sendable {413 case running, done, error, interrupted, unknown414 init(from decoder: Decoder) throws { self = QuantStatus(rawValue: (try? decoder.singleValueContainer().decode(String.self)) ?? "") ?? .unknown }415}416417/// A computation run by a server engine. It records the engine, the exact parameters (defaults written out), the418/// Python code that ran and the result: everything needed to reproduce a number.419struct QuantJob: Codable, Hashable, Sendable, Identifiable {420 var id: String421 var tool: String422 var params: [String: JSONValue]423 var status: QuantStatus424 var startedAt: Double425 var finishedAt: Double?426 var error: String?427 var code: String?428 var result: JSONValue?429 var started: Date { Date(timeIntervalSince1970: startedAt / 1000) }430 var finished: Date? { finishedAt.map { Date(timeIntervalSince1970: $0 / 1000) } }431}432433struct QuantJobList: Codable, Hashable, Sendable {434 var jobs: [QuantJob]435 var running: Int436}437