1use std::{future::IntoFuture, marker::PhantomData};
13
14use schemars::{JsonSchema, schema_for};
15use serde::de::DeserializeOwned;
16use serde::{Deserialize, Serialize};
17
18use rig_core::wasm_compat::{WasmBoxedFuture, WasmCompatSend};
19use tracing_futures::Instrument;
20
21use super::{
22 Agent,
23 run::{OutputMode, spec::UnhandledInvalidToolCall},
24 runner::AgentRunner,
25};
26use crate::{
27 completion::{Message, StructuredOutputError, Usage},
28 run::response::{CompletionCall, PromptResponse},
29};
30
31#[derive(Debug, Clone, Serialize, Deserialize)]
34pub struct TypedPromptResponse<T> {
35 pub output: T,
37 pub usage: Usage,
40 #[serde(default, skip_serializing_if = "Vec::is_empty")]
47 pub completion_calls: Vec<CompletionCall>,
48 #[serde(default)]
52 pub messages: Vec<Message>,
53 #[serde(default, skip_serializing_if = "Option::is_none")]
56 pub memory_append: Option<crate::run::MemoryAppend>,
57}
58
59impl<T> TypedPromptResponse<T> {
60 pub fn new(output: T, usage: Usage) -> Self {
62 Self {
63 output,
64 usage,
65 completion_calls: Vec::new(),
66 messages: Vec::new(),
67 memory_append: None,
68 }
69 }
70
71 pub fn with_completion_calls(mut self, completion_calls: Vec<CompletionCall>) -> Self {
73 self.completion_calls = completion_calls;
74 self
75 }
76
77 pub fn completion_calls(&self) -> &[CompletionCall] {
82 &self.completion_calls
83 }
84
85 pub fn requests(&self) -> usize {
87 self.completion_calls.len()
88 }
89}
90
91#[derive(Debug, Clone, Copy, PartialEq, Eq)]
93enum OutputSource {
94 Native,
96 OutputTool,
99}
100
101#[derive(Debug)]
104pub struct TypedOutput<T> {
105 source: OutputSource,
106 retries: usize,
107 _t: PhantomData<fn() -> T>,
108}
109
110pub type TypedRun<T> = AgentRunner<TypedOutput<T>>;
117
118impl<T> TypedRun<T>
119where
120 T: JsonSchema + DeserializeOwned + WasmCompatSend,
121{
122 pub(crate) fn native(agent: &Agent, prompt: impl Into<Message>) -> Self {
125 let mut runner = AgentRunner::from_agent(agent, prompt);
126 runner.config.output_schema = Some(schema_for!(T));
127 runner.config.output_mode = OutputMode::Native;
129 Self::from_runner(runner, OutputSource::Native)
130 }
131
132 pub(crate) fn output_tool(runner: AgentRunner) -> Self {
136 Self::from_runner(
137 runner.unhandled_invalid_tool_call(UnhandledInvalidToolCall::Ignore),
138 OutputSource::OutputTool,
139 )
140 }
141
142 fn from_runner(runner: AgentRunner, source: OutputSource) -> Self {
143 let output = TypedOutput {
144 source,
145 retries: 0,
146 _t: PhantomData,
147 };
148 runner.replace_output(output).0
149 }
150
151 pub fn retries(mut self, retries: usize) -> Self {
155 self.output.retries = retries;
156 self
157 }
158
159 async fn send(
160 self,
161 ambient: tracing::Span,
162 ) -> Result<TypedPromptResponse<T>, StructuredOutputError> {
163 let (
164 runner,
165 TypedOutput {
166 source, retries, ..
167 },
168 ) = self.replace_output(());
169 let mut usage = Usage::default();
170 let mut last_error = None;
171
172 for attempt in 0..=retries {
173 if retries > 0 {
174 tracing::debug!(
175 "Attempting to extract structured output. Retries left: {}",
176 retries - attempt
177 );
178 }
179 let (result, error_usage) = runner.clone().run_with_error_usage(ambient.clone()).await;
180 let outcome = match result {
181 Ok(response) => {
182 usage += response.usage;
183 recover_output(&response, source).map(|output| TypedPromptResponse {
184 output,
185 usage,
186 completion_calls: response.completion_calls,
187 messages: response.messages,
188 memory_append: response.memory_append,
189 })
190 }
191 Err(err) => {
192 usage += error_usage;
193 Err(StructuredOutputError::Prompt(err))
194 }
195 };
196 match outcome {
197 Ok(response) => return Ok(response),
198 Err(err) => {
199 if attempt < retries {
200 tracing::warn!(
201 "Attempt {attempt} to extract structured output failed: {err:?}. Retrying..."
202 );
203 }
204 last_error = Some(err);
205 }
206 }
207 }
208
209 Err(last_error.unwrap_or(StructuredOutputError::EmptyResponse))
210 }
211}
212
213fn recover_output<T: DeserializeOwned>(
215 response: &PromptResponse,
216 source: OutputSource,
217) -> Result<T, StructuredOutputError> {
218 let output = response.output();
219 match source {
220 OutputSource::Native => {
221 if output.is_empty() {
222 return Err(StructuredOutputError::EmptyResponse);
223 }
224 deserialize_structured_output(&output)
225 .map_err(|error| deserialization_error(&output, error))
226 }
227 OutputSource::OutputTool => {
228 let submissions = response.output_tool_calls();
229 if submissions == 0
233 && let Ok(value) = serde_json::from_str::<T>(output.trim())
234 {
235 return Ok(value);
236 }
237 if submissions == 0 {
238 tracing::warn!(
239 "The submit tool was not called. If this happens more than once, please ensure the model you are using is powerful enough to reliably call tools."
240 );
241 return Err(StructuredOutputError::EmptyResponse);
242 }
243 if submissions > 1 {
244 tracing::warn!(
245 "Multiple submit calls detected, using the first one. Providers / agents should only ensure one submit call."
246 );
247 }
248 serde_json::from_str(&output).map_err(|error| deserialization_error(&output, error))
249 }
250 }
251}
252
253fn deserialization_error(output: &str, error: serde_json::Error) -> StructuredOutputError {
254 StructuredOutputError::Deserialization {
255 output: output.to_string(),
256 error,
257 }
258}
259
260pub(crate) fn deserialize_structured_output<T: DeserializeOwned>(
263 text: &str,
264) -> Result<T, serde_json::Error> {
265 let trimmed = text.trim();
266 match serde_json::from_str::<T>(trimmed) {
267 Ok(value) => Ok(value),
268 Err(direct_err) => {
269 let Some(start) = trimmed.find(['{', '[']) else {
270 return Err(direct_err);
271 };
272 serde_json::Deserializer::from_str(&trimmed[start..])
273 .into_iter::<T>()
274 .next()
275 .unwrap_or(Err(direct_err))
276 }
277 }
278}
279
280impl<T> IntoFuture for TypedRun<T>
281where
282 T: JsonSchema + DeserializeOwned + WasmCompatSend + 'static,
283{
284 type Output = Result<TypedPromptResponse<T>, StructuredOutputError>;
285 type IntoFuture = WasmBoxedFuture<'static, Self::Output>;
286
287 fn into_future(self) -> Self::IntoFuture {
288 let ambient = tracing::Span::current();
292 let run_under = ambient.clone();
293 Box::pin(self.send(run_under).instrument(ambient))
294 }
295}