SPB Git

Repository Public

GraphLinkModels.swift 7.0 KB 206 lines swift

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
Files main
Menu

Theme