Skip to main content

rig_core/completion/message/
citation.rs

1//! What a provider says supports an answer text. A [`Citation`] lives on the
2//! [`Text`] it cites, with a byte [`Span`] into that text or none for the
3//! whole block, and the [`Source`]s behind it. The list is bound to the text
4//! it was resolved against: once the text is edited, [`Text::citations`]
5//! reads empty.
6//!
7//! Decoders never build a span: they hand the fold a
8//! [`WireCitation`] whose span names its unit, and
9//! the fold resolves it to bytes when the text block closes.
10//!
11//! ```
12//! use rig_core::message::{Citation, Source, SourceLocation, Text};
13//!
14//! let text = Text::new("Dock Seven is open.");
15//! let span = text.span(0..10).ok_or("on a character boundary")?;
16//! let mut citation = Citation::new([Source::new(SourceLocation::Url {
17//!     url: "https://example.com/docks".to_owned(),
18//! })]);
19//! citation.span = Some(span);
20//! let text = text.with_citations([citation]);
21//! assert_eq!(text.cited(&text.citations()[0]), Some("Dock Seven"));
22//! # Ok::<(), &str>(())
23//! ```
24
25use std::ops::Range;
26
27use serde::{Deserialize, Serialize};
28
29use super::{Fingerprint, Text};
30use crate::wire::{SpanUnit, WireCitation, WireSpan};
31
32/// A claim in a text and the sources that support it.
33#[non_exhaustive]
34#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
35pub struct Citation {
36    /// The bytes of the text it covers; `None` for the whole block.
37    #[serde(default, skip_serializing_if = "Option::is_none")]
38    pub span: Option<Span>,
39    /// What supports the claim.
40    #[serde(default)]
41    pub sources: Vec<Source>,
42}
43
44impl Citation {
45    /// A citation of the whole block by `sources`.
46    pub fn new(sources: impl IntoIterator<Item = Source>) -> Self {
47        Self {
48            span: None,
49            sources: sources.into_iter().collect(),
50        }
51    }
52}
53
54/// A byte range of a text, on character boundaries. The fold and
55/// [`Text::span`] make one, and stored history deserializes one;
56/// [`Text::with_citations`] drops any that is off a character boundary of
57/// its text.
58#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
59pub struct Span {
60    start: usize,
61    end: usize,
62}
63
64impl Span {
65    /// The first byte.
66    pub fn start(&self) -> usize {
67        self.start
68    }
69
70    /// The byte after the last.
71    pub fn end(&self) -> usize {
72        self.end
73    }
74
75    /// `start..end`.
76    pub fn range(&self) -> Range<usize> {
77        self.start..self.end
78    }
79}
80
81/// One source of a citation.
82#[non_exhaustive]
83#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
84pub struct Source {
85    /// Where the source is.
86    pub location: SourceLocation,
87    /// The source's title.
88    #[serde(default, skip_serializing_if = "Option::is_none")]
89    pub title: Option<String>,
90    /// The passage of the source the provider quoted.
91    #[serde(default, skip_serializing_if = "Option::is_none")]
92    pub cited_text: Option<String>,
93    /// The provider's confidence, 0 to 1.
94    #[serde(default, skip_serializing_if = "Option::is_none")]
95    pub confidence: Option<f32>,
96}
97
98impl Source {
99    /// A source at `location` with no title, quote or confidence.
100    pub fn new(location: SourceLocation) -> Self {
101        Self {
102            location,
103            title: None,
104            cited_text: None,
105            confidence: None,
106        }
107    }
108
109    /// Set the title.
110    pub fn title(mut self, title: impl Into<String>) -> Self {
111        self.title = Some(title.into());
112        self
113    }
114
115    /// Set the quoted passage of the source.
116    pub fn cited_text(mut self, text: impl Into<String>) -> Self {
117        self.cited_text = Some(text.into());
118        self
119    }
120
121    /// Set the provider's confidence.
122    pub fn confidence(mut self, confidence: f32) -> Self {
123        self.confidence = Some(confidence);
124        self
125    }
126}
127
128/// Where a cited source is.
129#[non_exhaustive]
130#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
131#[serde(tag = "type", rename_all = "snake_case")]
132pub enum SourceLocation {
133    /// A document of the request, by position or id, and where in it.
134    Document {
135        /// The document's position in the request.
136        #[serde(default, skip_serializing_if = "Option::is_none")]
137        index: Option<u32>,
138        /// The document's id.
139        #[serde(default, skip_serializing_if = "Option::is_none")]
140        id: Option<String>,
141        /// The part of the document cited.
142        #[serde(default, skip_serializing_if = "Option::is_none")]
143        within: Option<DocumentRange>,
144    },
145    /// A web page.
146    Url {
147        /// The page's address.
148        url: String,
149    },
150    /// A file the provider stores.
151    File {
152        /// The provider's file id.
153        file_id: String,
154        /// The file's name.
155        #[serde(default, skip_serializing_if = "Option::is_none")]
156        filename: Option<String>,
157        /// The container holding the file.
158        #[serde(default, skip_serializing_if = "Option::is_none")]
159        container_id: Option<String>,
160    },
161    /// A search result the request supplied.
162    SearchResult {
163        /// The result's position in the request.
164        index: u32,
165        /// The result's source, as the request named it.
166        source: String,
167        /// The content blocks of the result cited.
168        #[serde(default, skip_serializing_if = "Option::is_none")]
169        blocks: Option<Range<u32>>,
170    },
171    /// A tool's output.
172    ToolOutput {
173        /// The tool call or output id.
174        id: String,
175    },
176}
177
178/// The part of a document a citation covers.
179#[non_exhaustive]
180#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
181#[serde(tag = "unit", rename_all = "snake_case")]
182pub enum DocumentRange {
183    /// Characters of the document's text.
184    Chars(Range<u64>),
185    /// Pages, from 1, the end exclusive.
186    Pages(Range<u32>),
187    /// Content blocks or chunks.
188    Blocks(Range<u32>),
189}
190
191/// The citations of one text and the fingerprint of the text they fit.
192#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
193pub(super) struct Citations {
194    fingerprint: Fingerprint,
195    list: Vec<Citation>,
196}
197
198fn fingerprint(text: &str) -> Fingerprint {
199    Fingerprint::of(&text)
200}
201
202/// Whether `citation`'s span lies on character boundaries of `text`.
203fn fits(text: &str, citation: &Citation) -> bool {
204    citation
205        .span
206        .is_none_or(|span| text.get(span.range()).is_some())
207}
208
209impl Text {
210    /// The citations, while `text` is what they were resolved against;
211    /// empty once it has been edited.
212    pub fn citations(&self) -> &[Citation] {
213        match &self.citations {
214            Some(citations) if citations.fingerprint == fingerprint(&self.text) => &citations.list,
215            _ => &[],
216        }
217    }
218
219    /// This text with `citations`, bound to its current text. A citation
220    /// whose span is off a character boundary or past the end is dropped
221    /// with a warning.
222    pub fn with_citations(mut self, citations: impl IntoIterator<Item = Citation>) -> Self {
223        let list = citations
224            .into_iter()
225            .filter(|citation| {
226                let fits = fits(&self.text, citation);
227                if !fits {
228                    tracing::warn!(
229                        span = ?citation.span,
230                        "dropped a citation whose span does not fit its text"
231                    );
232                }
233                fits
234            })
235            .collect();
236        self.bind(list);
237        self
238    }
239
240    /// The text `citation` covers: its span, or the whole block. It reads
241    /// any citation against the current text and does not check that the
242    /// citation belongs to it, so a citation kept from before an edit gives
243    /// whatever text now sits at its span, or `None` past the end. Read
244    /// citations through [`Text::citations`], which hides them once the
245    /// text changes.
246    pub fn cited(&self, citation: &Citation) -> Option<&str> {
247        match citation.span {
248            Some(span) => self.text.get(span.range()),
249            None => Some(&self.text),
250        }
251    }
252
253    /// A span over `range`, in bytes of this text; `None` when either end
254    /// is off a character boundary or past the end, or `range` is reversed.
255    pub fn span(&self, range: Range<usize>) -> Option<Span> {
256        self.text.get(range.clone()).map(|_| Span {
257            start: range.start,
258            end: range.end,
259        })
260    }
261
262    fn bind(&mut self, list: Vec<Citation>) {
263        self.citations = (!list.is_empty()).then(|| Citations {
264            fingerprint: fingerprint(&self.text),
265            list,
266        });
267    }
268
269    /// Stored citations whose spans do not fit the stored text are dropped.
270    pub(super) fn checked(mut self) -> Self {
271        if let Some(citations) = &mut self.citations {
272            citations.list.retain(|citation| fits(&self.text, citation));
273            if citations.list.is_empty() {
274                self.citations = None;
275            }
276        }
277        self
278    }
279}
280
281/// Attach `wire` to `text`, the block the provider's item at `index` became:
282/// each span resolved to bytes of the text, after `kept`, the citations the
283/// block holds already. A span that does not resolve, or covers other text
284/// than the provider quoted, drops its citation with a warning; a citation
285/// never fails a reply. The completion fold is the only caller.
286pub(crate) fn attach(
287    text: &mut Text,
288    kept: Vec<Citation>,
289    wire: Vec<WireCitation>,
290    provider: &str,
291    index: usize,
292) {
293    let mut list = kept;
294    for citation in wire {
295        let WireCitation { span, sources } = citation;
296        let span = match span.map(|span| resolve(&text.text, &span)).transpose() {
297            Ok(span) => span,
298            Err(reason) => {
299                tracing::warn!(provider, index, reason, "dropped a citation");
300                continue;
301            }
302        };
303        list.push(Citation { span, sources });
304    }
305    text.bind(list);
306}
307
308/// The byte span `span` names in `text`.
309fn resolve(text: &str, span: &WireSpan) -> Result<Span, &'static str> {
310    let wire = |offset: u64| usize::try_from(offset).ok();
311    let (Some(start), Some(end)) = (wire(span.start), wire(span.end)) else {
312        return Err("the span is past the end of the text");
313    };
314    let byte = |offset: usize| match span.unit {
315        SpanUnit::Bytes => Some(offset),
316        SpanUnit::Chars => char_offset(text, offset),
317        SpanUnit::Utf16 => utf16_offset(text, offset),
318    };
319    let (Some(start), Some(end)) = (byte(start), byte(end)) else {
320        return Err("the span is past the end of the text or splits a character");
321    };
322    let Some(covered) = text.get(start..end) else {
323        return Err("the span is reversed, past the end of the text or splits a character");
324    };
325    if span
326        .quoted
327        .as_deref()
328        .is_some_and(|quoted| quoted != covered)
329    {
330        return Err("the span covers other text than the provider quoted");
331    }
332    Ok(Span { start, end })
333}
334
335/// The byte offset of the `chars`th character of `text`.
336fn char_offset(text: &str, chars: usize) -> Option<usize> {
337    text.char_indices()
338        .map(|(at, _)| at)
339        .chain(std::iter::once(text.len()))
340        .nth(chars)
341}
342
343/// The byte offset of the `units`th UTF-16 code unit of `text`, if it
344/// starts a character.
345fn utf16_offset(text: &str, units: usize) -> Option<usize> {
346    let mut seen = 0;
347    for (at, character) in text.char_indices() {
348        if seen == units {
349            return Some(at);
350        }
351        if seen > units {
352            return None;
353        }
354        seen += character.len_utf16();
355    }
356    (seen == units).then_some(text.len())
357}
358
359#[cfg(test)]
360mod tests;