Repository Public
1// SP Notes iOS2// File: Features/AI/AssistantModels.swift3// Description: The two state machines of the assistant: an action on a text (streamed result, stop, confirmation of an expensive4// request, regenerate) and a conversation about the notes (streamed answers with sources). Neither writes to a note:5// the sheet inserts the result only when the user chooses to.6//7// Author: Simon-Pierre Boucher8// Contact: contact@spboucher.ai9import Foundation10import Observation11import SPNotesCore1213/// Checked before every request: nil when the assistant can be reached, otherwise why not (offline, session ended).14typealias AssistantAvailability = @MainActor () -> AssistantFailure?1516// MARK: - Action on a text1718@MainActor19@Observable20final class AssistantActionModel {21 enum Phase: Equatable {22 case idle23 case streaming24 /// The server announced an expensive request; nothing was sent to a provider yet.25 case awaitingConfirmation(String)26 case finished(stopped: Bool)27 case failed(AssistantFailure)28 }2930 struct Invocation: Equatable {31 var action: AIActionKind32 var language: String?33 var instruction: String?34 }3536 /// The text the action works on: the selection, or the whole note.37 let sourceText: String38 let hasSelection: Bool3940 private(set) var phase: Phase = .idle41 /// The complete answer received so far (Markdown).42 private(set) var text = ""43 /// The answer as shown: refreshed at most a few times per second while streaming, so rendering keeps up with long answers.44 private(set) var renderedText = ""45 private(set) var modelLine: String?46 private(set) var invocation: Invocation?4748 @ObservationIgnored private let provider: any AssistantProvider49 @ObservationIgnored private let availability: AssistantAvailability50 @ObservationIgnored private var task: Task<Void, Never>?51 @ObservationIgnored private var generation = 052 @ObservationIgnored private var lastRender = Date.distantPast53 @ObservationIgnored var renderInterval: TimeInterval = 0.125455 init(sourceText: String, hasSelection: Bool, provider: any AssistantProvider, availability: @escaping AssistantAvailability = { nil }) {56 self.sourceText = sourceText57 self.hasSelection = hasSelection58 self.provider = provider59 self.availability = availability60 }6162 var isStreaming: Bool { phase == .streaming }63 var hasResult: Bool { !text.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty }64 /// True once a result can be inserted: the stream ended (or was stopped) with some text.65 var canInsert: Bool { if case .finished = phase { return hasResult } else { return false } }6667 /// Starts an action. Any running request is cancelled; the previous result is discarded.68 func run(_ invocation: Invocation, confirmExpensive: Bool = false) {69 task?.cancel()70 generation += 171 let current = generation72 self.invocation = invocation73 text = ""; renderedText = ""; modelLine = nil74 let source = sourceText75 if source.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty && invocation.action != .custom { phase = .failed(AssistantFailure(.emptyText)); return }76 if source.count > AssistantText.maxActionCharacters { phase = .failed(AssistantFailure(.tooLong)); return }77 if let failure = availability() { phase = .failed(failure); return }78 phase = .streaming79 let request = AIActionRequest(action: invocation.action, text: source, instruction: invocation.instruction, language: invocation.language,80 confirmExpensive: confirmExpensive ? true : nil)81 let provider = provider82 task = Task { [weak self] in83 do {84 let stream = try await provider.events(for: .action(request))85 for try await event in stream {86 guard let self, self.generation == current, !Task.isCancelled else { return }87 self.handle(event)88 if self.phase != .streaming { return }89 }90 guard let self, self.generation == current, !Task.isCancelled else { return }91 self.finish(stopped: false)92 } catch {93 guard let self, self.generation == current, !Task.isCancelled else { return }94 self.fail(error)95 }96 }97 }9899 private func handle(_ event: AIEvent) {100 switch event {101 case .meta(let meta): modelLine = AssistantText.modelLine(meta)102 case .text(let delta):103 text += delta104 if Date().timeIntervalSince(lastRender) >= renderInterval { renderedText = text; lastRender = Date() }105 case .done: finish(stopped: false)106 case .error(let error): renderedText = text; phase = .failed(.from(error))107 case .needsConfirmation(let confirmation):108 phase = .awaitingConfirmation(AssistantCostPlan.message(plan: confirmation.plan, fallback: confirmation.reason))109 case .other: break110 }111 }112113 private func finish(stopped: Bool) {114 renderedText = text115 if phase == .streaming { phase = .finished(stopped: stopped) }116 }117118 private func fail(_ error: Error) {119 renderedText = text120 if case .confirmExpensive(let plan, let message)? = error as? APIError {121 phase = .awaitingConfirmation(AssistantCostPlan.message(plan: plan, fallback: message))122 } else if (error as? APIError)?.isCancelled == true || error is CancellationError {123 finish(stopped: true)124 } else {125 phase = .failed(.from(error))126 }127 }128129 /// Stops the stream; what was received stays and can be inserted.130 func stop() {131 guard phase == .streaming else { return }132 generation += 1133 task?.cancel()134 task = nil135 finish(stopped: true)136 }137138 /// Runs the same action again (after a result, an error or a stop).139 func regenerate() {140 guard let invocation else { return }141 run(invocation)142 }143144 /// The user accepted the cost announced by the server.145 func confirmExpensive() {146 guard case .awaitingConfirmation = phase, let invocation else { return }147 run(invocation, confirmExpensive: true)148 }149150 /// Back to the list of actions; a running request is cancelled.151 func reset() {152 generation += 1153 task?.cancel()154 task = nil155 invocation = nil156 text = ""; renderedText = ""; modelLine = nil157 phase = .idle158 }159160 /// For tests: waits until the running request has ended.161 func settle() async { await task?.value }162}163164// MARK: - Questions about the notes165166struct AssistantSource: Identifiable, Hashable, Decodable {167 var n: Int?168 var pageId: String?169 var title: String?170 var heading: String?171 var excerpt: String?172 /// 2.0: the block that best supports the citation (the note opens at it); nil when the anchor is not a block.173 var blockId: String?174 var id: String { "\(n ?? 0)-\(pageId ?? "")-\(blockId ?? heading ?? "")" }175176 private struct Envelope: Decodable { var sources: [AssistantSource]? }177178 /// The `sources` list carried by a `meta` or `done` event (empty when there is none).179 static func list(in raw: RawJSON) -> [AssistantSource] {180 ((try? raw.decode(Envelope.self))?.sources ?? []).filter { $0.pageId != nil }181 }182183 /// One row per passage: sources of the same note stay separate when their blocks differ (each opens the note at its block);184 /// only exact repeats (same note, same block — or same note without any block) are merged.185 static func uniqueAnchors(_ sources: [AssistantSource]) -> [AssistantSource] {186 var seen = Set<String>()187 return sources.filter { source in188 guard let id = source.pageId else { return false }189 return seen.insert(id + "#" + (source.blockId ?? "")).inserted190 }191 }192193 /// One row per note: several passages of the same note are merged.194 static func uniquePages(_ sources: [AssistantSource]) -> [AssistantSource] {195 var seen = Set<String>()196 return sources.filter { source in197 guard let id = source.pageId else { return false }198 return seen.insert(id).inserted199 }200 }201}202203struct AssistantChatMessage: Identifiable, Equatable {204 enum Role: Equatable { case user, assistant }205 enum State: Equatable { case streaming, done, stopped, awaitingConfirmation(String), failed(AssistantFailure) }206 let id: UUID207 var role: Role208 var text: String209 var state: State = .done210 var sources: [AssistantSource] = []211 var modelLine: String?212}213214struct AssistantChatScope: Identifiable, Hashable {215 var mode: AIChatMode216 var title: String217 var symbol: String218 var needsPage: Bool219 var id: String { mode.rawValue }220221 static var all: [AssistantChatScope] {222 [223 AssistantChatScope(mode: .notes, title: String(localized: "Mes notes"), symbol: "books.vertical", needsPage: false),224 AssistantChatScope(mode: .summarise, title: String(localized: "Résumer cette note"), symbol: "text.redaction", needsPage: true),225 AssistantChatScope(mode: .actions, title: String(localized: "Actions de cette note"), symbol: "checkmark.circle", needsPage: true),226 AssistantChatScope(mode: .general, title: String(localized: "Général"), symbol: "sparkles", needsPage: false),227 ]228 }229230 static func scope(for mode: AIChatMode) -> AssistantChatScope { all.first { $0.mode == mode } ?? all[0] }231}232233@MainActor234@Observable235final class AssistantChatModel {236 var mode: AIChatMode = .notes237 private(set) var messages: [AssistantChatMessage] = []238 private(set) var isStreaming = false239 /// Kept for the life of the sheet only.240 private(set) var conversationId: String?241 /// The identifiers sent so far, one per send (a regenerated or confirmed answer is a new send).242 private(set) var clientIds: [String] = []243244 /// The note the sheet was opened from (modes "summarise" and "actions" work on it).245 let pageId: String?246 /// False while the note has never reached the server: page modes cannot work yet.247 var pageIsOnServer: Bool248249 @ObservationIgnored private let provider: any AssistantProvider250 @ObservationIgnored private let availability: AssistantAvailability251 @ObservationIgnored private var task: Task<Void, Never>?252 @ObservationIgnored private var generation = 0253 @ObservationIgnored private var lastQuestion: (text: String, mode: AIChatMode)?254255 init(pageId: String?, pageIsOnServer: Bool, provider: any AssistantProvider, availability: @escaping AssistantAvailability = { nil }) {256 self.pageId = pageId257 self.pageIsOnServer = pageIsOnServer258 self.provider = provider259 self.availability = availability260 }261262 static func newClientId() -> String { "ios-" + UUID().uuidString.lowercased() }263264 /// Sends a question. The answer streams into a new assistant message.265 func send(_ question: String) {266 let trimmed = question.trimmingCharacters(in: .whitespacesAndNewlines)267 guard !trimmed.isEmpty, !isStreaming else { return }268 messages.append(AssistantChatMessage(id: UUID(), role: .user, text: trimmed))269 lastQuestion = (trimmed, mode)270 start(question: trimmed, mode: mode, confirmExpensive: false)271 }272273 /// Sends the last question again (after an error or a stop). The failed answer is replaced.274 func retry() {275 guard let lastQuestion, !isStreaming else { return }276 if let last = messages.last, last.role == .assistant { messages.removeLast() }277 start(question: lastQuestion.text, mode: lastQuestion.mode, confirmExpensive: false)278 }279280 /// The user accepted the cost announced for the last question.281 func confirmExpensive() {282 guard let lastQuestion, !isStreaming, let last = messages.last, case .awaitingConfirmation = last.state else { return }283 messages.removeLast()284 start(question: lastQuestion.text, mode: lastQuestion.mode, confirmExpensive: true)285 }286287 func stop() {288 guard isStreaming else { return }289 generation += 1290 task?.cancel()291 task = nil292 isStreaming = false293 update { $0.state = .stopped }294 }295296 private func start(question: String, mode: AIChatMode, confirmExpensive: Bool) {297 task?.cancel()298 generation += 1299 let current = generation300 messages.append(AssistantChatMessage(id: UUID(), role: .assistant, text: "", state: .streaming))301 let scope = AssistantChatScope.scope(for: mode)302 if scope.needsPage && (pageId == nil || !pageIsOnServer) { update { $0.state = .failed(AssistantFailure(.pageNotSynced)) }; return }303 if let failure = availability() { update { $0.state = .failed(failure) }; return }304 let clientId = Self.newClientId()305 clientIds.append(clientId)306 let request = AIChatRequest(message: question, conversationId: conversationId, clientId: clientId, mode: mode, pageId: scope.needsPage ? pageId : nil,307 confirmExpensive: confirmExpensive ? true : nil)308 isStreaming = true309 let provider = provider310 task = Task { [weak self] in311 do {312 let stream = try await provider.events(for: .chat(request))313 for try await event in stream {314 guard let self, self.generation == current, !Task.isCancelled else { return }315 self.handle(event)316 if !self.isStreaming { return }317 }318 guard let self, self.generation == current, !Task.isCancelled else { return }319 self.end(.done)320 } catch {321 guard let self, self.generation == current, !Task.isCancelled else { return }322 if case .confirmExpensive(let plan, let message)? = error as? APIError {323 self.end(.awaitingConfirmation(AssistantCostPlan.message(plan: plan, fallback: message)))324 } else {325 self.end(.failed(.from(error)))326 }327 }328 }329 }330331 private func handle(_ event: AIEvent) {332 switch event {333 case .meta(let meta):334 if let id = meta.conversationId { conversationId = id }335 let sources = AssistantSource.list(in: meta.raw)336 update { $0.modelLine = AssistantText.modelLine(meta); if !sources.isEmpty { $0.sources = sources } }337 case .text(let delta):338 update { $0.text += delta }339 case .done(let done):340 // The final text has gone through the server's citation checks; its sources are the ones really cited.341 let sources = AssistantSource.list(in: done.raw)342 update { if let content = done.content, !content.isEmpty { $0.text = content }; if !sources.isEmpty { $0.sources = sources } }343 end(.done)344 case .error(let error): end(.failed(.from(error)))345 case .needsConfirmation(let confirmation):346 end(.awaitingConfirmation(AssistantCostPlan.message(plan: confirmation.plan, fallback: confirmation.reason)))347 case .other: break348 }349 }350351 private func end(_ state: AssistantChatMessage.State) {352 guard isStreaming else { return }353 isStreaming = false354 update { $0.state = state }355 }356357 private func update(_ body: (inout AssistantChatMessage) -> Void) {358 guard let index = messages.indices.last, messages[index].role == .assistant else { return }359 body(&messages[index])360 }361362 /// For tests: waits until the running request has ended.363 func settle() async { await task?.value }364}365