Skip to content

Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.

refactor: move message summarization into SummarizeMessages (#7815)

Vidit Ostwala0d16dde6ecf
diff --git a/lib/crewai/src/crewai/utilities/agent_utils.py b/lib/crewai/src/crewai/utilities/agent_utils.py
index 1678b0e56..1ec50a618 100644
--- a/lib/crewai/src/crewai/utilities/agent_utils.py
+++ b/lib/crewai/src/crewai/utilities/agent_utils.py
@@ -10,7 +10,7 @@ from datetime import datetime
import inspect
import json
import re
-from typing import TYPE_CHECKING, Any, Final, Literal, TypedDict
+from typing import TYPE_CHECKING, Any, Final, Literal, cast
from crewai_core.printer import PRINTER, ColoredText, Printer
from crewai_core.settings import Settings
@@ -128,16 +128,6 @@ def resolve_plus_response(response: Any) -> Any:
return asyncio.run(await_response())
-class SummaryContent(TypedDict):
- """Structure for summary content entries.
-
- Attributes:
- content: The summarized content.
- """
-
- content: str
-
-
console = Console()
_MULTIPLE_NEWLINES: Final[re.Pattern[str]] = re.compile(r"\n+")
@@ -840,18 +830,6 @@ def handle_context_length(
)
-def _estimate_token_count(text: str) -> int:
- """Estimate token count using a conservative cross-provider heuristic.
-
- Args:
- text: The text to estimate tokens for.
-
- Returns:
- Estimated token count (roughly 1 token per 4 characters).
- """
- return len(text) // 4
-
-
def _content_parts_text(content: list[dict[str, Any]]) -> str:
"""Text carried by a multimodal content-part list.
@@ -889,192 +867,281 @@ def message_content_text(msg: LLMMessage) -> str:
return str(content)
-def _split_text_by_token_limit(text: str, max_tokens: int) -> list[str]:
- """Split text into parts each estimated to fit within max_tokens."""
- if not text:
- return []
- if _estimate_token_count(text) <= max_tokens:
- return [text]
-
- # Inverse of _estimate_token_count (len // 4): each slice is at most max_tokens.
- max_chars = max(1, max_tokens * 4)
- return [text[i : i + max_chars] for i in range(0, len(text), max_chars)]
-
-
-def _expand_oversized_message(msg: LLMMessage, max_tokens: int) -> list[LLMMessage]:
- """Split a message whose content alone exceeds max_tokens into sub-messages."""
- msg_text = message_content_text(msg)
- if _estimate_token_count(msg_text) <= max_tokens:
- return [msg]
+class SummarizeMessages:
+ """Compact a message list so it fits the model context window.
- # Reserve budget for the [Part i/n] prefix added to each sub-message.
- body_max_tokens = max(1, max_tokens - 5)
- parts = _split_text_by_token_limit(msg_text, body_max_tokens)
- total_parts = len(parts)
- expanded: list[LLMMessage] = []
+ Preserves system messages, splits at message boundaries, formats with
+ role labels, and writes one structured summary back onto ``messages``.
+ Files attached to user messages are merged onto that summary.
+ """
- for index, part in enumerate(parts, start=1):
- part_content = (
- f"[Part {index}/{total_parts}]\n{part}" if total_parts > 1 else part
+ _CHARS_PER_TOKEN_LEVELS: Final[tuple[float, ...]] = (4.0, 3.0, 2.5)
+
+ def __init__(self) -> None:
+ self.messages: list[LLMMessage] = []
+ self.llm: LLM | BaseLLM | None = None
+ self.callbacks: list[TokenCalcHandler] = []
+ self.verbose = True
+
+ def summarize(
+ self,
+ messages: list[LLMMessage],
+ llm: LLM | BaseLLM,
+ callbacks: list[TokenCalcHandler],
+ verbose: bool = True,
+ ) -> None:
+ """Replace non-system messages with a single summary, in place."""
+ if llm is None:
+ raise RuntimeError("SummarizeMessages.summarize() must set an LLM first.")
+
+ self.llm = llm
+ self.callbacks = callbacks
+ self.verbose = verbose
+ self.messages = messages
+ preserved_files = self._collect_attached_files()
+ system_messages = [m for m in self.messages if m.get("role") == "system"]
+ work_messages = [m for m in self.messages if m.get("role") != "system"]
+ if not work_messages:
+ return
+
+ chunks = self._chunk_messages(
+ work_messages,
+ llm.get_context_window_size(),
+ char_level_index=0,
)
- expanded.append({**msg, "content": part_content})
-
- return expanded
-
-
-def _normalize_messages_for_chunking(
- messages: list[LLMMessage], max_tokens: int
-) -> list[LLMMessage]:
- """Return non-system messages with oversized entries split to fit max_tokens."""
- normalized: list[LLMMessage] = []
- for msg in messages:
- if msg.get("role") == "system":
- continue
- normalized.extend(_expand_oversized_message(msg, max_tokens))
- return normalized
-
-
-def _format_messages_for_summary(messages: list[LLMMessage]) -> str:
- """Format messages with role labels for summarization.
-
- Skips system messages. Handles None content, tool_calls, and
- multimodal content blocks.
+ summaries = self._get_summaries_for_chunks(chunks, char_level_index=0)
+ self._replace_history_with_summary(system_messages, summaries, preserved_files)
+
+ def _get_summaries_for_chunks(
+ self, chunks: list[list[LLMMessage]], char_level_index: int
+ ) -> list[str]:
+ total = len(chunks)
+ if self.verbose and total <= 1:
+ for index in range(1, total + 1):
+ PRINTER.print(
+ content=f"Summarizing {index}/{total}...",
+ color="yellow",
+ )
+ if self.verbose and total > 1:
+ PRINTER.print(
+ content=f"Summarizing {total} chunks in parallel...",
+ color="yellow",
+ )
+ return self._summarize_all(chunks, char_level_index)
- Args:
- messages: List of messages to format.
+ def _summarize_all(
+ self, chunks: list[list[LLMMessage]], char_level_index: int
+ ) -> list[str]:
+ """Run one coroutine per chunk and return the summaries in order."""
- Returns:
- Role-labeled conversation text.
- """
- lines: list[str] = []
- for msg in messages:
- role = msg.get("role", "user")
- if role == "system":
- continue
+ async def _summarize_one(chunk: list[LLMMessage], level_index: int) -> str:
+ """Summarize one chunk; only reachable from ``_summarize_all`` or itself."""
+ llm = cast("LLM | BaseLLM", self.llm)
- content = msg.get("content")
- if content is None:
- tool_calls = msg.get("tool_calls")
- if tool_calls:
- tool_names = []
- for tc in tool_calls:
- func = tc.get("function", {})
- name = (
- func.get("name", "unknown")
- if isinstance(func, dict)
- else "unknown"
+ try:
+ summary = str(
+ await llm.acall(
+ self._build_summary_prompt(chunk), callbacks=self.callbacks
)
- tool_names.append(name)
- content = f"[Called tools: {', '.join(tool_names)}]"
+ )
+ except LLMContextLengthExceededError:
+ pass
+ except Exception as error:
+ if not is_context_length_exceeded(error):
+ raise
else:
- content = ""
- elif isinstance(content, list):
- content = _content_parts_text(content)
-
- if role == "assistant":
- label = "[ASSISTANT]:"
- elif role == "tool":
- tool_name = msg.get("name", "unknown")
- label = f"[TOOL_RESULT ({tool_name})]:"
- else:
- label = "[USER]:"
-
- lines.append(f"{label} {content}")
-
- return "\n\n".join(lines)
-
-
-def _split_messages_into_chunks(
- messages: list[LLMMessage], max_tokens: int
-) -> list[list[LLMMessage]]:
- """Split messages into chunks at message boundaries.
-
- Excludes system messages and expands oversized single messages before
- chunking. Each chunk stays under max_tokens based on estimated token count.
-
- Args:
- messages: List of messages to split.
- max_tokens: Maximum estimated tokens per chunk.
-
- Returns:
- List of message chunks.
- """
- normalized = _normalize_messages_for_chunking(messages, max_tokens)
- if not normalized:
- return []
-
- chunks: list[list[LLMMessage]] = []
- current_chunk: list[LLMMessage] = []
- current_tokens = 0
-
- for msg in normalized:
- msg_tokens = _estimate_token_count(message_content_text(msg))
-
- if current_chunk and (current_tokens + msg_tokens) > max_tokens:
- chunks.append(current_chunk)
- current_chunk = []
- current_tokens = 0
-
- current_chunk.append(msg)
- current_tokens += msg_tokens
-
- if current_chunk:
- chunks.append(current_chunk)
-
- return chunks
-
-
-def _extract_summary_tags(text: str) -> str:
- """Extract content between <summary></summary> tags.
-
- Falls back to the full text if no tags are found.
-
- Args:
- text: Text potentially containing summary tags.
+ match = re.search(r"<summary>(.*?)</summary>", summary, re.DOTALL)
+ if match:
+ return match.group(1).strip()
+ return summary.strip()
+
+ if level_index + 1 >= len(self._CHARS_PER_TOKEN_LEVELS):
+ raise LLMContextLengthExceededError(
+ "Summarization chunk still exceeds the context window after "
+ f"retries at {self._CHARS_PER_TOKEN_LEVELS} chars-per-token levels."
+ ) from None
+
+ next_level = level_index + 1
+ if self.verbose:
+ chars_per_token = self._CHARS_PER_TOKEN_LEVELS[next_level]
+ PRINTER.print(
+ content=(
+ "Summarization chunk exceeded context window; retrying with "
+ f"tighter token estimate (1 token per {chars_per_token} chars)."
+ ),
+ color="yellow",
+ )
- Returns:
- Extracted summary content, or full text if no tags found.
- """
- match = re.search(r"<summary>(.*?)</summary>", text, re.DOTALL)
- if match:
- return match.group(1).strip()
- return text.strip()
+ sub_chunks = self._chunk_messages(
+ chunk,
+ llm.get_context_window_size(),
+ char_level_index=next_level,
+ )
+ if not sub_chunks:
+ raise LLMContextLengthExceededError(
+ "Summarization chunk could not be split further."
+ ) from None
+ if len(sub_chunks) == 1:
+ return await _summarize_one(sub_chunks[0], next_level)
-async def _asummarize_chunks(
- chunks: list[list[LLMMessage]],
- llm: LLM | BaseLLM,
- callbacks: list[TokenCalcHandler],
-) -> list[SummaryContent]:
- """Summarize multiple message chunks concurrently using asyncio.
+ parts = await asyncio.gather(
+ *[_summarize_one(sub_chunk, next_level) for sub_chunk in sub_chunks]
+ )
+ return "\n\n".join(parts)
- Args:
- chunks: List of message chunks to summarize.
- llm: LLM instance (must support ``acall``).
- callbacks: List of callbacks for the LLM.
+ async def _gather() -> list[str]:
+ coroutines = [_summarize_one(chunk, char_level_index) for chunk in chunks]
+ return list(await asyncio.gather(*coroutines))
- Returns:
- Ordered list of summary contents, one per chunk.
- """
+ coro = _gather()
+ if is_inside_event_loop():
+ ctx = contextvars.copy_context()
+ with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+ return pool.submit(ctx.run, asyncio.run, coro).result()
+ return asyncio.run(coro)
- async def _summarize_one(chunk: list[LLMMessage]) -> SummaryContent:
- conversation_text = _format_messages_for_summary(chunk)
- summarization_messages = [
+ def _build_summary_prompt(self, chunk: list[LLMMessage]) -> list[LLMMessage]:
+ conversation = self._conversation_text(chunk)
+ return [
format_message_for_llm(
I18N_DEFAULT.slice("summarizer_system_message"), role="system"
),
format_message_for_llm(
I18N_DEFAULT.slice("summarize_instruction").format(
- conversation=conversation_text
+ conversation=conversation
),
),
]
- summary = await llm.acall(summarization_messages, callbacks=callbacks)
- extracted = _extract_summary_tags(str(summary))
- return {"content": extracted}
- results = await asyncio.gather(*[_summarize_one(chunk) for chunk in chunks])
- return list(results)
+ def _collect_attached_files(self) -> dict[str, Any]:
+ preserved: dict[str, Any] = {}
+ for msg in self.messages:
+ if msg.get("role") == "user" and msg.get("files"):
+ preserved.update(msg["files"])
+ return preserved
+
+ def _replace_history_with_summary(
+ self,
+ system_messages: list[LLMMessage],
+ summaries: list[str],
+ preserved_files: dict[str, Any],
+ ) -> None:
+ merged = "\n\n".join(summaries)
+ summary_message = format_message_for_llm(
+ I18N_DEFAULT.slice("summary").format(merged_summary=merged)
+ )
+ if preserved_files:
+ summary_message["files"] = preserved_files
+
+ self.messages.clear()
+ self.messages.extend(system_messages)
+ self.messages.append(summary_message)
+
+ def _approx_tokens(self, text: str, chars_per_token: float = 4.0) -> int:
+ """Estimate token count from character length and a chars-per-token heuristic."""
+ if not text:
+ return 0
+ return int(len(text) / chars_per_token)
+
+ def _chars_per_token(self, char_level_index: int) -> float:
+ return self._CHARS_PER_TOKEN_LEVELS[char_level_index]
+
+ def _messages_ready_to_chunk(
+ self,
+ messages: list[LLMMessage],
+ max_tokens: int,
+ char_level_index: int = 0,
+ ) -> list[LLMMessage]:
+ """Drop system messages and split any entry that exceeds max_tokens."""
+ chars_per_token = self._chars_per_token(char_level_index)
+ ready: list[LLMMessage] = []
+ for msg in messages:
+ if msg.get("role") == "system":
+ continue
+
+ text = message_content_text(msg)
+ if not text or self._approx_tokens(text, chars_per_token) <= max_tokens:
+ ready.append(msg)
+ continue
+
+ part_prefix_tokens = 5
+ body_max_tokens = max(1, max_tokens - part_prefix_tokens)
+ max_chars = max(1, int(body_max_tokens * chars_per_token))
+ parts = [text[i : i + max_chars] for i in range(0, len(text), max_chars)]
+ total_parts = len(parts)
+ for index, part in enumerate(parts, start=1):
+ ready.append(
+ {**msg, "content": f"[Part {index}/{total_parts}]\n{part}"}
+ )
+ return ready
+
+ def _conversation_text(self, messages: list[LLMMessage]) -> str:
+ """Format messages with role labels, skipping system messages."""
+ lines: list[str] = []
+ for msg in messages:
+ role = msg.get("role", "user")
+ if role == "system":
+ continue
+
+ if role == "assistant":
+ prefix = "[ASSISTANT]:"
+ elif role == "tool":
+ prefix = f"[TOOL_RESULT ({msg.get('name', 'unknown')})]:"
+ else:
+ prefix = "[USER]:"
+
+ content = msg.get("content")
+ if content is None:
+ tool_calls = msg.get("tool_calls") or []
+ names = []
+ for tool_call in tool_calls:
+ func = tool_call.get("function", {})
+ names.append(
+ func.get("name", "unknown")
+ if isinstance(func, dict)
+ else "unknown"
+ )
+ body = f"[Called tools: {', '.join(names)}]" if names else ""
+ elif isinstance(content, list):
+ body = _content_parts_text(content)
+ else:
+ body = str(content)
+
+ lines.append(f"{prefix} {body}")
+ return "\n\n".join(lines)
+
+ def _chunk_messages(
+ self,
+ messages: list[LLMMessage],
+ max_tokens: int,
+ char_level_index: int = 0,
+ ) -> list[list[LLMMessage]]:
+ """Split messages into chunks that stay under max_tokens."""
+ chars_per_token = self._chars_per_token(char_level_index)
+ normalized = self._messages_ready_to_chunk(
+ messages, max_tokens, char_level_index=char_level_index
+ )
+ if not normalized:
+ return []
+
+ chunks: list[list[LLMMessage]] = []
+ current_chunk: list[LLMMessage] = []
+ current_tokens = 0
+ for msg in normalized:
+ msg_tokens = self._approx_tokens(
+ message_content_text(msg), chars_per_token=chars_per_token
+ )
+ if current_chunk and (current_tokens + msg_tokens) > max_tokens:
+ chunks.append(current_chunk)
+ current_chunk = []
+ current_tokens = 0
+ current_chunk.append(msg)
+ current_tokens += msg_tokens
+
+ if current_chunk:
+ chunks.append(current_chunk)
+ return chunks
def summarize_messages(
@@ -1098,69 +1165,9 @@ def summarize_messages(
callbacks: List of callbacks for LLM
verbose: Whether to print progress.
"""
- preserved_files: dict[str, Any] = {}
- for msg in messages:
- if msg.get("role") == "user" and msg.get("files"):
- preserved_files.update(msg["files"])
-
- system_messages = [m for m in messages if m.get("role") == "system"]
- non_system_messages = [m for m in messages if m.get("role") != "system"]
-
- if not non_system_messages:
- return
-
- max_tokens = llm.get_context_window_size()
- chunks = _split_messages_into_chunks(non_system_messages, max_tokens)
-
- total_chunks = len(chunks)
-
- if total_chunks <= 1:
- summarized_contents: list[SummaryContent] = []
- for idx, chunk in enumerate(chunks, 1):
- if verbose:
- PRINTER.print(
- content=f"Summarizing {idx}/{total_chunks}...",
- color="yellow",
- )
- conversation_text = _format_messages_for_summary(chunk)
- summarization_messages = [
- format_message_for_llm(
- I18N_DEFAULT.slice("summarizer_system_message"), role="system"
- ),
- format_message_for_llm(
- I18N_DEFAULT.slice("summarize_instruction").format(
- conversation=conversation_text
- ),
- ),
- ]
- summary = llm.call(summarization_messages, callbacks=callbacks)
- extracted = _extract_summary_tags(str(summary))
- summarized_contents.append({"content": extracted})
- else:
- if verbose:
- PRINTER.print(
- content=f"Summarizing {total_chunks} chunks in parallel...",
- color="yellow",
- )
- coro = _asummarize_chunks(chunks=chunks, llm=llm, callbacks=callbacks)
- if is_inside_event_loop():
- ctx = contextvars.copy_context()
- with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
- summarized_contents = pool.submit(ctx.run, asyncio.run, coro).result()
- else:
- summarized_contents = asyncio.run(coro)
-
- merged_summary = "\n\n".join(content["content"] for content in summarized_contents)
-
- messages.clear()
- messages.extend(system_messages)
-
- summary_message = format_message_for_llm(
- I18N_DEFAULT.slice("summary").format(merged_summary=merged_summary)
+ SummarizeMessages().summarize(
+ messages=messages, llm=llm, callbacks=callbacks, verbose=verbose
)
- if preserved_files:
- summary_message["files"] = preserved_files
- messages.append(summary_message)
def show_agent_logs(
diff --git a/lib/crewai/tests/utilities/test_agent_utils.py b/lib/crewai/tests/utilities/test_agent_utils.py
index 9416d5dfd..20ac2a7f8 100644
--- a/lib/crewai/tests/utilities/test_agent_utils.py
+++ b/lib/crewai/tests/utilities/test_agent_utils.py
@@ -20,16 +20,9 @@ from crewai.agents.parser import AgentFinish
from crewai.tools.base_tool import BaseTool
from crewai.llms.context_window import CONTEXT_WINDOW_USAGE_RATIO
from crewai.utilities.agent_utils import (
- _asummarize_chunks,
- _estimate_token_count,
- _expand_oversized_message,
- _extract_summary_tags,
- _format_messages_for_summary,
message_content_text,
- _normalize_messages_for_chunking,
- _split_messages_into_chunks,
- _split_text_by_token_limit,
format_message_for_llm,
+ LLMContextLengthExceededError,
convert_tools_to_openai_schema,
handle_max_iterations_exceeded,
execute_single_native_tool_call,
@@ -38,13 +31,20 @@ from crewai.utilities.agent_utils import (
NativeToolCallResult,
parse_tool_call_args,
summarize_messages,
+ SummarizeMessages,
)
from crewai.utilities.i18n import I18N_DEFAULT
+_summarizer = SummarizeMessages()
+_approx_tokens = _summarizer._approx_tokens
+_conversation_text = _summarizer._conversation_text
+_messages_ready_to_chunk = _summarizer._messages_ready_to_chunk
+_chunk_messages = _summarizer._chunk_messages
+
def _estimate_summarization_request_tokens(chunk: list[dict[str, Any]]) -> int:
"""Estimate tokens for the full summarization LLM request for one chunk."""
- conversation_text = _format_messages_for_summary(chunk)
+ conversation_text = _conversation_text(chunk)
summarization_messages = [
format_message_for_llm(
I18N_DEFAULT.slice("summarizer_system_message"), role="system"
@@ -56,7 +56,7 @@ def _estimate_summarization_request_tokens(chunk: list[dict[str, Any]]) -> int:
),
]
return sum(
- _estimate_token_count(str(message.get("content", "")))
+ _approx_tokens(str(message.get("content", "")))
for message in summarization_messages
)
@@ -349,7 +349,7 @@ class TestSummarizeMessages:
mock_llm = MagicMock()
mock_llm.get_context_window_size.return_value = 1000
- mock_llm.call.return_value = "<summary>Summarized conversation about image analysis.</summary>"
+ mock_llm.acall = AsyncMock(return_value="<summary>Summarized conversation about image analysis.</summary>")
summarize_messages(
messages=messages,
@@ -380,7 +380,7 @@ class TestSummarizeMessages:
mock_llm = MagicMock()
mock_llm.get_context_window_size.return_value = 1000
- mock_llm.call.return_value = "<summary>Summarized conversation.</summary>"
+ mock_llm.acall = AsyncMock(return_value="<summary>Summarized conversation.</summary>")
summarize_messages(
messages=messages,
@@ -406,7 +406,7 @@ class TestSummarizeMessages:
mock_llm = MagicMock()
mock_llm.get_context_window_size.return_value = 1000
- mock_llm.call.return_value = "<summary>A greeting exchange.</summary>"
+ mock_llm.acall = AsyncMock(return_value="<summary>A greeting exchange.</summary>")
summarize_messages(
messages=messages,
@@ -429,7 +429,7 @@ class TestSummarizeMessages:
mock_llm = MagicMock()
mock_llm.get_context_window_size.return_value = 1000
- mock_llm.call.return_value = "<summary>Summary</summary>"
+ mock_llm.acall = AsyncMock(return_value="<summary>Summary</summary>")
summarize_messages(
messages=messages,
@@ -451,7 +451,7 @@ class TestSummarizeMessages:
mock_llm = MagicMock()
mock_llm.get_context_window_size.return_value = 1000
- mock_llm.call.return_value = "<summary>User asked about AI, assistant found resources.</summary>"
+ mock_llm.acall = AsyncMock(return_value="<summary>User asked about AI, assistant found resources.</summary>")
summarize_messages(
messages=messages,
@@ -475,7 +475,7 @@ class TestSummarizeMessages:
mock_llm = MagicMock()
mock_llm.get_context_window_size.return_value = 1000
- mock_llm.call.return_value = "<summary>Greeting exchange.</summary>"
+ mock_llm.acall = AsyncMock(return_value="<summary>Greeting exchange.</summary>")
summarize_messages(
messages=messages,
@@ -484,7 +484,7 @@ class TestSummarizeMessages:
)
- call_args = mock_llm.call.call_args[0][0]
+ call_args = mock_llm.acall.call_args[0][0]
user_msg_content = call_args[1]["content"]
assert "[USER]:" in user_msg_content
assert "[ASSISTANT]:" in user_msg_content
@@ -500,7 +500,7 @@ class TestSummarizeMessages:
mock_llm = MagicMock()
mock_llm.get_context_window_size.return_value = 1000
- mock_llm.call.return_value = "Here is the summary:\n<summary>The extracted summary content.</summary>\nExtra text."
+ mock_llm.acall = AsyncMock(return_value="Here is the summary:\n<summary>The extracted summary content.</summary>\nExtra text.")
summarize_messages(
messages=messages,
@@ -524,7 +524,7 @@ class TestSummarizeMessages:
mock_llm = MagicMock()
mock_llm.get_context_window_size.return_value = 1000
- mock_llm.call.return_value = "<summary>User searched for Python info.</summary>"
+ mock_llm.acall = AsyncMock(return_value="<summary>User searched for Python info.</summary>")
summarize_messages(
messages=messages,
@@ -533,7 +533,7 @@ class TestSummarizeMessages:
)
- call_args = mock_llm.call.call_args[0][0]
+ call_args = mock_llm.acall.call_args[0][0]
user_msg_content = call_args[1]["content"]
assert "[TOOL_RESULT (web_search)]:" in user_msg_content
@@ -555,7 +555,7 @@ class TestSummarizeMessages:
)
# No LLM call should have been made
- mock_llm.call.assert_not_called()
+ mock_llm.acall.assert_not_called()
# System messages should remain untouched
assert len(messages) == 2
assert messages[0]["content"] == "You are a helpful assistant."
@@ -563,14 +563,14 @@ class TestSummarizeMessages:
class TestFormatMessagesForSummary:
- """Tests for _format_messages_for_summary helper."""
+ """Tests for _conversation_text helper."""
def test_skips_system_messages(self) -> None:
messages: list[dict[str, Any]] = [
{"role": "system", "content": "System prompt"},
{"role": "user", "content": "Hello"},
]
- result = _format_messages_for_summary(messages)
+ result = _conversation_text(messages)
assert "System prompt" not in result
assert "[USER]: Hello" in result
@@ -579,7 +579,7 @@ class TestFormatMessagesForSummary:
{"role": "user", "content": "Question"},
{"role": "assistant", "content": "Answer"},
]
- result = _format_messages_for_summary(messages)
+ result = _conversation_text(messages)
assert "[USER]: Question" in result
assert "[ASSISTANT]: Answer" in result
@@ -587,7 +587,7 @@ class TestFormatMessagesForSummary:
messages: list[dict[str, Any]] = [
{"role": "tool", "content": "Result data", "name": "search_tool"},
]
- result = _format_messages_for_summary(messages)
+ result = _conversation_text(messages)
assert "[TOOL_RESULT (search_tool)]:" in result
assert "Result data" in result
@@ -597,14 +597,14 @@ class TestFormatMessagesForSummary:
{"function": {"name": "calculator", "arguments": "{}"}}
]},
]
- result = _format_messages_for_summary(messages)
+ result = _conversation_text(messages)
assert "[Called tools: calculator]" in result
def test_handles_none_content_without_tool_calls(self) -> None:
messages: list[dict[str, Any]] = [
{"role": "assistant", "content": None},
]
- result = _format_messages_for_summary(messages)
+ result = _conversation_text(messages)
assert "[ASSISTANT]:" in result
def test_handles_multimodal_content(self) -> None:
@@ -614,49 +614,59 @@ class TestFormatMessagesForSummary:
{"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}}
]},
]
- result = _format_messages_for_summary(messages)
+ result = _conversation_text(messages)
assert "[USER]: Describe this image" in result
def test_empty_messages(self) -> None:
- result = _format_messages_for_summary([])
+ result = _conversation_text([])
assert result == ""
class TestExtractSummaryTags:
- """Tests for _extract_summary_tags helper."""
+ """Summary tags are pulled out inside _summarize_all."""
+
+ def _from_reply(self, reply: str) -> str:
+ summarizer = SummarizeMessages()
+ summarizer.llm = MagicMock()
+ summarizer.callbacks = []
+ summarizer.llm.acall = AsyncMock(return_value=reply)
+ results = summarizer._summarize_all(
+ chunks=[[{"role": "user", "content": "x"}]], char_level_index=0
+ )
+ return results[0]
def test_extracts_content_from_tags(self) -> None:
text = "Preamble\n<summary>The actual summary.</summary>\nPostamble"
- assert _extract_summary_tags(text) == "The actual summary."
+ assert self._from_reply(text) == "The actual summary."
def test_handles_multiline_content(self) -> None:
text = "<summary>\nLine 1\nLine 2\nLine 3\n</summary>"
- result = _extract_summary_tags(text)
+ result = self._from_reply(text)
assert "Line 1" in result
assert "Line 2" in result
assert "Line 3" in result
def test_falls_back_when_no_tags(self) -> None:
text = "Just a plain summary without tags."
- assert _extract_summary_tags(text) == text
+ assert self._from_reply(text) == text
def test_handles_empty_string(self) -> None:
- assert _extract_summary_tags("") == ""
+ assert self._from_reply("") == ""
def test_extracts_first_match(self) -> None:
text = "<summary>First</summary> text <summary>Second</summary>"
- assert _extract_summary_tags(text) == "First"
+ assert self._from_reply(text) == "First"
class TestSplitMessagesIntoChunks:
- """Tests for _split_messages_into_chunks helper."""
+ """Tests for _chunk_messages helper."""
def test_single_chunk_when_under_limit(self) -> None:
messages: list[dict[str, Any]] = [
{"role": "user", "content": "Hello"},
{"role": "assistant", "content": "Hi"},
]
- chunks = _split_messages_into_chunks(messages, max_tokens=1000)
+ chunks = _chunk_messages(messages, max_tokens=1000)
assert len(chunks) == 1
assert len(chunks[0]) == 2
@@ -667,7 +677,7 @@ class TestSplitMessagesIntoChunks:
{"role": "user", "content": "C" * 100},
]
# max_tokens=30 should cause splits
- chunks = _split_messages_into_chunks(messages, max_tokens=30)
+ chunks = _chunk_messages(messages, max_tokens=30)
assert len(chunks) == 3
def test_excludes_system_messages(self) -> None:
@@ -675,21 +685,21 @@ class TestSplitMessagesIntoChunks:
{"role": "system", "content": "System prompt"},
{"role": "user", "content": "Hello"},
]
- chunks = _split_messages_into_chunks(messages, max_tokens=1000)
+ chunks = _chunk_messages(messages, max_tokens=1000)
assert len(chunks) == 1
for chunk in chunks:
for msg in chunk:
assert msg.get("role") != "system"
def test_empty_messages(self) -> None:
- chunks = _split_messages_into_chunks([], max_tokens=1000)
+ chunks = _chunk_messages([], max_tokens=1000)
assert chunks == []
def test_only_system_messages(self) -> None:
messages: list[dict[str, Any]] = [
{"role": "system", "content": "System prompt"},
]
- chunks = _split_messages_into_chunks(messages, max_tokens=1000)
+ chunks = _chunk_messages(messages, max_tokens=1000)
assert chunks == []
def test_handles_none_content(self) -> None:
@@ -697,7 +707,7 @@ class TestSplitMessagesIntoChunks:
{"role": "assistant", "content": None},
{"role": "user", "content": "Follow up"},
]
- chunks = _split_messages_into_chunks(messages, max_tokens=1000)
+ chunks = _chunk_messages(messages, max_tokens=1000)
assert len(chunks) == 1
assert len(chunks[0]) == 2
@@ -706,11 +716,11 @@ class TestSplitMessagesIntoChunks:
{"role": "tool", "content": "X" * 1200, "name": "web_scraper"},
]
max_tokens = 100
- chunks = _split_messages_into_chunks(messages, max_tokens=max_tokens)
+ chunks = _chunk_messages(messages, max_tokens=max_tokens)
assert len(chunks) > 1
for chunk in chunks:
chunk_tokens = sum(
- _estimate_token_count(message_content_text(msg)) for msg in chunk
+ _approx_tokens(message_content_text(msg)) for msg in chunk
)
assert chunk_tokens <= max_tokens
@@ -721,11 +731,11 @@ class TestSplitMessagesIntoChunks:
{"role": "assistant", "content": "Done"},
]
max_tokens = 100
- chunks = _split_messages_into_chunks(messages, max_tokens=max_tokens)
+ chunks = _chunk_messages(messages, max_tokens=max_tokens)
assert len(chunks) > 1
for chunk in chunks:
chunk_tokens = sum(
- _estimate_token_count(message_content_text(msg)) for msg in chunk
+ _approx_tokens(message_content_text(msg)) for msg in chunk
)
assert chunk_tokens <= max_tokens
@@ -743,7 +753,7 @@ class TestSplitMessagesIntoChunks:
{"role": "assistant", "content": "Collected HubSpot results."},
]
- chunks = _split_messages_into_chunks(messages, max_tokens=chunk_budget)
+ chunks = _chunk_messages(messages, max_tokens=chunk_budget)
assert len(chunks) > 1
for chunk in chunks:
@@ -805,84 +815,58 @@ class TestMessageContentText:
assert "image_url" not in text
-class TestSplitTextByTokenLimit:
- """Tests for _split_text_by_token_limit helper."""
-
- def test_empty_string(self) -> None:
- assert _split_text_by_token_limit("", max_tokens=100) == []
-
- def test_under_limit_returns_single_part(self) -> None:
- assert _split_text_by_token_limit("hello", max_tokens=100) == ["hello"]
+class TestMessagesReadyToChunk:
+ """Tests for _messages_ready_to_chunk."""
- def test_split_preserves_content(self) -> None:
- text = "a" * 600
- parts = _split_text_by_token_limit(text, max_tokens=100)
- assert len(parts) > 1
- assert "".join(parts) == text
+ def test_keeps_short_message(self) -> None:
+ messages: list[dict[str, Any]] = [{"role": "user", "content": "hello"}]
+ assert _messages_ready_to_chunk(messages, max_tokens=100) == messages
- def test_each_part_estimated_under_limit(self) -> None:
- text = "b" * 1200
+ def test_splits_long_text_and_keeps_each_part_under_limit(self) -> None:
+ messages: list[dict[str, Any]] = [{"role": "user", "content": "b" * 1200}]
max_tokens = 100
- parts = _split_text_by_token_limit(text, max_tokens=max_tokens)
- assert all(_estimate_token_count(part) <= max_tokens for part in parts)
-
-
-class TestExpandOversizedMessage:
- """Tests for _expand_oversized_message helper."""
-
- def test_returns_original_when_under_limit(self) -> None:
- msg: dict[str, Any] = {"role": "user", "content": "hello"}
- expanded = _expand_oversized_message(msg, max_tokens=100)
- assert expanded == [msg]
+ ready = _messages_ready_to_chunk(messages, max_tokens=max_tokens)
+ assert len(ready) > 1
+ assert ready[0]["content"].startswith("[Part 1/")
+ assert all(
+ _approx_tokens(message_content_text(msg)) <= max_tokens for msg in ready
+ )
def test_splits_tool_output_with_metadata(self) -> None:
- msg: dict[str, Any] = {
- "role": "tool",
- "content": "Z" * 1200,
- "name": "fetch_page",
- "tool_call_id": "call_123",
- }
- expanded = _expand_oversized_message(msg, max_tokens=100)
- assert len(expanded) > 1
- assert all(part["role"] == "tool" for part in expanded)
- assert all(part["name"] == "fetch_page" for part in expanded)
- assert all(part["tool_call_id"] == "call_123" for part in expanded)
- assert expanded[0]["content"].startswith("[Part 1/")
+ messages: list[dict[str, Any]] = [
+ {
+ "role": "tool",
+ "content": "Z" * 1200,
+ "name": "fetch_page",
+ "tool_call_id": "call_123",
+ }
+ ]
+ ready = _messages_ready_to_chunk(messages, max_tokens=100)
+ assert len(ready) > 1
+ assert all(part["role"] == "tool" for part in ready)
+ assert all(part["name"] == "fetch_page" for part in ready)
+ assert all(part["tool_call_id"] == "call_123" for part in ready)
def test_preserves_non_content_fields(self) -> None:
mock_file = MagicMock()
- msg: dict[str, Any] = {
- "role": "user",
- "content": "X" * 1200,
- "files": {"report.pdf": mock_file},
- }
- expanded = _expand_oversized_message(msg, max_tokens=100)
- assert len(expanded) > 1
- assert all(part["role"] == "user" for part in expanded)
- assert all(part["files"] == {"report.pdf": mock_file} for part in expanded)
-
- def test_each_part_estimated_under_limit(self) -> None:
- msg: dict[str, Any] = {"role": "user", "content": "Y" * 1200}
- max_tokens = 100
- expanded = _expand_oversized_message(msg, max_tokens=max_tokens)
- assert len(expanded) > 1
- assert all(
- _estimate_token_count(message_content_text(part)) <= max_tokens
- for part in expanded
- )
-
-
-class TestNormalizeMessagesForChunking:
- """Tests for _normalize_messages_for_chunking helper."""
+ messages: list[dict[str, Any]] = [
+ {
+ "role": "user",
+ "content": "X" * 1200,
+ "files": {"report.pdf": mock_file},
+ }
+ ]
+ ready = _messages_ready_to_chunk(messages, max_tokens=100)
+ assert len(ready) > 1
+ assert all(part["files"] == {"report.pdf": mock_file} for part in ready)
def test_excludes_system_messages(self) -> None:
messages: list[dict[str, Any]] = [
{"role": "system", "content": "System prompt"},
{"role": "user", "content": "Hello"},
]
- normalized = _normalize_messages_for_chunking(messages, max_tokens=1000)
- assert len(normalized) == 1
- assert normalized[0]["role"] == "user"
+ ready = _messages_ready_to_chunk(messages, max_tokens=1000)
+ assert ready == [{"role": "user", "content": "Hello"}]
def test_expands_oversized_and_preserves_small_messages(self) -> None:
messages: list[dict[str, Any]] = [
@@ -891,32 +875,31 @@ class TestNormalizeMessagesForChunking:
{"role": "assistant", "content": "Done"},
]
max_tokens = 100
- normalized = _normalize_messages_for_chunking(messages, max_tokens=max_tokens)
- assert normalized[0]["content"] == "Short"
- assert normalized[-1]["content"] == "Done"
- assert len(normalized) > 3
+ ready = _messages_ready_to_chunk(messages, max_tokens=max_tokens)
+ assert ready[0]["content"] == "Short"
+ assert ready[-1]["content"] == "Done"
+ assert len(ready) > 3
assert all(
- _estimate_token_count(message_content_text(msg)) <= max_tokens
- for msg in normalized
+ _approx_tokens(message_content_text(msg)) <= max_tokens for msg in ready
)
class TestEstimateTokenCount:
- """Tests for _estimate_token_count helper."""
+ """Tests for _approx_tokens helper."""
def test_empty_string(self) -> None:
- assert _estimate_token_count("") == 0
+ assert _approx_tokens("") == 0
def test_short_string(self) -> None:
- assert _estimate_token_count("hello") == 1 # 5 // 4 = 1
+ assert _approx_tokens("hello") == 1 # 5 // 4 = 1
def test_longer_string(self) -> None:
- assert _estimate_token_count("a" * 100) == 25 # 100 // 4 = 25
+ assert _approx_tokens("a" * 100) == 25 # 100 // 4 = 25
def test_approximation_is_conservative(self) -> None:
# For English text, actual token count is typically lower than char/4
text = "The quick brown fox jumps over the lazy dog."
- estimated = _estimate_token_count(text)
+ estimated = _approx_tokens(text)
assert estimated > 0
assert estimated == len(text) // 4
@@ -961,12 +944,10 @@ class TestParallelSummarization:
# acall should have been awaited once per chunk
assert mock_llm.acall.await_count == 3
- # sync call should NOT have been used for chunk summarization
mock_llm.call.assert_not_called()
- def test_single_chunk_uses_sync_call(self) -> None:
- """When there is only one chunk, summarize_messages should use
- the sync llm.call path (no async overhead)."""
+ def test_single_chunk_uses_one_coroutine(self) -> None:
+ """One chunk still goes through _summarize_all."""
messages: list[dict[str, Any]] = [
{"role": "user", "content": "Short message"},
{"role": "assistant", "content": "Short reply"},
@@ -974,7 +955,7 @@ class TestParallelSummarization:
mock_llm = MagicMock()
mock_llm.get_context_window_size.return_value = 100_000
- mock_llm.call.return_value = "<summary>Short summary</summary>"
+ mock_llm.acall = AsyncMock(return_value="<summary>Short summary</summary>")
summarize_messages(
messages=messages,
@@ -983,7 +964,7 @@ class TestParallelSummarization:
)
- mock_llm.call.assert_called_once()
+ mock_llm.acall.assert_awaited_once()
def test_parallel_results_preserve_order(self) -> None:
"""Summaries must appear in the same order as the original chunks,
@@ -1020,8 +1001,8 @@ class TestParallelSummarization:
pos_c = summary_content.index("Summary-C")
assert pos_a < pos_b < pos_c
- def test_asummarize_chunks_returns_ordered_results(self) -> None:
- """Direct test of the async helper _asummarize_chunks."""
+ def test_summarize_all_returns_ordered_results(self) -> None:
+ """Direct test of _summarize_all."""
chunk_a: list[dict[str, Any]] = [{"role": "user", "content": "Chunk A"}]
chunk_b: list[dict[str, Any]] = [{"role": "user", "content": "Chunk B"}]
@@ -1033,18 +1014,77 @@ class TestParallelSummarization:
]
)
- results = asyncio.run(
- _asummarize_chunks(
- chunks=[chunk_a, chunk_b],
+ summarizer = SummarizeMessages()
+ summarizer.llm = mock_llm
+ summarizer.callbacks = []
+ results = summarizer._summarize_all(
+ chunks=[chunk_a, chunk_b], char_level_index=0
+ )
+
+ assert results == ["Result A", "Result B"]
+
+ def test_summarize_all_retries_after_context_length_error(self) -> None:
+ """A chunk that overflows context is retried after tighter token estimation."""
+ chunk: list[dict[str, Any]] = [{"role": "user", "content": "x" * 800}]
+
+ mock_llm = MagicMock()
+ mock_llm.get_context_window_size.return_value = 100_000
+ mock_llm.acall = AsyncMock(
+ side_effect=[
+ LLMContextLengthExceededError("context length exceeded"),
+ "<summary>Recovered summary</summary>",
+ ]
+ )
+
+ summarizer = SummarizeMessages()
+ summarizer.llm = mock_llm
+ summarizer.callbacks = []
+ summarizer.verbose = False
+
+ results = summarizer._summarize_all(chunks=[chunk], char_level_index=0)
+
+ assert results == ["Recovered summary"]
+ assert mock_llm.acall.await_count == 2
+
+ def test_summarize_messages_retries_each_char_per_token_level(self) -> None:
+ """Context errors step through chunk levels 0, 1, and 2 before succeeding."""
+ messages: list[dict[str, Any]] = [{"role": "user", "content": "x" * 800}]
+ recorded_levels: list[int] = []
+ original_chunk = SummarizeMessages._chunk_messages
+
+ def tracking_chunk(
+ self: SummarizeMessages,
+ chunk_messages: list[dict[str, Any]],
+ max_tokens: int,
+ char_level_index: int = 0,
+ ) -> list[list[dict[str, Any]]]:
+ recorded_levels.append(char_level_index)
+ return original_chunk(
+ self, chunk_messages, max_tokens, char_level_index=char_level_index
+ )
+
+ mock_llm = MagicMock()
+ mock_llm.get_context_window_size.return_value = 100_000
+ mock_llm.acall = AsyncMock(
+ side_effect=[
+ LLMContextLengthExceededError("context length exceeded"),
+ LLMContextLengthExceededError("context length exceeded"),
+ "<summary>Final summary</summary>",
+ ]
+ )
+
+ with patch.object(SummarizeMessages, "_chunk_messages", tracking_chunk):
+ summarize_messages(
+ messages=messages,
llm=mock_llm,
callbacks=[],
-
+ verbose=False,
)
- )
- assert len(results) == 2
- assert results[0]["content"] == "Result A"
- assert results[1]["content"] == "Result B"
+ assert len(messages) == 1
+ assert "Final summary" in messages[0]["content"]
+ assert recorded_levels == [0, 1, 2]
+ assert mock_llm.acall.await_count == 3
@patch("crewai.utilities.agent_utils.is_inside_event_loop", return_value=True)
def test_works_inside_existing_event_loop(self, _mock_loop: Any) -> None:
@@ -1170,7 +1210,7 @@ class TestParallelSummarizationVCR:
# Patch get_context_window_size to return 200 — forces multiple chunks
with patch.object(type(llm), "get_context_window_size", return_value=200):
non_system = [m for m in messages if m.get("role") != "system"]
- chunks = _split_messages_into_chunks(non_system, max_tokens=200)
+ chunks = _chunk_messages(non_system, max_tokens=200)
assert len(chunks) > 1, f"Expected multiple chunks, got {len(chunks)}"
summarize_messages(