SPB Git

Repository Public

ResearchModels.swift 20.2 KB 547 lines swift

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

Theme