Documentation
¶
Overview ¶
Package contextwindow builds and budgets model-facing context.
Index ¶
- Constants
- func AppendContributions(result *BuildResult, contributions []Contribution)
- func Breakdown(systemTokens, skillTokens, historyTokens int, contributions []Contribution) map[string]int
- func ContributorPreview(content string) string
- func EstimateBuildUsage(systemPrompt string, messages []database.MessageEntity, ...) model.TokenUsage
- func EstimateInputTokens(systemPrompt string, messages []database.MessageEntity) int
- func EstimateMessageTokens(messages []database.MessageEntity) int
- func EstimateTokens(text string) int
- func EstimateUsageLedInputTokens(systemPrompt string, messages []database.MessageEntity, ...) int
- func MergeUsage(estimated, reported *model.TokenUsage) model.TokenUsage
- func OutputReserve(_ *model.Model, contextWindow int, policy *config.ContextConfig) int
- func ProviderUsageEntity(usage *model.TokenUsage) *database.EntryTokenUsageEntity
- func RecentTailTarget(input RecentTailInput) int
- func SummaryOutputLimit(outputReserve, modelMaxTokens int) (int, error)
- func TopContributors(systemPrompt string, messages []database.MessageEntity, ...) []model.TokenContributor
- type Base
- type Budget
- type BuildResult
- type Contribution
- type RecentTailInput
- type SummaryBudget
- type SummaryBudgetInput
- type ToolSchemaEstimator
Constants ¶
const ( // DefaultOutputReserve is the fallback output token reserve. DefaultOutputReserve = 16_384 // DefaultSafetyMargin is the fallback safety reserve. DefaultSafetyMargin = 8_192 // DefaultProviderReserve is the fallback provider overhead reserve. DefaultProviderReserve = 2_048 // ReservePercent caps the default output reserve as a percentage of context window. ReservePercent = 20 )
const ( // SummaryReservePercent is the percentage of output reserve available to summaries. SummaryReservePercent = 80 // DefaultUnknownModelSummaryMaxTokens limits summaries for models without a declared output limit. DefaultUnknownModelSummaryMaxTokens = 4_096 // MinimumSummaryOutputTokens is the smallest viable summary output allowance. MinimumSummaryOutputTokens = 64 // DefaultSummaryRequestEnvelopeTokens reserves request wrapper overhead. DefaultSummaryRequestEnvelopeTokens = 32 )
const ( // ContributionSourceExtension is the default source for extension-provided context. ContributionSourceExtension = "extension" // ContributionRoleSystem is the default role for extension-provided context. ContributionRoleSystem = "system" // ContributionMaxTokens limits a single extension contribution. ContributionMaxTokens = 2048 // ContributionAggregateMaxTokens limits all extension contributions in one context build. ContributionAggregateMaxTokens = 8192 // BreakdownSystem is the token breakdown key for the base system prompt. BreakdownSystem = "system" // BreakdownSkills is the token breakdown key for available and active skills. BreakdownSkills = "skills" // BreakdownHistory is the token breakdown key for conversation history. BreakdownHistory = "history" // BreakdownExtensions is the token breakdown key for extension context. BreakdownExtensions = "extensions" )
const (
// MaxContributors is the maximum number of contributors exposed in usage diagnostics.
MaxContributors = 8
)
Variables ¶
This section is empty.
Functions ¶
func AppendContributions ¶
func AppendContributions(result *BuildResult, contributions []Contribution)
AppendContributions appends extension context blocks to result.SystemPrompt.
func Breakdown ¶
func Breakdown(systemTokens, skillTokens, historyTokens int, contributions []Contribution) map[string]int
Breakdown returns the token breakdown for model-facing context.
func ContributorPreview ¶
ContributorPreview returns a compact single-line content preview.
func EstimateBuildUsage ¶
func EstimateBuildUsage( systemPrompt string, messages []database.MessageEntity, contributions []Contribution, selectedModel *model.Model, breakdown map[string]int, usageAnchor *database.ContextUsageAnchorEntity, ) model.TokenUsage
EstimateBuildUsage estimates the current model-facing context usage.
func EstimateInputTokens ¶
func EstimateInputTokens(systemPrompt string, messages []database.MessageEntity) int
EstimateInputTokens estimates the model-facing input tokens for system prompt plus messages.
func EstimateMessageTokens ¶
func EstimateMessageTokens(messages []database.MessageEntity) int
EstimateMessageTokens estimates the model-facing token count for messages.
func EstimateTokens ¶
EstimateTokens returns a rough cross-provider estimate used until provider usage arrives.
func EstimateUsageLedInputTokens ¶
func EstimateUsageLedInputTokens( systemPrompt string, messages []database.MessageEntity, contributions []Contribution, usageAnchor *database.ContextUsageAnchorEntity, ) int
EstimateUsageLedInputTokens combines provider-reported anchor usage with local trailing estimates.
func MergeUsage ¶
func MergeUsage(estimated, reported *model.TokenUsage) model.TokenUsage
MergeUsage overlays provider-reported usage on an estimated usage snapshot.
func OutputReserve ¶
OutputReserve returns the output token reserve for the given model/policy.
func ProviderUsageEntity ¶
func ProviderUsageEntity(usage *model.TokenUsage) *database.EntryTokenUsageEntity
ProviderUsageEntity converts model usage into database usage metadata for persisted provider entries.
func RecentTailTarget ¶
func RecentTailTarget(input RecentTailInput) int
RecentTailTarget returns the number of newest tokens to keep untouched during compaction.
func SummaryOutputLimit ¶
SummaryOutputLimit computes floor(80% of reserve), bounded by model capability.
func TopContributors ¶
func TopContributors( systemPrompt string, messages []database.MessageEntity, contributions []Contribution, ) []model.TokenContributor
TopContributors returns the largest contributors to model-facing context.
Types ¶
type Base ¶
type Base struct {
UsageAnchor *database.ContextUsageAnchorEntity
BaseSystemPrompt string
SkillPrompt string
SystemPrompt string
ActiveSkills []core.ActivatedSkill
SkillDiagnostics []core.SkillActivationDiagnostic
Messages []database.MessageEntity
HistoryTokens int
SystemTokens int
SkillTokens int
}
Base describes context inputs before extension context-build hooks mutate them.
type Budget ¶
type Budget struct {
InputTokens int
ContextWindow int
UsableInput int
OutputReserve int
ToolSchemaReserve int
ProviderReserve int
SafetyMargin int
}
Budget describes usable context after output, provider, safety, and tool reserves.
func BudgetFromUsage ¶
func BudgetFromUsage(usage *model.TokenUsage) Budget
BudgetFromUsage reconstructs budget diagnostics from usage breakdown fields.
func NewBudget ¶
func NewBudget( usage *model.TokenUsage, selectedModel *model.Model, policy *config.ContextConfig, estimateTools ToolSchemaEstimator, ) Budget
NewBudget builds a context budget from current usage and policy.
func (Budget) TotalReserve ¶
TotalReserve returns the tokens reserved from the context window.
func (Budget) UsageWithBudget ¶
func (budget Budget) UsageWithBudget(usage *model.TokenUsage) model.TokenUsage
UsageWithBudget adds budget diagnostics to usage.
type BuildResult ¶
type BuildResult struct {
Breakdown map[string]int
UsageAnchor *database.ContextUsageAnchorEntity
SystemPrompt string
Contributions []Contribution
Messages []database.MessageEntity
Usage model.TokenUsage
ExtensionContributionTokenLimit int
}
BuildResult is the model-facing context assembled for a provider request.
type Contribution ¶
type Contribution struct {
Metadata map[string]any
Source string
Name string
Role string
Content string
Tokens int
}
Contribution describes extension-provided context appended to the system prompt.
func ContributionsFromPayload ¶
func ContributionsFromPayload(payload map[string]any) ([]Contribution, error)
ContributionsFromPayload parses extension context-build contributions and enforces the core per-contribution and aggregate token limits.
func ContributionsFromPayloadWithLimit ¶
func ContributionsFromPayloadWithLimit(payload map[string]any, aggregateMaxTokens int) ([]Contribution, error)
ContributionsFromPayloadWithLimit parses contributions using an explicit aggregate limit.
type RecentTailInput ¶
RecentTailInput describes the policy inputs for selecting the verbatim tail kept during compaction.
type SummaryBudget ¶
type SummaryBudget struct {
ContextWindow int
SystemPromptTokens int
PreviousSummaryTokens int
SplitTurnTokens int
FixedInputTokens int
ReducibleHistoryTokens int
MaxInputTokens int
TotalInputTokens int
ProviderReserve int
SafetyMargin int
EnvelopeTokens int
MaxOutputTokens int
}
SummaryBudget is a tool-free, finite compaction request budget.
func NewSummaryBudget ¶
func NewSummaryBudget(input SummaryBudgetInput) SummaryBudget
NewSummaryBudget computes the complete request budget.
func (*SummaryBudget) AvailableHistoryTokens ¶
func (budget *SummaryBudget) AvailableHistoryTokens() int
AvailableHistoryTokens returns input room after non-reducible overhead.
func (*SummaryBudget) Validate ¶
func (budget *SummaryBudget) Validate() error
Validate reports fixed or reducible overflow without sending a request.
type SummaryBudgetInput ¶
type SummaryBudgetInput struct {
ContextWindow int
SystemPromptTokens int
PreviousSummaryTokens int
SplitTurnTokens int
HistoryTokens int
ProviderReserve int
SafetyMargin int
EnvelopeTokens int
MaxOutputTokens int
}
SummaryBudgetInput contains every summary-request budget component. Previous and split tokens are diagnostic portions of SystemPromptTokens, not additions.
type ToolSchemaEstimator ¶
type ToolSchemaEstimator func() int
ToolSchemaEstimator estimates the token cost of available tool definitions.