aspero_core/
provider.rs

1//! The `Provider` trait: the contract every literature source implements.
2//!
3//! Rules every implementation follows (the engine relies on them):
4//!
5//! 1. **No merging, no caching, no retries.** A provider makes the request,
6//!    maps the response, and returns. Retries, backoff, rate limiting, caching
7//!    and merging are the engine's job, so they are consistent and shared.
8//! 2. **Declared capabilities are honoured.** Every [`Filter`] listed in
9//!    [`Capabilities::search_filters`] is applied when present in a query. The
10//!    engine reports filters a provider doesn't declare as ignored, so nothing
11//!    is dropped silently. Unknown keys in [`SearchQuery::extra`] are
12//!    rejected with [`Error::BadRequest`].
13//! 3. **Batch lookups answer every ID.** [`Provider::lookup`] returns one
14//!    [`Lookup`] per input ID, in input order, with `record: None` for IDs the
15//!    provider doesn't know. Whole-call failures are `Err`.
16//! 4. **Errors are mapped** into [`crate::Error`], including non-provider
17//!    bodies (e.g. an API gateway's 429 page).
18//! 5. **Usage is reported** when the provider exposes it (credits spent,
19//!    budget remaining), so agents can pace themselves.
20//!
21//! Each provider also owns its HTTP mapping, credentials and default
22//! [`ResiliencePolicy`](crate::ResiliencePolicy).
23
24use std::borrow::Cow;
25use std::collections::BTreeMap;
26use std::fmt;
27
28use async_trait::async_trait;
29use jiff::Timestamp;
30use serde::{Deserialize, Serialize};
31
32use crate::error::{Error, Result};
33use crate::id::{IdKind, WorkId};
34use crate::record::{FieldSet, SourceRecord};
35use crate::work::WorkType;
36
37/// Stable short name of a provider, e.g. `openalex`. Lowercase ASCII letters,
38/// digits and `-`.
39#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize)]
40pub struct ProviderId(Cow<'static, str>);
41
42impl ProviderId {
43    /// For built-in providers.
44    ///
45    /// # Panics
46    /// If `id` is not a valid provider name (checked at compile time when used
47    /// in a `const`).
48    pub const fn from_static(id: &'static str) -> Self {
49        assert!(Self::is_valid(id), "invalid provider id");
50        ProviderId(Cow::Borrowed(id))
51    }
52
53    pub fn parse(id: &str) -> Option<Self> {
54        Self::is_valid(id).then(|| ProviderId(Cow::Owned(id.to_owned())))
55    }
56
57    pub fn as_str(&self) -> &str {
58        &self.0
59    }
60
61    const fn is_valid(id: &str) -> bool {
62        let b = id.as_bytes();
63        if b.is_empty() {
64            return false;
65        }
66        let mut i = 0;
67        while i < b.len() {
68            if !(b[i].is_ascii_lowercase() || b[i].is_ascii_digit() || b[i] == b'-') {
69                return false;
70            }
71            i += 1;
72        }
73        true
74    }
75}
76
77impl fmt::Display for ProviderId {
78    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
79        f.write_str(&self.0)
80    }
81}
82
83impl<'de> Deserialize<'de> for ProviderId {
84    fn deserialize<D: serde::Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
85        let s = String::deserialize(d)?;
86        ProviderId::parse(&s)
87            .ok_or_else(|| serde::de::Error::custom(format!("invalid provider id {s:?}")))
88    }
89}
90
91/// What a provider can do. The engine routes on this before calling.
92#[derive(Debug, Clone, Default, PartialEq, Eq)]
93#[non_exhaustive]
94pub struct Capabilities {
95    /// Identifier kinds [`Provider::lookup`] accepts.
96    pub lookup_kinds: Vec<IdKind>,
97    /// Most IDs per `lookup` call; the engine splits larger batches. 0 is
98    /// treated as 1.
99    pub max_batch: usize,
100    /// Fields this provider can supply at all.
101    pub fields: FieldSet,
102    pub search: bool,
103    /// Supports [`SearchMode::Citation`]: a matcher built for reference
104    /// strings, not just keyword search.
105    pub citation_search: bool,
106    /// Reports editorial notices in detail and in both directions (a work's
107    /// corrections, a correction's work), so the engine asks it about
108    /// records other providers supplied.
109    pub notices: bool,
110    pub search_filters: Vec<Filter>,
111    /// Identifier kinds whose "not found" here is final: no other provider
112    /// can know them (doi.org for DOIs), so lookups stop asking.
113    pub final_misses: Vec<IdKind>,
114    pub citations: bool,
115    pub references: bool,
116    pub recommend: bool,
117}
118
119/// Common search filters (see [`SearchQuery`]).
120#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
121#[serde(rename_all = "snake_case")]
122#[non_exhaustive]
123pub enum Filter {
124    Years,
125    WorkType,
126    OpenAccess,
127}
128
129/// Inclusive publication-year range; either end may be open.
130#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
131pub struct YearRange {
132    pub from: Option<i16>,
133    pub to: Option<i16>,
134}
135
136/// An opaque, provider-specific continuation token.
137#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
138#[serde(transparent)]
139pub struct Cursor(pub String);
140
141#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
142#[non_exhaustive]
143pub struct PageReq {
144    /// Requested page size. Providers cap it at their own maximum and may
145    /// return fewer, never more.
146    pub limit: u32,
147    /// `None` for the first page.
148    pub cursor: Option<Cursor>,
149}
150
151impl PageReq {
152    pub const DEFAULT_LIMIT: u32 = 25;
153
154    pub fn first(limit: u32) -> Self {
155        PageReq {
156            limit,
157            cursor: None,
158        }
159    }
160}
161
162impl Default for PageReq {
163    fn default() -> Self {
164        PageReq::first(Self::DEFAULT_LIMIT)
165    }
166}
167
168/// How [`SearchQuery::text`] should be interpreted.
169#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Hash, Serialize, Deserialize)]
170#[serde(rename_all = "snake_case")]
171#[non_exhaustive]
172pub enum SearchMode {
173    /// Free-text keywords.
174    #[default]
175    Keywords,
176    /// A whole, possibly messy reference string ("LeCun Y, Bengio Y. Deep
177    /// learning. Nature. 2015"), to be matched to the work it cites. Only
178    /// sent to providers declaring [`Capabilities::citation_search`].
179    Citation,
180}
181
182#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
183#[non_exhaustive]
184pub struct SearchQuery {
185    pub text: String,
186    pub mode: SearchMode,
187    pub years: Option<YearRange>,
188    pub work_type: Option<WorkType>,
189    pub open_access: Option<bool>,
190    pub fields: FieldSet,
191    pub page: PageReq,
192    /// Provider-specific parameters, passed through by name.
193    pub extra: BTreeMap<String, String>,
194}
195
196impl SearchQuery {
197    pub fn new(text: impl Into<String>) -> Self {
198        SearchQuery {
199            text: text.into(),
200            fields: FieldSet::DEFAULT,
201            ..SearchQuery::default()
202        }
203    }
204
205    /// A [`SearchMode::Citation`] query for a reference string.
206    pub fn citation(reference: impl Into<String>) -> Self {
207        SearchQuery {
208            mode: SearchMode::Citation,
209            ..SearchQuery::new(reference)
210        }
211    }
212
213    /// The common filters this query actually uses.
214    pub fn filters(&self) -> Vec<Filter> {
215        [
216            self.years.map(|_| Filter::Years),
217            self.work_type.as_ref().map(|_| Filter::WorkType),
218            self.open_access.map(|_| Filter::OpenAccess),
219        ]
220        .into_iter()
221        .flatten()
222        .collect()
223    }
224}
225
226/// The answer for one requested ID in a batch lookup.
227#[derive(Debug, Clone, PartialEq)]
228pub struct Lookup {
229    /// The ID as requested.
230    pub id: WorkId,
231    /// `None`: the provider doesn't know this ID.
232    pub record: Option<SourceRecord>,
233}
234
235/// A page of works: search hits in rank order, or one side of the citation graph.
236#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
237#[non_exhaustive]
238pub struct Page {
239    pub hits: Vec<Hit>,
240    /// Total matches, if the provider reports it.
241    pub total: Option<u64>,
242    /// `None` on the last page.
243    pub next: Option<Cursor>,
244}
245
246impl Page {
247    pub fn new(hits: Vec<Hit>, total: Option<u64>, next: Option<Cursor>) -> Self {
248        Page { hits, total, next }
249    }
250}
251
252/// One work in a [`Page`].
253#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
254pub struct Hit {
255    pub record: SourceRecord,
256    /// The provider's relevance score, if it gives one. Only comparable
257    /// within one provider's results for one query.
258    pub score: Option<f64>,
259}
260
261impl Hit {
262    pub fn new(record: SourceRecord, score: Option<f64>) -> Self {
263        Hit { record, score }
264    }
265}
266
267/// Usage accounting reported by the provider, in its own units (OpenAlex:
268/// USD). Any part may be unknown.
269#[derive(Debug, Clone, Copy, Default, PartialEq, Serialize, Deserialize)]
270#[non_exhaustive]
271pub struct Usage {
272    /// Spent by this call.
273    pub cost: Option<f64>,
274    /// Left in the current budget period.
275    pub remaining: Option<f64>,
276    /// When the budget resets.
277    pub resets_at: Option<Timestamp>,
278}
279
280impl Usage {
281    /// Usage of this call followed by `later`: costs add up; the remaining
282    /// budget and reset time are the most recent known.
283    pub fn then(self, later: Usage) -> Usage {
284        Usage {
285            cost: match (self.cost, later.cost) {
286                (Some(a), Some(b)) => Some(a + b),
287                (a, b) => a.or(b),
288            },
289            remaining: later.remaining.or(self.remaining),
290            resets_at: later.resets_at.or(self.resets_at),
291        }
292    }
293}
294
295/// A provider result plus the usage it cost.
296#[derive(Debug, Clone, PartialEq)]
297pub struct Response<T> {
298    pub value: T,
299    pub usage: Option<Usage>,
300}
301
302impl<T> Response<T> {
303    pub fn new(value: T) -> Self {
304        Response { value, usage: None }
305    }
306
307    pub fn with_usage(value: T, usage: Usage) -> Self {
308        Response {
309            value,
310            usage: Some(usage),
311        }
312    }
313}
314
315/// A source of scholarly metadata. See the [module docs](self) for the rules
316/// implementations follow.
317///
318/// Operations default to [`Error::Unsupported`]; a provider overrides those
319/// it declares in [`Provider::capabilities`].
320#[async_trait]
321pub trait Provider: Send + Sync {
322    fn id(&self) -> ProviderId;
323
324    fn capabilities(&self) -> &Capabilities;
325
326    /// Looks up works by ID. One [`Lookup`] per input, in input order.
327    /// Callers pass at most `max_batch` IDs, all of a kind in `lookup_kinds`.
328    async fn lookup(&self, ids: &[WorkId], fields: FieldSet) -> Result<Response<Vec<Lookup>>> {
329        let _ = (ids, fields);
330        Err(Error::Unsupported("lookup"))
331    }
332
333    async fn search(&self, query: &SearchQuery) -> Result<Response<Page>> {
334        let _ = query;
335        Err(Error::Unsupported("search"))
336    }
337
338    /// Works that cite `id`.
339    async fn citations(
340        &self,
341        id: &WorkId,
342        page: &PageReq,
343        fields: FieldSet,
344    ) -> Result<Response<Page>> {
345        let _ = (id, page, fields);
346        Err(Error::Unsupported("citations"))
347    }
348
349    /// Works that `id` cites.
350    async fn references(
351        &self,
352        id: &WorkId,
353        page: &PageReq,
354        fields: FieldSet,
355    ) -> Result<Response<Page>> {
356        let _ = (id, page, fields);
357        Err(Error::Unsupported("references"))
358    }
359
360    /// Works similar to `positive` and unlike `negative`.
361    async fn recommend(
362        &self,
363        positive: &[WorkId],
364        negative: &[WorkId],
365        page: &PageReq,
366        fields: FieldSet,
367    ) -> Result<Response<Page>> {
368        let _ = (positive, negative, page, fields);
369        Err(Error::Unsupported("recommend"))
370    }
371}
372
373#[cfg(test)]
374mod tests {
375    use super::*;
376
377    struct Nothing(Capabilities);
378
379    #[async_trait]
380    impl Provider for Nothing {
381        fn id(&self) -> ProviderId {
382            ProviderId::from_static("nothing")
383        }
384
385        fn capabilities(&self) -> &Capabilities {
386            &self.0
387        }
388    }
389
390    #[test]
391    fn usage_adds_costs_and_keeps_latest_budget() {
392        let first = Usage {
393            cost: Some(0.001),
394            remaining: Some(0.9),
395            resets_at: None,
396        };
397        let second = Usage {
398            cost: Some(0.0001),
399            remaining: None,
400            resets_at: None,
401        };
402        let total = first.then(second);
403        assert!((total.cost.unwrap() - 0.0011).abs() < 1e-12);
404        assert_eq!(total.remaining, Some(0.9));
405    }
406
407    #[test]
408    fn provider_ids_are_validated() {
409        assert!(ProviderId::parse("openalex").is_some());
410        assert!(ProviderId::parse("s2-graph").is_some());
411        assert!(ProviderId::parse("OpenAlex").is_none());
412        assert!(ProviderId::parse("").is_none());
413        assert!(serde_json::from_str::<ProviderId>(r#""bad id""#).is_err());
414    }
415
416    #[test]
417    fn query_reports_the_filters_it_uses() {
418        let mut q = SearchQuery::new("transformers");
419        assert!(q.filters().is_empty());
420        q.years = Some(YearRange {
421            from: Some(2017),
422            to: None,
423        });
424        q.open_access = Some(true);
425        assert_eq!(q.filters(), [Filter::Years, Filter::OpenAccess]);
426    }
427
428    #[test]
429    fn unimplemented_operations_are_unsupported_and_dyn_compatible() {
430        let p: Box<dyn Provider> = Box::new(Nothing(Capabilities::default()));
431        let query = SearchQuery::new("x");
432        let result = block_on_ready(p.search(&query));
433        assert!(matches!(result, Err(Error::Unsupported("search"))));
434    }
435
436    /// Polls a future that is immediately ready (no runtime in `core`).
437    fn block_on_ready<F: std::future::Future>(fut: F) -> F::Output {
438        use std::task::{Context, Poll, Waker};
439        let mut fut = std::pin::pin!(fut);
440        match fut.as_mut().poll(&mut Context::from_waker(Waker::noop())) {
441            Poll::Ready(out) => out,
442            Poll::Pending => panic!("future was not immediately ready"),
443        }
444    }
445}
aspero_core/provider.rs

aspero_core/
provider.rs
