rig_core/completion/message/
citation.rs1use std::ops::Range;
26
27use serde::{Deserialize, Serialize};
28
29use super::{Fingerprint, Text};
30use crate::wire::{SpanUnit, WireCitation, WireSpan};
31
32#[non_exhaustive]
34#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
35pub struct Citation {
36 #[serde(default, skip_serializing_if = "Option::is_none")]
38 pub span: Option<Span>,
39 #[serde(default)]
41 pub sources: Vec<Source>,
42}
43
44impl Citation {
45 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#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
59pub struct Span {
60 start: usize,
61 end: usize,
62}
63
64impl Span {
65 pub fn start(&self) -> usize {
67 self.start
68 }
69
70 pub fn end(&self) -> usize {
72 self.end
73 }
74
75 pub fn range(&self) -> Range<usize> {
77 self.start..self.end
78 }
79}
80
81#[non_exhaustive]
83#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
84pub struct Source {
85 pub location: SourceLocation,
87 #[serde(default, skip_serializing_if = "Option::is_none")]
89 pub title: Option<String>,
90 #[serde(default, skip_serializing_if = "Option::is_none")]
92 pub cited_text: Option<String>,
93 #[serde(default, skip_serializing_if = "Option::is_none")]
95 pub confidence: Option<f32>,
96}
97
98impl Source {
99 pub fn new(location: SourceLocation) -> Self {
101 Self {
102 location,
103 title: None,
104 cited_text: None,
105 confidence: None,
106 }
107 }
108
109 pub fn title(mut self, title: impl Into<String>) -> Self {
111 self.title = Some(title.into());
112 self
113 }
114
115 pub fn cited_text(mut self, text: impl Into<String>) -> Self {
117 self.cited_text = Some(text.into());
118 self
119 }
120
121 pub fn confidence(mut self, confidence: f32) -> Self {
123 self.confidence = Some(confidence);
124 self
125 }
126}
127
128#[non_exhaustive]
130#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
131#[serde(tag = "type", rename_all = "snake_case")]
132pub enum SourceLocation {
133 Document {
135 #[serde(default, skip_serializing_if = "Option::is_none")]
137 index: Option<u32>,
138 #[serde(default, skip_serializing_if = "Option::is_none")]
140 id: Option<String>,
141 #[serde(default, skip_serializing_if = "Option::is_none")]
143 within: Option<DocumentRange>,
144 },
145 Url {
147 url: String,
149 },
150 File {
152 file_id: String,
154 #[serde(default, skip_serializing_if = "Option::is_none")]
156 filename: Option<String>,
157 #[serde(default, skip_serializing_if = "Option::is_none")]
159 container_id: Option<String>,
160 },
161 SearchResult {
163 index: u32,
165 source: String,
167 #[serde(default, skip_serializing_if = "Option::is_none")]
169 blocks: Option<Range<u32>>,
170 },
171 ToolOutput {
173 id: String,
175 },
176}
177
178#[non_exhaustive]
180#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
181#[serde(tag = "unit", rename_all = "snake_case")]
182pub enum DocumentRange {
183 Chars(Range<u64>),
185 Pages(Range<u32>),
187 Blocks(Range<u32>),
189}
190
191#[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
202fn 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 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 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 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 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 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
281pub(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
308fn 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
335fn 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
343fn 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;