Repository Public
1// Author: Simon-Pierre Boucher — contact@spboucher.ai2// File: Packages/LocalChatKnowledge/Sources/AppleNLEmbeddingProvider.swift3// Description: Zero-download embedding provider backed by the sentence embeddings that ship with the OS (NaturalLanguage), one vector space per language.4import Foundation5import LocalChatCore6import NaturalLanguage7import Synchronization89public enum AppleNLEmbeddingError: LocalizedError, Sendable, Equatable {10 case unavailable(String)11 case noVectors12 public var errorDescription: String? {13 switch self {14 case .unavailable(let language): "This system has no built-in sentence embedding for “\(language)”."15 case .noVectors: "The built-in embedding returned no vector for this text."16 }17 }18}1920/// Each language has its own model, so its vectors are only comparable with vectors of the same language: the language is part of `identifier`.21public final class AppleNLEmbeddingProvider: EmbeddingProvider {22 public let language: NLLanguage23 public let identifier: String24 public let dimension: Int25 public let isRemote = false26 private struct Box: @unchecked Sendable { let embedding: NLEmbedding } // only touched under the mutex27 private let box: Mutex<Box>2829 public static let candidateLanguages: [NLLanguage] = [.english, .french, .spanish, .german, .italian, .portuguese, .simplifiedChinese, .japanese, .dutch, .russian]3031 /// Nil when the OS has no sentence embedding for the language.32 public init?(language: NLLanguage = .english) {33 guard let embedding = NLEmbedding.sentenceEmbedding(for: language), embedding.dimension > 0 else { return nil }34 self.language = language; identifier = "apple.nl.sentence.\(language.rawValue)"; dimension = embedding.dimension35 box = Mutex(Box(embedding: embedding))36 }3738 /// Recreates the provider a collection was indexed with (`identifier` → language).39 public convenience init?(identifier: String) {40 let prefix = "apple.nl.sentence."41 guard identifier.hasPrefix(prefix) else { return nil }42 self.init(language: NLLanguage(rawValue: String(identifier.dropFirst(prefix.count))))43 }4445 /// Languages for which the OS provides a sentence embedding right now.46 public static func availableLanguages() -> [NLLanguage] { candidateLanguages.filter { NLEmbedding.sentenceEmbedding(for: $0) != nil } }4748 public static func dominantLanguage(of sample: String) -> NLLanguage? {49 let recognizer = NLLanguageRecognizer(); recognizer.processString(String(sample.prefix(4000)))50 return recognizer.dominantLanguage51 }5253 /// The provider for the dominant language of `sample`, else for `fallback`, else nil.54 public static func best(forSample sample: String, fallback: NLLanguage = .english) -> AppleNLEmbeddingProvider? {55 if let detected = dominantLanguage(of: sample), let provider = AppleNLEmbeddingProvider(language: detected) { return provider }56 return AppleNLEmbeddingProvider(language: fallback)57 }5859 public func embed(_ texts: [String]) async throws -> [[Float]] {60 guard !texts.isEmpty else { return [] }61 let dimension = dimension62 let (vectors, produced): ([[Float]], Int) = box.withLock { box in63 var produced = 064 let out = texts.map { text -> [Float] in65 // the model is trained on sentences: long chunks are averaged over their beginning66 let trimmed = String(text.trimmingCharacters(in: .whitespacesAndNewlines).prefix(2000))67 if !trimmed.isEmpty, let v = box.embedding.vector(for: trimmed), v.count == dimension { produced += 1; return v.map(Float.init) }68 return [Float](repeating: 0, count: dimension) // scores 0 against every query69 }70 return (out, produced)71 }72 guard produced > 0 else { throw AppleNLEmbeddingError.noVectors }73 return vectors74 }75}76