SPB Git

Repository Public MIT

Records.swift 26.1 KB 600 lines swift

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

Theme