Documentation
¶
Overview ¶
Package contextplan fits one durable session into a bounded provider request. It reads a contextstate.Session, decides what fits a token window and what does not, and returns a provider.Request plus the list of decisions it made. See docs/plans/contextplan.md.
Index ¶
Constants ¶
const ( // DefaultSmoothingFactor is the EWMA weight Observe applies when // Calibrate receives a non-positive alpha. DefaultSmoothingFactor = 0.3 // MinCorrectionFactor is the floor Observe clamps the correction // factor to. MinCorrectionFactor = 0.5 // MaxCorrectionFactor is the ceiling Observe clamps the correction // factor to. MaxCorrectionFactor = 2.0 )
EWMA smoothing bounds for Calibrated.
const ( // DefaultTriggerPercent compacts at this percent of Window.Budget(). DefaultTriggerPercent = 100 // DefaultTargetPercent compacts down to this percent of Budget(). DefaultTargetPercent = 10 // DefaultRecentTail is the message-count bound of the tail fill. DefaultRecentTail = 8 // MaxRecentTail is the highest tail bound a caller may set. MaxRecentTail = 64 // CompactionAlgorithm names the idempotency-key fingerprint scheme. CompactionAlgorithm = "context-compact-v1" )
Compaction thresholds and bounds.
const StubContentBytes = 256
StubContentBytes bounds the stub Plan builds for a RetentionCompliance payload past its age-driven turn.
Variables ¶
var ( // ErrNoMessages is Compact's error for an empty message list. ErrNoMessages = errors.New("contextplan: no messages to compact") // ErrEstimateFailed is Compact's error when the token estimator // fails. ErrEstimateFailed = errors.New("contextplan: token estimate failed") // ErrRetentionOverflow is Compact's error when the retention set // alone exceeds the window budget. ErrRetentionOverflow = errors.New("contextplan: retention set alone exceeds the window") // ErrNoObjective is Compact's error when no user message exists to // retain as the objective. ErrNoObjective = errors.New("contextplan: no user message to retain as objective") )
Sentinel errors for Compact; test with errors.Is.
var ( // ErrNilStore is NewPlanner's error when store is nil. ErrNilStore = errors.New("contextplan: store must not be nil") // ErrNilCache is NewPlanner's error when cache is nil. ErrNilCache = errors.New("contextplan: cache must not be nil") // ErrNilSession is Plan's error when sess is nil. ErrNilSession = errors.New("contextplan: session must not be nil") )
Sentinel errors for NewPlanner and Plan; test with errors.Is.
var ( // ErrMaxTokensNotPositive is Validate's error when MaxTokens <= 0. ErrMaxTokensNotPositive = errors.New("contextplan: max tokens must be positive") // ErrReserveNegative is Validate's error when Reserve < 0. ErrReserveNegative = errors.New("contextplan: reserve must not be negative") // ErrReserveTooLarge is Validate's error when Reserve >= MaxTokens. ErrReserveTooLarge = errors.New("contextplan: reserve must be less than max tokens") )
Sentinel errors for Window.Validate; test with errors.Is.
Functions ¶
func IsReasoningEvent ¶
func IsReasoningEvent(e contextstate.SourceEvent) bool
IsReasoningEvent reports whether e.Kind == provider.ReasoningEventKind.
func StubContent ¶
StubContent truncates content to StubContentBytes, appending truncationMarker inside that cap when truncation occurs. It returns content unchanged when content already fits. StubContentBytes is a cap, not a promised length: the cut prefix passes through bytes.ToValidUTF8 with an empty replacement, so every invalid byte drops and the result may be shorter.
Types ¶
type Calibrated ¶
type Calibrated struct {
// contains filtered or unexported fields
}
Calibrated wraps a provider.TokenEstimator with an exponentially weighted moving average, corrected after each completed turn through Observe. A *Calibrated implements provider.TokenEstimator. Safe for concurrent use: one mutex guards factor, the only mutable field.
func Calibrate ¶
func Calibrate(est provider.TokenEstimator, alpha float64) *Calibrated
Calibrate wraps est with an EWMA correction factor. alpha is the EWMA smoothing weight in (0, 1]; a value outside that range, including zero or negative, falls back to DefaultSmoothingFactor. A nil est is a caller error caught at the first EstimateTokens call, not at construction, matching the wrapped interface's own contract.
func (*Calibrated) EstimateTokens ¶
func (c *Calibrated) EstimateTokens(req provider.Request) (int, error)
EstimateTokens calls the wrapped estimator, then scales the result by the current EWMA correction factor, itself always within [MinCorrectionFactor, MaxCorrectionFactor].
func (*Calibrated) Observe ¶
func (c *Calibrated) Observe(estimated, actual int)
Observe records one completed turn: estimated is the value EstimateTokens returned to the caller for that turn - the already-corrected figure, not a raw pre-scale count - and actual is the real provider.Usage.TotalTokens for the same turn. Observe corrects factor multiplicatively against estimated, so the fixed point is unchanged from before this fix: a corrected estimate that tracks actual. The result is clamped to [MinCorrectionFactor, MaxCorrectionFactor]. A non-positive estimated or a non-positive actual is a no-op.
type CompactResult ¶
type CompactResult struct {
Kept []provider.Message
Dropped []provider.Message
BeforeTokens int
AfterTokens int
TriggerTokens int
TargetTokens int
Compacted bool
Key string
}
CompactResult is Compact's output.
func Compact ¶
func Compact(msgs []provider.Message, w Window, e provider.TokenEstimator) (CompactResult, error)
Compact applies the trigger check and the retention policy. An invalid window fails Window.Validate before any estimate. A request at or above the trigger compacts; below it passes through with Compacted false. The retention set is mandatory; the tail fill is optional and stops at the first unit that breaks contiguity, the message-count bound, or the target. Kept preserves the original relative order. The Key is deterministic per input.
type Compaction ¶
type Compaction struct {
TriggerPercent int
TargetPercent int
TargetTokens int
RecentTail int
PreserveNames []string
}
Compaction configures compaction thresholds and retention. The zero value means the defaults, never "disabled": TriggerPercent zero means DefaultTriggerPercent, TargetPercent zero means DefaultTargetPercent, RecentTail zero means DefaultRecentTail.
func (Compaction) Validate ¶
func (c Compaction) Validate() error
Validate rejects percents outside [0, 100], a negative TargetTokens or RecentTail, a RecentTail over MaxRecentTail, an empty but present PreserveNames entry, and duplicate PreserveNames entries. When TargetTokens is zero, a TargetPercent at or above the resolved TriggerPercent is rejected; when TargetTokens is positive, that comparison is skipped and Window.Validate instead rejects a TargetTokens at or above Budget().
type Elision ¶
type Elision struct {
Ref contextstate.ContentRef
Reason ElisionReason
Kept int
SpoolRef string
}
Elision is one drop or trim decision Plan made for one payload. Ref is always the resolved PayloadRecord's ContentRef. Kept is the byte length of StubContent's return for a stubbed payload; zero means Plan inserted no message at all for that payload. SpoolRef is the spool.Spool.Spool reference for a successful durable write, set only for ElisionReasonWindowOverflow and ElisionReasonRetentionExpired when Planner carries a non-nil spooler and the write succeeded. Empty in every other case, including a failed write.
type ElisionReason ¶
type ElisionReason string
ElisionReason is the closed set of reasons Plan drops or trims a payload.
const ( // ElisionReasonWindowOverflow marks a payload dropped because the // window filled before this payload's turn. ElisionReasonWindowOverflow ElisionReason = "window_overflow" // ElisionReasonRetentionExpired marks a payload whose full content // dropped for age, but whose RetentionClass earned it a stub // instead of a full removal. ElisionReasonRetentionExpired ElisionReason = "retention_expired" // ElisionReasonReasoningRedacted marks a payload excluded because // IsReasoningEvent marked its source event; the content never // entered Request.Messages at all. ElisionReasonReasoningRedacted ElisionReason = "reasoning_redacted" // ElisionReasonRevoked marks a payload contextstate.MemStore.Get // denied as revoked. Security-relevant, unlike the two budget-driven // reasons above: a caller that ignores this reason gets a Request // silently missing content its own store denied. ElisionReasonRevoked ElisionReason = "revoked" )
The three reasons Plan records against an Elision.
type PlanResult ¶
PlanResult is Plan's output: the built request, every elision decision Plan made, and the estimator's total over Request.Messages. EstimatedTokens stays at or under Window.Budget() for a deterministic estimator whose empty-list total fits. A larger fixed overhead exceeds it; an estimator that errors on the final call reports zero.
type Planner ¶
type Planner struct {
// contains filtered or unexported fields
}
Planner fits one session's source events into a bounded provider request. Built only through NewPlanner. Safe for concurrent use: its three dependencies guard their own state, and Plan holds no other mutable state of its own between calls.
func NewPlanner ¶
func NewPlanner(store *contextstate.MemStore, cache *memory.Store, spooler *spool.Spool) (*Planner, error)
NewPlanner builds a Planner over store, the durable payload source, cache, a same-process decode cache, and spooler, an optional durable overflow target. A nil store wraps ErrNilStore; a nil cache wraps ErrNilCache. A nil spooler is valid: Plan never calls Spool.Spool, and behaves exactly as it does with a wired spooler that never gets used, byte for byte.
func (*Planner) Plan ¶
func (p *Planner) Plan(ctx context.Context, sess *contextstate.Session, w Window, e provider.TokenEstimator) (PlanResult, error)
Plan walks sess.Source newest to oldest. For every event it resolves the full contextstate.PayloadRecord through one store.Get call before it decides anything, including a reasoning event's and a payload it ends up fully dropping. A revoked payload never enters Request.Messages and always produces an ElisionReasonRevoked entry, checked before the reasoning check. A reasoning event never enters Request.Messages and always produces an ElisionReasonReasoningRedacted entry. For every other event, Plan adds the decoded provider.Message while the running estimate stays at or under w.Budget(); once the next-oldest message would exceed the budget, a RetentionCompliance payload gets a stub instead, unless the stub itself would exceed the budget, in which case it drops too. A wired Spool receives the full payload behind every ElisionReasonWindowOverflow and ElisionReasonRetentionExpired entry, keyed to record.Ref.SubjectID, best-effort, never failing Plan. EstimatedTokens stays at or under w.Budget() for a deterministic estimator whose empty-list total fits. A larger fixed overhead exceeds it; an estimator that errors on the final call reports zero. Plan returns a non-nil error only on a malformed Window, a nil sess, or a payload-resolution failure other than a revocation; it never returns a partial PlanResult.
type Window ¶
type Window struct {
MaxTokens int
Reserve int
Compaction Compaction
}
Window is the token budget for one planned request. MaxTokens is the model's context window; Reserve is the headroom Plan never spends, held back for the model's own reply. Compaction carries the compaction thresholds and retention rules; its zero value means the defaults, never "disabled".
func (Window) Budget ¶
Budget returns MaxTokens - Reserve, the tokens Plan may spend on Request.Messages.
func (Window) CompactTarget ¶
CompactTarget returns the target in tokens: TargetTokens when positive, else Budget times TargetPercent, floored.
func (Window) CompactTrigger ¶
CompactTrigger returns the trigger in tokens: Budget times TriggerPercent, floored.
Source Files