Documentation
¶
Overview ¶
Package contextguard implements an ADK plugin that prevents conversations from exceeding the LLM's context window. Before every model call it delegates to a configurable Strategy that decides whether and how to compact the conversation history.
Two strategies are provided out of the box:
ThresholdStrategy: estimates token count and summarizes when the remaining capacity drops below a safety buffer (two-tier: fixed 20k for large windows, 20% for small ones). This is a reactive guard.
SlidingWindowStrategy: compacts when the number of Content entries exceeds a configured maximum, regardless of token count. This is a preventive, periodic compaction based on turn count.
Both strategies use the agent's own LLM for summarization and share the same structured system prompt, state keys, and helper functions.
Usage:
guard := contextguard.New(registry)
guard.Add("assistant", llmModel)
guard.Add("researcher", llmResearcher, contextguard.WithSlidingWindow(30))
runnr, _ := runner.New(runner.Config{
Agent: myAgent,
PluginConfig: guard.PluginConfig(),
})
Index ¶
Constants ¶
const ( // StrategyThreshold selects the token-threshold strategy: summarization // fires when estimated token usage approaches the model's context window. StrategyThreshold = "threshold" // StrategySlidingWindow selects the sliding-window strategy: summarization // fires when the number of Content entries exceeds a configured limit. StrategySlidingWindow = "sliding_window" )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AgentOption ¶
type AgentOption func(*agentConfig)
AgentOption configures per-agent behavior when calling Add.
func WithMaxCompactionAttempts ¶ added in v0.12.0
func WithMaxCompactionAttempts(n int) AgentOption
WithMaxCompactionAttempts sets the maximum number of summarization retries when a single compaction pass still exceeds the threshold. Applies to both strategies. Defaults to 3 when not set or when n <= 0.
func WithMaxTokens ¶
func WithMaxTokens(maxTokens int) AgentOption
WithMaxTokens sets a manual context window size override (in tokens). Only used by the threshold strategy. When set, the ModelRegistry is bypassed for this agent.
func WithSlidingWindow ¶
func WithSlidingWindow(maxTurns int) AgentOption
WithSlidingWindow selects the sliding-window strategy with the given maximum number of Content entries before compaction.
type ContextGuard ¶
type ContextGuard struct {
// contains filtered or unexported fields
}
ContextGuard accumulates per-agent strategies and produces a single runner.PluginConfig. Use New to create one, Add to register agents, and PluginConfig to get the final configuration.
func New ¶
func New(registry ModelRegistry) *ContextGuard
New creates a ContextGuard backed by the given ModelRegistry.
func (*ContextGuard) Add ¶
func (g *ContextGuard) Add(agentID string, llm model.LLM, opts ...AgentOption)
Add registers an agent with its LLM for summarization. Without options, the threshold strategy is used with limits from the ModelRegistry.
func (*ContextGuard) PluginConfig ¶
func (g *ContextGuard) PluginConfig() runner.PluginConfig
PluginConfig returns a runner.PluginConfig ready to pass to the ADK launcher or runner.
type CrushRegistry ¶
type CrushRegistry struct {
// contains filtered or unexported fields
}
CrushRegistry implements ModelRegistry using catwalk's embedded model database. All model metadata (context windows, max tokens, costs) is compiled into the binary — no network calls, no background goroutines.
Usage:
registry := contextguard.NewCrushRegistry() guard := contextguard.New(registry)
func NewCrushRegistry ¶
func NewCrushRegistry() *CrushRegistry
NewCrushRegistry creates a registry pre-loaded with every model from catwalk's embedded provider database.
func (*CrushRegistry) ContextWindow ¶
func (r *CrushRegistry) ContextWindow(modelID string) int
ContextWindow returns the context window size (in tokens) for the given model ID. Returns 128000 if the model is not found.
func (*CrushRegistry) DefaultMaxTokens ¶
func (r *CrushRegistry) DefaultMaxTokens(modelID string) int
DefaultMaxTokens returns the default max output tokens for the given model ID. Returns 4096 if the model is not found.
type ModelRegistry ¶
type ModelRegistry interface {
// ContextWindow returns the maximum context window size (in tokens) for
// the given model ID. If the model is unknown, a reasonable default
// should be returned (e.g. 128000).
ContextWindow(modelID string) int
// DefaultMaxTokens returns the default maximum output tokens for the
// given model ID. If the model is unknown, a reasonable default should
// be returned (e.g. 4096).
DefaultMaxTokens(modelID string) int
}
ModelRegistry provides model metadata needed by the ContextGuard plugin. Implementations can fetch data from a remote source, a local config, or a static map — the plugin only depends on this interface.
type Strategy ¶
type Strategy interface {
Name() string
Compact(ctx agent.CallbackContext, req *model.LLMRequest) error
}
Strategy defines how a compaction algorithm decides whether and how to compact conversation history before an LLM call.
Source Files