Repository Public
1// Author: Simon-Pierre Boucher — contact@spboucher.ai2// File: Packages/LocalChatCore/Sources/ContextAssembler.swift3// Description: Smart Context Engine: builds the prompt for a turn inside a token budget (system prompt, summary, retrieved sources, recent turns) and reports what was used.4import Foundation56public struct ContextSegment: Sendable, Hashable, Identifiable {7 public enum Kind: String, Sendable { case system, summary, knowledge, history, attachments, reservedOutput, free }8 public var kind: Kind9 public var tokens: Int10 public var id: String { kind.rawValue }11 public init(kind: Kind, tokens: Int) { self.kind = kind; self.tokens = tokens }12}1314public struct AssembledContext: Sendable {15 public var messages: [PromptMessage]16 public var segments: [ContextSegment] // for the context-window visualization17 public var contextLength: Int18 public var includedMessageIDs: [UUID]19 public var droppedMessageIDs: [UUID] // on the active branch but outside the window20 public var tokensAreExact: Bool // false when counts come from the character estimate21 public var usedTokens: Int { segments.filter { $0.kind != .free && $0.kind != .reservedOutput }.reduce(0) { $0 + $1.tokens } }22 public var needsCompaction: Bool { !droppedMessageIDs.isEmpty }23}2425public struct ContextAssembler: Sendable {26 public typealias Counter = @Sendable (String) async -> Int?27 public init() {}2829 static let perMessageOverhead = 6 // role markers of chat templates3031 public func assemble(conversation: Conversation, branch: [ChatMessage], knowledge: [KnowledgeHit] = [],32 attachmentData: @Sendable (Attachment) -> Data? = { _ in nil }, supportsVision: Bool = false,33 extraSystem: String? = nil, counter: Counter) async -> AssembledContext {34 var exact = true35 func count(_ text: String) async -> Int {36 if text.isEmpty { return 0 }37 if let n = await counter(text) { return n }38 exact = false; return TokenEstimator.estimate(text)39 }4041 let window = max(512, conversation.settings.contextLength)42 let reserve = min(conversation.settings.maxTokens, max(256, window / 2))43 var budget = window - reserve4445 // 1. system prompt (always kept)46 var system = conversation.systemPrompt.trimmingCharacters(in: .whitespacesAndNewlines)47 if let extraSystem, !extraSystem.isEmpty { system = system.isEmpty ? extraSystem : system + "\n\n" + extraSystem }48 let systemTokens = system.isEmpty ? 0 : await count(system) + Self.perMessageOverhead49 budget -= systemTokens5051 // 2. retrieved sources (kept, trimmed to a third of the window)52 var knowledgeText = ""; var knowledgeTokens = 053 if !knowledge.isEmpty {54 let cap = window / 3; var block = "Use the following sources when they are relevant. Cite them as [n].\n"55 for (i, hit) in knowledge.enumerated() {56 let entry = "\n[\(i + 1)] \(hit.document.name)\(hit.page.map { ", p. \($0)" } ?? "")\n\(hit.text)\n"57 let t = await count(block + entry)58 if t > cap { break }59 block += entry; knowledgeTokens = t60 }61 if knowledgeTokens > 0 { knowledgeText = block; knowledgeTokens += Self.perMessageOverhead; budget -= knowledgeTokens }62 }6364 // 3. summary of older turns, when one exists and still matches this branch65 var summaryTokens = 0; var summaryText = ""; var startIndex = 066 let turns = branch.filter { $0.role != .system }67 if let summary = conversation.summary, let cut = turns.firstIndex(where: { $0.id == summary.coversThroughMessageID }) {68 summaryText = "Summary of the earlier conversation:\n" + summary.text69 summaryTokens = await count(summaryText) + Self.perMessageOverhead70 if summaryTokens < budget / 2 { budget -= summaryTokens; startIndex = cut + 1 } else { summaryTokens = 0; summaryText = "" }71 }7273 // 4. recent turns, newest first, until the budget is exhausted (the last user turn is always kept)74 var kept: [(ChatMessage, PromptMessage, Int)] = []; var historyTokens = 0; var attachmentTokens = 075 var dropped: [UUID] = turns.prefix(startIndex).filter { _ in summaryText.isEmpty }.map(\.id)76 var open = true77 for (offset, message) in turns[startIndex...].enumerated().reversed() {78 let index = startIndex + offset79 if message.status == .failed || (message.role == .assistant && message.content.isEmpty && message.toolCalls.isEmpty) { continue }80 var content = message.content; var images: [ImageInput] = []; var extra = 081 for a in message.attachments {82 switch a.kind {83 case .document, .audio:84 if let text = a.extractedText, !text.isEmpty {85 let block = "\n\n<attachment name=\"\(a.fileName)\">\n\(text)\n</attachment>"86 content += block; extra += await count(block)87 }88 case .image:89 if supportsVision, let data = attachmentData(a) { images.append(ImageInput(data: data, mimeType: a.mimeType)); extra += 280 }90 else { content += "\n\n[Image attached: \(a.fileName) — the current model cannot see images]" }91 }92 }93 let role: PromptMessage.Role = switch message.role { case .user: .user; case .assistant: .assistant; case .tool: .tool; case .system: .system }94 let prompt = PromptMessage(role: role, content: content, images: images, toolCalls: message.toolCalls,95 toolCallID: message.toolResult?.callID, toolName: message.toolResult?.name)96 let tokens = await count(content) + Self.perMessageOverhead + (images.isEmpty ? 0 : 280 * images.count)97 let isLast = index == turns.count - 198 if open && (tokens <= budget || isLast) {99 budget -= tokens; historyTokens += tokens - extra; attachmentTokens += extra100 kept.append((message, prompt, tokens))101 } else { open = false; dropped.append(message.id) }102 }103 kept.reverse()104 // a window must not start with an orphan tool result or assistant turn105 while let first = kept.first, first.0.role == .tool || (first.0.role == .assistant && kept.count > 1) {106 dropped.append(first.0.id); historyTokens -= first.2; kept.removeFirst()107 }108109 var messages: [PromptMessage] = []110 if !system.isEmpty { messages.append(.system(system)) }111 var preface: [String] = []112 if !summaryText.isEmpty { preface.append(summaryText) }113 if !knowledgeText.isEmpty { preface.append(knowledgeText) }114 if !preface.isEmpty {115 // one system turn only: many chat templates reject a second one116 if messages.isEmpty { messages.append(.system(preface.joined(separator: "\n\n"))) }117 else { messages[0].content += "\n\n" + preface.joined(separator: "\n\n") }118 }119 messages.append(contentsOf: kept.map(\.1))120121 let used = systemTokens + summaryTokens + knowledgeTokens + max(0, historyTokens) + attachmentTokens122 let segments = [123 ContextSegment(kind: .system, tokens: systemTokens), ContextSegment(kind: .summary, tokens: summaryTokens),124 ContextSegment(kind: .knowledge, tokens: knowledgeTokens), ContextSegment(kind: .history, tokens: max(0, historyTokens)),125 ContextSegment(kind: .attachments, tokens: attachmentTokens), ContextSegment(kind: .reservedOutput, tokens: reserve),126 ContextSegment(kind: .free, tokens: max(0, window - reserve - used)),127 ]128 return AssembledContext(messages: messages, segments: segments, contextLength: window, includedMessageIDs: kept.map(\.0.id),129 droppedMessageIDs: dropped, tokensAreExact: exact)130 }131132 /// The turns a new summary should fold in: everything on the branch that no longer fits, plus what the previous summary covered.133 public func compactionInput(conversation: Conversation, branch: [ChatMessage], dropped: [UUID]) -> (text: String, lastID: UUID, count: Int)? {134 let turns = branch.filter { $0.role == .user || $0.role == .assistant }135 guard let lastDropped = turns.last(where: { dropped.contains($0.id) }), let end = turns.firstIndex(where: { $0.id == lastDropped.id }) else { return nil }136 var start = 0; var text = ""137 if let s = conversation.summary, let cut = turns.firstIndex(where: { $0.id == s.coversThroughMessageID }), cut < end {138 start = cut + 1; text = "Previous summary:\n\(s.text)\n\nNew turns:\n"139 }140 for m in turns[start...end] { text += "\(m.role == .user ? "User" : "Assistant"): \(m.content)\n\n" }141 return (text, lastDropped.id, end + 1)142 }143144 public static let summarizationInstruction = """145 You compress conversations. Write a faithful summary of the conversation below in at most 250 words. Keep names, numbers, decisions, \146 constraints, code identifiers and open questions. Do not add anything that is not in the conversation. Write in the conversation's language.147 """148}149