1use std::{future::IntoFuture, marker::PhantomData};
13
14use schemars::{JsonSchema, schema_for};
15use serde::de::DeserializeOwned;
16use serde::{Deserialize, Serialize};
17
18use rig_core::structured_output;
19use rig_core::wasm_compat::{WasmBoxedFuture, WasmCompatSend};
20use tracing_futures::Instrument;
21
22use super::{Agent, runner::AgentRunner};
23use crate::{
24 completion::{Message, StructuredOutputError, Usage},
25 run::response::{CompletionCall, PromptResponse},
26 run::{OutputMode, spec::UnhandledInvalidToolCall},
27};
28
29#[derive(Debug, Clone, Serialize, Deserialize)]
32pub struct TypedPromptResponse<T> {
33 pub output: T,
35 pub usage: Usage,
38 #[serde(default, skip_serializing_if = "Vec::is_empty")]
45 pub completion_calls: Vec<CompletionCall>,
46 #[serde(default)]
50 pub messages: Vec<Message>,
51}
52
53impl<T> TypedPromptResponse<T> {
54 pub fn completion_calls(&self) -> &[CompletionCall] {
59 &self.completion_calls
60 }
61
62 pub fn requests(&self) -> usize {
64 self.completion_calls.len()
65 }
66}
67
68#[derive(Debug, Clone, Copy, PartialEq, Eq)]
70enum OutputSource {
71 Native,
73 OutputTool,
76}
77
78#[derive(Debug)]
81pub struct TypedOutput<T> {
82 source: OutputSource,
83 retries: usize,
84 _t: PhantomData<fn() -> T>,
85}
86
87pub type TypedRun<T> = AgentRunner<TypedOutput<T>>;
94
95impl<T> TypedRun<T>
96where
97 T: JsonSchema + DeserializeOwned + WasmCompatSend,
98{
99 pub(crate) fn native(agent: &Agent, prompt: impl Into<Message>) -> Self {
102 let mut runner = AgentRunner::from_agent(agent, prompt);
103 runner.config.spec_mut().output_schema = Some(schema_for!(T));
104 runner.config.spec_mut().output_mode = OutputMode::Native;
106 Self::from_runner(runner, OutputSource::Native)
107 }
108
109 pub(crate) fn output_tool(runner: AgentRunner) -> Self {
113 Self::from_runner(
114 runner.unhandled_invalid_tool_call(UnhandledInvalidToolCall::Ignore),
115 OutputSource::OutputTool,
116 )
117 }
118
119 fn from_runner(runner: AgentRunner, source: OutputSource) -> Self {
120 let output = TypedOutput {
121 source,
122 retries: 0,
123 _t: PhantomData,
124 };
125 runner.replace_output(output).0
126 }
127
128 pub fn retries(mut self, retries: usize) -> Self {
132 self.output.retries = retries;
133 self
134 }
135
136 async fn send(
137 self,
138 ambient: tracing::Span,
139 ) -> Result<TypedPromptResponse<T>, StructuredOutputError> {
140 let (
141 runner,
142 TypedOutput {
143 source, retries, ..
144 },
145 ) = self.replace_output(());
146 let mut usage = Usage::default();
147 let mut last_error = None;
148
149 for attempt in 0..=retries {
150 if retries > 0 {
151 tracing::debug!(
152 "Attempting to extract structured output. Retries left: {}",
153 retries - attempt
154 );
155 }
156 let (result, attempt_usage) =
157 runner.clone().run_with_error_usage(ambient.clone()).await;
158 if attempt_usage != Usage::default() {
160 usage += attempt_usage;
161 }
162 let outcome = match result {
163 Ok(response) => {
164 recover_output(&response, source).map(|output| TypedPromptResponse {
165 output,
166 usage,
167 completion_calls: response.completion_calls,
168 messages: response.messages,
169 })
170 }
171 Err(err) => Err(StructuredOutputError::Prompt(err)),
172 };
173 match outcome {
174 Ok(response) => return Ok(response),
175 Err(err) => {
176 if attempt < retries {
177 tracing::warn!(
178 "Attempt {attempt} to extract structured output failed: {err:?}. Retrying..."
179 );
180 }
181 last_error = Some(err);
182 }
183 }
184 }
185
186 Err(last_error.unwrap_or(StructuredOutputError::EmptyResponse))
187 }
188}
189
190fn recover_output<T: DeserializeOwned>(
192 response: &PromptResponse,
193 source: OutputSource,
194) -> Result<T, StructuredOutputError> {
195 let output = response.output();
196 match source {
197 OutputSource::Native => {
198 if output.is_empty() {
199 return Err(StructuredOutputError::EmptyResponse);
200 }
201 structured_output::json_in_text(&output)
202 .map_err(|error| deserialization_error(&output, error))
203 }
204 OutputSource::OutputTool => {
205 let submissions = response.output_tool_calls();
206 if submissions == 0
210 && let Ok(value) = serde_json::from_str::<T>(output.trim())
211 {
212 return Ok(value);
213 }
214 if submissions == 0 {
215 tracing::warn!(
216 "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."
217 );
218 return Err(StructuredOutputError::EmptyResponse);
219 }
220 if submissions > 1 {
221 tracing::warn!(
222 "Multiple submit calls detected, using the first one. Providers / agents should only ensure one submit call."
223 );
224 }
225 serde_json::from_str(&output).map_err(|error| deserialization_error(&output, error))
226 }
227 }
228}
229
230fn deserialization_error(output: &str, error: serde_json::Error) -> StructuredOutputError {
231 StructuredOutputError::Deserialization {
232 output: output.to_string(),
233 error,
234 }
235}
236
237impl<T> IntoFuture for TypedRun<T>
238where
239 T: JsonSchema + DeserializeOwned + WasmCompatSend + 'static,
240{
241 type Output = Result<TypedPromptResponse<T>, StructuredOutputError>;
242 type IntoFuture = WasmBoxedFuture<'static, Self::Output>;
243
244 fn into_future(self) -> Self::IntoFuture {
245 let ambient = tracing::Span::current();
249 let run_under = ambient.clone();
250 Box::pin(self.send(run_under).instrument(ambient))
251 }
252}