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    pub citations: bool,
112    pub references: bool,
113    pub recommend: bool,
114}
115
116/// Common search filters (see [`SearchQuery`]).
117#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
118#[serde(rename_all = "snake_case")]
119#[non_exhaustive]
120pub enum Filter {
121    Years,
122    WorkType,
123    OpenAccess,
124}
125
126/// Inclusive publication-year range; either end may be open.
127#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
128pub struct YearRange {
129    pub from: Option<i16>,
130    pub to: Option<i16>,
131}
132
133/// An opaque, provider-specific continuation token.
134#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
135#[serde(transparent)]
136pub struct Cursor(pub String);
137
138#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
139#[non_exhaustive]
140pub struct PageReq {
141    /// Requested page size. Providers cap it at their own maximum and may
142    /// return fewer, never more.
143    pub limit: u32,
144    /// `None` for the first page.
145    pub cursor: Option<Cursor>,
146}
147
148impl PageReq {
149    pub const DEFAULT_LIMIT: u32 = 25;
150
151    pub fn first(limit: u32) -> Self {
152        PageReq {
153            limit,
154            cursor: None,
155        }
156    }
157}
158
159impl Default for PageReq {
160    fn default() -> Self {
161        PageReq::first(Self::DEFAULT_LIMIT)
162    }
163}
164
165/// How [`SearchQuery::text`] should be interpreted.
166#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Hash, Serialize, Deserialize)]
167#[serde(rename_all = "snake_case")]
168#[non_exhaustive]
169pub enum SearchMode {
170    /// Free-text keywords.
171    #[default]
172    Keywords,
173    /// A whole, possibly messy reference string ("LeCun Y, Bengio Y. Deep
174    /// learning. Nature. 2015"), to be matched to the work it cites. Only
175    /// sent to providers declaring [`Capabilities::citation_search`].
176    Citation,
177}
178
179#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
180#[non_exhaustive]
181pub struct SearchQuery {
182    pub text: String,
183    pub mode: SearchMode,
184    pub years: Option<YearRange>,
185    pub work_type: Option<WorkType>,
186    pub open_access: Option<bool>,
187    pub fields: FieldSet,
188    pub page: PageReq,
189    /// Provider-specific parameters, passed through by name.
190    pub extra: BTreeMap<String, String>,
191}
192
193impl SearchQuery {
194    pub fn new(text: impl Into<String>) -> Self {
195        SearchQuery {
196            text: text.into(),
197            fields: FieldSet::DEFAULT,
198            ..SearchQuery::default()
199        }
200    }
201
202    /// A [`SearchMode::Citation`] query for a reference string.
203    pub fn citation(reference: impl Into<String>) -> Self {
204        SearchQuery {
205            mode: SearchMode::Citation,
206            ..SearchQuery::new(reference)
207        }
208    }
209
210    /// The common filters this query actually uses.
211    pub fn filters(&self) -> Vec<Filter> {
212        [
213            self.years.map(|_| Filter::Years),
214            self.work_type.as_ref().map(|_| Filter::WorkType),
215            self.open_access.map(|_| Filter::OpenAccess),
216        ]
217        .into_iter()
218        .flatten()
219        .collect()
220    }
221}
222
223/// The answer for one requested ID in a batch lookup.
224#[derive(Debug, Clone, PartialEq)]
225pub struct Lookup {
226    /// The ID as requested.
227    pub id: WorkId,
228    /// `None`: the provider doesn't know this ID.
229    pub record: Option<SourceRecord>,
230}
231
232/// A page of works: search hits in rank order, or one side of the citation graph.
233#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
234#[non_exhaustive]
235pub struct Page {
236    pub hits: Vec<Hit>,
237    /// Total matches, if the provider reports it.
238    pub total: Option<u64>,
239    /// `None` on the last page.
240    pub next: Option<Cursor>,
241}
242
243impl Page {
244    pub fn new(hits: Vec<Hit>, total: Option<u64>, next: Option<Cursor>) -> Self {
245        Page { hits, total, next }
246    }
247}
248
249/// One work in a [`Page`].
250#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
251pub struct Hit {
252    pub record: SourceRecord,
253    /// The provider's relevance score, if it gives one. Only comparable
254    /// within one provider's results for one query.
255    pub score: Option<f64>,
256}
257
258impl Hit {
259    pub fn new(record: SourceRecord, score: Option<f64>) -> Self {
260        Hit { record, score }
261    }
262}
263
264/// Usage accounting reported by the provider, in its own units (OpenAlex:
265/// USD). Any part may be unknown.
266#[derive(Debug, Clone, Copy, Default, PartialEq, Serialize, Deserialize)]
267#[non_exhaustive]
268pub struct Usage {
269    /// Spent by this call.
270    pub cost: Option<f64>,
271    /// Left in the current budget period.
272    pub remaining: Option<f64>,
273    /// When the budget resets.
274    pub resets_at: Option<Timestamp>,
275}
276
277impl Usage {
278    /// Usage of this call followed by `later`: costs add up; the remaining
279    /// budget and reset time are the most recent known.
280    pub fn then(self, later: Usage) -> Usage {
281        Usage {
282            cost: match (self.cost, later.cost) {
283                (Some(a), Some(b)) => Some(a + b),
284                (a, b) => a.or(b),
285            },
286            remaining: later.remaining.or(self.remaining),
287            resets_at: later.resets_at.or(self.resets_at),
288        }
289    }
290}
291
292/// A provider result plus the usage it cost.
293#[derive(Debug, Clone, PartialEq)]
294pub struct Response<T> {
295    pub value: T,
296    pub usage: Option<Usage>,
297}
298
299impl<T> Response<T> {
300    pub fn new(value: T) -> Self {
301        Response { value, usage: None }
302    }
303
304    pub fn with_usage(value: T, usage: Usage) -> Self {
305        Response {
306            value,
307            usage: Some(usage),
308        }
309    }
310}
311
312/// A source of scholarly metadata. See the [module docs](self) for the rules
313/// implementations follow.
314///
315/// Operations default to [`Error::Unsupported`]; a provider overrides those
316/// it declares in [`Provider::capabilities`].
317#[async_trait]
318pub trait Provider: Send + Sync {
319    fn id(&self) -> ProviderId;
320
321    fn capabilities(&self) -> &Capabilities;
322
323    /// Looks up works by ID. One [`Lookup`] per input, in input order.
324    /// Callers pass at most `max_batch` IDs, all of a kind in `lookup_kinds`.
325    async fn lookup(&self, ids: &[WorkId], fields: FieldSet) -> Result<Response<Vec<Lookup>>> {
326        let _ = (ids, fields);
327        Err(Error::Unsupported("lookup"))
328    }
329
330    async fn search(&self, query: &SearchQuery) -> Result<Response<Page>> {
331        let _ = query;
332        Err(Error::Unsupported("search"))
333    }
334
335    /// Works that cite `id`.
336    async fn citations(
337        &self,
338        id: &WorkId,
339        page: &PageReq,
340        fields: FieldSet,
341    ) -> Result<Response<Page>> {
342        let _ = (id, page, fields);
343        Err(Error::Unsupported("citations"))
344    }
345
346    /// Works that `id` cites.
347    async fn references(
348        &self,
349        id: &WorkId,
350        page: &PageReq,
351        fields: FieldSet,
352    ) -> Result<Response<Page>> {
353        let _ = (id, page, fields);
354        Err(Error::Unsupported("references"))
355    }
356
357    /// Works similar to `positive` and unlike `negative`.
358    async fn recommend(
359        &self,
360        positive: &[WorkId],
361        negative: &[WorkId],
362        page: &PageReq,
363        fields: FieldSet,
364    ) -> Result<Response<Page>> {
365        let _ = (positive, negative, page, fields);
366        Err(Error::Unsupported("recommend"))
367    }
368}
369
370#[cfg(test)]
371mod tests {
372    use super::*;
373
374    struct Nothing(Capabilities);
375
376    #[async_trait]
377    impl Provider for Nothing {
378        fn id(&self) -> ProviderId {
379            ProviderId::from_static("nothing")
380        }
381
382        fn capabilities(&self) -> &Capabilities {
383            &self.0
384        }
385    }
386
387    #[test]
388    fn usage_adds_costs_and_keeps_latest_budget() {
389        let first = Usage {
390            cost: Some(0.001),
391            remaining: Some(0.9),
392            resets_at: None,
393        };
394        let second = Usage {
395            cost: Some(0.0001),
396            remaining: None,
397            resets_at: None,
398        };
399        let total = first.then(second);
400        assert!((total.cost.unwrap() - 0.0011).abs() < 1e-12);
401        assert_eq!(total.remaining, Some(0.9));
402    }
403
404    #[test]
405    fn provider_ids_are_validated() {
406        assert!(ProviderId::parse("openalex").is_some());
407        assert!(ProviderId::parse("s2-graph").is_some());
408        assert!(ProviderId::parse("OpenAlex").is_none());
409        assert!(ProviderId::parse("").is_none());
410        assert!(serde_json::from_str::<ProviderId>(r#""bad id""#).is_err());
411    }
412
413    #[test]
414    fn query_reports_the_filters_it_uses() {
415        let mut q = SearchQuery::new("transformers");
416        assert!(q.filters().is_empty());
417        q.years = Some(YearRange {
418            from: Some(2017),
419            to: None,
420        });
421        q.open_access = Some(true);
422        assert_eq!(q.filters(), [Filter::Years, Filter::OpenAccess]);
423    }
424
425    #[test]
426    fn unimplemented_operations_are_unsupported_and_dyn_compatible() {
427        let p: Box<dyn Provider> = Box::new(Nothing(Capabilities::default()));
428        let query = SearchQuery::new("x");
429        let result = block_on_ready(p.search(&query));
430        assert!(matches!(result, Err(Error::Unsupported("search"))));
431    }
432
433    /// Polls a future that is immediately ready (no runtime in `core`).
434    fn block_on_ready<F: std::future::Future>(fut: F) -> F::Output {
435        use std::task::{Context, Poll, Waker};
436        let mut fut = std::pin::pin!(fut);
437        match fut.as_mut().poll(&mut Context::from_waker(Waker::noop())) {
438            Poll::Ready(out) => out,
439            Poll::Pending => panic!("future was not immediately ready"),
440        }
441    }
442}
aspero_core/provider.rs

aspero_core/
provider.rs
