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
- Variables
- func BalancedCuts(events []session.SessionEvent) ([]bool, error)
- func EstimateTokens(events []session.SessionEvent) int
- func IsBalancedAt(events []session.SessionEvent, cut int) (bool, error)
- func NearestBalancedFrom(events []session.SessionEvent, start int) int
- func PruneText(text string, threshold, head, tail int) (string, bool)
- func ShouldCompact(events []session.SessionEvent, maxTokens int) bool
- type BasicEngine
- type Compactor
- type Config
- type Result
- type Summarizer
Constants ¶
const BasicEngineSumm = "【摘要】过去对话摘要如下:"
BasicEngineSumm is the summary title or prefix used by BasicEngine.
const PruneMarker = "\n... [内容已省略] ...\n"
PruneMarker replaces the removed middle portion.
Variables ¶
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 ¶
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 ¶
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 ¶
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.