compaction

package
v0.1.4 Latest Latest
Warning

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

Go to latest
Published: Nov 20, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package compaction summarizes long conversations using surface replacement (S01), matching compaction/compaction and compaction-engine-basic. When estimated event tokens exceed MaxTokens, it summarizes the oldest surface into an assistant message with a replacement range. Source events remain immutable and append-only. New events can still be appended, and request headers use effective events only. Summarizer supports BasicEngine (prefix summaries without an LLM) and an optional LLMEngine with an injected llm.LLMAdapter.

BasicEngine is the deterministic, LLM-free summarizer for S01. It extracts user messages into a past-conversation summary bounded by maxRunes. This keeps compaction available offline or without credentials; LLMEngine can replace it when more concise model-generated summaries are desired.

Tool pairing matches compaction/tool-pairing upstream. Safe cut points depend on balanced tool calls and results, not just step markers. Cutting between a call and its result leaves invalid history that can stall the model.

Tool-result pruning matches compaction-tool-result-pruner: keep the head and tail of long text and replace the middle with a marker. Rune boundaries preserve Unicode code points; text below the threshold is unchanged with changed=false.

Index

Constants

View Source
const BasicEngineSumm = "【摘要】过去对话摘要如下:"

BasicEngineSumm is the summary title or prefix used by BasicEngine.

View Source
const PruneMarker = "\n... [内容已省略] ...\n"

PruneMarker replaces the removed middle portion.

Variables

View Source
var ErrUnbalanced = errors.New("compaction: unbalanced tool pairing")

ErrUnbalanced indicates an unmatched tool result or unbalanced history.

Functions

func BalancedCuts

func BalancedCuts(events []session.SessionEvent) ([]bool, error)

BalancedCuts reports balance at N+1 cuts for N events: cut[0] precedes all events, cut[i] follows event i, and cut[N] is last. Zero outstanding calls is balanced.

func EstimateTokens

func EstimateTokens(events []session.SessionEvent) int

EstimateTokens estimates total event tokens for trigger decisions.

func IsBalancedAt

func IsBalancedAt(events []session.SessionEvent, cut int) (bool, error)

IsBalancedAt checks a cut in the range 0..len(events).

func NearestBalancedFrom

func NearestBalancedFrom(events []session.SessionEvent, start int) int

NearestBalancedFrom finds the first balanced cut at or after start, or -1. It advances a proposed compaction boundary without splitting tool pairs.

func PruneText

func PruneText(text string, threshold, head, tail int) (string, bool)

PruneText preserves text at or below threshold runes. Otherwise it keeps head and tail runes with PruneMarker between them. Counts are nonnegative and the tail is limited to available content.

func ShouldCompact

func ShouldCompact(events []session.SessionEvent, maxTokens int) bool

ShouldCompact reports whether compaction is needed.

Types

type BasicEngine

type BasicEngine struct{}

BasicEngine produces deterministic summaries without an LLM.

func (*BasicEngine) Summarize

func (b *BasicEngine) Summarize(ctx context.Context, events []session.SessionEvent, maxRunes int) (string, error)

Summarize uses the first few user messages, truncated to maxRunes.

type Compactor

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

Compactor checks the trigger, selects a range, summarizes, and creates its replacement.

func New

func New(cfg Config, summarizer Summarizer) *Compactor

New creates a compactor, using BasicEngine when summarizer is nil.

func (*Compactor) Compact

func (c *Compactor) Compact(ctx context.Context, events []session.SessionEvent) (Result, error)

Compact summarizes the oldest events while preserving KeepTail recent messages. It appends an assistant summary with SurfaceOp replacing that range and returns the resulting event list.

func (*Compactor) ShouldCompact

func (c *Compactor) ShouldCompact(events []session.SessionEvent) bool

ShouldCompact checks the configured threshold.

type Config

type Config struct {
	MaxTokens       int // Compact when estimated event tokens exceed this threshold.
	KeepTail        int // Number of recent messages preserved without replacement.
	SummaryMaxRunes int // Maximum summary length in runes.
}

Config configures compaction.

func (Config) WithDefaults

func (c Config) WithDefaults() Config

WithDefaults returns a copy with defaults filled in.

type Result

type Result struct {
	Start       uint64               // Inclusive start sequence of the replaced range.
	End         uint64               // Inclusive end sequence of the replaced range.
	Summary     string               // Summary text.
	Replacement session.SessionEvent // Generated replacement summary event, including SurfaceOp.
	// Effective contains the original events plus the appended Replacement.
	Effective []session.SessionEvent
}

Result contains the output of one compaction.

type Summarizer

type Summarizer interface {
	// Summarize returns the summary text.
	Summarize(ctx context.Context, events []session.SessionEvent, maxRunes int) (string, error)
}

Summarizer summarizes old events selected for replacement.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL