scitadel_core/ports/
repository.rs

1use std::collections::HashMap;
2
3use crate::error::CoreError;
4use crate::models::{
5    Assessment, Citation, DownloadStatus, Paper, PaperId, ResearchQuestion, Search, SearchResult,
6    SearchTerm, SnowballRun,
7};
8
9/// Port for paper persistence.
10pub trait PaperRepository: Send + Sync {
11    fn save(&self, paper: &Paper) -> Result<(), CoreError>;
12    /// Save multiple papers, resolving DOI conflicts with existing records.
13    /// Returns a map of original_id → resolved_id for papers whose ID was
14    /// remapped to an existing record (callers should use this to fix up
15    /// search_results and other references).
16    fn save_many(&self, papers: &[Paper]) -> Result<HashMap<PaperId, PaperId>, CoreError>;
17    fn get(&self, paper_id: &str) -> Result<Option<Paper>, CoreError>;
18    fn find_by_doi(&self, doi: &str) -> Result<Option<Paper>, CoreError>;
19    fn find_by_title(&self, title: &str) -> Result<Option<Paper>, CoreError>;
20    fn list_all(&self, limit: i64, offset: i64) -> Result<Vec<Paper>, CoreError>;
21    /// Persist extracted full text for a paper. Used by `read_paper_tool`
22    /// after the first PDF/HTML extraction so subsequent reads (TUI
23    /// reader, MCP `get_annotated_paper`) hit the DB instead of
24    /// re-running pdf-extract. Idempotent — overwrites the existing
25    /// `full_text` column.
26    fn update_full_text(&self, paper_id: &str, text: &str) -> Result<(), CoreError>;
27    /// Persist the outcome of a download attempt. `local_path` is the
28    /// absolute path to the saved file on success (any non-`Failed`
29    /// status); pass `None` for `Failed`. `last_attempt_at` is set to
30    /// `now()` automatically. See #112.
31    fn update_download_state(
32        &self,
33        paper_id: &str,
34        local_path: Option<&str>,
35        status: DownloadStatus,
36    ) -> Result<(), CoreError>;
37    /// Assign a stable citation key to a paper. Called once per paper
38    /// by the 0.6.0 backfill migration (and per-paper on new ingest).
39    /// Must be unique across the DB — the caller is responsible for
40    /// running the Better-BibTeX algorithm + disambiguation before
41    /// calling this. See ADR-006 + `scitadel-export::bibtex::assign_keys`.
42    fn update_bibtex_key(&self, paper_id: &str, key: &str) -> Result<(), CoreError>;
43}
44
45/// Port for search run persistence.
46pub trait SearchRepository: Send + Sync {
47    fn save(&self, search: &Search) -> Result<(), CoreError>;
48    fn get(&self, search_id: &str) -> Result<Option<Search>, CoreError>;
49    fn save_results(&self, results: &[SearchResult]) -> Result<(), CoreError>;
50    fn get_results(&self, search_id: &str) -> Result<Vec<SearchResult>, CoreError>;
51    fn list_searches(&self, limit: i64) -> Result<Vec<Search>, CoreError>;
52    fn diff_searches(
53        &self,
54        search_id_a: &str,
55        search_id_b: &str,
56    ) -> Result<(Vec<String>, Vec<String>), CoreError>;
57}
58
59/// Port for research question and search term persistence.
60pub trait QuestionRepository: Send + Sync {
61    fn save_question(&self, question: &ResearchQuestion) -> Result<(), CoreError>;
62    fn get_question(&self, question_id: &str) -> Result<Option<ResearchQuestion>, CoreError>;
63    fn list_questions(&self) -> Result<Vec<ResearchQuestion>, CoreError>;
64    fn save_term(&self, term: &SearchTerm) -> Result<(), CoreError>;
65    fn get_terms(&self, question_id: &str) -> Result<Vec<SearchTerm>, CoreError>;
66}
67
68/// Port for relevance assessment persistence.
69pub trait AssessmentRepository: Send + Sync {
70    fn save(&self, assessment: &Assessment) -> Result<(), CoreError>;
71    fn get_for_paper(
72        &self,
73        paper_id: &str,
74        question_id: Option<&str>,
75    ) -> Result<Vec<Assessment>, CoreError>;
76    fn get_for_question(&self, question_id: &str) -> Result<Vec<Assessment>, CoreError>;
77}
78
79/// Port for citation edge and snowball run persistence.
80pub trait CitationRepository: Send + Sync {
81    fn save(&self, citation: &Citation) -> Result<(), CoreError>;
82    fn save_many(&self, citations: &[Citation]) -> Result<(), CoreError>;
83    fn get_references(&self, paper_id: &str) -> Result<Vec<Citation>, CoreError>;
84    fn get_citations(&self, paper_id: &str) -> Result<Vec<Citation>, CoreError>;
85    fn exists(
86        &self,
87        source_paper_id: &str,
88        target_paper_id: &str,
89        direction: &str,
90    ) -> Result<bool, CoreError>;
91    fn save_snowball_run(&self, run: &SnowballRun) -> Result<(), CoreError>;
92    fn get_snowball_run(&self, run_id: &str) -> Result<Option<SnowballRun>, CoreError>;
93    fn list_snowball_runs(&self, limit: i64) -> Result<Vec<SnowballRun>, CoreError>;
94}
scitadel_core/ports/repository.rs

scitadel_core/ports/
repository.rs
