SPB Git

Repository Public

SearchModels.swift 7.8 KB 191 lines swift

1// SP Notes Core2// File: Sources/SPNotesAPI/SearchModels.swift3// Description: Additions to the search models: result kinds, the remaining fields of a hybrid hit (scores, source,4//              highlights), near-duplicate pages and the state of the search index.5//6// Author: Simon-Pierre Boucher7// Contact: contact@spboucher.ai8import Foundation910/// The kinds of a hybrid search hit (`SearchHit.kind`, `SearchQuery.kinds`).11public enum SearchKind {12    /// A passage of a page.13    public static let page = "page"14    /// A passage of a database row page.15    public static let entry = "entry"16    /// A passage of an attachment (extracted text).17    public static let file = "file"18    /// A bibliographic reference (only with `SearchQuery.group`).19    public static let reference = "reference"20    public static let all = [page, entry, file, reference]21}2223/// A piece of `SearchHit.snippet`: plain text, or a matched term to highlight.24public struct SearchSnippetSegment: Sendable, Equatable {25    public var text: String26    public var isMatch: Bool2728    public init(text: String, isMatch: Bool) {29        self.text = text30        self.isMatch = isMatch31    }32}3334extension SearchQuery {35    /// A hybrid query that never leaves the server: keyword ranking only, the text is NOT sent to the embedding36    /// provider (`semantic=0`). Without `semantic: false` the server embeds every hybrid query (a paid call).37    public static func keywords(_ text: String, limit: Int? = nil, kinds: [String]? = nil, group: Bool = false, section: PageSection? = nil,38                                since: String? = nil, until: String? = nil, includeArchived: Bool = false) -> SearchQuery {39        var query = SearchQuery(text, mode: .hybrid, limit: limit, semantic: false, section: section, since: since, until: until, includeArchived: includeArchived)40        query.kinds = kinds41        query.group = group42        return query43    }44}4546/// The fields of a hybrid hit that `SearchHit` does not store: they are read from `raw`.47extension SearchHit {48    private var object: JSONValue? { try? JSONValue(parsing: raw.data) }4950    /// Id of the indexed passage (`ref:<id>` for a reference).51    public var chunkId: String? { object?["chunkId"]?.stringValue }52    /// `page`, `attachment` or `reference`.53    public var sourceType: String? { object?["sourceType"]?.stringValue }54    /// Id of the page, attachment or reference the passage comes from.55    public var sourceId: String? { object?["sourceId"]?.stringValue }56    /// Cosine similarity of the passage (0 when the query was not embedded).57    public var semanticScore: Double? { object?["semantic"]?.doubleValue }58    /// Keyword rank of the passage.59    public var keywordScore: Double? { object?["keyword"]?.doubleValue }60    public var isArchived: Bool? { object?["archived"]?.boolValue }61    /// Grouped results: number of other matching passages of the same source.62    public var more: Int? { object?["more"]?.intValue }63    /// The attachment of a `file` hit.64    public var attachmentId: String? { object?["attachmentId"]?.stringValue }65    /// The reference of a `reference` hit.66    public var referenceId: String? { kind == SearchKind.reference ? sourceId : nil }6768    /// `snippet` cut at its highlight markers (U+0001 … U+0002 around each matched term).69    public var snippetSegments: [SearchSnippetSegment] { SearchHit.segments(of: snippet ?? "") }7071    /// Splits a highlighted excerpt into plain and matched pieces.72    public static func segments(of snippet: String) -> [SearchSnippetSegment] {73        var out: [SearchSnippetSegment] = []74        var current = ""75        var inMatch = false76        func flush() {77            if !current.isEmpty { out.append(SearchSnippetSegment(text: current, isMatch: inMatch)) }78            current = ""79        }80        for character in snippet {81            if character == "\u{1}" { flush(); inMatch = true }82            else if character == "\u{2}" { flush(); inMatch = false }83            else { current.append(character) }84        }85        flush()86        return out87    }88}8990/// One side of a near-duplicate pair.91public struct DuplicatePage: Codable, Sendable, Equatable, Identifiable {92    public var id: String93    public var title: String?94    public var icon: String?95    public var wordCount: Int?96    public var updatedAt: Date?97}9899/// An item of `GET /api/search/duplicates`: two pages with passages whose embeddings are almost identical.100public struct DuplicatePair: Codable, Sendable, Equatable {101    public var a: DuplicatePage102    public var b: DuplicatePage103    /// Cosine similarity, 0…1.104    public var similarity: Double105}106107/// A page waiting to be indexed.108public struct SearchIndexPendingPage: Codable, Sendable, Equatable, Identifiable {109    public var id: String110    public var title: String?111    public var icon: String?112    public var updatedAt: Date?113}114115/// An index job that failed for good.116public struct SearchIndexFailure: Codable, Sendable, Equatable, Identifiable {117    public var id: String118    public var sourceId: String?119    public var sourceType: String?120    public var error: String?121    public var at: Date?122}123124/// `health` of `GET /api/search/index-state`: what the index is missing.125public struct SearchIndexHealth: Codable, Sendable, Equatable {126    /// Pages never indexed or changed since (≤ 50).127    public var pending: [SearchIndexPendingPage]128    public var pendingFiles: Int?129    public var failed: [SearchIndexFailure]130    /// Index jobs waiting in the queue.131    public var queued: Int?132    /// `false`: no embedding provider, the search is keyword-only.133    public var embeddingsConfigured: Bool?134135    enum CodingKeys: String, CodingKey { case pending, pendingFiles, failed, queued, embeddingsConfigured }136137    public init(from decoder: Decoder) throws {138        let c = try decoder.container(keyedBy: CodingKeys.self)139        pending = (try? c.decodeIfPresent([SearchIndexPendingPage].self, forKey: .pending)) ?? []140        pendingFiles = c.lenientInt(.pendingFiles)141        failed = (try? c.decodeIfPresent([SearchIndexFailure].self, forKey: .failed)) ?? []142        queued = c.lenientInt(.queued)143        embeddingsConfigured = try? c.decodeIfPresent(Bool.self, forKey: .embeddingsConfigured)144    }145}146147/// `GET /api/search/index-state`. The counters arrive as text from this route (`"pages": "2"`): they are read from148/// either form.149public struct SearchIndexState: Codable, Sendable, Equatable {150    public var pages: Int?151    public var attachments: Int?152    public var chunks: Int?153    /// Chunks that have an embedding.154    public var embedded: Int?155    public var indexedSources: Int?156    public var lastIndexed: Date?157    /// Sources indexed with another embedding model or version.158    public var stale: Int?159    /// The embedding model.160    public var model: String?161    public var version: Int?162    public var health: SearchIndexHealth?163164    enum CodingKeys: String, CodingKey {165        case pages, attachments, chunks, embedded, stale, model, version, health166        case indexedSources = "indexed_sources"167        case lastIndexed = "last_indexed"168    }169170    public init(from decoder: Decoder) throws {171        let c = try decoder.container(keyedBy: CodingKeys.self)172        pages = c.lenientInt(.pages)173        attachments = c.lenientInt(.attachments)174        chunks = c.lenientInt(.chunks)175        embedded = c.lenientInt(.embedded)176        indexedSources = c.lenientInt(.indexedSources)177        lastIndexed = c.lenientDate(.lastIndexed)178        stale = c.lenientInt(.stale)179        model = try? c.decodeIfPresent(String.self, forKey: .model)180        version = c.lenientInt(.version)181        health = try? c.decodeIfPresent(SearchIndexHealth.self, forKey: .health)182    }183}184185/// Answer of `POST /api/search/index-state`.186public struct SearchReindexResult: Codable, Sendable, Equatable {187    public var ok: Bool188    /// Jobs queued.189    public var queued: Int?190}191
Files main
Menu

Theme