calute.agents.compaction_agent

calute.agents.compaction_agent#

Dedicated agent for intelligent context compaction through summarization.

This module provides the CompactionAgent class, which specializes in compacting conversation context and message histories through intelligent summarization. It helps manage context length in long-running conversations by creating concise summaries while preserving critical information.

The agent supports features like: - Multiple summary length modes (brief, concise, detailed) - Topic preservation during summarization - Message history compaction with recent message preservation - Fallback truncation when LLM-based summarization fails - Asynchronous LLM integration for summary generation

Typical usage example:

from calute.agents.compaction_agent import CompactionAgent

agent = CompactionAgent(

llm_client=my_llm_client, target_length=”concise”

)

# Summarize raw context summary = agent.summarize_context(long_context)

# Compact message history compacted = agent.summarize_messages(messages, preserve_recent=3)

class calute.agents.compaction_agent.CompactionAgent(llm_client: Any, target_length: str = 'concise')[source]#

Bases: object

Agent specialized in compacting context through intelligent summarization.

CompactionAgent provides intelligent context compaction capabilities using LLM-based summarization. It can summarize raw text context or entire message histories while preserving important information and recent interactions.

The agent uses configurable length instructions to control output verbosity and supports topic preservation to ensure critical subjects are covered in summaries.

llm_client#

LLM client instance used for generating summaries. Must support generate_completion method for async completion.

target_length#

Target summary verbosity level. One of: - ‘brief’: Extremely concise, 2-3 sentences - ‘concise’: Balanced, captures key points in paragraphs - ‘detailed’: Comprehensive, preserves context and decisions

length_instructions#

Dictionary mapping length modes to instruction prompts used to guide the LLM’s summarization behavior.

Example

>>> agent = CompactionAgent(llm_client=client, target_length="brief")
>>> summary = agent.summarize_context("Long conversation text...")
>>> print(summary)  # Returns 2-3 sentence summary
summarize_context(context: str, preserve_topics: list[str] | None = None) → str[source]#

Summarize context intelligently using LLM-based summarization.

Uses the configured LLM client to generate an intelligent summary of the provided context. The summary respects the configured target_length setting and can preserve specific topics during compaction.

Parameters

  • context – The raw text context to summarize. If empty or under 200 characters, returns the original context unchanged.

  • preserve_topics – Optional list of topic keywords that must be covered in the summary. These topics are explicitly mentioned in the summarization prompt to ensure coverage.

Returns

Summarized context text. Returns original context if it’s

too short (< 200 chars) or if summarization fails.

Return type

str

Raises

No exceptions are raised; errors fall back to truncation. –

Note

  • Uses asyncio to run the async LLM completion synchronously

  • Falls back to _fallback_truncate if LLM call fails

  • Temperature is set to 0.3 for consistent, focused summaries

  • Max tokens is limited to 2048 for the summary response

Example

>>> summary = agent.summarize_context(
...     "Long conversation about AI and machine learning...",
...     preserve_topics=["neural networks", "training data"]
... )
summarize_messages(messages: list[dict[str, str]], preserve_recent: int = 3) → list[dict[str, str]][source]#

Summarize a list of messages into a compacted conversation history.

Compacts a message history by summarizing older messages while preserving recent messages unchanged. System messages are always preserved separately. The summary is inserted as a special user message indicating it represents the previous conversation.

Parameters

  • messages – List of message dictionaries with ‘role’ and ‘content’ keys. Roles typically include ‘system’, ‘user’, and ‘assistant’.

  • preserve_recent – Number of most recent non-system messages to keep unchanged. Defaults to 3. Set to 0 to summarize all messages.

Returns

Compacted message list containing:

  • All original system messages (preserved as-is)

  • One summary message with role ‘user’ containing the summary

  • The most recent preserve_recent messages unchanged

Return type

list[dict[str, str]]

Note

  • If total messages <= preserve_recent + 1, returns original messages

  • System messages are separated and always preserved at the beginning

  • The summary message includes a header indicating how many messages were summarized: “[PREVIOUS CONVERSATION SUMMARY - N messages]”

Example

>>> messages = [
...     {"role": "system", "content": "You are helpful."},
...     {"role": "user", "content": "Hello"},
...     {"role": "assistant", "content": "Hi there!"},
...     {"role": "user", "content": "Tell me about AI"},
...     {"role": "assistant", "content": "AI is..."},
... ]
>>> compacted = agent.summarize_messages(messages, preserve_recent=2)
>>> len(compacted)  # system + summary + 2 recent = 4 messages
4
calute.agents.compaction_agent.create_compaction_agent(llm_client: Any, target_length: str = 'concise') → CompactionAgent[source]#

Factory function to create a compaction agent.

Convenience factory for creating CompactionAgent instances with the specified configuration. Provides a simple interface for agent creation without needing to import and instantiate the class directly.

Parameters

  • llm_client – LLM client instance for generating summaries. Should support the generate_completion method for async completion.

  • target_length – Target summary length mode. Valid values are: - ‘brief’: Extremely brief summaries (2-3 sentences) - ‘concise’: Balanced summaries with key points (default) - ‘detailed’: Comprehensive summaries preserving context

Returns

Configured compaction agent instance ready for use.

Return type

CompactionAgent

Example

>>> agent = create_compaction_agent(my_llm_client, "brief")
>>> summary = agent.summarize_context("Long text...")
Contents