SPB Git

Repository Public

SearchRepository.swift 7.3 KB 138 lines swift

1// SP Notes Core2// File: Sources/SPNotesSync/Repositories/SearchRepository.swift3// Description: One search for the apps: the local full-text index (instant, offline) and, when the server can be4//              reached, its hybrid / semantic search — merged into one list where every result says where it comes5//              from. The local results never wait for the network. See docs/REPOSITORIES.md.6//7// Author: Simon-Pierre Boucher8// Contact: contact@spboucher.ai9import Foundation10import SPNotesAPI11import SPNotesStore1213/// One line of the merged result list.14public struct UnifiedSearchResult: Sendable, Equatable, Identifiable {15    public enum Origin: String, Sendable, Equatable {16        /// Found by the local full-text index only.17        case local18        /// Found by the server only (semantic match, or a page that is not on this device).19        case server20        /// Found by both.21        case both22    }2324    public var pageId: String25    public var title: String26    public var icon: String?27    public var section: String?28    /// Local excerpt with `SPNotesStore.SearchHit.highlightStart / highlightEnd` markers when there is a local29    /// match, else the server excerpt converted to the same markers.30    public var snippet: String31    public var origin: Origin32    /// The passage the server matched: scroll to this block (hybrid mode).33    public var blockId: String?34    public var heading: String?35    /// bm25 of the local index (lower is better); nil without a local match.36    public var localScore: Double?37    /// The server's fused score (higher is better); nil without a server match.38    public var serverScore: Double?39    /// The local page summary, when the page is on this device.40    public var page: PageSummary?4142    public var id: String { pageId + "#" + (blockId ?? "") }43}4445/// The outcome of a search.46public struct SearchOutcome: Sendable, Equatable {47    public var results: [UnifiedSearchResult]48    /// Whether the server took part. False offline, in `.localOnly`, or when it failed (`serverError` says why).49    public var usedServer: Bool50    public var serverError: RepositoryError?51}5253public enum SearchScope: Sendable, Equatable {54    /// The local index only (no request).55    case localOnly56    /// Local index + the server's hybrid search with semantic ranking. **The server embeds the query: one paid57    /// provider call per search** — use it on an explicit "search by meaning" action, not while typing.58    case hybrid59    /// Local index + the server's search without the embedding call (`semantic=0`): free. The default.60    case serverLexical61}6263public struct SearchRepository: Sendable {64    let context: RepositoryContext65    public init(context: RepositoryContext) { self.context = context }6667    /// The local results only: synchronous with the store, for search-as-you-type.68    public func local(_ text: String, filters: SearchFilters = SearchFilters(), limit: Int = 50) async throws -> [UnifiedSearchResult] {69        do {70            return try await context.store.search(query: text, filters: filters, limit: limit).map(Self.result)71        } catch { throw RepositoryError.from(error) }72    }7374    /// Local and server results merged. The server failing (offline, 5xx, no embedding provider) never fails the75    /// search: the local results are returned with `usedServer == false`.76    public func search(_ text: String, scope: SearchScope = .serverLexical, filters: SearchFilters = SearchFilters(), limit: Int = 40) async throws -> SearchOutcome {77        let localHits = try await local(text, filters: filters, limit: limit)78        let trimmed = text.trimmingCharacters(in: .whitespacesAndNewlines)79        guard scope != .localOnly, !trimmed.isEmpty else { return SearchOutcome(results: localHits, usedServer: false, serverError: nil) }80        var query = SearchQuery(trimmed, mode: .hybrid, limit: min(max(limit, 1), 60), semantic: scope == .serverLexical ? false : nil,81                                section: filters.section.flatMap(PageSection.init(rawValue:)), includeArchived: filters.includeArchived)82        query.since = filters.updatedAfter.map { String(APIDate.string(from: $0).prefix(10)) }83        query.until = filters.updatedBefore.map { String(APIDate.string(from: $0).prefix(10)) }84        let remote: [SPNotesAPI.SearchHit]85        do {86            remote = try await context.api.search(query)87        } catch {88            return SearchOutcome(results: localHits, usedServer: false, serverError: RepositoryError.from(error))89        }90        return SearchOutcome(results: await merge(local: localHits, remote: remote, limit: limit), usedServer: true, serverError: nil)91    }9293    /// Merges the two lists: a page found by both is labelled `.both` and keeps the local excerpt with the server's94    /// passage anchor; pages found by both come first (in the server's order), then the rest interleaved by rank95    /// (reciprocal-rank fusion), so that neither source hides the other.96    func merge(local: [UnifiedSearchResult], remote: [SPNotesAPI.SearchHit], limit: Int) async -> [UnifiedSearchResult] {97        var byPage: [String: UnifiedSearchResult] = [:]98        var rank: [String: Double] = [:]99        for (index, hit) in local.enumerated() {100            byPage[hit.pageId] = hit101            rank[hit.pageId, default: 0] += 1.0 / Double(60 + index)102        }103        for (index, hit) in remote.enumerated() {104            guard let pageId = hit.targetPageID else { continue }105            rank[pageId, default: 0] += 1.0 / Double(60 + index)106            if var existing = byPage[pageId] {107                guard existing.origin == .local else { continue }   // a second passage of the same page: the first one stands108                existing.origin = .both109                existing.blockId = hit.blockId110                existing.heading = hit.heading111                existing.serverScore = hit.score112                byPage[pageId] = existing113            } else {114                let summary = try? await context.store.summary(id: pageId)115                byPage[pageId] = UnifiedSearchResult(pageId: pageId, title: hit.title ?? summary?.title ?? "", icon: hit.icon ?? summary?.icon, section: hit.section ?? summary?.section,116                                                     snippet: Self.markers(hit.snippet ?? hit.content ?? summary?.preview ?? ""), origin: .server, blockId: hit.blockId,117                                                     heading: hit.heading, localScore: nil, serverScore: hit.score, page: summary)118            }119        }120        let ordered = byPage.values.sorted { a, b in121            let ra = rank[a.pageId] ?? 0, rb = rank[b.pageId] ?? 0122            if ra != rb { return ra > rb }123            return a.pageId < b.pageId124        }125        return Array(ordered.prefix(limit))126    }127128    static func result(_ hit: SPNotesStore.SearchHit) -> UnifiedSearchResult {129        UnifiedSearchResult(pageId: hit.page.id, title: hit.page.title, icon: hit.page.icon, section: hit.page.section, snippet: hit.snippet, origin: .local,130                            blockId: nil, heading: nil, localScore: hit.score, serverScore: nil, page: hit.page)131    }132133    /// The server marks matches with U+0001 / U+0002; the apps render one convention, the local one.134    static func markers(_ text: String) -> String {135        String(text.map { $0 == "\u{1}" ? SPNotesStore.SearchHit.highlightStart : ($0 == "\u{2}" ? SPNotesStore.SearchHit.highlightEnd : $0) })136    }137}138
Files main
Menu

Theme