Skip to main content

rig_core/providers/gemini/streaming/
document.rs

1//! The GenerateContent reassembler: a `streamGenerateContent` reply's chunks
2//! rebuilt into the `generateContent` body the same turn has unary. The
3//! REST, Vertex AI and gRPC wires share it, each over its chunks' REST JSON.
4//!
5//! ```
6//! use rig_core::providers::gemini::streaming::GenerateContentChunk;
7//! use rig_core::providers::gemini::streaming::document::GenerateContentResponse;
8//! use rig_core::wire::document::Reassemble;
9//! use serde_json::json;
10//!
11//! let mut document = GenerateContentResponse::default();
12//! for text in ["Hel", "lo"] {
13//!     let chunk = json!({"candidates": [{"content": {"parts": [{"text": text}], "role": "model"}, "index": 0}]});
14//!     document.absorb(&GenerateContentChunk(chunk.as_object().cloned().unwrap_or_default()));
15//! }
16//! assert_eq!(document.finish()["candidates"][0]["content"]["parts"], json!([{"text": "Hello"}]));
17//! ```
18
19use serde_json::{Map, Value};
20
21use super::{GenerateContentChunk, merge_part};
22use crate::json_utils::Lenient;
23use crate::wire::document::{Reassemble, keep, slot};
24
25/// The `generateContent` body a stream of chunks adds up to.
26///
27/// Candidates are kept by their `index`. Their parts append, and a text
28/// part continues the text part before it while `thought` stays the same,
29/// as the unary body states a run of text as one part: its text appends,
30/// a signature joins it unless both carry one, and its other fields
31/// replace. An empty text part with no signature carries nothing. A part
32/// that holds only a signature joins the part before it.
33/// `citationMetadata.citationSources` append. `promptFeedback` keeps its
34/// first value; every other field keeps its last non-null one, and a
35/// `null` only fills an absent field. A reply with no chunk has no
36/// document.
37#[derive(Debug, Default)]
38pub struct GenerateContentResponse {
39    document: Map<String, Value>,
40    /// The `index` of each candidate held, in order.
41    indices: Vec<u64>,
42    /// Signatures that arrived alone before any part of their candidate,
43    /// which the candidate's next part takes.
44    signatures: Vec<(u64, String)>,
45}
46
47impl GenerateContentResponse {
48    /// Fold one streamed candidate into the candidate of its `index`.
49    fn candidate(&mut self, position: usize, candidate: &Value) {
50        let Value::Object(candidate) = candidate else {
51            return;
52        };
53        let index = candidate
54            .get("index")
55            .and_then(Value::as_u64)
56            .unwrap_or(position as u64);
57        let candidates = slot(&mut self.document, "candidates", Value::Array);
58        let Value::Array(candidates) = candidates else {
59            return;
60        };
61        let at = match self.indices.iter().position(|held| *held == index) {
62            Some(at) => at,
63            None => {
64                self.indices.push(index);
65                candidates.push(Value::Object(Map::new()));
66                candidates.len() - 1
67            }
68        };
69        let Some(Value::Object(held)) = candidates.get_mut(at) else {
70            return;
71        };
72        for (key, value) in candidate {
73            match (key.as_str(), value) {
74                ("content", Value::Object(content)) => {
75                    if let Value::Object(held) = slot(held, "content", Value::Object) {
76                        content_into(held, content, index, &mut self.signatures);
77                    }
78                }
79                ("citationMetadata", Value::Object(citations)) => {
80                    if let Value::Object(held) = slot(held, "citationMetadata", Value::Object) {
81                        for (key, value) in citations {
82                            match (key.as_str(), held.get_mut(key), value) {
83                                (
84                                    "citationSources",
85                                    Some(Value::Array(sources)),
86                                    Value::Array(more),
87                                ) => {
88                                    sources.extend(more.iter().cloned());
89                                }
90                                (_, _, value) => keep(held, key, value),
91                            }
92                        }
93                    }
94                }
95                (_, value) => keep(held, key, value),
96            }
97        }
98    }
99}
100
101/// Fold a streamed candidate's `content` into the content held so far.
102fn content_into(
103    held: &mut Map<String, Value>,
104    content: &Map<String, Value>,
105    index: u64,
106    signatures: &mut Vec<(u64, String)>,
107) {
108    for (key, value) in content {
109        let Value::Array(more) = value else {
110            keep(held, key, value);
111            continue;
112        };
113        if key != "parts" {
114            keep(held, key, value);
115            continue;
116        }
117        let Value::Array(parts) = slot(held, "parts", Value::Array) else {
118            return;
119        };
120        for part in more {
121            part_into(parts, part, index, signatures);
122        }
123    }
124}
125
126/// Append one streamed part to a candidate's parts, joining the part before
127/// it where the unary body states them as one.
128fn part_into(
129    parts: &mut Vec<Value>,
130    part: &Value,
131    index: u64,
132    signatures: &mut Vec<(u64, String)>,
133) {
134    let signature = super::signature(part).map(str::to_owned);
135    if let Some(text) = part.str("text") {
136        if text.is_empty() && signature.is_none() {
137            return;
138        }
139        let thought = part.bool("thought") == Some(true);
140        if let Some(last) = parts.last_mut()
141            && last.str("text").is_some()
142            && (last.bool("thought") == Some(true)) == thought
143            && !(super::signature(last).is_some() && signature.is_some())
144        {
145            merge_part(last, part);
146            return;
147        }
148    } else if let Value::Object(fields) = part
149        && super::is_bare(fields)
150        && let Some(signature) = signature
151    {
152        match parts.last_mut().and_then(Value::as_object_mut) {
153            Some(last) => {
154                last.insert("thoughtSignature".to_owned(), Value::String(signature));
155            }
156            None => signatures.push((index, signature)),
157        }
158        return;
159    }
160    let mut part = part.clone();
161    if let Some(at) = signatures.iter().position(|(held, _)| *held == index)
162        && let Some(fields) = part.as_object_mut()
163    {
164        let (_, signature) = signatures.remove(at);
165        fields
166            .entry("thoughtSignature")
167            .or_insert(Value::String(signature));
168    }
169    parts.push(part);
170}
171
172impl crate::wire::document::Serves<crate::operation::Completion> for GenerateContentResponse {}
173
174/// Each chunk in REST JSON; the document is `Null` when there were none.
175impl Reassemble<GenerateContentChunk> for GenerateContentResponse {
176    fn absorb(&mut self, GenerateContentChunk(chunk): &GenerateContentChunk) {
177        for (key, value) in chunk {
178            match (key.as_str(), value) {
179                ("candidates", Value::Array(candidates)) => {
180                    for (position, candidate) in candidates.iter().enumerate() {
181                        self.candidate(position, candidate);
182                    }
183                }
184                // Candidates of another type fail the decoder; the document
185                // keeps the ones it holds.
186                ("candidates", _) => {}
187                ("promptFeedback", value) => {
188                    if self.document.get(key).is_none_or(Value::is_null) {
189                        self.document.insert(key.clone(), value.clone());
190                    }
191                }
192                (_, value) => keep(&mut self.document, key, value),
193            }
194        }
195    }
196
197    fn finish(self) -> Value {
198        if self.document.is_empty() {
199            Value::Null
200        } else {
201            Value::Object(self.document)
202        }
203    }
204}
205
206#[cfg(test)]
207mod tests;