1use std::borrow::Borrow;
32use std::collections::BTreeSet;
33use std::sync::Arc;
34
35use rig_core::catalog::ModelSpec;
36use rig_core::completion::{
37 AssistantContent, CompletionRequest, CompletionResponse, Message, Reasoning, UnsupportedOption,
38};
39use rig_core::conversation::Conversation;
40use rig_core::message::{StopReason, ToolResultContent, UserContent};
41use serde::{Deserialize, Serialize};
42
43use super::{SummaryState, summarized_prefix};
44
45#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
47#[serde(default, deny_unknown_fields)]
48pub struct CompactionSettings {
49 pub enabled: bool,
52 pub reserve_tokens: u64,
54 pub keep_recent_tokens: u64,
56}
57
58impl Default for CompactionSettings {
59 fn default() -> Self {
61 Self {
62 enabled: true,
63 reserve_tokens: 16_384,
64 keep_recent_tokens: 20_000,
65 }
66 }
67}
68
69impl CompactionSettings {
70 pub fn should_compact(&self, context_tokens: u64, context_window: u64) -> bool {
73 self.enabled && context_tokens > context_window.saturating_sub(self.reserve_tokens)
74 }
75}
76
77const ESTIMATED_IMAGE_CHARS: u64 = 4_800;
79
80fn chars(text: &str) -> u64 {
82 text.encode_utf16().count() as u64
83}
84
85fn result_chars(content: &[ToolResultContent]) -> u64 {
87 content
88 .iter()
89 .map(|part| match part {
90 ToolResultContent::Text(text) => chars(&text.text),
91 ToolResultContent::Image(_) => ESTIMATED_IMAGE_CHARS,
92 ToolResultContent::Json { value } => chars(&value.to_string()),
93 })
94 .fold(0, u64::saturating_add)
95}
96
97fn message_chars(message: &Message) -> Vec<u64> {
100 match message {
101 Message::System { content } => vec![chars(content)],
102 Message::User { content } => {
103 let mut parts = Vec::new();
104 let mut rest = None::<u64>;
105 for item in content {
106 match item {
107 UserContent::ToolResult(result) => parts.push(result_chars(&result.content)),
108 UserContent::Text(text) => {
109 rest = Some(rest.unwrap_or(0).saturating_add(chars(&text.text)));
110 }
111 UserContent::Image(_) => {
112 rest = Some(rest.unwrap_or(0).saturating_add(ESTIMATED_IMAGE_CHARS));
113 }
114 _ => rest = Some(rest.unwrap_or(0)),
115 }
116 }
117 parts.extend(rest);
118 parts
119 }
120 Message::Assistant(reply) => vec![
121 reply
122 .content
123 .iter()
124 .map(|item| match item {
125 AssistantContent::Text(text) => chars(&text.text),
126 AssistantContent::Reasoning(reasoning) => chars(&reasoning.text),
127 AssistantContent::ToolCall(call) => chars(call.function.name.as_str())
128 .saturating_add(chars(
129 &serde_json::to_string(&call.function.arguments).unwrap_or_default(),
130 )),
131 _ => 0,
132 })
133 .fold(0, u64::saturating_add),
134 ],
135 }
136}
137
138pub fn estimate_message_tokens(message: &Message) -> u64 {
142 message_chars(message)
143 .into_iter()
144 .map(|chars| chars.div_ceil(4))
145 .fold(0, u64::saturating_add)
146}
147
148pub fn estimate_tokens(messages: &[impl Borrow<Message>]) -> u64 {
150 messages
151 .iter()
152 .map(|message| estimate_message_tokens(message.borrow()))
153 .fold(0, u64::saturating_add)
154}
155
156fn provider_tokens(chars: u64) -> u64 {
158 chars.saturating_mul(2).div_ceil(7)
159}
160
161pub fn request_tokens(
166 (system, tools): (Option<&str>, Option<&str>),
167 messages: &[impl Borrow<Message>],
168 anchor: Option<(u64, usize)>,
169) -> u64 {
170 let estimate = |messages: &[_]| {
171 messages
172 .iter()
173 .flat_map(|message: &_| message_chars(Borrow::<Message>::borrow(message)))
174 .map(provider_tokens)
175 .fold(0, u64::saturating_add)
176 };
177 if let Some((tokens, at)) = anchor {
178 let after = messages.get(at.saturating_add(1)..).unwrap_or_default();
179 return tokens.saturating_add(estimate(after));
180 }
181 let system = system.map_or(0, |text| provider_tokens(chars(text)));
182 let tools = tools.map_or(0, |json| provider_tokens(chars(json)));
183 system
184 .saturating_add(tools)
185 .saturating_add(estimate(messages))
186}
187
188fn is_tool_result(message: &Message) -> bool {
190 matches!(message, Message::User { content } if content.iter().any(|item| matches!(item, UserContent::ToolResult(_))))
191}
192
193fn is_turn_start(message: &Message) -> bool {
195 !matches!(message, Message::Assistant(_)) && !is_tool_result(message)
196}
197
198fn cut_points(messages: &[Arc<Message>]) -> Vec<bool> {
202 let mut allowed: Vec<bool> = messages
203 .iter()
204 .map(|message| !is_tool_result(message))
205 .collect();
206 let mut calls: Vec<(usize, &rig_core::message::CallId)> = Vec::new();
207 for (at, message) in messages.iter().enumerate() {
208 match &**message {
209 Message::Assistant(reply) => {
210 calls.extend(reply.tool_calls().map(|call| (at, &call.id)))
211 }
212 Message::User { content } => {
213 for result in content.iter().filter_map(UserContent::as_tool_result) {
214 let made = calls.iter().rev().find(|(_, id)| **id == result.call);
215 if let Some(&(made, _)) = made {
216 for inside in allowed.iter_mut().take(at.saturating_add(1)).skip(made + 1) {
217 *inside = false;
218 }
219 }
220 }
221 }
222 Message::System { .. } => {}
223 }
224 }
225 allowed
226}
227
228pub(crate) fn may_keep_from(messages: &[Arc<Message>], at: usize) -> bool {
231 at == messages.len() || cut_points(messages).get(at) == Some(&true)
232}
233
234pub fn find_cut_point(
242 messages: &[Arc<Message>],
243 (start, end): (usize, usize),
244 keep_recent_tokens: u64,
245 overflowed: bool,
246) -> usize {
247 let end = end.min(messages.len());
248 let allowed = cut_points(messages);
249 let cut_points: Vec<usize> = (start..end)
250 .filter(|&at| allowed.get(at).copied().unwrap_or(false))
251 .collect();
252 let Some(&first) = cut_points.first() else {
253 return start;
254 };
255 let mut cut = first;
256 let mut accumulated = 0u64;
257 for at in (start..end).rev() {
258 let tokens = messages
259 .get(at)
260 .map_or(0, |message| estimate_message_tokens(message));
261 if tokens == 0 {
262 continue;
263 }
264 accumulated = accumulated.saturating_add(tokens);
265 if accumulated >= keep_recent_tokens {
266 cut = cut_points
268 .iter()
269 .copied()
270 .find(|&candidate| candidate >= at)
271 .or(cut_points.last().copied())
272 .unwrap_or(first);
273 if overflowed && cut.saturating_add(1) == end {
274 cut = end;
275 }
276 break;
277 }
278 }
279 cut
280}
281
282fn split_turn_start(messages: &[Arc<Message>], start: usize, first_kept: usize) -> Option<usize> {
285 let starts = |at: usize| messages.get(at).is_some_and(|it| is_turn_start(it));
286 let last = messages.len().checked_sub(1)?;
287 (!starts(first_kept)).then(|| (start..=first_kept.min(last)).rev().find(|&at| starts(at)))?
288}
289
290#[derive(Clone, Debug, PartialEq)]
292pub struct CompactionPreparation {
293 pub replaces: Vec<Arc<Message>>,
296 pub to_summarize: Vec<Arc<Message>>,
298 pub turn_prefix: Vec<Arc<Message>>,
300 pub previous: Option<SummaryState>,
303 pub files: FileLists,
306}
307
308#[derive(Clone, Debug, Default, PartialEq, Eq)]
310pub struct FileLists {
311 pub read_files: Vec<String>,
313 pub modified_files: Vec<String>,
315}
316
317pub fn prepare_compaction(
324 conversation: &Conversation,
325 keep_recent_tokens: u64,
326 overflowed: bool,
327) -> Option<CompactionPreparation> {
328 if !overflowed && super::already_compacted(conversation) {
329 return None;
330 }
331 let messages = conversation.messages();
332 let range = (summarized_prefix(conversation), messages.len());
333 let first_kept = find_cut_point(messages, range, keep_recent_tokens, overflowed);
334 prepare_compaction_at(conversation, first_kept)
335}
336
337pub fn prepare_compaction_at(
342 conversation: &Conversation,
343 first_kept: usize,
344) -> Option<CompactionPreparation> {
345 let messages = conversation.messages();
346 let start = summarized_prefix(conversation);
347 if first_kept <= start || !may_keep_from(messages, first_kept) {
348 return None;
349 }
350 let turn_start = split_turn_start(messages, start, first_kept);
351 let to_summarize = messages.get(start..turn_start.unwrap_or(first_kept))?;
352 let turn_prefix = turn_start.and_then(|turn_start| messages.get(turn_start..first_kept));
353 let turn_prefix = turn_prefix.unwrap_or_default();
354 let previous = (start > 0).then(|| super::summary_state(conversation));
355 let mut ops = FileOperations::default();
356 if let Some(state) = &previous {
357 ops.read.extend(state.read_files.iter().cloned());
358 ops.edited.extend(state.modified_files.iter().cloned());
359 }
360 for message in to_summarize.iter().chain(turn_prefix) {
361 ops.extract(message);
362 }
363 Some(CompactionPreparation {
364 replaces: messages.get(..first_kept)?.to_vec(),
365 to_summarize: to_summarize.to_vec(),
366 turn_prefix: turn_prefix.to_vec(),
367 previous,
368 files: ops.lists(),
369 })
370}
371
372#[derive(Default)]
374struct FileOperations {
375 read: BTreeSet<String>,
376 written: BTreeSet<String>,
377 edited: BTreeSet<String>,
378}
379
380impl FileOperations {
381 fn extract(&mut self, message: &Message) {
383 let Message::Assistant(reply) = message else {
384 return;
385 };
386 for call in reply.tool_calls() {
387 let Some(path) = call
388 .function
389 .arguments
390 .get("path")
391 .and_then(|path| path.as_str())
392 .filter(|path| is_listed(path))
393 else {
394 continue;
395 };
396 let set = match call.function.name.as_str() {
397 "read" => &mut self.read,
398 "write" => &mut self.written,
399 "edit" => &mut self.edited,
400 _ => continue,
401 };
402 set.insert(path.to_owned());
403 }
404 }
405
406 fn lists(&self) -> FileLists {
408 let modified: BTreeSet<&String> = self.edited.iter().chain(&self.written).collect();
409 FileLists {
410 read_files: self
411 .read
412 .iter()
413 .filter(|path| !modified.contains(path))
414 .cloned()
415 .collect(),
416 modified_files: modified.into_iter().cloned().collect(),
417 }
418 }
419}
420
421fn is_listed(path: &str) -> bool {
424 !path.is_empty() && !path.contains('\n')
425}
426
427pub(crate) fn format_file_operations(read_files: &[String], modified_files: &[String]) -> String {
429 let lists = [
430 ("read-files", read_files),
431 ("modified-files", modified_files),
432 ];
433 let mut text = String::new();
434 for (tag, files) in lists {
435 let files: Vec<&str> = files.iter().map(String::as_str).collect();
436 let files: Vec<&str> = files.into_iter().filter(|path| is_listed(path)).collect();
437 if !files.is_empty() {
438 text.push_str(&format!("\n\n<{tag}>\n{}\n</{tag}>", files.join("\n")));
439 }
440 }
441 text
442}
443
444pub(crate) fn take_file_list<'t>(body: &'t str, tag: &str) -> (&'t str, Vec<String>) {
447 let (open, close) = (format!("\n\n<{tag}>\n"), format!("\n</{tag}>"));
448 let listed = body.strip_suffix(close.as_str());
449 match listed.and_then(|listed| listed.rsplit_once(open.as_str())) {
450 Some((rest, files)) => (rest, files.split('\n').map(str::to_owned).collect()),
451 None => (body, Vec::new()),
452 }
453}
454
455pub(crate) fn without_file_lists(summary: &str) -> &str {
458 let mut text = summary;
459 loop {
460 let end = text.trim_end();
461 let tagged = ["read-files", "modified-files"]
462 .into_iter()
463 .find_map(|tag| {
464 let listed = end.strip_suffix(&format!("</{tag}>"))?;
465 listed.rfind(&format!("<{tag}>"))
466 });
467 match tagged.and_then(|at| end.get(..at)) {
468 Some(before) => text = before.trim_end(),
469 None => return text,
470 }
471 }
472}
473
474const TOOL_RESULT_MAX_CHARS: usize = 2_000;
476
477fn truncate_for_summary(text: &str, max_chars: usize) -> String {
480 let total = text.encode_utf16().count();
481 if total <= max_chars {
482 return text.to_owned();
483 }
484 let mut units = 0;
485 let mut end = 0;
486 for (at, character) in text.char_indices() {
487 units += character.len_utf16();
488 if units > max_chars {
489 break;
490 }
491 end = at + character.len_utf8();
492 }
493 format!(
494 "{}\n\n[... {} more characters truncated]",
495 text.get(..end).unwrap_or_default(),
496 total - max_chars
497 )
498}
499
500pub fn serialize_conversation(messages: &[impl Borrow<Message>]) -> String {
503 let mut parts = Vec::new();
504 for message in messages {
505 match message.borrow() {
506 Message::System { content } if !content.is_empty() => {
507 parts.push(format!("[User]: {content}"));
508 }
509 Message::System { .. } => {}
510 Message::User { content } => {
511 for result in content.iter().filter_map(UserContent::as_tool_result) {
512 let text: String = result.content.iter().map(|part| part.to_text("")).collect();
513 if !text.is_empty() {
514 parts.push(format!(
515 "[Tool result]: {}",
516 truncate_for_summary(&text, TOOL_RESULT_MAX_CHARS)
517 ));
518 }
519 }
520 let text: String = content
521 .iter()
522 .filter_map(|item| match item {
523 UserContent::Text(text) => Some(text.text.as_str()),
524 _ => None,
525 })
526 .collect();
527 if !text.is_empty() {
528 parts.push(format!("[User]: {text}"));
529 }
530 }
531 Message::Assistant(reply) => {
532 let calls: Vec<String> = reply
533 .tool_calls()
534 .map(|call| {
535 let arguments: Vec<String> = call
536 .function
537 .arguments
538 .iter()
539 .map(|(key, value)| format!("{key}={value}"))
540 .collect();
541 format!("{}({})", call.function.name.as_str(), arguments.join(", "))
542 })
543 .collect();
544 let texts: Vec<&str> = reply
545 .content
546 .iter()
547 .filter_map(AssistantContent::as_text)
548 .collect();
549 if !texts.is_empty() {
550 parts.push(format!("[Assistant]: {}", texts.join("\n")));
551 }
552 if !calls.is_empty() {
553 parts.push(format!("[Assistant tool calls]: {}", calls.join("; ")));
554 }
555 }
556 }
557 }
558 parts.join("\n\n")
559}
560
561pub const SUMMARIZATION_SYSTEM_PROMPT: &str = "You are a context summarization assistant. Your task is to read a conversation between a user and an AI assistant, then produce a structured summary following the exact format specified.
563
564Do NOT continue the conversation. Do NOT respond to any questions in the conversation. ONLY output the structured summary.";
565
566const SUMMARIZATION_PROMPT: &str = "The messages above are a conversation to summarize. Create a structured context checkpoint summary that another LLM will use to continue the work.
567
568Use this EXACT format:
569
570## Goal
571[What is the user trying to accomplish? Can be multiple items if the session covers different tasks.]
572
573## Constraints & Preferences
574- [Any constraints, preferences, or requirements mentioned by user]
575- [Or \"(none)\" if none were mentioned]
576
577## Progress
578### Done
579- [x] [Completed tasks/changes]
580
581### In Progress
582- [ ] [Current work]
583
584### Blocked
585- [Issues preventing progress, if any]
586
587## Key Decisions
588- **[Decision]**: [Brief rationale]
589
590## Next Steps
5911. [Ordered list of what should happen next]
592
593## Critical Context
594- [Any data, examples, or references needed to continue]
595- [Or \"(none)\" if not applicable]
596
597Keep each section concise. Preserve exact file paths, function names, and error messages.";
598
599const UPDATE_SUMMARIZATION_PROMPT: &str = "The messages above are NEW conversation messages to incorporate into the existing summary provided in <previous-summary> tags.
600
601Update the existing structured summary with new information. RULES:
602- PRESERVE all existing information from the previous summary
603- ADD new progress, decisions, and context from the new messages
604- UPDATE the Progress section: move items from \"In Progress\" to \"Done\" when completed
605- UPDATE \"Next Steps\" based on what was accomplished
606- PRESERVE exact file paths, function names, and error messages
607- If something is no longer relevant, you may remove it
608
609Use this EXACT format:
610
611## Goal
612[Preserve existing goals, add new ones if the task expanded]
613
614## Constraints & Preferences
615- [Preserve existing, add new ones discovered]
616
617## Progress
618### Done
619- [x] [Include previously done items AND newly completed items]
620
621### In Progress
622- [ ] [Current work - update based on progress]
623
624### Blocked
625- [Current blockers - remove if resolved]
626
627## Key Decisions
628- **[Decision]**: [Brief rationale] (preserve all previous, add new)
629
630## Next Steps
6311. [Update based on current state]
632
633## Critical Context
634- [Preserve important context, add new if needed]
635
636Keep each section concise. Preserve exact file paths, function names, and error messages.";
637
638const TURN_PREFIX_SUMMARIZATION_PROMPT: &str = "The messages above are earlier context from an ongoing conversation. Later messages are stored separately and do not need to be reconstructed.
639
640Create a concise checkpoint of the user's request and the progress shown above. This checkpoint will be placed before the later messages so the conversation can continue with the necessary context.
641
642## Original Request
643[What did the user ask for?]
644
645## Progress So Far
646- [Key decisions and work completed in these messages]
647
648## Context Needed to Continue
649- [Information from these messages needed to understand the later work]
650
651Only summarize information explicitly present above. Do not infer or recreate later messages.";
652
653const CONTEXT_SAFETY_TOKENS: u64 = 4_096;
656
657const CONTEXT_SAFETY_PERCENT: u64 = 15;
659
660const MIN_OUTPUT_WITH_RATIO_MARGIN: u64 = 32_768;
662
663pub fn clamp_max_tokens(spec: &ModelSpec, input_tokens: u64, max_tokens: u64) -> u64 {
667 let Some(window) = spec
668 .context_window
669 .map(u64::from)
670 .filter(|&window| window > 0)
671 else {
672 return max_tokens.max(1);
673 };
674 let ratio = input_tokens
675 .saturating_mul(CONTEXT_SAFETY_PERCENT)
676 .div_ceil(100);
677 let margin = CONTEXT_SAFETY_TOKENS.max(ratio);
678 let mut room = window.saturating_sub(input_tokens).saturating_sub(margin);
679 if room < MIN_OUTPUT_WITH_RATIO_MARGIN {
680 let fixed = window
681 .saturating_sub(input_tokens)
682 .saturating_sub(CONTEXT_SAFETY_TOKENS);
683 room = MIN_OUTPUT_WITH_RATIO_MARGIN.min(fixed);
684 }
685 max_tokens.min(room.max(1))
686}
687
688pub fn summarization_request(
697 (system, prompt): (&str, String),
698 spec: &ModelSpec,
699 reasoning: Option<Reasoning>,
700 max_output: Option<u64>,
701) -> Result<CompletionRequest, UnsupportedOption> {
702 let mut options = spec.default_options(reasoning);
703 options.cache = None;
704 if reasoning.is_some() && spec.validate(&options).is_err() {
705 options.reasoning = None;
706 }
707 spec.validate(&options)?;
708 if spec.default_options(None).cache.is_some() {
712 options.cache = Some(rig_core::completion::CacheRetention::None);
713 }
714 let input = request_tokens(
715 (Some(system), None),
716 &[Message::user(prompt.as_str())],
717 None,
718 );
719 let request = CompletionRequest::new(Message::user(prompt))
720 .preamble(system.to_owned())
721 .options(options);
722 let most = match max_output {
723 Some(exact) => Some(exact),
724 None => spec
725 .output_limit()
726 .map(|most| clamp_max_tokens(spec, input, u64::from(most))),
727 };
728 Ok(match most {
729 Some(most) => request.max_tokens(most),
730 None => request,
731 })
732}
733
734fn with_focus(prompt: &str, instructions: &str) -> String {
736 let instructions = instructions.trim();
737 if instructions.is_empty() {
738 prompt.to_owned()
739 } else {
740 format!("{prompt}\n\nAdditional focus: {instructions}")
741 }
742}
743
744pub fn summary_request(
752 messages: &[impl Borrow<Message>],
753 (previous, instructions): (Option<&SummaryState>, &str),
754 spec: &ModelSpec,
755 reasoning: Option<Reasoning>,
756) -> Result<CompletionRequest, UnsupportedOption> {
757 let previous = previous.and_then(SummaryState::previous_summary);
759 let base = match previous {
760 Some(_) => UPDATE_SUMMARIZATION_PROMPT,
761 None => SUMMARIZATION_PROMPT,
762 };
763 let mut prompt = format!(
764 "<conversation>\n{}\n</conversation>\n\n",
765 serialize_conversation(messages)
766 );
767 if let Some(previous) = previous {
768 prompt.push_str(&format!(
769 "<previous-summary>\n{previous}\n</previous-summary>\n\n"
770 ));
771 }
772 prompt.push_str(&with_focus(base, instructions));
773 summarization_request((SUMMARIZATION_SYSTEM_PROMPT, prompt), spec, reasoning, None)
774}
775
776pub fn turn_prefix_request(
783 messages: &[impl Borrow<Message>],
784 instructions: &str,
785 spec: &ModelSpec,
786 reasoning: Option<Reasoning>,
787) -> Result<CompletionRequest, UnsupportedOption> {
788 let prompt = format!(
789 "# Conversation\n{}\n\n# Instructions\n{TURN_PREFIX_SUMMARIZATION_PROMPT}",
790 serialize_conversation(messages)
791 );
792 let prompt = with_focus(&prompt, instructions);
793 summarization_request((SUMMARIZATION_SYSTEM_PROMPT, prompt), spec, reasoning, None)
794}
795
796pub fn no_history(previous: Option<&SummaryState>) -> String {
799 previous
800 .map_or("No prior history.", |state| &state.summary)
801 .to_owned()
802}
803
804pub fn merge_split_turn(history: &str, prefix: &str) -> String {
807 let history = without_file_lists(history);
808 format!("{history}\n\n---\n\n**Turn Context (split turn):**\n\n{prefix}")
809}
810
811#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
813pub enum SummaryFailure {
814 #[error("{0} failed: {1}")]
816 Failed(&'static str, String),
817 #[error("{0} failed: generation hit the token cap and the summary is incomplete")]
819 Truncated(&'static str),
820 #[error("{0} attempted to call a tool")]
822 CalledTool(&'static str),
823 #[error("{0} failed: the summary is empty")]
825 Empty(&'static str),
826}
827
828pub fn summary_text(
836 response: &CompletionResponse,
837 label: &'static str,
838) -> Result<String, SummaryFailure> {
839 match response.stop() {
840 StopReason::Error(why) | StopReason::Aborted(why) => {
841 let why = if why.is_empty() {
842 "Unknown error".to_owned()
843 } else {
844 why
845 };
846 Err(SummaryFailure::Failed(label, why))
847 }
848 StopReason::Length => Err(SummaryFailure::Truncated(label)),
849 _ if response.tool_calls().next().is_some() => Err(SummaryFailure::CalledTool(label)),
850 _ => {
851 let texts: Vec<&str> = response
852 .choice
853 .iter()
854 .filter_map(AssistantContent::as_text)
855 .collect();
856 let text = texts.join("\n");
857 match text.trim().is_empty() {
858 true => Err(SummaryFailure::Empty(label)),
859 false => Ok(text),
860 }
861 }
862 }
863}
864
865#[cfg(test)]
866mod tests;