smart_compact

package
v0.260418.2200 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 18, 2026 License: MPL-2.0 Imports: 8 Imported by: 0

Documentation

Overview

Package smart_compact provides conversation compression strategies and transformers for Anthropic requests.

The package includes:

  • CompressionStrategy interface for defining compression algorithms
  • Strategy implementations (conversation replay, document, round-only, round-files)
  • Transform implementations that implement transform.Transform interface
  • Legacy CompactTransformer for test compatibility only (production code uses ThinkingCompactTransform)

Strategies compress conversation rounds by removing thinking blocks, tool calls, and tool results while preserving the essential flow of user requests and assistant responses.

For new code, prefer using the transform.Transform implementations:

  • NewCompactTransform() / ThinkingCompactTransform - removes thinking blocks
  • NewRoundOnlyTransform() / RoundOnlyTransform - keeps only user/assistant text
  • NewRoundFilesTransform() / RoundFilesTransform - keeps text + virtual file tools
  • NewConversationReplayTransformer() - replay-based compression
  • NewConversationDocumentTransformer() - document-based compression
  • NewDeduplicationTransform() - removes duplicate tool calls
  • NewPurgeErrorsTransform() - removes errored tool inputs

Index

Constants

View Source 
const (
	VirtualReadTool   = "read_file"
	ExpiredContentMsg = "Content has expired, please view again"
)

Virtual tool constants

Variables

This section is empty.

Functions

func CreateBetaVirtualToolCalls 

func CreateBetaVirtualToolCalls(files []string) []any

CreateBetaVirtualToolCalls creates virtual tool calls for beta API.

func CreateVirtualToolCalls 

func CreateVirtualToolCalls(files []string) []any

CreateVirtualToolCalls creates virtual tool use + result messages.

func FormatFileNote 

func FormatFileNote(files []string) string

FormatFileNote formats collected file paths into a note string.

func NewCompactTransform added in v0.260414.2000 

func NewCompactTransform(keepLastNRounds int) transform.Transform

NewCompactTransform creates a new ThinkingCompactTransform with default config.

The keepLastNRounds parameter controls how many recent conversation rounds should have their thinking blocks preserved. Higher values retain more reasoning context but save fewer tokens.

Recommendations:

  • keepLastNRounds=1: Default, preserves only the current request's thinking
  • keepLastNRounds=2-3: Suitable for multi-step reasoning, debugging, or document analysis
  • Minimum allowed value is 1 (current round's thinking is always preserved)

func NewCompactTransformWithConfig added in v0.260414.2000 

func NewCompactTransformWithConfig(config CompactConfig) transform.Transform

NewCompactTransformWithConfig creates a new ThinkingCompactTransform with custom config.

func NewConversationDocumentTransformer added in v0.260414.2000 

func NewConversationDocumentTransformer() transform.Transform

NewConversationDocumentTransformer creates a new document-based compact transformer.

func NewConversationReplayTransformer added in v0.260414.2000 

func NewConversationReplayTransformer() transform.Transform

NewConversationReplayTransformer creates a new replay transformer.

func NewDeduplicationTransform added in v0.260414.2000 

func NewDeduplicationTransform() transform.Transform

NewDeduplicationTransform creates a new DeduplicationTransform.

func NewPurgeErrorsTransform added in v0.260414.2000 

func NewPurgeErrorsTransform(gracePeriodTurns int) transform.Transform

NewPurgeErrorsTransform creates a PurgeErrorsTransform. gracePeriodTurns is the number of turns after which errored tool inputs are removed. 0 disables the transform.

func NewRoundFilesTransformer 

func NewRoundFilesTransformer() transform.Transform

NewRoundFilesTransformer creates a transform.Transform for round-files compression.

func NewRoundOnlyTransformer 

func NewRoundOnlyTransformer() transform.Transform

NewRoundOnlyTransformer creates a transform.Transform for round-only compression.

func NewXMLCompactTransform added in v0.260414.2000 

func NewXMLCompactTransform() transform.Transform

NewXMLCompactTransform creates a new XMLCompactTransform.

func NewXMLCompactionTransformer added in v0.260414.2000 

func NewXMLCompactionTransformer() transform.Transform

NewXMLCompactionTransformer creates a new compaction transformer.

func RemoveBetaThinkingBlocks added in v0.260414.2000 

func RemoveBetaThinkingBlocks(content []anthropic.BetaContentBlockParamUnion, count int) ([]anthropic.BetaContentBlockParamUnion, int)

RemoveBetaThinkingBlocks removes thinking content blocks from beta message content. Returns the filtered content and the count of removed blocks.

func RemoveV1ThinkingBlocks added in v0.260414.2000 

func RemoveV1ThinkingBlocks(content []anthropic.ContentBlockParamUnion, count int) ([]anthropic.ContentBlockParamUnion, int)

RemoveV1ThinkingBlocks removes thinking content blocks from v1 message content. Returns the filtered content and the count of removed blocks.

func ShouldCompactRound added in v0.260414.2000 

func ShouldCompactRound(stats *protocol.RoundStats, cfg CompactConfig) bool

ShouldCompactRound performs guard checks to determine if a round is safe to compact.

Guard checks:

  • UserMessageCount == 1: Round should have exactly one pure user message as start
  • AssistantCount >= MinAssistantCount: Round should have at least MinAssistantCount assistant responses

Note: ToolResultCount is not enforced as a guard because not all conversations use tools. A round is valid with just user/assistant text exchanges.

Returns false if the round structure appears malformed, preventing compaction on potentially incorrectly grouped rounds.

Types

type CompactConfig added in v0.260414.2000 

type CompactConfig struct {
	KeepLastNRounds   int // Number of recent rounds to preserve thinking blocks (min: 1)
	MinAssistantCount int // Minimum assistant messages required for compaction (default: 1)
}

CompactConfig holds configuration for round compaction.

func DefaultCompactConfig added in v0.260414.2000 

func DefaultCompactConfig() CompactConfig

DefaultCompactConfig returns the default configuration for compaction.

type CompactTransformer 

type CompactTransformer struct {
	// contains filtered or unexported fields
}

CompactTransformer implements the Transformer interface.

func NewCompactTransformer 

func NewCompactTransformer(keepLastNRounds int, opts ...Option) *CompactTransformer

NewCompactTransformer creates a new smart_compact transformer instance.

The keepLastNRounds parameter controls how many recent conversation rounds should have their thinking blocks preserved. Higher values retain more reasoning context but save fewer tokens.

Recommendations:

  • keepLastNRounds=1: Default, preserves only the current request's thinking
  • keepLastNRounds=2-3: Suitable for multi-step reasoning, debugging, or document analysis
  • Minimum allowed value is 1 (current round's thinking is always preserved)

func (*CompactTransformer) HandleV1 

func (t *CompactTransformer) HandleV1(req *anthropic.MessageNewParams) error

HandleV1 compacts an Anthropic v1 request by removing thinking fields from non-current rounds.

func (*CompactTransformer) HandleV1Beta 

func (t *CompactTransformer) HandleV1Beta(req *anthropic.BetaMessageNewParams) error

HandleV1Beta compacts an Anthropic v1beta request by removing thinking fields from non-current rounds.

type CompressionStrategy 

type CompressionStrategy interface {
	// Name returns the strategy identifier
	Name() string

	// CompressV1 compresses v1 messages
	CompressV1(messages []anthropic.MessageParam) []anthropic.MessageParam

	// CompressBeta compresses beta messages
	CompressBeta(messages []anthropic.BetaMessageParam) []anthropic.BetaMessageParam
}

CompressionStrategy defines the interface for compression algorithms.

type ConversationDocumentStrategy added in v0.260414.2000 

type ConversationDocumentStrategy struct {
	// contains filtered or unexported fields
}

ConversationDocumentStrategy compresses conversation history into an Anthropic document content block placed in a user message.

Unlike ConditionalCompactStrategy (which produces an assistant text message), this strategy uses the Anthropic document block type, allowing the model to reference the conversation history as a cited document.

Only activates when: 1. Last user message contains "compact" (case-insensitive) 2. Request has tool definitions

func NewConversationDocumentStrategy added in v0.260414.2000 

func NewConversationDocumentStrategy() *ConversationDocumentStrategy

NewConversationDocumentStrategy creates a new document-based compact strategy.

func (*ConversationDocumentStrategy) CompressBeta added in v0.260414.2000 

func (s *ConversationDocumentStrategy) CompressBeta(messages []anthropic.BetaMessageParam) []anthropic.BetaMessageParam

CompressBeta compresses beta messages into a user message with a document block.

func (*ConversationDocumentStrategy) CompressV1 added in v0.260414.2000 

func (s *ConversationDocumentStrategy) CompressV1(messages []anthropic.MessageParam) []anthropic.MessageParam

CompressV1 compresses v1 messages into a user message with a document block.

func (*ConversationDocumentStrategy) Name added in v0.260414.2000 

func (s *ConversationDocumentStrategy) Name() string

Name returns the strategy identifier.

type ConversationDocumentTransformer added in v0.260414.2000 

type ConversationDocumentTransformer struct {
	// contains filtered or unexported fields
}

ConversationDocumentTransformer applies document-based compression using transform.Transform interface.

Conditions for activation (same as ConditionalCompactTransformer): 1. Last user message contains "compact" (case-insensitive) 2. Request has tool definitions

func (*ConversationDocumentTransformer) Apply added in v0.260414.2000 

func (t *ConversationDocumentTransformer) Apply(ctx *transform.TransformContext) error

Apply applies the document-based compression to the request.

func (*ConversationDocumentTransformer) Name added in v0.260414.2000 

func (t *ConversationDocumentTransformer) Name() string

Name returns the transform identifier.

type ConversationReplayStrategy added in v0.260414.2000 

type ConversationReplayStrategy struct {
	// contains filtered or unexported fields
}

ConversationReplayStrategy compresses conversation history by reconstructing historical message blocks into a single assistant message.

Each conversation turn is represented as: - A text block with "[User]" or "[Assistant]" role prefix - Followed by the original tool_use and tool_result blocks (for assistant turns)

This preserves the structural information (tool calls, results) while fitting everything into a single assistant message that the model can reference.

Beta API: produces assistant message with reconstructed blocks. V1 API: falls back to XML text message (v1 lacks rich block types for this pattern).

func NewConversationReplayStrategy added in v0.260414.2000 

func NewConversationReplayStrategy() *ConversationReplayStrategy

NewConversationReplayStrategy creates a new replay-based strategy.

func (*ConversationReplayStrategy) CompressBeta added in v0.260414.2000 

func (s *ConversationReplayStrategy) CompressBeta(messages []anthropic.BetaMessageParam) []anthropic.BetaMessageParam

CompressBeta reconstructs historical beta messages into a single assistant message with typed blocks preserving tool_use/tool_result structure.

func (*ConversationReplayStrategy) CompressV1 added in v0.260414.2000 

func (s *ConversationReplayStrategy) CompressV1(messages []anthropic.MessageParam) []anthropic.MessageParam

CompressV1 falls back to XML text message since v1 lacks the block variety needed.

func (*ConversationReplayStrategy) Name added in v0.260414.2000 

func (s *ConversationReplayStrategy) Name() string

Name returns the strategy identifier.

type ConversationReplayTransformer added in v0.260414.2000 

type ConversationReplayTransformer struct {
	// contains filtered or unexported fields
}

ConversationReplayTransformer applies replay-based compression using transform.Transform interface.

Same trigger conditions as other compact transformers: 1. Last user message contains "compact" (case-insensitive) 2. Request has tool definitions

func (*ConversationReplayTransformer) Apply added in v0.260414.2000 

func (t *ConversationReplayTransformer) Apply(ctx *transform.TransformContext) error

Apply applies the replay-based compression to the request.

func (*ConversationReplayTransformer) Name added in v0.260414.2000 

func (t *ConversationReplayTransformer) Name() string

Name returns the transform identifier.

type DeduplicationTransform added in v0.260414.2000 

type DeduplicationTransform struct{}

DeduplicationTransform removes duplicate tool calls from messages. For each unique tool signature (name + params), only the most recent call's output is kept; earlier occurrences have their tool_result content replaced with a placeholder.

func (*DeduplicationTransform) Apply added in v0.260414.2000 

func (t *DeduplicationTransform) Apply(ctx *transform.TransformContext) error

func (*DeduplicationTransform) Name added in v0.260414.2000 

func (t *DeduplicationTransform) Name() string

type Option added in v0.260414.2000 

type Option = func(*CompactTransformer)

Option configures a CompactTransformer.

func WithMinAssistant added in v0.260414.2000 

func WithMinAssistant(count int) Option

WithMinAssistant sets the minimum assistant count required for compaction.

type PathUtil 

type PathUtil struct {
	// contains filtered or unexported fields
}

PathUtil extracts and manipulates file paths from tool parameters.

func NewPathUtil 

func NewPathUtil() *PathUtil

NewPathUtil creates a new path utility.

func (*PathUtil) Extract 

func (e *PathUtil) Extract(input string) []string

Extract extracts all file paths from input string.

func (*PathUtil) ExtractFromMap 

func (e *PathUtil) ExtractFromMap(m map[string]any) []string

ExtractFromMap extracts file paths from map (tool input parameters).

type PurgeErrorsTransform added in v0.260414.2000 

type PurgeErrorsTransform struct {
	// contains filtered or unexported fields
}

PurgeErrorsTransform removes the input of errored tool calls that are older than a configurable number of turns. The error output (tool_result content) is preserved so the LLM still has context about what went wrong.

A "turn" here is counted by user-message boundaries. A value of 0 disables the transform entirely.

func (*PurgeErrorsTransform) Apply added in v0.260414.2000 

func (t *PurgeErrorsTransform) Apply(ctx *transform.TransformContext) error

func (*PurgeErrorsTransform) Name added in v0.260414.2000 

func (t *PurgeErrorsTransform) Name() string

type RoundFilesTransform added in v0.260414.2000 

type RoundFilesTransform struct {
	// contains filtered or unexported fields
}

RoundFilesTransform keeps user/assistant + file paths as virtual tool calls. This removes tool_use/tool_result blocks but injects virtual tool calls summarizing which files were used in each round.

func NewRoundFilesTransform added in v0.260414.2000 

func NewRoundFilesTransform() *RoundFilesTransform

NewRoundFilesTransform creates a new RoundFilesTransform.

func NewRoundWithFilesStrategy 

func NewRoundWithFilesStrategy() *RoundFilesTransform

NewRoundWithFilesStrategy creates a RoundFilesTransform for direct use (mainly for tests). This returns the concrete type so tests can call CompressV1/CompressBeta directly.

func (*RoundFilesTransform) Apply added in v0.260414.2000 

func (t *RoundFilesTransform) Apply(ctx *transform.TransformContext) error

Apply applies the round-files compression to the request.

func (*RoundFilesTransform) CompressBeta added in v0.260414.2000 

func (t *RoundFilesTransform) CompressBeta(messages []anthropic.BetaMessageParam) []anthropic.BetaMessageParam

CompressBeta compresses beta messages keeping user/assistant + virtual file tool calls.

func (*RoundFilesTransform) CompressV1 added in v0.260414.2000 

func (t *RoundFilesTransform) CompressV1(messages []anthropic.MessageParam) []anthropic.MessageParam

CompressV1 compresses v1 messages keeping user/assistant + virtual file tool calls.

func (*RoundFilesTransform) Name added in v0.260414.2000 

func (t *RoundFilesTransform) Name() string

Name returns the transform identifier.

type RoundOnlyTransform added in v0.260414.2000 

type RoundOnlyTransform struct {
	// contains filtered or unexported fields
}

RoundOnlyTransform keeps only user request + assistant conclusion. This removes all tool_use, tool_result, and thinking blocks from historical rounds.

func NewRoundOnlyStrategy 

func NewRoundOnlyStrategy() *RoundOnlyTransform

NewRoundOnlyStrategy creates a RoundOnlyTransform for direct use (mainly for tests). This returns the concrete type so tests can call CompressV1/CompressBeta directly.

func NewRoundOnlyTransform added in v0.260414.2000 

func NewRoundOnlyTransform() *RoundOnlyTransform

NewRoundOnlyTransform creates a new RoundOnlyTransform.

func (*RoundOnlyTransform) Apply added in v0.260414.2000 

func (t *RoundOnlyTransform) Apply(ctx *transform.TransformContext) error

Apply applies the round-only compression to the request.

func (*RoundOnlyTransform) CompressBeta added in v0.260414.2000 

func (t *RoundOnlyTransform) CompressBeta(messages []anthropic.BetaMessageParam) []anthropic.BetaMessageParam

CompressBeta compresses beta messages (same logic as CompressV1).

func (*RoundOnlyTransform) CompressV1 added in v0.260414.2000 

func (t *RoundOnlyTransform) CompressV1(messages []anthropic.MessageParam) []anthropic.MessageParam

CompressV1 compresses v1 messages by keeping only user request + assistant conclusion.

func (*RoundOnlyTransform) Name added in v0.260414.2000 

func (t *RoundOnlyTransform) Name() string

Name returns the transform identifier.

type ThinkingCompactTransform added in v0.260414.2000 

type ThinkingCompactTransform struct {
	// contains filtered or unexported fields
}

ThinkingCompactTransform removes thinking fields from non-current rounds. This is the transform-style implementation that implements transform.Transform.

func (*ThinkingCompactTransform) Apply added in v0.260414.2000 

func (t *ThinkingCompactTransform) Apply(ctx *transform.TransformContext) error

Apply applies the compaction to the request.

func (*ThinkingCompactTransform) Name added in v0.260414.2000 

func (t *ThinkingCompactTransform) Name() string

Name returns the transform identifier.

type XMLCompactTransform added in v0.260414.2000 

type XMLCompactTransform struct {
	// contains filtered or unexported fields
}

XMLCompactTransform compresses conversation history into XML format.

This is a pure compression strategy that always compresses the conversation into an XML-formatted assistant message. The conditional logic should be handled at the Virtual Model layer using ConditionalWrapper.

func (*XMLCompactTransform) Apply added in v0.260414.2000 

func (t *XMLCompactTransform) Apply(ctx *transform.TransformContext) error

Apply applies XML compression to the request.

func (*XMLCompactTransform) Name added in v0.260414.2000 

func (t *XMLCompactTransform) Name() string

Name returns the transform identifier.

type XMLCompactionStrategy added in v0.260414.2000 

type XMLCompactionStrategy struct {
	// contains filtered or unexported fields
}

XMLCompactionStrategy compresses conversation history using Anthropic's native compaction block type (BetaCompactionBlockParam).

Beta API: produces assistant message with compaction block. V1 API: compaction block is unsupported; falls back to assistant text message with XML.

func NewXMLCompactionStrategy added in v0.260414.2000 

func NewXMLCompactionStrategy() *XMLCompactionStrategy

NewXMLCompactionStrategy creates a new compaction-based strategy.

func (*XMLCompactionStrategy) CompressBeta added in v0.260414.2000 

func (s *XMLCompactionStrategy) CompressBeta(messages []anthropic.BetaMessageParam) []anthropic.BetaMessageParam

CompressBeta compresses beta messages into a single assistant message with a compaction block.

func (*XMLCompactionStrategy) CompressV1 added in v0.260414.2000 

func (s *XMLCompactionStrategy) CompressV1(messages []anthropic.MessageParam) []anthropic.MessageParam

CompressV1 falls back to XML text message since compaction block is beta-only.

type XMLCompactionTransformer added in v0.260414.2000 

type XMLCompactionTransformer struct {
	// contains filtered or unexported fields
}

XMLCompactionTransformer applies compaction block compression using transform.Transform interface.

Same trigger conditions as other compact transformers: 1. Last user message contains "compact" (case-insensitive) 2. Request has tool definitions

func (*XMLCompactionTransformer) Apply added in v0.260414.2000 

func (t *XMLCompactionTransformer) Apply(ctx *transform.TransformContext) error

Apply applies the compaction block compression to the request.

func (*XMLCompactionTransformer) Name added in v0.260414.2000 

func (t *XMLCompactionTransformer) Name() string

Name returns the transform identifier.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.