Skip to main content

rig_agent/
extractor.rs

1//! Typed extraction through an agent's `submit` output tool, with configurable retries.
2//!
3//! ```no_run
4//! use rig_agent::extractor::ExtractorBuilder;
5//! use rig_core::{Model, providers::openai::{self, OpenAI}};
6//! # async fn run() -> Result<(), Box<dyn std::error::Error>> {
7//! #[derive(serde::Deserialize, serde::Serialize, schemars::JsonSchema)]
8//! struct Person { name: String, age: u8 }
9//! let model = OpenAI::from_env()?.completion(openai::GPT_4O);
10//! let extractor = ExtractorBuilder::<Person>::new(model).retries(2).build();
11//! let person = extractor.extract("John is 30.").await?.output;
12//! # Ok(())
13//! # }
14//! ```
15
16use std::marker::PhantomData;
17
18use schemars::JsonSchema;
19use serde::{Serialize, de::DeserializeOwned};
20
21use rig_core::{
22    message::{Message, ToolChoice},
23    vector_store::{VectorStoreIndex, request::DynamicSearchFilter},
24    wasm_compat::{WasmCompatSend, WasmCompatSync},
25};
26
27use crate::agent::{Agent, AgentBuilder, AgentHook, ModelRef, OutputMode, TypedRun};
28
29const SUBMIT_TOOL_NAME: &str = "submit";
30
31/// An agent configured for structured extraction: every [`extract`](Self::extract)
32/// is a one-call [`TypedRun`] in output-tool mode with this extractor's retry
33/// budget.
34pub struct Extractor<T>
35where
36    T: JsonSchema + DeserializeOwned + WasmCompatSend + WasmCompatSync,
37{
38    agent: Agent,
39    retries: usize,
40    _t: PhantomData<T>,
41}
42
43impl<T> Extractor<T>
44where
45    T: JsonSchema + DeserializeOwned + WasmCompatSend + WasmCompatSync,
46{
47    /// Set a different default model for this extractor's subsequent runs.
48    /// Use the model registered under `label` in the extractor's handler table.
49    pub fn with_model_label(mut self, label: impl Into<ModelRef>) -> Self {
50        self.agent.set_model_label(label);
51        self
52    }
53
54    /// Register `model` in the extractor's handler table and use it.
55    pub fn with_model(
56        mut self,
57        model: impl Into<rig_core::DynModel<rig_core::operation::Completion>>,
58    ) -> Self {
59        self.agent.set_model(model);
60        self
61    }
62
63    /// The agent behind this extractor.
64    pub fn agent(&self) -> &Agent {
65        &self.agent
66    }
67
68    /// Extract structured data from `text`.
69    ///
70    /// The returned run supports history, a per-run model, and retry overrides,
71    /// and can be awaited for a
72    /// [`TypedPromptResponse<T>`](crate::agent::TypedPromptResponse). The
73    /// model must call the `submit` tool; a run in which it does not is an
74    /// empty response and, within the retry budget, is retried from scratch.
75    /// Usage accumulates across attempts, including attempts that received a
76    /// billed response but failed extraction; attempts whose completion call
77    /// itself errored contribute no usage.
78    pub fn extract(&self, text: impl Into<Message>) -> TypedRun<T> {
79        let runner = self.agent.prompt(text).max_turns(1).output_tool(
80            SUBMIT_TOOL_NAME,
81            "Submit the structured data you extracted from the provided text.",
82            false,
83        );
84        TypedRun::output_tool(runner).retries(self.retries)
85    }
86}
87
88/// Builder for the Extractor
89pub struct ExtractorBuilder<T>
90where
91    T: JsonSchema + DeserializeOwned + Serialize + WasmCompatSend + WasmCompatSync + 'static,
92{
93    agent_builder: AgentBuilder,
94    _t: PhantomData<T>,
95    retries: Option<usize>,
96}
97
98/// Generate setters forwarding to the matching inner [`AgentBuilder`] methods.
99macro_rules! forward_agent_builder {
100    ($( $(#[$attr:meta])* $name:ident $([$gen:ident : $($bound:tt)+])?
101        ( $($arg:ident : $ty:ty),* );)+) => {$(
102        $(#[$attr])*
103        pub fn $name $(<$gen>)? (mut self, $($arg: $ty),*) -> Self
104        $(where $gen: $($bound)+)?
105        {
106            self.agent_builder = self.agent_builder.$name($($arg),*);
107            self
108        }
109    )+};
110}
111
112impl<T> ExtractorBuilder<T>
113where
114    T: JsonSchema + DeserializeOwned + Serialize + WasmCompatSend + WasmCompatSync + 'static,
115{
116    /// An extractor of `T` over `model`.
117    pub fn new(model: impl Into<rig_core::DynModel<rig_core::operation::Completion>>) -> Self {
118        Self::from_agent_builder(AgentBuilder::new(model))
119    }
120
121    /// Configure an agent builder for extraction of `T`, replacing its preamble,
122    /// output schema, tool choice, and output mode. The tool choice is always
123    /// [`ToolChoice::Required`], since an extraction is one turn that must call
124    /// the `submit` tool.
125    pub fn from_agent_builder(builder: AgentBuilder) -> Self {
126        Self {
127            agent_builder: builder
128                .preamble("\
129                    You are an AI assistant whose purpose is to extract structured data from the provided text.\n\
130                    You will have access to a `submit` function that defines the structure of the data to extract from the provided text.\n\
131                    Use the `submit` function to submit the structured data.\n\
132                    Be sure to fill out every field and ALWAYS CALL THE `submit` function, even with default values!!!.
133                ")
134                .output_schema::<T>()
135                .tool_choice(ToolChoice::Required)
136                .output_mode(OutputMode::Tool),
137            retries: None,
138            _t: PhantomData,
139        }
140    }
141
142    /// Append instructions to the extractor's preamble. The extraction
143    /// preamble itself is fixed (it tells the model to call the output
144    /// tool); this adds to it, as [`AgentBuilder::append_preamble`] does,
145    /// and never replaces it.
146    pub fn append_preamble(mut self, preamble: &str) -> Self {
147        self.agent_builder = self.agent_builder.append_preamble(&format!(
148            "\n=============== ADDITIONAL INSTRUCTIONS ===============\n{preamble}"
149        ));
150        self
151    }
152
153    forward_agent_builder! {
154        /// Add a context document to the extractor
155        context(doc: &str);
156
157        /// Set provider-specific parameters for every extraction attempt.
158        additional_params(params: serde_json::Value);
159
160        /// Set the maximum number of tokens for the completion
161        max_tokens(max_tokens: u64);
162
163        /// Add a provider-independent lifecycle hook to every extraction attempt.
164        ///
165        /// Completion-response hooks receive canonical Rig content, usage, prompt,
166        /// and identity fields, just like hooks attached directly to an agent.
167        add_hook[H: AgentHook + 'static](hook: H);
168    }
169
170    /// Retrieve `samples` documents from `index` for every extraction.
171    ///
172    /// This delegates to [`AgentBuilder::dynamic_context`] and therefore uses
173    /// the same completion-call hook lifecycle as an agent.
174    pub fn dynamic_context<I, F>(mut self, samples: usize, index: I) -> Self
175    where
176        I: VectorStoreIndex<Filter = F> + 'static,
177        F: DynamicSearchFilter + WasmCompatSend + WasmCompatSync + 'static,
178    {
179        self.agent_builder = self.agent_builder.dynamic_context(samples, index);
180        self
181    }
182
183    /// Set the maximum number of retries for the extractor.
184    pub fn retries(mut self, retries: usize) -> Self {
185        self.retries = Some(retries);
186        self
187    }
188
189    /// Build the Extractor
190    pub fn build(self) -> Extractor<T> {
191        Extractor {
192            agent: self.agent_builder.build(),
193            _t: PhantomData,
194            retries: self.retries.unwrap_or(0),
195        }
196    }
197}
198
199#[cfg(test)]
200mod tests;