Repository Public
1// SP Notes Core2// File: Sources/SPNotesAPI/ResearchModels.swift3// Description: Models of the research workspace (`/api/research/**`): references (also the `reference` kind of the4// entity feed), extracts, DOI lookup, BibTeX import / export, experiments, working papers, LaTeX export.5//6// Author: Simon-Pierre Boucher7// Contact: contact@spboucher.ai8import Foundation910// MARK: - References1112/// How a reference was established (`ResearchReference.verified`).13public enum ReferenceVerification {14 /// Typed or imported by the user.15 public static let user = "user"16 /// Metadata fetched from Crossref by DOI.17 public static let doiVerified = "doi_verified"18 /// Proposed by a model: to be checked.19 public static let aiSuggested = "ai_suggested"20}2122/// A bibliographic reference: the object of the reference routes and the `reference` row of the entity feed.23public struct ResearchReference: Codable, Sendable, Equatable, Identifiable {24 public var id: String25 /// The page the reference is attached to; `nil` = library only.26 public var pageId: String?27 /// BibTeX key, unique in the workspace (the server derives or de-duplicates it: `doe2021title`, `…a`, `…b`).28 public var citeKey: String29 /// BibTeX entry type (`article`, `book`, `misc`…).30 public var entryType: String?31 public var title: String32 /// "First Last" names.33 public var authors: [String]?34 public var year: Int?35 public var journal: String?36 public var doi: String?37 public var url: String?38 /// The generated BibTeX entry.39 public var bibtex: String?40 /// BibTeX tags (and `extracts`), free-form JSON object.41 public var fields: RawJSON?42 /// See `ReferenceVerification`.43 public var verified: String?44 /// The attached PDF.45 public var attachmentId: String?46 public var createdAt: Date?47 public var updatedAt: Date?48 /// Soft delete: the row stays in the feed with a date here (`GET` of a deleted reference answers 404).49 public var deletedAt: Date?50 public var rev: Int64?51 /// Only with `references(ids:)` on a server with the AI workstream: "Doe & Roe (2021)".52 public var label: String?53 /// Only with `references(ids:)` on a server with the AI workstream: the formatted entry.54 public var citation: String?55}5657/// Body of `POST /api/research/references`. With a client `id` the call is idempotent (201 again, the stored58/// reference untouched — even deleted: check `deletedAt`).59public struct ReferenceDraft: Encodable, Sendable, Equatable {60 public var id: String?61 public var pageId: String?62 public var citeKey: String?63 public var entryType: String?64 /// 1…1000 characters.65 public var title: String66 public var authors: [String]?67 public var year: Int?68 public var journal: String?69 public var doi: String?70 public var url: String?71 /// Extra BibTeX tags (JSON object).72 public var fields: RawJSON?73 /// See `ReferenceVerification` (server default `user`).74 public var verified: String?75 public var attachmentId: String?7677 public init(id: String? = nil, pageId: String? = nil, citeKey: String? = nil, entryType: String? = nil, title: String, authors: [String]? = nil,78 year: Int? = nil, journal: String? = nil, doi: String? = nil, url: String? = nil, fields: RawJSON? = nil, verified: String? = nil,79 attachmentId: String? = nil) {80 self.id = id81 self.pageId = pageId82 self.citeKey = citeKey83 self.entryType = entryType84 self.title = title85 self.authors = authors86 self.year = year87 self.journal = journal88 self.doi = doi89 self.url = url90 self.fields = fields91 self.verified = verified92 self.attachmentId = attachmentId93 }94}9596/// Body of `PATCH /api/research/references/<id>`. Only what is set is sent. `fields` is a partial edit of the BibTeX97/// tags: listed tags are replaced, an empty value (`""` or `null`) removes a tag, the others are kept.98public struct ReferenceChanges: Encodable, Sendable, Equatable {99 public var pageId: PatchValue<String>?100 public var citeKey: String?101 public var entryType: String?102 public var title: String?103 public var authors: [String]?104 public var year: PatchValue<Int>?105 public var journal: PatchValue<String>?106 public var doi: PatchValue<String>?107 public var url: PatchValue<String>?108 public var fields: RawJSON?109 public var verified: String?110 public var attachmentId: PatchValue<String>?111112 public init(pageId: PatchValue<String>? = nil, citeKey: String? = nil, entryType: String? = nil, title: String? = nil, authors: [String]? = nil,113 year: PatchValue<Int>? = nil, journal: PatchValue<String>? = nil, doi: PatchValue<String>? = nil, url: PatchValue<String>? = nil,114 fields: RawJSON? = nil, verified: String? = nil, attachmentId: PatchValue<String>? = nil) {115 self.pageId = pageId116 self.citeKey = citeKey117 self.entryType = entryType118 self.title = title119 self.authors = authors120 self.year = year121 self.journal = journal122 self.doi = doi123 self.url = url124 self.fields = fields125 self.verified = verified126 self.attachmentId = attachmentId127 }128129 enum CodingKeys: String, CodingKey { case pageId, citeKey, entryType, title, authors, year, journal, doi, url, fields, verified, attachmentId }130131 public func encode(to encoder: Encoder) throws {132 var c = encoder.container(keyedBy: CodingKeys.self)133 try c.encodePatch(pageId, forKey: .pageId)134 try c.encodeIfPresent(citeKey, forKey: .citeKey)135 try c.encodeIfPresent(entryType, forKey: .entryType)136 try c.encodeIfPresent(title, forKey: .title)137 try c.encodeIfPresent(authors, forKey: .authors)138 try c.encodePatch(year, forKey: .year)139 try c.encodePatch(journal, forKey: .journal)140 try c.encodePatch(doi, forKey: .doi)141 try c.encodePatch(url, forKey: .url)142 try c.encodeIfPresent(fields, forKey: .fields)143 try c.encodeIfPresent(verified, forKey: .verified)144 try c.encodePatch(attachmentId, forKey: .attachmentId)145 }146}147148/// Answer of `references(ids:)`: the references found and the ids that do not exist.149public struct ReferenceLookup: Sendable, Equatable {150 /// Only the references whose id was asked for (a server without the AI workstream ignores `ids` and answers the151 /// whole library: the client filters).152 public var references: [ResearchReference]153 /// Ids asked for and not found (the `x-missing-ids` header when the server sends it, else computed).154 public var missingIDs: [String]155156 public init(references: [ResearchReference], missingIDs: [String]) {157 self.references = references158 self.missingIDs = missingIDs159 }160}161162/// A page as the reference links report it.163public struct ReferenceLinkedPage: Codable, Sendable, Equatable, Identifiable {164 public var id: String165 public var title: String?166 public var icon: String?167 public var type: String?168}169170/// `GET /api/research/references/<id>/links` — where a reference is used.171public struct ReferenceLinks: Codable, Sendable, Equatable {172 /// The page the reference lives on.173 public var attached: ReferenceLinkedPage?174 /// Pages whose text cites its key. Items kept raw: no citing page could be produced on the scratch server.175 public var citing: [RawJSON]?176 /// Experiments of those pages (raw, same reason).177 public var experiments: [RawJSON]?178 /// Its PDF attachment (raw; `null` without one).179 public var pdf: RawJSON?180}181182// MARK: - Extracts183184/// A quoted extract of a reference (stored in `fields.extracts`).185public struct ReferenceExtract: Codable, Sendable, Equatable, Identifiable {186 public var id: String187 public var quote: String188 /// Free text: "p. 7", "§3".189 public var page: String?190 /// Personal note.191 public var note: String?192 /// ISO date kept as the server sent it (it must be sent back unchanged to restore a deleted extract).193 public var createdAt: String?194 public var updatedAt: String?195}196197/// Body of an extract creation. A client `id` makes a retry harmless (the stored extract is returned).198public struct ReferenceExtractDraft: Encodable, Sendable, Equatable {199 public var id: String?200 public var quote: String201 public var page: String?202 public var note: String?203204 public init(id: String? = nil, quote: String, page: String? = nil, note: String? = nil) {205 self.id = id206 self.quote = quote207 self.page = page208 self.note = note209 }210}211212/// Changes of an extract. Observed: `page` and `note` that are not sent are kept.213public struct ReferenceExtractChanges: Sendable, Equatable {214 public var quote: String?215 public var page: PatchValue<String>?216 public var note: PatchValue<String>?217218 public init(quote: String? = nil, page: PatchValue<String>? = nil, note: PatchValue<String>? = nil) {219 self.quote = quote220 self.page = page221 self.note = note222 }223}224225/// Answer of the extract mutations: the extract concerned and the whole list after the change.226public struct ReferenceExtractChange: Codable, Sendable, Equatable {227 /// `nil` when a delete found nothing to remove.228 public var extract: ReferenceExtract?229 public var extracts: [ReferenceExtract]230}231232// MARK: - DOI233234/// The reference already holding a DOI.235public struct DOIDuplicate: Codable, Sendable, Equatable, Identifiable {236 public var id: String237 public var citeKey: String?238 public var title: String?239 public var pageId: String?240}241242/// `GET /api/research/references/doi?doi=` — Crossref metadata (nothing is saved), or the stored reference when the243/// DOI is already in the library (`duplicate`; Crossref is then not called).244public struct DOILookup: Codable, Sendable, Equatable {245 public var doi: String246 public var title: String?247 public var authors: [String]?248 public var year: Int?249 public var journal: String?250 public var entryType: String?251 public var url: String?252 /// BibTeX tags found by Crossref (absent for a duplicate).253 public var fields: RawJSON?254 /// The cite key the reference would get (or has).255 public var citeKey: String?256 public var duplicate: DOIDuplicate?257}258259/// Answer of `POST /api/research/references/doi`: the reference (new: HTTP 201; already stored: 200).260public struct DOIAddResult: Decodable, Sendable, Equatable {261 public var reference: ResearchReference262 /// The DOI was already in the library: nothing was created.263 public var duplicate: Bool264 /// The existing reference was attached to the page given.265 public var linked: Bool266267 enum CodingKeys: String, CodingKey { case duplicate, linked }268269 public init(from decoder: Decoder) throws {270 reference = try ResearchReference(from: decoder)271 let c = try decoder.container(keyedBy: CodingKeys.self)272 duplicate = (try? c.decodeIfPresent(Bool.self, forKey: .duplicate)) ?? false273 linked = (try? c.decodeIfPresent(Bool.self, forKey: .linked)) ?? false274 }275}276277// MARK: - BibTeX278279/// An entry the import created.280public struct BibTeXCreated: Codable, Sendable, Equatable, Identifiable {281 public var id: String282 public var citeKey: String?283 public var title: String?284}285286/// An entry a dry run would create.287public struct BibTeXCandidate: Codable, Sendable, Equatable {288 public var citeKey: String?289 public var title: String?290 public var year: Int?291}292293/// An entry left out (duplicate DOI or cite key) or unreadable.294public struct BibTeXIssue: Codable, Sendable, Equatable {295 public var citeKey: String?296 /// The stored reference it collides with.297 public var existingKey: String?298 public var reason: String?299}300301public struct BibTeXImportCounts: Codable, Sendable, Equatable {302 public var created: Int?303 public var wouldCreate: Int?304 public var skipped: Int?305 public var failed: Int?306}307308/// Answer of `POST /api/research/references/import-bibtex`. Duplicates are skipped, never overwritten.309public struct BibTeXImportResult: Codable, Sendable, Equatable {310 public var dryRun: Bool311 /// Entries read.312 public var parsed: Int313 public var created: [BibTeXCreated]314 /// Dry run only (≤ 500).315 public var wouldCreate: [BibTeXCandidate]316 public var skipped: [BibTeXIssue]317 public var failed: [BibTeXIssue]318 /// The complete counts (the lists are capped).319 public var counts: BibTeXImportCounts?320}321322/// A BibTeX export.323public struct BibTeXExport: Sendable, Equatable {324 /// The `.bib` text.325 public var text: String326 /// Number of entries (`x-export-count`).327 public var count: Int?328 /// File name proposed by the server (`library.bib`, `<page title>.bib`).329 public var suggestedFilename: String?330331 public init(text: String, count: Int? = nil, suggestedFilename: String? = nil) {332 self.text = text333 self.count = count334 self.suggestedFilename = suggestedFilename335 }336}337338// MARK: - Experiments339340/// The states of an experiment (`ResearchExperiment.status`).341public enum ExperimentStatus {342 public static let planned = "planned"343 public static let running = "running"344 public static let done = "done"345 public static let failed = "failed"346}347348/// An experiment of a research page.349public struct ResearchExperiment: Codable, Sendable, Equatable, Identifiable {350 public var id: String351 public var pageId: String?352 public var name: String353 /// See `ExperimentStatus`.354 public var status: String?355 /// Free-form JSON object.356 public var params: RawJSON?357 /// Free-form JSON object.358 public var metrics: RawJSON?359 public var datasetRef: String?360 public var repoUrl: String?361 public var notes: String?362 /// Set by the server when the status becomes `running` …363 public var startedAt: Date?364 /// … and `done` / `failed`.365 public var finishedAt: Date?366 public var createdAt: Date?367 public var updatedAt: Date?368}369370/// Body of `POST /api/research/experiments`.371public struct ExperimentDraft: Encodable, Sendable, Equatable {372 public var pageId: String?373 /// 1…300 characters.374 public var name: String375 public var status: String?376 public var params: RawJSON?377 public var metrics: RawJSON?378 public var datasetRef: String?379 public var repoUrl: String?380 public var notes: String?381382 public init(pageId: String? = nil, name: String, status: String? = nil, params: RawJSON? = nil, metrics: RawJSON? = nil, datasetRef: String? = nil,383 repoUrl: String? = nil, notes: String? = nil) {384 self.pageId = pageId385 self.name = name386 self.status = status387 self.params = params388 self.metrics = metrics389 self.datasetRef = datasetRef390 self.repoUrl = repoUrl391 self.notes = notes392 }393}394395/// Body of `PATCH /api/research/experiments/<id>`. `params` and `metrics` REPLACE the stored objects.396public struct ExperimentChanges: Encodable, Sendable, Equatable {397 public var pageId: PatchValue<String>?398 public var name: String?399 public var status: String?400 public var params: RawJSON?401 public var metrics: RawJSON?402 public var datasetRef: PatchValue<String>?403 public var repoUrl: PatchValue<String>?404 public var notes: PatchValue<String>?405406 public init(pageId: PatchValue<String>? = nil, name: String? = nil, status: String? = nil, params: RawJSON? = nil, metrics: RawJSON? = nil,407 datasetRef: PatchValue<String>? = nil, repoUrl: PatchValue<String>? = nil, notes: PatchValue<String>? = nil) {408 self.pageId = pageId409 self.name = name410 self.status = status411 self.params = params412 self.metrics = metrics413 self.datasetRef = datasetRef414 self.repoUrl = repoUrl415 self.notes = notes416 }417418 enum CodingKeys: String, CodingKey { case pageId, name, status, params, metrics, datasetRef, repoUrl, notes }419420 public func encode(to encoder: Encoder) throws {421 var c = encoder.container(keyedBy: CodingKeys.self)422 try c.encodePatch(pageId, forKey: .pageId)423 try c.encodeIfPresent(name, forKey: .name)424 try c.encodeIfPresent(status, forKey: .status)425 try c.encodeIfPresent(params, forKey: .params)426 try c.encodeIfPresent(metrics, forKey: .metrics)427 try c.encodePatch(datasetRef, forKey: .datasetRef)428 try c.encodePatch(repoUrl, forKey: .repoUrl)429 try c.encodePatch(notes, forKey: .notes)430 }431}432433// MARK: - Research tasks434435/// One task of `POST /api/research/tasks`. These routes are the 2.x research view of the task table: prefer436/// `createTaskIdempotent` (client ids) for anything created offline.437public struct ResearchTaskDraft: Encodable, Sendable, Equatable {438 public var title: String439 public var status: TaskStatus?440 public var priority: TaskPriority?441 /// A date string. Observed: a bare day `YYYY-MM-DD` is stored at 00:00 UTC here (12:00 UTC through `/api/tasks`).442 public var dueAt: String?443 public var project: String?444445 public init(title: String, status: TaskStatus? = nil, priority: TaskPriority? = nil, dueAt: String? = nil, project: String? = nil) {446 self.title = title447 self.status = status448 self.priority = priority449 self.dueAt = dueAt450 self.project = project451 }452}453454// MARK: - Working papers455456/// The statuses of a working paper (`properties.status` of a research page).457public enum PaperStatus {458 public static let planning = "planning"459 public static let research = "research"460 public static let development = "development"461 public static let writing = "writing"462 public static let submitted = "submitted"463 public static let published = "published"464}465466/// An item of `GET /api/research/overview`: one research page with its counters.467public struct ResearchPaperOverview: Codable, Sendable, Equatable, Identifiable {468 /// The page id.469 public var id: String470 public var title: String471 public var icon: String?472 /// See `PaperStatus`.473 public var status: String?474 public var venue: String?475 public var deadline: String?476 public var repoUrl: String?477 /// Raw items (no dataset could be produced on the scratch server).478 public var datasets: [RawJSON]?479 public var wordCount: Int?480 public var references: Int?481 public var experiments: Int?482 public var experimentsRunning: Int?483 public var openTasks: Int?484 public var overdueTasks: Int?485 public var attachments: Int?486 public var updatedAt: Date?487 public var lastActivity: Date?488 public var createdAt: Date?489}490491// MARK: - LaTeX export (AI workstream, API-NEXT-AI §8.1)492493/// A figure placeholder of a LaTeX export.494public struct LaTeXFigure: Codable, Sendable, Equatable {495 public var attachmentId: String?496 public var name: String?497 /// The name used in `\includegraphics{figures/<file>}`.498 public var file: String?499}500501/// The `x-export-report` header of the `.tex` export.502public struct LaTeXExportReport: Codable, Sendable, Equatable {503 public var pages: Int?504 public var sections: Int?505 public var citeKeys: Int?506 public var missingKeys: Int?507 public var missingRefs: Int?508 public var figures: Int?509 public var hypotheses: Int?510 public var experiments: Int?511 public var unknownNodes: [String]?512}513514/// `GET /api/research/export.tex?format=tex` — the LaTeX skeleton of a project.515public struct LaTeXExport: Sendable, Equatable {516 public var tex: String517 public var report: LaTeXExportReport?518 /// Path of the companion `.bib` (`x-bib-url`).519 public var bibURL: String?520 public var suggestedFilename: String?521522 public init(tex: String, report: LaTeXExportReport? = nil, bibURL: String? = nil, suggestedFilename: String? = nil) {523 self.tex = tex524 self.report = report525 self.bibURL = bibURL526 self.suggestedFilename = suggestedFilename527 }528}529530/// `GET /api/research/export.tex?format=json` — the export with its bibliography and diagnostics.531public struct LaTeXExportBundle: Codable, Sendable, Equatable {532 public var projectId: String533 public var title: String?534 public var tex: String535 public var bib: String?536 public var citeKeys: [String]?537 /// Cited but absent from the library.538 public var missingKeys: [String]?539 public var missingRefs: [RawJSON]?540 public var figures: [LaTeXFigure]?541 public var sections: Int?542 public var hypotheses: Int?543 public var experiments: Int?544 public var unknownNodes: [String]?545 public var bibUrl: String?546}547