Skip to main content

rig_agent/integrations/
cli_chatbot.rs

1//! Terminal chat loops for agents and custom chat implementations.
2//!
3//! ```no_run
4//! use rig_agent::{Agent, completion::PromptError, integrations::cli_chatbot::ChatBotBuilder};
5//! async fn chat(agent: Agent) -> Result<(), PromptError> {
6//!     ChatBotBuilder::new().agent(agent).max_turns(3).build().run().await
7//! }
8//! ```
9
10use rig_core::error::ProviderError;
11use rig_core::{
12    markers::{Missing, Provided},
13    message::Message,
14};
15
16use crate::{
17    agent::{Agent, MultiTurnStreamItem},
18    completion::{PromptError, Usage},
19    streaming::{Item, StreamEvent},
20};
21use rig_core::wasm_compat::WasmCompatSend;
22
23/// One chat turn against caller-owned history, as the CLI chatbot drives it.
24///
25/// [`Agent`] implements it through [`Agent::chat`]; implement it on your own
26/// type to put something other than an agent behind
27/// [`ChatBotBuilder::chat`].
28pub trait Chat {
29    /// Execute one turn and append only committed messages to `history`.
30    fn chat(
31        &self,
32        prompt: impl Into<Message> + WasmCompatSend,
33        history: &mut Vec<Message>,
34    ) -> impl Future<Output = Result<String, PromptError>> + WasmCompatSend;
35}
36
37impl Chat for Agent {
38    async fn chat(
39        &self,
40        prompt: impl Into<Message> + WasmCompatSend,
41        history: &mut Vec<Message>,
42    ) -> Result<String, PromptError> {
43        Agent::chat(self, prompt, history)
44            .await
45            .map(|response| response.output())
46    }
47}
48use futures::StreamExt;
49use std::io::{self, Write};
50
51/// A chatbot over any [`Chat`] implementation.
52pub struct ChatImpl<T>(T)
53where
54    T: Chat;
55
56/// A chatbot over an [`Agent`], streaming each answer as it is produced.
57pub struct AgentImpl {
58    agent: Agent,
59    max_turns: usize,
60    show_usage: bool,
61    usage: Usage,
62}
63
64/// Builds a [`ChatBot`]: give it an agent or a [`Chat`], then `build`.
65pub struct ChatBotBuilder<T = Missing>(T);
66
67/// A terminal chat loop over an agent or a [`Chat`]; see [`ChatBot::run`].
68pub struct ChatBot<T>(T);
69
70/// Execute and display turns with optional usage reporting.
71#[allow(private_interfaces)]
72trait CliChat {
73    async fn request(
74        &mut self,
75        prompt: &str,
76        history: &mut Vec<Message>,
77    ) -> Result<String, PromptError>;
78
79    fn show_usage(&self) -> bool {
80        false
81    }
82
83    fn usage(&self) -> Option<Usage> {
84        None
85    }
86}
87
88impl<T> CliChat for ChatImpl<T>
89where
90    T: Chat,
91{
92    async fn request(
93        &mut self,
94        prompt: &str,
95        history: &mut Vec<Message>,
96    ) -> Result<String, PromptError> {
97        let res = self.0.chat(prompt, history).await?;
98        println!("{res}");
99
100        Ok(res)
101    }
102}
103
104impl CliChat for AgentImpl {
105    async fn request(
106        &mut self,
107        prompt: &str,
108        history: &mut Vec<Message>,
109    ) -> Result<String, PromptError> {
110        let mut response_stream = self
111            .agent
112            .prompt(prompt)
113            .history(history.clone())
114            .max_turns(self.max_turns)
115            .stream();
116
117        let mut acc = String::new();
118        let mut messages = Vec::new();
119
120        let result = loop {
121            let Some(chunk) = response_stream.next().await else {
122                println!();
123                break Ok(acc);
124            };
125
126            match chunk {
127                Ok(MultiTurnStreamItem::StreamAssistantItem(Item::Event(StreamEvent::Text {
128                    text,
129                    ..
130                }))) => {
131                    print!("{text}");
132                    acc.push_str(&text);
133                }
134                Ok(MultiTurnStreamItem::FinalResponse(final_response)) => {
135                    self.usage = final_response.usage();
136                    messages = final_response.messages;
137                }
138                Err(e) => break Err(e),
139                _ => continue,
140            }
141        };
142
143        if result.is_ok() {
144            history.extend(messages);
145        }
146
147        result
148    }
149
150    fn show_usage(&self) -> bool {
151        self.show_usage
152    }
153
154    fn usage(&self) -> Option<Usage> {
155        Some(self.usage)
156    }
157}
158
159impl Default for ChatBotBuilder<Missing> {
160    fn default() -> Self {
161        Self(Missing)
162    }
163}
164
165impl ChatBotBuilder<Missing> {
166    /// A builder with nothing chosen yet.
167    pub fn new() -> Self {
168        Self::default()
169    }
170
171    /// Chat with `agent`.
172    pub fn agent(self, agent: Agent) -> ChatBotBuilder<Provided<AgentImpl>> {
173        ChatBotBuilder(Provided(AgentImpl {
174            agent,
175            max_turns: 1,
176            show_usage: false,
177            usage: Usage::default(),
178        }))
179    }
180
181    /// Chat with any [`Chat`] implementation.
182    pub fn chat<T: Chat>(self, chatbot: T) -> ChatBotBuilder<Provided<ChatImpl<T>>> {
183        ChatBotBuilder(Provided(ChatImpl(chatbot)))
184    }
185}
186
187impl<T> ChatBotBuilder<Provided<ChatImpl<T>>>
188where
189    T: Chat,
190{
191    /// The chatbot.
192    pub fn build(self) -> ChatBot<ChatImpl<T>> {
193        ChatBot(self.0.0)
194    }
195}
196
197impl ChatBotBuilder<Provided<AgentImpl>> {
198    /// Set the total model-call budget for each prompt, including the initial
199    /// call and every retry or continuation. Zero emits no model calls.
200    pub fn max_turns(self, max_turns: usize) -> Self {
201        ChatBotBuilder(Provided(AgentImpl {
202            max_turns,
203            ..self.0.0
204        }))
205    }
206
207    /// Print the token usage after every answer.
208    pub fn show_usage(self) -> Self {
209        ChatBotBuilder(Provided(AgentImpl {
210            show_usage: true,
211            ..self.0.0
212        }))
213    }
214
215    /// The chatbot.
216    pub fn build(self) -> ChatBot<AgentImpl> {
217        ChatBot(self.0.0)
218    }
219}
220
221#[allow(private_bounds)]
222impl<T> ChatBot<T>
223where
224    T: CliChat,
225{
226    /// Read prompts from stdin and print answers until `exit`.
227    /// Returns prompt failures and stdout flush errors; input read errors are printed.
228    pub async fn run(mut self) -> Result<(), PromptError> {
229        let stdin = io::stdin();
230        let mut stdout = io::stdout();
231        let mut history = vec![];
232
233        loop {
234            print!("> ");
235            stdout.flush().map_err(|e| {
236                PromptError::Provider(ProviderError::Response(format!(
237                    "failed to flush stdout: {e}"
238                )))
239            })?;
240
241            let mut input = String::new();
242            match stdin.read_line(&mut input) {
243                Ok(_) => {
244                    let input = input.trim();
245                    if input == "exit" {
246                        break;
247                    }
248
249                    tracing::info!("Prompt:\n{input}\n");
250
251                    println!();
252                    println!("========================== Response ============================");
253
254                    self.0.request(input, &mut history).await?;
255
256                    println!("================================================================");
257                    println!();
258
259                    if self.0.show_usage()
260                        && let Some(Usage {
261                            input_tokens,
262                            output_tokens,
263                            ..
264                        }) = self.0.usage()
265                    {
266                        let input_tokens = input_tokens.unwrap_or(0);
267                        let output_tokens = output_tokens.unwrap_or(0);
268                        println!("Input {input_tokens} tokens\nOutput {output_tokens} tokens");
269                    }
270                }
271                Err(e) => println!("Error reading request: {e}"),
272            }
273        }
274
275        Ok(())
276    }
277}