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 = None;
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
137                        .messages()
138                        .map(<[rig_core::completion::Message]>::to_vec);
139                }
140                Err(e) => {
141                    // Preserve structured run errors rather than reducing them to display text.
142                    break Err(crate::agent::streaming_error_into_prompt(e));
143                }
144                _ => continue,
145            }
146        };
147
148        if let Ok(response) = &result {
149            if let Some(messages) = messages {
150                history.extend(messages);
151            } else {
152                history.push(Message::user(prompt));
153                history.push(Message::assistant(response.as_str()));
154            }
155        }
156
157        result
158    }
159
160    fn show_usage(&self) -> bool {
161        self.show_usage
162    }
163
164    fn usage(&self) -> Option<Usage> {
165        Some(self.usage)
166    }
167}
168
169impl Default for ChatBotBuilder<Missing> {
170    fn default() -> Self {
171        Self(Missing)
172    }
173}
174
175impl ChatBotBuilder<Missing> {
176    /// A builder with nothing chosen yet.
177    pub fn new() -> Self {
178        Self::default()
179    }
180
181    /// Chat with `agent`.
182    pub fn agent(self, agent: Agent) -> ChatBotBuilder<Provided<AgentImpl>> {
183        ChatBotBuilder(Provided(AgentImpl {
184            agent,
185            max_turns: 1,
186            show_usage: false,
187            usage: Usage::default(),
188        }))
189    }
190
191    /// Chat with any [`Chat`] implementation.
192    pub fn chat<T: Chat>(self, chatbot: T) -> ChatBotBuilder<Provided<ChatImpl<T>>> {
193        ChatBotBuilder(Provided(ChatImpl(chatbot)))
194    }
195}
196
197impl<T> ChatBotBuilder<Provided<ChatImpl<T>>>
198where
199    T: Chat,
200{
201    /// The chatbot.
202    pub fn build(self) -> ChatBot<ChatImpl<T>> {
203        ChatBot(self.0.0)
204    }
205}
206
207impl ChatBotBuilder<Provided<AgentImpl>> {
208    /// Set the total model-call budget for each prompt, including the initial
209    /// call and every retry or continuation. Zero emits no model calls.
210    pub fn max_turns(self, max_turns: usize) -> Self {
211        ChatBotBuilder(Provided(AgentImpl {
212            max_turns,
213            ..self.0.0
214        }))
215    }
216
217    /// Print the token usage after every answer.
218    pub fn show_usage(self) -> Self {
219        ChatBotBuilder(Provided(AgentImpl {
220            show_usage: true,
221            ..self.0.0
222        }))
223    }
224
225    /// The chatbot.
226    pub fn build(self) -> ChatBot<AgentImpl> {
227        ChatBot(self.0.0)
228    }
229}
230
231#[allow(private_bounds)]
232impl<T> ChatBot<T>
233where
234    T: CliChat,
235{
236    /// Read prompts from stdin and print answers until `exit`.
237    /// Returns prompt failures and stdout flush errors; input read errors are printed.
238    pub async fn run(mut self) -> Result<(), PromptError> {
239        let stdin = io::stdin();
240        let mut stdout = io::stdout();
241        let mut history = vec![];
242
243        loop {
244            print!("> ");
245            stdout.flush().map_err(|e| {
246                PromptError::CompletionError(ProviderError::Response(format!(
247                    "failed to flush stdout: {e}"
248                )))
249            })?;
250
251            let mut input = String::new();
252            match stdin.read_line(&mut input) {
253                Ok(_) => {
254                    let input = input.trim();
255                    if input == "exit" {
256                        break;
257                    }
258
259                    tracing::info!("Prompt:\n{input}\n");
260
261                    println!();
262                    println!("========================== Response ============================");
263
264                    self.0.request(input, &mut history).await?;
265
266                    println!("================================================================");
267                    println!();
268
269                    if self.0.show_usage()
270                        && let Some(Usage {
271                            input_tokens,
272                            output_tokens,
273                            ..
274                        }) = self.0.usage()
275                    {
276                        let input_tokens = input_tokens.unwrap_or(0);
277                        let output_tokens = output_tokens.unwrap_or(0);
278                        println!("Input {input_tokens} tokens\nOutput {output_tokens} tokens");
279                    }
280                }
281                Err(e) => println!("Error reading request: {e}"),
282            }
283        }
284
285        Ok(())
286    }
287}