Repository Public
1// Author: Simon-Pierre Boucher — contact@spboucher.ai2// File: Packages/LocalChatKnowledge/Sources/KnowledgeEngine.swift3// Description: Search entry point for chat and agents: embeds the query with each collection's own model and runs hybrid retrieval, falling back to keywords when no embedder is available.4import Foundation5import LocalChatCore6import Synchronization78public enum KnowledgeSearchMode: String, Sendable {9 case none // nothing was searched yet, or no collection was given10 case hybrid // vectors + keywords11 case vectorOnly // the query has no searchable word12 case keywordOnly // no embedder could be used: BM25 only13}1415public final class KnowledgeEngine: KnowledgeSearching {16 public typealias ProviderResolver = @Sendable (String) async -> (any EmbeddingProvider)?17 public let store: KnowledgeStore18 private let resolver: ProviderResolver19 private let allowRemoteProcessing: Bool20 private let mmrLambda: Double?21 private struct State { var mode: KnowledgeSearchMode = .none; var notes: [String] = [] }22 private let state = Mutex(State())2324 /// - Parameters:25 /// - providerResolver: returns the embedding provider for a collection's `embedderID`, or nil when it is not available (model not downloaded…).26 /// - allowRemoteProcessing: a remote embedder would receive the query text; it is only used when this is true.27 /// - mmrLambda: 0…1 to diversify results (1 = relevance only), nil to disable.28 public init(store: KnowledgeStore, allowRemoteProcessing: Bool = false, mmrLambda: Double? = 0.7, providerResolver: @escaping ProviderResolver) {29 self.store = store; self.allowRemoteProcessing = allowRemoteProcessing; self.mmrLambda = mmrLambda; resolver = providerResolver30 }3132 /// How the last search was actually run.33 public var lastSearchMode: KnowledgeSearchMode { state.withLock { $0.mode } }34 /// Why some collections were searched without vectors in the last search.35 public var lastSearchNotes: [String] { state.withLock { $0.notes } }3637 public func search(_ query: String, collections: [UUID], limit: Int) async throws -> [KnowledgeHit] {38 let text = query.trimmingCharacters(in: .whitespacesAndNewlines)39 guard !text.isEmpty, !collections.isEmpty, limit > 0 else { state.withLock { $0 = State() }; return [] }40 var vectors: [UUID: [Float]] = [:]; var notes: [String] = []; var cache: [String: [Float]?] = [:]41 for id in collections {42 guard let collection = try store.collection(id) else { continue }43 if let known = cache[collection.embedderID] { if let known { vectors[id] = known }; continue }44 var vector: [Float]?45 if let provider = await resolver(collection.embedderID) {46 if provider.isRemote && !allowRemoteProcessing { notes.append("“\(collection.name)”: the embedding model is remote and remote processing is off.") }47 else if provider.dimension != collection.dimension { notes.append("“\(collection.name)”: the embedding model changed; re-index the collection.") }48 else {49 do { vector = try await provider.embed([text]).first.flatMap { $0.count == collection.dimension ? $0 : nil } }50 catch { notes.append("“\(collection.name)”: \((error as? LocalizedError)?.errorDescription ?? String(describing: error))") }51 }52 } else { notes.append("“\(collection.name)”: the embedding model “\(collection.embedderID)” is not available.") }53 cache[collection.embedderID] = .some(vector)54 if let vector { vectors[id] = vector }55 }56 let result = try store.search(text: text, queryVectors: vectors, collections: collections, limit: limit, mmrLambda: mmrLambda)57 let mode: KnowledgeSearchMode = result.usedVectors ? (KnowledgeStore.ftsQuery(text) == nil ? .vectorOnly : .hybrid) : .keywordOnly58 state.withLock { $0 = State(mode: mode, notes: notes) }59 return result.hits60 }61}62