Repository Public
1// SP Notes Core2// File: Sources/SPNotesAPI/GraphLinkModels.swift3// Description: Models of the 2.x graph routes: backlinks explorer and unlinked mentions, the neighbourhood of a page,4// AI link suggestions and their decisions.5//6// Author: Simon-Pierre Boucher7// Contact: contact@spboucher.ai8import Foundation910// MARK: - Backlinks1112/// A page of the backlinks explorer, with its link counts.13public struct BacklinkPage: Codable, Sendable, Equatable, Identifiable {14 public var id: String15 public var title: String16 public var icon: String?17 public var type: String?18 public var section: String?19 public var updatedAt: Date?20 /// Links arriving from live pages.21 public var incoming: Int22 /// Links leaving to live pages.23 public var outgoing: Int24 /// Pending AI link suggestions that involve the page.25 public var suggested: Int?26}2728/// A page whose text contains the exact title of another page without linking to it.29public struct UnlinkedMention: Codable, Sendable, Equatable, Identifiable {30 /// The page that mentions.31 public var fromId: String32 public var fromTitle: String33 public var fromIcon: String?34 /// The page whose title is mentioned.35 public var toId: String36 public var toTitle: String37 public var toIcon: String?38 /// ≤ 200 characters around the mention.39 public var excerpt: String?40 /// `<fromId>:<toId>`.41 public var key: String?4243 public var id: String { key ?? "\(fromId):\(toId)" }44}4546/// `GET /api/graph/backlinks`.47public struct BacklinksOverview: Codable, Sendable, Equatable {48 /// Ranked by incoming links (≤ 300), filtered by title when `search` is given.49 public var pages: [BacklinkPage]50 /// Unlinked mentions (≤ 400), dismissed ones left out; scoped to one page when `pageID` is given.51 public var mentions: [UnlinkedMention]52}5354/// What to do with an unlinked mention (`POST /api/graph/backlinks`).55public enum MentionAction: String, Codable, Sendable, CaseIterable {56 /// Appends "See also @page" to the mentioning page (a real link; a new version of that page).57 case link58 /// Hides the mention from the explorer.59 case dismiss60 /// Shows it again.61 case undismiss62}6364// MARK: - Neighbourhood6566/// A node of a page neighbourhood (`kind`: `page`, `database`, `research`, `row`, `attachment`, `tag`).67public struct GraphNeighborNode: Codable, Sendable, Equatable, Identifiable {68 public var id: String69 public var kind: String70 public var title: String?71 public var icon: String?72 public var section: String?73 public var updatedAt: Date?74 public var databaseId: String?75 public var degree: Int?76 /// Incoming edges (`in` on the wire).77 public var incoming: Int?78 /// Outgoing edges (`out` on the wire).79 public var outgoing: Int?8081 enum CodingKeys: String, CodingKey {82 case id, kind, title, icon, section, updatedAt, databaseId, degree83 case incoming = "in"84 case outgoing = "out"85 }86}8788/// An edge of a page neighbourhood.89public struct GraphNeighborEdge: Codable, Sendable, Equatable, Identifiable {90 public var id: String91 /// Node id.92 public var source: String93 /// Node id.94 public var target: String95 /// `link`, `relation`, `ai_suggested`, `attachment`, `tag`.96 public var kind: String97 /// `accepted` or `suggested`.98 public var status: String?99 /// link: `link` | `ai`; relation: the property name; ai_suggested: the model id.100 public var sub: String?101 public var confidence: Double?102 public var rationale: String?103 /// The model that proposed the edge.104 public var model: String?105}106107public struct GraphNeighborStats: Codable, Sendable, Equatable {108 public var pages: Int?109 public var edges: Int?110 public var suggested: Int?111}112113/// A page linked to the centre (`linked` of the neighbourhood, confirmed links and database relations only).114public struct LinkedPage: Codable, Sendable, Equatable, Identifiable {115 public var id: String116 public var title: String?117 public var icon: String?118 /// `link` or `relation`.119 public var kind: String?120 /// `out` (the centre links to it) or `in`.121 public var direction: String?122}123124/// `GET /api/graph/neighbors`. An unknown page answers 200 with an empty graph.125public struct GraphNeighborhood: Codable, Sendable, Equatable {126 public var nodes: [GraphNeighborNode]127 public var edges: [GraphNeighborEdge]128 /// The page asked for.129 public var center: String?130 public var stats: GraphNeighborStats?131 /// Only with `includeLinked`.132 public var linked: [LinkedPage]?133 /// Only with `includeLinked`: the pending suggestions of the page (≤ 50).134 public var suggestions: [LinkSuggestion]?135}136137// MARK: - Suggestions138139/// The states of an AI link suggestion.140public enum LinkSuggestionStatus: String, Codable, Sendable, CaseIterable {141 case suggested, accepted, rejected142}143144/// An AI link suggestion between two pages (a `knowledge_edges` row of kind `ai_suggested`).145public struct LinkSuggestion: Codable, Sendable, Equatable, Identifiable {146 public var id: String147 public var fromId: String148 public var toId: String149 /// `suggested`, `accepted`, `rejected`.150 public var status: String?151 /// 0…1; below 0.6 the web app folds the suggestion under "Low confidence".152 public var confidence: Double?153 public var rationale: String?154 public var model: String?155 public var createdAt: Date?156 public var decidedAt: Date?157 public var fromTitle: String?158 public var fromIcon: String?159 public var toTitle: String?160 public var toIcon: String?161}162163public struct LinkSuggestionCounts: Codable, Sendable, Equatable {164 public var suggested: Int165 public var accepted: Int166 public var rejected: Int167}168169/// `GET /api/graph/suggestions`.170public struct LinkSuggestionList: Codable, Sendable, Equatable {171 /// The suggestions in the asked status (≤ 200), best confidence first.172 public var items: [LinkSuggestion]173 /// Counts of the whole workspace, whatever the filter.174 public var counts: LinkSuggestionCounts175}176177/// Answer of `PATCH /api/graph/suggestions`.178public struct LinkSuggestionDecision: Codable, Sendable, Equatable {179 public var ok: Bool180 public var id: String?181 public var status: String?182 public var fromId: String?183 public var toId: String?184}185186/// `result` of an inline suggest: what the pass over one page did.187public struct LinkSuggestRun: Codable, Sendable, Equatable {188 public var pageId: String?189 /// Semantically close pages given to the model.190 public var candidates: Int?191 public var suggested: Int?192 public var declined: Int?193 public var model: String?194 public var costUsd: Double?195 /// Why nothing was done (`no candidates`, `page not found`): no model was called.196 public var skipped: String?197}198199/// Answer of `POST /api/graph/suggestions`.200public struct LinkSuggestRequestResult: Codable, Sendable, Equatable {201 /// `true`: a background job was queued (`jobId`); `false`: the page was processed inline (`result`).202 public var queued: Bool203 public var jobId: String?204 public var result: LinkSuggestRun?205}206