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::{Agent, runner::AgentRunner};
22use crate::{
23 completion::{Message, StructuredOutputError, Usage},
24 run::response::{CompletionCall, PromptResponse},
25 run::{OutputMode, spec::UnhandledInvalidToolCall},
26};
27
28#[derive(Debug, Clone, Serialize, Deserialize)]
31pub struct TypedPromptResponse<T> {
32 pub output: T,
34 pub usage: Usage,
37 #[serde(default, skip_serializing_if = "Vec::is_empty")]
44 pub completion_calls: Vec<CompletionCall>,
45 #[serde(default)]
49 pub messages: Vec<Message>,
50}
51
52impl<T> TypedPromptResponse<T> {
53 pub fn new(output: T, usage: Usage) -> Self {
55 Self {
56 output,
57 usage,
58 completion_calls: Vec::new(),
59 messages: Vec::new(),
60 }
61 }
62
63 pub fn with_completion_calls(mut self, completion_calls: Vec<CompletionCall>) -> Self {
65 self.completion_calls = completion_calls;
66 self
67 }
68
69 pub fn completion_calls(&self) -> &[CompletionCall] {
74 &self.completion_calls
75 }
76
77 pub fn requests(&self) -> usize {
79 self.completion_calls.len()
80 }
81}
82
83#[derive(Debug, Clone, Copy, PartialEq, Eq)]
85enum OutputSource {
86 Native,
88 OutputTool,
91}
92
93#[derive(Debug)]
96pub struct TypedOutput<T> {
97 source: OutputSource,
98 retries: usize,
99 _t: PhantomData<fn() -> T>,
100}
101
102pub type TypedRun<T> = AgentRunner<TypedOutput<T>>;
109
110impl<T> TypedRun<T>
111where
112 T: JsonSchema + DeserializeOwned + WasmCompatSend,
113{
114 pub(crate) fn native(agent: &Agent, prompt: impl Into<Message>) -> Self {
117 let mut runner = AgentRunner::from_agent(agent, prompt);
118 runner.config.spec_mut().output_schema = Some(schema_for!(T));
119 runner.config.spec_mut().output_mode = OutputMode::Native;
121 Self::from_runner(runner, OutputSource::Native)
122 }
123
124 pub(crate) fn output_tool(runner: AgentRunner) -> Self {
128 Self::from_runner(
129 runner.unhandled_invalid_tool_call(UnhandledInvalidToolCall::Ignore),
130 OutputSource::OutputTool,
131 )
132 }
133
134 fn from_runner(runner: AgentRunner, source: OutputSource) -> Self {
135 let output = TypedOutput {
136 source,
137 retries: 0,
138 _t: PhantomData,
139 };
140 runner.replace_output(output).0
141 }
142
143 pub fn retries(mut self, retries: usize) -> Self {
147 self.output.retries = retries;
148 self
149 }
150
151 async fn send(
152 self,
153 ambient: tracing::Span,
154 ) -> Result<TypedPromptResponse<T>, StructuredOutputError> {
155 let (
156 runner,
157 TypedOutput {
158 source, retries, ..
159 },
160 ) = self.replace_output(());
161 let mut usage = Usage::default();
162 let mut last_error = None;
163
164 for attempt in 0..=retries {
165 if retries > 0 {
166 tracing::debug!(
167 "Attempting to extract structured output. Retries left: {}",
168 retries - attempt
169 );
170 }
171 let (result, error_usage) = runner.clone().run_with_error_usage(ambient.clone()).await;
172 let outcome = match result {
173 Ok(response) => {
174 usage += response.usage;
175 recover_output(&response, source).map(|output| TypedPromptResponse {
176 output,
177 usage,
178 completion_calls: response.completion_calls,
179 messages: response.messages,
180 })
181 }
182 Err(err) => {
183 usage += error_usage;
184 Err(StructuredOutputError::Prompt(err))
185 }
186 };
187 match outcome {
188 Ok(response) => return Ok(response),
189 Err(err) => {
190 if attempt < retries {
191 tracing::warn!(
192 "Attempt {attempt} to extract structured output failed: {err:?}. Retrying..."
193 );
194 }
195 last_error = Some(err);
196 }
197 }
198 }
199
200 Err(last_error.unwrap_or(StructuredOutputError::EmptyResponse))
201 }
202}
203
204fn recover_output<T: DeserializeOwned>(
206 response: &PromptResponse,
207 source: OutputSource,
208) -> Result<T, StructuredOutputError> {
209 let output = response.output();
210 match source {
211 OutputSource::Native => {
212 if output.is_empty() {
213 return Err(StructuredOutputError::EmptyResponse);
214 }
215 deserialize_structured_output(&output)
216 .map_err(|error| deserialization_error(&output, error))
217 }
218 OutputSource::OutputTool => {
219 let submissions = response.output_tool_calls();
220 if submissions == 0
224 && let Ok(value) = serde_json::from_str::<T>(output.trim())
225 {
226 return Ok(value);
227 }
228 if submissions == 0 {
229 tracing::warn!(
230 "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."
231 );
232 return Err(StructuredOutputError::EmptyResponse);
233 }
234 if submissions > 1 {
235 tracing::warn!(
236 "Multiple submit calls detected, using the first one. Providers / agents should only ensure one submit call."
237 );
238 }
239 serde_json::from_str(&output).map_err(|error| deserialization_error(&output, error))
240 }
241 }
242}
243
244fn deserialization_error(output: &str, error: serde_json::Error) -> StructuredOutputError {
245 StructuredOutputError::Deserialization {
246 output: output.to_string(),
247 error,
248 }
249}
250
251pub(crate) fn deserialize_structured_output<T: DeserializeOwned>(
254 text: &str,
255) -> Result<T, serde_json::Error> {
256 let trimmed = text.trim();
257 match serde_json::from_str::<T>(trimmed) {
258 Ok(value) => Ok(value),
259 Err(direct_err) => {
260 let Some(start) = trimmed.find(['{', '[']) else {
261 return Err(direct_err);
262 };
263 serde_json::Deserializer::from_str(&trimmed[start..])
264 .into_iter::<T>()
265 .next()
266 .unwrap_or(Err(direct_err))
267 }
268 }
269}
270
271impl<T> IntoFuture for TypedRun<T>
272where
273 T: JsonSchema + DeserializeOwned + WasmCompatSend + 'static,
274{
275 type Output = Result<TypedPromptResponse<T>, StructuredOutputError>;
276 type IntoFuture = WasmBoxedFuture<'static, Self::Output>;
277
278 fn into_future(self) -> Self::IntoFuture {
279 let ambient = tracing::Span::current();
283 let run_under = ambient.clone();
284 Box::pin(self.send(run_under).instrument(ambient))
285 }
286}