contextwindow

package
v0.0.0-...-820128f Latest Latest
Warning

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

Go to latest
Published: Aug 19, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package contextwindow builds and budgets model-facing context.

Index

Constants

View Source
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
)
View Source
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
)
View Source
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"
)
View Source
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

func ContributorPreview(content string) string

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

func EstimateTokens(text string) int

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

func OutputReserve(_ *model.Model, contextWindow int, policy *config.ContextConfig) int

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

func SummaryOutputLimit(outputReserve, modelMaxTokens int) (int, error)

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

func (budget Budget) TotalReserve() int

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.

func (Budget) Validate

func (budget Budget) Validate() error

Validate reports whether estimated input fits inside usable context.

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

type RecentTailInput struct {
	ContextWindow int
	CurrentTokens int
}

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.

Jump to

Keyboard shortcuts

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