Documentation
¶
Overview ¶
Package context provides context management for the agent loop.
The context manager wraps the existing context.Assembler and provides additional functionality for context updates, eviction, and summarization during agent execution.
Thread Safety:
All types in this package are designed for concurrent use.
Index ¶
- Constants
- type EvictionMetadata
- type EvictionPolicy
- type HybridPolicy
- type LRUPolicy
- type Manager
- func (m *Manager) AddMessage(ctx *agent.AssembledContext, role, content string)
- func (m *Manager) Assemble(ctx context.Context, query string, budget int) (*agent.AssembledContext, error)
- func (m *Manager) Evict(ctx context.Context, current *agent.AssembledContext, tokensToFree int) (*agent.AssembledContext, error)
- func (m *Manager) FormatForLLM(ctx *agent.AssembledContext) string
- func (m *Manager) GetTokenCount(ctx *agent.AssembledContext) int
- func (m *Manager) InjectToolsIntoPrompt(ctx *agent.AssembledContext, toolDefs []tools.ToolDefinition)
- func (m *Manager) Reset()
- func (m *Manager) Update(ctx context.Context, current *agent.AssembledContext, result *tools.Result) (*agent.AssembledContext, error)
- type ManagerConfig
- type RelevancePolicy
Constants ¶
const ( // DefaultInitialBudget is the default token budget for initial context. DefaultInitialBudget = 8000 // DefaultMaxContextSize is the maximum context size before eviction. DefaultMaxContextSize = 100000 // DefaultEvictionTarget is the target size after eviction. DefaultEvictionTarget = 80000 // CharsPerToken approximates characters per token. CharsPerToken = 4.0 // DefaultMaxToolResultLength is the maximum length for tool result output. // Results longer than this are summarized/truncated. // Fixed in cb_30a after trace_logs_18 showed 16000+ char results causing context overflow. DefaultMaxToolResultLength = 4000 // DefaultMaxToolResults is the maximum number of tool results to keep in context. // Older results are summarized when this limit is exceeded. // Fixed in cb_30a after trace_logs_18 showed 23 messages overwhelming the model. DefaultMaxToolResults = 10 )
Default configuration.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type EvictionMetadata ¶
type EvictionMetadata struct {
// AddedAt maps entry ID to the step when it was added.
AddedAt map[string]int
// LastAccessed maps entry ID to the last step it was accessed.
LastAccessed map[string]int
// CurrentStep is the current agent step.
CurrentStep int
// ProtectedIDs are entries that should not be evicted.
ProtectedIDs map[string]bool
}
EvictionMetadata provides additional information for eviction decisions.
func NewEvictionMetadata ¶
func NewEvictionMetadata() *EvictionMetadata
NewEvictionMetadata creates a new metadata instance.
type EvictionPolicy ¶
type EvictionPolicy interface {
// Name returns the policy name.
Name() string
// SelectForEviction selects entries to evict to free the target tokens.
//
// Inputs:
// ctx - Current context
// tokensToFree - Target tokens to free
// metadata - Additional metadata about entries
//
// Outputs:
// []string - IDs of entries to evict
SelectForEviction(ctx *agent.AssembledContext, tokensToFree int, metadata *EvictionMetadata) []string
}
EvictionPolicy defines the interface for context eviction strategies.
func GetEvictionPolicy ¶
func GetEvictionPolicy(name string) (EvictionPolicy, error)
GetEvictionPolicy returns an eviction policy by name.
Returns an error if the policy name is not recognized. Valid names: "lru", "relevance", "hybrid"
func MustGetEvictionPolicy ¶
func MustGetEvictionPolicy(name string) EvictionPolicy
MustGetEvictionPolicy returns an eviction policy by name, defaulting to hybrid if the name is not recognized.
Use GetEvictionPolicy if you want to handle unknown policy names explicitly.
type HybridPolicy ¶
type HybridPolicy struct {
// RelevanceWeight is the weight for relevance (0.0-1.0).
// The remaining weight goes to recency.
RelevanceWeight float64
// MaxAgeSteps is the maximum age (in steps) used for normalization.
// Ages beyond this are capped at 1.0. Default is 100.
MaxAgeSteps int
}
HybridPolicy combines LRU and relevance.
func NewHybridPolicy ¶
func NewHybridPolicy() *HybridPolicy
NewHybridPolicy creates a hybrid policy with default weights.
func (*HybridPolicy) SelectForEviction ¶
func (p *HybridPolicy) SelectForEviction(ctx *agent.AssembledContext, tokensToFree int, metadata *EvictionMetadata) []string
SelectForEviction uses a combined score of relevance and recency.
type LRUPolicy ¶
type LRUPolicy struct{}
LRUPolicy implements least-recently-used eviction.
func (*LRUPolicy) SelectForEviction ¶
func (p *LRUPolicy) SelectForEviction(ctx *agent.AssembledContext, tokensToFree int, metadata *EvictionMetadata) []string
SelectForEviction selects the oldest entries.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager handles context assembly and management for the agent.
It wraps the existing cbcontext.Assembler and provides additional functionality for maintaining context during multi-step agent execution.
Thread Safety:
Manager is safe for concurrent use.
func NewManager ¶
func NewManager(g *graph.Graph, idx *index.SymbolIndex, config *ManagerConfig) (*Manager, error)
NewManager creates a new context manager.
Description:
Creates a manager that wraps the existing Assembler and provides additional context management capabilities.
Inputs:
g - The code graph. Must be frozen. Must not be nil. idx - The symbol index. Must not be nil. config - Manager configuration (nil uses defaults).
Outputs:
*Manager - The configured manager, or nil if validation fails. error - Non-nil if g or idx is nil.
Example:
manager, err := NewManager(graph, index, nil)
if err != nil {
return fmt.Errorf("create context manager: %w", err)
}
func (*Manager) AddMessage ¶
func (m *Manager) AddMessage(ctx *agent.AssembledContext, role, content string)
AddMessage adds a message to the conversation history.
Thread Safety: This method is safe for concurrent use.
func (*Manager) Assemble ¶
func (m *Manager) Assemble(ctx context.Context, query string, budget int) (*agent.AssembledContext, error)
Assemble builds initial context for a query.
Description:
Uses the underlying Assembler to build initial context, then wraps it in an AssembledContext suitable for the agent loop.
Inputs:
ctx - Context for cancellation. query - The user's query. budget - Maximum token budget.
Outputs:
*agent.AssembledContext - The assembled context. error - Non-nil if assembly fails.
Thread Safety: This method is safe for concurrent use.
func (*Manager) Evict ¶
func (m *Manager) Evict(ctx context.Context, current *agent.AssembledContext, tokensToFree int) (*agent.AssembledContext, error)
Evict removes entries to free tokens from context.
Description:
Removes the least relevant/oldest entries to bring context under the target size.
Inputs:
ctx - Context for cancellation. current - Current assembled context. tokensToFree - Number of tokens to free.
Outputs:
*agent.AssembledContext - Context with entries removed. error - Non-nil if eviction fails.
Thread Safety: This method is safe for concurrent use.
func (*Manager) FormatForLLM ¶
func (m *Manager) FormatForLLM(ctx *agent.AssembledContext) string
FormatForLLM formats the context for LLM consumption.
Thread Safety: This method is safe for concurrent use.
func (*Manager) GetTokenCount ¶
func (m *Manager) GetTokenCount(ctx *agent.AssembledContext) int
GetTokenCount returns the current token count.
Thread Safety: This method is safe for concurrent use.
func (*Manager) InjectToolsIntoPrompt ¶
func (m *Manager) InjectToolsIntoPrompt(ctx *agent.AssembledContext, toolDefs []tools.ToolDefinition)
InjectToolsIntoPrompt adds available tools to an assembled context's system prompt.
Description:
Public method to inject tool definitions into an existing assembled context. This is called by the execute phase when it has access to the tool registry.
Inputs:
ctx - The assembled context to modify. toolDefs - Available tool definitions from ToolRegistry.
Thread Safety: This method is safe for concurrent use.
func (*Manager) Reset ¶
func (m *Manager) Reset()
Reset clears the manager state for a new session.
Thread Safety: This method is safe for concurrent use.
func (*Manager) Update ¶
func (m *Manager) Update(ctx context.Context, current *agent.AssembledContext, result *tools.Result) (*agent.AssembledContext, error)
Update modifies context based on a tool result.
Description:
Integrates tool results into the current context, potentially adding new code entries or updating relevance scores. Tool results are truncated if they exceed MaxToolResultLength. Older results are summarized if MaxToolResults is exceeded.
Inputs:
ctx - Context for cancellation. current - Current assembled context. result - Tool result to integrate.
Outputs:
*agent.AssembledContext - Updated context. error - Non-nil if update fails.
Thread Safety: This method is safe for concurrent use.
type ManagerConfig ¶
type ManagerConfig struct {
// InitialBudget is the token budget for initial assembly.
InitialBudget int
// MaxContextSize triggers eviction when exceeded.
MaxContextSize int
// EvictionTarget is the target size after eviction.
EvictionTarget int
// EvictionPolicy determines how to evict entries.
// Options: "lru", "relevance", "hybrid"
EvictionPolicy string
// SystemPrompt is the base system prompt.
SystemPrompt string
// MaxToolResultLength is the maximum length for individual tool result output.
// Results longer than this are truncated with an ellipsis indicator.
// Fixed in cb_30a after trace_logs_18 showed 16000+ char results.
MaxToolResultLength int
// MaxToolResults is the maximum number of tool results to keep in context.
// Older results are summarized/pruned when this limit is exceeded.
// Fixed in cb_30a after trace_logs_18 showed 23 messages overwhelming the model.
MaxToolResults int
}
ManagerConfig configures the context manager.
func DefaultManagerConfig ¶
func DefaultManagerConfig() ManagerConfig
DefaultManagerConfig returns sensible defaults.
type RelevancePolicy ¶
type RelevancePolicy struct{}
RelevancePolicy implements relevance-based eviction.
func (*RelevancePolicy) SelectForEviction ¶
func (p *RelevancePolicy) SelectForEviction(ctx *agent.AssembledContext, tokensToFree int, metadata *EvictionMetadata) []string
SelectForEviction selects the lowest relevance entries.
Source Files