contextmgr

package
v0.0.1-alpha.2 Latest Latest
Warning

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

Go to latest
Published: Jul 25, 2026 License: Apache-2.0 Imports: 6 Imported by: 0

Documentation

Overview

Package contextmgr implements the Tokenizer, Budgeter, and Checkpointer ports (ADR-0008): estimate token cost, decide what enters the context window in priority order, and checkpoint/reconstruct when the window fills up.

Token counts are deliberately approximate. ADR-0008 treats the budget as a soft ceiling with a safety margin, so a calibrated per-family heuristic is the default. An exact counter (tiktoken BPE, or a provider count endpoint) can be dropped in behind the Tokenizer port without touching callers — the heuristic ships first because a BPE table fetched over the network at runtime would break the local-first guarantee.

Index

Constants

View Source
const (
	AnthropicCharsPerToken = 3.6
	OpenAICharsPerToken    = 4.0
)

Characters-per-token ratios, calibrated against representative English prose and source code for each family. Anthropic's tokenizer runs slightly denser than the OpenAI cl100k/o200k families on the same text.

View Source
const DefaultHighWater = 0.8

DefaultHighWater is the fraction of the context window at which a checkpoint is taken when Checkpointer.HighWater is unset. Leaves headroom for the turn that writes the checkpoint itself.

Variables

This section is empty.

Functions

func CountMessages

func CountMessages(tk Tokenizer, msgs []ports.Message) int

CountMessages estimates the total token cost of a neutral message history, counting every block kind that carries text or JSON plus per-block framing overhead.

Types

type Budgeter

type Budgeter struct {
	Tokenizer Tokenizer
	// Budget is the soft token ceiling for the assembled context.
	Budget int
}

Budgeter decides what enters the context window for a turn (ADR-0008). A zero Budget means no limit is configured and everything passes through.

func (Budgeter) Fit

func (b Budgeter) Fit(in Input) Output

Fit assembles in into a budgeted Output, admitting sections in ADR-0008 priority order: system → active task + progress → reconstructed checkpoint → retrieved memory → retained recent messages. The system prompt is always kept, even if it alone exceeds the budget: a context without it is useless, and ADR-0008 treats the budget as a soft ceiling.

type Checkpoint

type Checkpoint struct {
	// Summary is the condensed narrative of what happened before the cut.
	Summary string
	// Tasks is the task tree, which must survive the boundary intact (T-063).
	Tasks TaskTree
	// Recent holds the messages retained verbatim across the cut.
	Recent []ports.Message
}

Checkpoint is a structured snapshot of a session's working state.

type Checkpointer

type Checkpointer struct {
	// Root is the directory holding checkpoint.md.
	Root string
	// Window is the model's context window in tokens. Zero means unknown, in
	// which case checkpointing never triggers automatically.
	Window int
	// HighWater is the fraction of Window that triggers a checkpoint. Zero uses
	// DefaultHighWater.
	HighWater float64
}

Checkpointer writes and reads checkpoint.md and decides when the live context has grown enough to warrant a cut (ADR-0008).

func (Checkpointer) Read

func (c Checkpointer) Read() (Checkpoint, error)

Read loads the checkpoint. A missing file yields a zero Checkpoint and no error — the first session has nothing to reconstruct.

func (Checkpointer) Reconstruct

func (c Checkpointer) Reconstruct(system string, memory []string, recent []ports.Message) (Input, error)

Reconstruct reads the checkpoint and assembles a Budgeter Input in ADR-0008 injection order: the caller's system prompt, the checkpoint's active task, the checkpoint summary, retrieved memory, and retained recent messages. recent overrides the checkpoint's digest when non-nil (live messages are better than a digest of them).

func (Checkpointer) ShouldCheckpoint

func (c Checkpointer) ShouldCheckpoint(used int) bool

ShouldCheckpoint reports whether used tokens have reached the high-water mark.

func (Checkpointer) Write

func (c Checkpointer) Write(cp Checkpoint) error

Write persists cp to <Root>/checkpoint.md, replacing any previous checkpoint.

type Heuristic

type Heuristic struct {
	CharsPerToken float64
}

Heuristic is a characters-per-token estimator. A zero CharsPerToken falls back to the OpenAI ratio.

func (Heuristic) Count

func (h Heuristic) Count(text string) int

Count estimates the token count of text, rounding up so a non-empty string is never free.

type Input

type Input struct {
	// System is the system prompt. Never dropped — without it the agent loses
	// its identity and rules.
	System string
	// Task is the active task description (highest-priority working state).
	Task string
	// Progress is the active task's progress notes.
	Progress string
	// Checkpoint is the reconstructed checkpoint summary.
	Checkpoint string
	// Memory holds hybrid-retrieved memory chunks, most relevant first
	// (ADR-0003).
	Memory []string
	// Recent holds retained recent messages in chronological order.
	Recent []ports.Message
}

Input is everything that could enter the context window for one turn, before budgeting. Sections are listed in ADR-0008 priority order.

type Output

type Output struct {
	System     string
	Task       string
	Progress   string
	Checkpoint string
	Memory     []string
	Recent     []ports.Message

	// Used is the estimated token count of the retained content.
	Used int
	// Dropped counts the sections and items that did not fit.
	Dropped int
}

Output is the budgeted context: the same sections, truncated to fit.

type Status

type Status int

Status is a task node's state.

const (
	StatusOpen Status = iota
	StatusInProgress
	StatusDone
)

type TaskNode

type TaskNode struct {
	ID     string
	Title  string
	Status Status
}

TaskNode is one task in the tree. Nesting is encoded in the dotted ID ("T1" is a root, "T1.1" is its child) so the tree is flat in memory but renders and reparses as a hierarchy (T-063).

type TaskTree

type TaskTree struct {
	Nodes []TaskNode
}

TaskTree is the ordered task list that survives checkpoint boundaries.

func ParseTaskTree

func ParseTaskTree(s string) (TaskTree, error)

ParseTaskTree restores a tree from Render's output. Lines that do not match the task shape are ignored, so the tree can be embedded in a larger document.

func (TaskTree) Active

func (t TaskTree) Active() (TaskNode, bool)

Active returns the first in-progress task — the one the Budgeter treats as highest-priority working state (ADR-0008).

func (*TaskTree) Add

func (t *TaskTree) Add(id, title string, status Status)

Add appends a task, or updates it in place when the ID already exists.

func (TaskTree) Render

func (t TaskTree) Render() string

Render writes the tree as indented markdown checkboxes — human-readable in checkpoint.md and machine-parseable by ParseTaskTree.

func (*TaskTree) SetStatus

func (t *TaskTree) SetStatus(id string, status Status) bool

SetStatus updates one task's status, reporting whether the ID was found.

type Tiktoken

type Tiktoken struct {
	// contains filtered or unexported fields
}

Tiktoken is the exact token counter backed by github.com/pkoukk/tiktoken-go (Change 0005 / T-452). It satisfies the Tokenizer port for OpenAI-shaped model prefixes. Anthropic stays on the heuristic — Anthropic's BPE isn't publicly published.

func NewTiktoken

func NewTiktoken(model string) (*Tiktoken, error)

NewTiktoken builds a Tiktoken for the given "<provider>/<model>" string. It picks cl100k_base for gpt-4/gpt-3.5-turbo-style models and o200k_base for gpt-4o/gpt-4.1/gpt-4.5 family, falling back to cl100k_base when the model is unrecognized. Returns an error when the underlying tiktoken-go call fails (e.g. network blip on first download) — callers should fall back to Heuristic rather than failing the whole turn.

func (*Tiktoken) Count

func (t *Tiktoken) Count(text string) int

Count runs the underlying BPE on text and returns the token count.

type Tokenizer

type Tokenizer interface {
	Count(text string) int
}

Tokenizer estimates the token cost of text. Implementations must be safe for concurrent use.

func ForModel

func ForModel(model string) Tokenizer

ForModel returns the Tokenizer calibrated for a "<provider>/<model>" string, selecting by prefix (the same convention as the provider adapters, ADR-0005). Unknown prefixes get the OpenAI-compatible default.

Jump to

Keyboard shortcuts

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