Repository Public
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