use std::{future::IntoFuture, marker::PhantomData};
use schemars::{JsonSchema, schema_for};
use serde::de::DeserializeOwned;
use serde::{Deserialize, Serialize};
use rig_core::wasm_compat::{WasmBoxedFuture, WasmCompatSend};
use tracing_futures::Instrument;
use super::{
Agent,
hook::AgentHook,
run::{OutputMode, spec::UnhandledInvalidToolCall},
runner::AgentRunner,
};
use crate::{
completion::{Message, StructuredOutputError, Usage},
run::response::{CompletionCall, PromptResponse},
tool::ToolContext,
};
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct TypedPromptResponse<T> {
pub output: T,
pub usage: Usage,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub completion_calls: Vec<CompletionCall>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub memory_append: Option<crate::run::MemoryAppend>,
}
impl<T> TypedPromptResponse<T> {
pub fn new(output: T, usage: Usage) -> Self {
Self {
output,
usage,
completion_calls: Vec::new(),
memory_append: None,
}
}
pub fn with_completion_calls(mut self, completion_calls: Vec<CompletionCall>) -> Self {
self.completion_calls = completion_calls;
self
}
pub fn completion_calls(&self) -> &[CompletionCall] {
&self.completion_calls
}
pub fn requests(&self) -> usize {
self.completion_calls.len()
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum TypedOutput {
Native,
OutputTool,
}
#[must_use = "a typed run does nothing until awaited"]
pub struct TypedRun<T> {
runner: AgentRunner,
retries: u64,
output: TypedOutput,
_t: PhantomData<T>,
}
macro_rules! forward_runner_setters {
() => {
pub fn tool_context(mut self, context: ToolContext) -> Self {
self.runner = self.runner.tool_context(context);
self
}
pub fn history<H, Item>(mut self, history: H) -> Self
where
H: IntoIterator<Item = Item>,
Item: Into<Message>,
{
self.runner = self.runner.history(history);
self
}
pub fn preamble(mut self, preamble: impl Into<String>) -> Self {
self.runner = self.runner.preamble(preamble);
self
}
pub fn without_preamble(mut self) -> Self {
self.runner = self.runner.without_preamble();
self
}
pub fn document(mut self, document: crate::completion::Document) -> Self {
self.runner = self.runner.document(document);
self
}
pub fn documents(
mut self,
documents: impl IntoIterator<Item = crate::completion::Document>,
) -> Self {
self.runner = self.runner.documents(documents);
self
}
pub fn temperature(mut self, temperature: f64) -> Self {
self.runner = self.runner.temperature(temperature);
self
}
pub fn without_temperature(mut self) -> Self {
self.runner = self.runner.without_temperature();
self
}
pub fn max_tokens(mut self, max_tokens: u64) -> Self {
self.runner = self.runner.max_tokens(max_tokens);
self
}
pub fn without_max_tokens(mut self) -> Self {
self.runner = self.runner.without_max_tokens();
self
}
pub fn merge_additional_params(
mut self,
params: serde_json::Map<String, serde_json::Value>,
) -> Self {
self.runner = self.runner.merge_additional_params(params);
self
}
pub fn replace_additional_params(mut self, params: serde_json::Value) -> Self {
self.runner = self.runner.replace_additional_params(params);
self
}
pub fn without_additional_params(mut self) -> Self {
self.runner = self.runner.without_additional_params();
self
}
pub fn tool_choice(mut self, tool_choice: rig_core::message::ToolChoice) -> Self {
self.runner = self.runner.tool_choice(tool_choice);
self
}
pub fn without_tool_choice(mut self) -> Self {
self.runner = self.runner.without_tool_choice();
self
}
pub fn record_content_telemetry(mut self, enabled: bool) -> Self {
self.runner = self.runner.record_content_telemetry(enabled);
self
}
pub fn conversation(mut self, id: impl Into<rig_core::id::ConversationId>) -> Self {
self.runner = self.runner.conversation(id);
self
}
pub fn without_memory(mut self) -> Self {
self.runner = self.runner.without_memory();
self
}
pub fn max_invalid_tool_call_retries(mut self, retries: usize) -> Self {
self.runner = self.runner.max_invalid_tool_call_retries(retries);
self
}
pub fn using_model(mut self, model: impl Into<$crate::agent::ModelRef>) -> Self {
self.runner = self.runner.using_model(model);
self
}
pub fn using_model_value(
mut self,
model: impl Into<rig_core::DynModel<rig_core::operation::Completion>>,
) -> Self {
self.runner = self.runner.using_model_value(model);
self
}
pub fn max_turns(mut self, max_turns: usize) -> Self {
self.runner = self.runner.max_turns(max_turns);
self
}
pub fn add_hook<H>(mut self, hook: H) -> Self
where
H: AgentHook + 'static,
{
self.runner = self.runner.add_hook(hook);
self
}
pub fn tool_concurrency(mut self, concurrency: usize) -> Self {
self.runner = self.runner.tool_concurrency(concurrency);
self
}
};
}
impl<T> TypedRun<T>
where
T: JsonSchema + DeserializeOwned + WasmCompatSend,
{
pub(crate) fn native(agent: &Agent, prompt: impl Into<Message>) -> Self {
let mut runner = AgentRunner::from_agent(agent, prompt);
runner.config.output_schema = Some(schema_for!(T));
runner.config.output_mode = OutputMode::Native;
Self::from_runner(runner, TypedOutput::Native)
}
pub(crate) fn output_tool(runner: AgentRunner) -> Self {
Self::from_runner(
runner.unhandled_invalid_tool_call(UnhandledInvalidToolCall::Ignore),
TypedOutput::OutputTool,
)
}
pub(crate) fn from_runner(runner: AgentRunner, output: TypedOutput) -> Self {
Self {
runner,
retries: 0,
output,
_t: PhantomData,
}
}
pub fn retries(mut self, retries: u64) -> Self {
self.retries = retries;
self
}
forward_runner_setters!();
async fn send(
self,
ambient: tracing::Span,
) -> Result<TypedPromptResponse<T>, StructuredOutputError> {
let mut usage = Usage::default();
let mut last_error = None;
for attempt in 0..=self.retries {
if self.retries > 0 {
tracing::debug!(
"Attempting to extract structured output. Retries left: {}",
self.retries - attempt
);
}
let (result, error_usage) = self
.runner
.clone()
.run_with_error_usage(ambient.clone())
.await;
let outcome = match result {
Ok(response) => {
usage += response.usage;
recover_output(&response, self.output).map(|output| TypedPromptResponse {
output,
usage,
completion_calls: response.completion_calls,
memory_append: response.memory_append,
})
}
Err(err) => {
usage += error_usage;
Err(StructuredOutputError::PromptError(err))
}
};
match outcome {
Ok(response) => return Ok(response),
Err(err) => {
if attempt < self.retries {
tracing::warn!(
"Attempt {attempt} to extract structured output failed: {err:?}. Retrying..."
);
}
last_error = Some(err);
}
}
}
Err(last_error.unwrap_or(StructuredOutputError::EmptyResponse))
}
}
fn recover_output<T: DeserializeOwned>(
response: &PromptResponse,
output: TypedOutput,
) -> Result<T, StructuredOutputError> {
match output {
TypedOutput::Native => {
if response.output.is_empty() {
return Err(StructuredOutputError::EmptyResponse);
}
Ok(deserialize_structured_output(&response.output)?)
}
TypedOutput::OutputTool => {
let submissions = response.output_tool_calls();
if submissions == 0
&& let Ok(value) = serde_json::from_str::<T>(response.output.trim())
{
return Ok(value);
}
if submissions == 0 {
tracing::warn!(
"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."
);
return Err(StructuredOutputError::EmptyResponse);
}
if submissions > 1 {
tracing::warn!(
"Multiple submit calls detected, using the first one. Providers / agents should only ensure one submit call."
);
}
Ok(serde_json::from_str(&response.output)?)
}
}
}
pub(crate) fn deserialize_structured_output<T: DeserializeOwned>(
text: &str,
) -> Result<T, serde_json::Error> {
let trimmed = text.trim();
match serde_json::from_str::<T>(trimmed) {
Ok(value) => Ok(value),
Err(direct_err) => {
let Some(start) = trimmed.find(['{', '[']) else {
return Err(direct_err);
};
serde_json::Deserializer::from_str(&trimmed[start..])
.into_iter::<T>()
.next()
.unwrap_or(Err(direct_err))
}
}
}
impl<T> IntoFuture for TypedRun<T>
where
T: JsonSchema + DeserializeOwned + WasmCompatSend + 'static,
{
type Output = Result<TypedPromptResponse<T>, StructuredOutputError>;
type IntoFuture = WasmBoxedFuture<'static, Self::Output>;
fn into_future(self) -> Self::IntoFuture {
let ambient = tracing::Span::current();
let run_under = ambient.clone();
Box::pin(self.send(run_under).instrument(ambient))
}
}