Repository Public MIT
1// =============================================================================2// SP BOUCHER | SOFTWARE & RESEARCH3// ARTIFICIAL INTELLIGENCE • FINANCE • ENGINEERING4// =============================================================================5//6// PROJECT METADATA7// -----------------------------------------------------------------------------8// Project : ORIX Astra9// File : Packages/AstraPersistence/Sources/Records.swift10// Module : Packages11// Repository : https://git.spboucher.ai/orix-astra12// Created : 2026-11-2113// Last Modified : 2026-11-2214//15// =============================================================================16// AUTHOR & PROFESSIONAL AFFILIATION17// =============================================================================18//19// Author : Simon-Pierre Boucher20// Position : Professor of Finance21// Institution : Université du Québec en Outaouais (UQO)22// Department : Département des sciences administratives23// Organization : SP Boucher24//25// Website : https://spboucher.ai26// Git : https://git.spboucher.ai27//28// =============================================================================29// OFFICIAL CONTACT DIRECTORY30// =============================================================================31//32// General : info@spboucher.ai33// Professional : contact@spboucher.ai34// Direct : simon@spboucher.ai35// Research : research@spboucher.ai36// Development : dev@spboucher.ai37// Support : support@spboucher.ai38// Security/Admin : admin@spboucher.ai39// Notifications : notifications@spboucher.ai40//41// Preferred Contact: support@spboucher.ai42//43// =============================================================================44// COPYRIGHT & INTELLECTUAL PROPERTY45// =============================================================================46//47// Copyright (c) 202648// Simon-Pierre Boucher49//50// All rights reserved where applicable.51//52// This file is governed by the applicable project license,53// copyright notices, institutional agreements and relevant law.54//55// Unless expressly authorized by the applicable license or56// rights holder, copying, redistribution, sublicensing,57// publication and commercial exploitation are not permitted.58//59// Existing third-party rights and notices remain unaffected.60//61// =============================================================================62// CONFIDENTIALITY & SECURITY63// =============================================================================64//65// Classification : Public66// Distribution : Public repository; use is governed by the project license67// Security Contact : admin@spboucher.ai68//69// Access to this source does not independently grant permission70// to redistribute or disclose confidential materials.71//72// Do not embed credentials, private keys, access tokens,73// certificates or confidential personal information.74//75// =============================================================================76// LICENSE & MAINTENANCE77// =============================================================================78//79// License : Proprietary, all rights reserved (see license file)80// License File : LICENSE81// Maintainer : Simon-Pierre Boucher82// Technical Contact: dev@spboucher.ai83//84// =============================================================================85// END OF SP BOUCHER SOURCE HEADER86// =============================================================================8788import Foundation89import GRDB90import AstraCore9192// MARK: - Conversations9394public struct ConversationRecord: AstraRecord {95 public static let databaseTableName = "conversation"96 public var id: String97 /// Empty until the person names the conversation or `autoTitleIfNeeded` runs.98 public var title: String99 public var createdAt: Date100 public var updatedAt: Date101 public var pinned: Bool102 public var archived: Bool103 public var model: ModelRef104 public var systemPrompt: String105 public var parameters: GenerationParameters106 /// The person's own cap on the context window, in tokens; nil = the model's limit.107 public var contextWindowCap: Int?108 public var truncationStrategy: TruncationStrategy109 public var memoryEnabled: Bool110 public var presetID: String?111 public var routing: RoutingPreferences?112 /// Last message of the branch being shown. Maintained by the store; changes to it through `updateConversation` are ignored.113 public var activeLeafID: String?114115 public init(id: String = UUID().uuidString, title: String = "", createdAt: Date = Date(), updatedAt: Date? = nil, pinned: Bool = false,116 archived: Bool = false, model: ModelRef, systemPrompt: String = "", parameters: GenerationParameters = .default,117 contextWindowCap: Int? = nil, truncationStrategy: TruncationStrategy = .dropOldest, memoryEnabled: Bool = true,118 presetID: String? = nil, routing: RoutingPreferences? = nil, activeLeafID: String? = nil) {119 self.id = id; self.title = title; self.createdAt = createdAt; self.updatedAt = updatedAt ?? createdAt; self.pinned = pinned120 self.archived = archived; self.model = model; self.systemPrompt = systemPrompt; self.parameters = parameters121 self.contextWindowCap = contextWindowCap; self.truncationStrategy = truncationStrategy; self.memoryEnabled = memoryEnabled122 self.presetID = presetID; self.routing = routing; self.activeLeafID = activeLeafID123 }124125 /// The context budget for a model whose window is `modelWindow` tokens, honouring the person's cap.126 public func contextBudget(modelWindow: Int, reservedForOutput: Int) -> ContextBudget {127 ContextBudget(window: contextWindowCap.map { min($0, modelWindow) } ?? modelWindow, reservedForOutput: reservedForOutput, strategy: truncationStrategy)128 }129}130131public enum ConversationFilter: Sendable, Hashable { case active, archived, all }132133public struct ConversationSearchHit: Sendable, Hashable, Identifiable {134 public var conversation: ConversationRecord135 /// The best matching message, when the match is in a message rather than only in the title.136 public var messageID: String?137 public var snippet: String138 public var matchedTitle: Bool139 public var id: String { conversation.id }140}141142// MARK: - Messages143144public enum MessageStatus: String, Sendable, Codable, Hashable, CaseIterable { case streaming, complete, stopped, failed }145146public struct MessageRecord: Sendable, Codable, Hashable, Identifiable {147 public var id: String148 public var conversationID: String149 public var parentID: String?150 public var role: PromptMessage.Role151 public var text: String152 public var reasoningSummary: String153 public var toolCalls: [ToolCall]154 /// Tool turns: the call being answered.155 public var toolCallID: String?156 public var toolName: String?157 public var toolIsError: Bool158 public var status: MessageStatus159 public var error: AstraError?160 /// The model that was asked. `reportedModel` and `servedBy` are what the provider said actually answered.161 public var model: ModelRef?162 public var reportedModel: String?163 public var servedBy: String?164 public var usage: TokenUsage?165 public var stopReason: StopReason?166 public var cost: CostEstimate?167 public var timeToFirstToken: TimeInterval?168 public var totalTime: TimeInterval?169 public var createdAt: Date170 public var updatedAt: Date171 public var bookmarked: Bool172173 public init(id: String = UUID().uuidString, conversationID: String, parentID: String? = nil, role: PromptMessage.Role, text: String = "",174 reasoningSummary: String = "", toolCalls: [ToolCall] = [], toolCallID: String? = nil, toolName: String? = nil,175 toolIsError: Bool = false, status: MessageStatus = .complete, error: AstraError? = nil, model: ModelRef? = nil,176 reportedModel: String? = nil, servedBy: String? = nil, usage: TokenUsage? = nil, stopReason: StopReason? = nil,177 cost: CostEstimate? = nil, timeToFirstToken: TimeInterval? = nil, totalTime: TimeInterval? = nil, createdAt: Date = Date(),178 updatedAt: Date? = nil, bookmarked: Bool = false) {179 self.id = id; self.conversationID = conversationID; self.parentID = parentID; self.role = role; self.text = text180 self.reasoningSummary = reasoningSummary; self.toolCalls = toolCalls; self.toolCallID = toolCallID; self.toolName = toolName181 self.toolIsError = toolIsError; self.status = status; self.error = error; self.model = model; self.reportedModel = reportedModel182 self.servedBy = servedBy; self.usage = usage; self.stopReason = stopReason; self.cost = cost; self.timeToFirstToken = timeToFirstToken183 self.totalTime = totalTime; self.createdAt = createdAt; self.updatedAt = updatedAt ?? createdAt; self.bookmarked = bookmarked184 }185186 /// The turn as a provider sees it (images are added by the caller from the attachments).187 public var promptMessage: PromptMessage {188 PromptMessage(role: role, text: text, toolCalls: toolCalls, toolCallID: toolCallID, toolName: toolName, toolIsError: toolIsError)189 }190191 public var tokensPerSecond: Double? {192 GenerationTiming(timeToFirstToken: timeToFirstToken, totalTime: totalTime).tokensPerSecond(outputTokens: usage?.outputTokens, reasoningTokens: usage?.reasoningTokens)193 }194}195196/// Everything known when a generation ends, successfully or not.197public struct MessageCompletion: Sendable, Hashable {198 public var text: String199 public var reasoningSummary: String200 public var toolCalls: [ToolCall]201 public var status: MessageStatus202 public var error: AstraError?203 public var reportedModel: String?204 public var servedBy: String?205 public var usage: TokenUsage?206 public var stopReason: StopReason?207 public var cost: CostEstimate?208 public var timeToFirstToken: TimeInterval?209 public var totalTime: TimeInterval?210211 public init(text: String, reasoningSummary: String = "", toolCalls: [ToolCall] = [], status: MessageStatus = .complete,212 error: AstraError? = nil, reportedModel: String? = nil, servedBy: String? = nil, usage: TokenUsage? = nil,213 stopReason: StopReason? = .endOfTurn, cost: CostEstimate? = nil, timeToFirstToken: TimeInterval? = nil, totalTime: TimeInterval? = nil) {214 self.text = text; self.reasoningSummary = reasoningSummary; self.toolCalls = toolCalls; self.status = status; self.error = error215 self.reportedModel = reportedModel; self.servedBy = servedBy; self.usage = usage; self.stopReason = stopReason; self.cost = cost216 self.timeToFirstToken = timeToFirstToken; self.totalTime = totalTime217 }218219 /// Maps an orchestrator outcome: a cancelled generation is `stopped`, any other error is `failed`.220 public init(outcome: GenerationOutcome, cost: CostEstimate? = nil) {221 let status: MessageStatus = switch outcome.error {222 case nil: .complete223 case .cancelled?: .stopped224 default: .failed225 }226 self.init(text: outcome.text, reasoningSummary: outcome.reasoningSummary, toolCalls: outcome.toolCalls, status: status,227 error: outcome.error, reportedModel: outcome.start.reportedModel, servedBy: outcome.start.servedBy, usage: outcome.usage,228 stopReason: outcome.stopReason, cost: cost, timeToFirstToken: outcome.timing.timeToFirstToken, totalTime: outcome.timing.totalTime)229 }230}231232// MARK: - Attachments233234public enum AttachmentKind: String, Sendable, Codable, Hashable, CaseIterable { case image, pdf, text, file }235236public struct AttachmentRecord: AstraRecord {237 public static let databaseTableName = "attachment"238 public var id: String239 public var messageID: String240 public var kind: AttachmentKind241 /// Display name only. It is never used to build a path: the bytes live in a file named after `sha256`.242 public var filename: String243 public var mimeType: String244 public var byteSize: Int245 public var sha256: String246 /// Text extracted from a document, sent to models that cannot read the file itself.247 public var extractedText: String?248 public var createdAt: Date249}250251/// A file about to be attached to a message.252public struct AttachmentDraft: Sendable, Hashable {253 public var kind: AttachmentKind254 public var filename: String255 public var mimeType: String256 public var data: Data257 public var extractedText: String?258 public init(kind: AttachmentKind, filename: String, mimeType: String, data: Data, extractedText: String? = nil) {259 self.kind = kind; self.filename = filename; self.mimeType = mimeType; self.data = data; self.extractedText = extractedText260 }261}262263// MARK: - Arena264265public enum ArenaEntryStatus: String, Sendable, Codable, Hashable { case pending, streaming, complete, stopped, failed }266267public struct ArenaSessionRecord: AstraRecord {268 public static let databaseTableName = "arenaSession"269 public var id: String270 public var title: String271 public var prompt: String272 public var system: String273 public var parameters: GenerationParameters274 /// Blind sessions hide model names until the person picks a winner; entries are shown in `revealOrder`.275 public var blind: Bool276 public var createdAt: Date277 public var templateID: String?278}279280public struct ArenaEntryRecord: AstraRecord {281 public static let databaseTableName = "arenaEntry"282 public var id: String283 public var sessionID: String284 /// Order in which the competitors were chosen.285 public var ordinal: Int286 public var model: ModelRef287 public var reportedModel: String?288 public var servedBy: String?289 public var text: String290 public var status: ArenaEntryStatus291 public var usage: TokenUsage?292 public var timeToFirstToken: TimeInterval?293 public var totalTime: TimeInterval?294 public var tokensPerSecond: Double?295 public var cost: CostEstimate?296 public var error: AstraError?297 public var stopReason: StopReason?298 public var isWinner: Bool299 /// Display position: shuffled for blind sessions, equal to `ordinal` otherwise.300 public var revealOrder: Int301 public var createdAt: Date302303 /// "Model A", "Model B"... by display position.304 public var blindLabel: String {305 let letters = Array("ABCDEFGHIJKLMNOPQRSTUVWXYZ")306 return "Model " + (revealOrder < letters.count ? String(letters[max(0, revealOrder)]) : String(revealOrder + 1))307 }308}309310public enum ExportFormat: String, Sendable, Codable, Hashable, CaseIterable {311 case json, csv, markdown312 public var fileExtension: String { self == .markdown ? "md" : rawValue }313}314315// MARK: - Agents316317public enum AgentMemoryPolicy: String, Sendable, Codable, Hashable, CaseIterable { case none, readOnly, readWrite }318319public struct AgentProfileRecord: AstraRecord {320 public static let databaseTableName = "agentProfile"321 public var id: String322 public var name: String323 public var instructions: String324 public var model: ModelRef325 public var allowedTools: [String]326 public var maxSteps: Int327 public var maxToolCalls: Int328 public var maxOutputTokens: Int329 public var maxCostUSD: Double?330 public var memoryPolicy: AgentMemoryPolicy331 public var createdAt: Date332 public var updatedAt: Date333334 public init(id: String = UUID().uuidString, name: String, instructions: String = "", model: ModelRef, allowedTools: [String] = [],335 maxSteps: Int = 12, maxToolCalls: Int = 24, maxOutputTokens: Int = 8_000, maxCostUSD: Double? = nil,336 memoryPolicy: AgentMemoryPolicy = .none, createdAt: Date = Date(), updatedAt: Date? = nil) {337 self.id = id; self.name = name; self.instructions = instructions; self.model = model; self.allowedTools = allowedTools338 self.maxSteps = maxSteps; self.maxToolCalls = maxToolCalls; self.maxOutputTokens = maxOutputTokens; self.maxCostUSD = maxCostUSD339 self.memoryPolicy = memoryPolicy; self.createdAt = createdAt; self.updatedAt = updatedAt ?? createdAt340 }341}342343public enum AgentRunStatus: String, Sendable, Codable, Hashable, CaseIterable {344 case running, awaitingApproval, completed, failed, cancelled, budgetExceeded345 public var isFinished: Bool { self != .running && self != .awaitingApproval }346}347348public struct AgentRunRecord: AstraRecord {349 public static let databaseTableName = "agentRun"350 public var id: String351 /// Nil once the profile has been deleted; `profileName` keeps the audit trail readable.352 public var profileID: String?353 public var profileName: String354 public var model: ModelRef?355 public var goal: String356 public var status: AgentRunStatus357 public var startedAt: Date358 public var finishedAt: Date?359 public var stepCount: Int360 public var toolCallCount: Int361 public var usage: TokenUsage362 public var costUSD: Double?363 public var result: String?364 public var error: String?365}366367public enum AgentStepKind: String, Sendable, Codable, Hashable, CaseIterable {368 case plan, modelMessage, toolCall, toolResult, approvalRequest, approvalDecision, memoryRead, memoryWrite, note, error, final369}370371public enum ApprovalDecision: String, Sendable, Codable, Hashable, CaseIterable { case approved, denied, autoApproved, expired }372373/// One audit event of an agent run. Every text field was passed through `Redactor.redact` before being stored.374public struct AgentStepRecord: AstraRecord {375 public static let databaseTableName = "agentStep"376 public var id: String377 public var runID: String378 public var ordinal: Int379 public var kind: AgentStepKind380 public var toolName: String?381 public var text: String382 /// Redacted JSON text of the tool arguments.383 public var inputJSON: String?384 /// Redacted JSON text of the tool result.385 public var outputJSON: String?386 public var approval: ApprovalDecision?387 public var createdAt: Date388 public var finishedAt: Date?389 public var usage: TokenUsage?390 public var costUSD: Double?391392 public var input: JSONValue? { inputJSON.flatMap { JSONValue.parse($0) } }393 public var output: JSONValue? { outputJSON.flatMap { JSONValue.parse($0) } }394}395396public struct AgentStepDraft: Sendable, Hashable {397 public var kind: AgentStepKind398 public var toolName: String?399 public var text: String400 public var input: JSONValue?401 public var output: JSONValue?402 public var approval: ApprovalDecision?403 public var usage: TokenUsage?404 public var costUSD: Double?405 public var createdAt: Date406 public var finishedAt: Date?407 public init(kind: AgentStepKind, toolName: String? = nil, text: String = "", input: JSONValue? = nil, output: JSONValue? = nil,408 approval: ApprovalDecision? = nil, usage: TokenUsage? = nil, costUSD: Double? = nil, createdAt: Date = Date(), finishedAt: Date? = nil) {409 self.kind = kind; self.toolName = toolName; self.text = text; self.input = input; self.output = output; self.approval = approval410 self.usage = usage; self.costUSD = costUSD; self.createdAt = createdAt; self.finishedAt = finishedAt411 }412}413414// MARK: - Prompt studio415416public struct PromptTemplateRecord: AstraRecord {417 public static let databaseTableName = "promptTemplate"418 public var id: String419 public var name: String420 public var system: String421 /// User message with `{{variable}}` placeholders.422 public var userTemplate: String423 public var parameters: GenerationParameters424 public var currentVersion: Int425 public var createdAt: Date426 public var updatedAt: Date427428 public var variables: [String] { PromptRenderer.variables(in: system + "\n" + userTemplate) }429}430431public struct PromptTemplateVersionRecord: AstraRecord {432 public static let databaseTableName = "promptTemplateVersion"433 public var id: String434 public var templateID: String435 public var version: Int436 public var name: String437 public var system: String438 public var userTemplate: String439 public var parameters: GenerationParameters440 public var note: String?441 public var createdAt: Date442}443444/// A reusable system instruction with parameters, applied to conversations.445public struct PresetRecord: AstraRecord {446 public static let databaseTableName = "preset"447 public var id: String448 public var name: String449 public var system: String450 public var parameters: GenerationParameters451 public var createdAt: Date452 public var updatedAt: Date453 public init(id: String = UUID().uuidString, name: String, system: String = "", parameters: GenerationParameters = .default,454 createdAt: Date = Date(), updatedAt: Date? = nil) {455 self.id = id; self.name = name; self.system = system; self.parameters = parameters; self.createdAt = createdAt456 self.updatedAt = updatedAt ?? createdAt457 }458}459460// MARK: - Usage461462public enum UsageOrigin: String, Sendable, Codable, Hashable, CaseIterable { case conversation, arena, agent, promptStudio, benchmark, other }463464/// One finished generation. Rows outlive the conversation, arena session or agent run they came from.465public struct UsageRecord: AstraRecord {466 public static let databaseTableName = "usage"467 public var id: String468 public var date: Date469 public var provider: ProviderKind470 public var modelID: String471 public var endpointID: String?472 public var inputTokens: Int473 public var outputTokens: Int474 public var cachedInputTokens: Int475 public var reasoningTokens: Int476 /// Nil when the cost is unknown; never guessed.477 public var costUSD: Double?478 public var costBasis: CostEstimate.Basis479 public var origin: UsageOrigin480 public var originID: String?481482 public init(id: String = UUID().uuidString, date: Date = Date(), model: ModelRef, usage: TokenUsage?, cost: CostEstimate?,483 origin: UsageOrigin, originID: String? = nil) {484 self.id = id; self.date = date; provider = model.provider; modelID = model.modelID; endpointID = model.endpointID485 inputTokens = usage?.inputTokens ?? 0; outputTokens = usage?.outputTokens ?? 0; cachedInputTokens = usage?.cachedInputTokens ?? 0486 reasoningTokens = usage?.reasoningTokens ?? 0; costUSD = cost?.amountUSD; costBasis = cost?.basis ?? .unavailable487 self.origin = origin; self.originID = originID488 }489}490491public enum UsageGrouping: Sendable, Hashable { case day, provider, model, origin }492493/// A sum over ledger rows. `key` is `yyyy-MM-dd` for days, the provider raw value, `provider|model`, or the origin raw value.494public struct UsageAggregate: Sendable, Codable, Hashable, Identifiable {495 public var key: String496 public var label: String497 public var requests: Int498 public var inputTokens: Int499 public var outputTokens: Int500 public var cachedInputTokens: Int501 public var reasoningTokens: Int502 /// Sum of the known costs; `unpricedRequests` counts the rows that had none.503 public var costUSD: Double504 public var unpricedRequests: Int505 public var id: String { key }506 public var totalTokens: Int { inputTokens + outputTokens }507}508509// MARK: - Memory510511public struct MemoryRecord: AstraRecord {512 public static let databaseTableName = "memory"513 public var id: String514 public var text: String515 public var createdAt: Date516 public var updatedAt: Date517 public var enabled: Bool518 public var sourceConversationID: String?519}520521// MARK: - Documents522523public struct DocumentRecord: AstraRecord {524 public static let databaseTableName = "document"525 public var id: String526 public var name: String527 /// Free-form kind such as `pdf`, `text`, `markdown`, `web`.528 public var kind: String529 public var byteSize: Int530 public var sha256: String531 public var createdAt: Date532}533534public struct ChunkRecord: Sendable, Codable, Hashable, Identifiable {535 public var id: String536 public var documentID: String537 public var ordinal: Int538 public var text: String539 public var embedding: [Float]?540}541542public struct ChunkDraft: Sendable, Hashable {543 public var text: String544 public var embedding: [Float]?545 public init(text: String, embedding: [Float]? = nil) { self.text = text; self.embedding = embedding }546}547548public struct ChunkHit: Sendable, Hashable, Identifiable {549 public var chunk: ChunkRecord550 public var documentName: String551 /// BM25 relevance, higher is better (0 for substring fallback matches).552 public var score: Double553 public var id: String { chunk.id }554}555556// MARK: - Benchmarks557558public struct BenchmarkRecord: AstraRecord {559 public static let databaseTableName = "benchmark"560 public var id: String561 public var model: ModelRef562 public var deviceModel: String563 public var osVersion: String564 public var modelRevision: String?565 public var isColdStart: Bool566 public var timeToFirstToken: TimeInterval?567 public var tokensPerSecond: Double?568 public var promptTokens: Int?569 public var outputTokens: Int?570 public var peakMemoryBytes: Int?571 public var thermalState: String572 public var createdAt: Date573 public var notes: String574575 public init(id: String = UUID().uuidString, model: ModelRef, deviceModel: String, osVersion: String, modelRevision: String? = nil,576 isColdStart: Bool, timeToFirstToken: TimeInterval? = nil, tokensPerSecond: Double? = nil, promptTokens: Int? = nil,577 outputTokens: Int? = nil, peakMemoryBytes: Int? = nil, thermalState: String = "nominal", createdAt: Date = Date(), notes: String = "") {578 self.id = id; self.model = model; self.deviceModel = deviceModel; self.osVersion = osVersion; self.modelRevision = modelRevision579 self.isColdStart = isColdStart; self.timeToFirstToken = timeToFirstToken; self.tokensPerSecond = tokensPerSecond580 self.promptTokens = promptTokens; self.outputTokens = outputTokens; self.peakMemoryBytes = peakMemoryBytes581 self.thermalState = thermalState; self.createdAt = createdAt; self.notes = notes582 }583}584585// MARK: - Storage and deletion586587public struct StorageUsage: Sendable, Codable, Hashable {588 /// Bytes of the database file in use (free pages excluded), write-ahead log not counted.589 public var databaseBytes: Int64590 public var attachmentBytes: Int64591 public var attachmentFileCount: Int592 public var totalBytes: Int64 { databaseBytes + attachmentBytes }593}594595public struct DeletionResult: Sendable, Codable, Hashable {596 public var rowsDeleted: Int597 /// Database pages released plus attachment files removed. Database space is reusable at once; the file itself shrinks on `compact()`.598 public var bytesFreed: Int64599}600