contextasm

package
v0.32.3 Latest Latest
Warning

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

 Go to latest Published: Jun 18, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrManifestMismatch = errors.New("contextasm: context manifest mismatch")

Functions

func AssembleContext 

func AssembleContext(segs []Segment) (prompt string, stablePrefixHash string)

AssembleContext renders segments into a single prompt whose stable prefix is byte-identical across turns when the stable segments are unchanged.

func HashBytes 

func HashBytes(b []byte) string

func HashString 

func HashString(s string) string

func HashTokenIDs 

func HashTokenIDs(tokens []int) string

HashTokenIDs hashes token IDs under an explicit little-endian encoding so the value is stable across 32-bit/64-bit Go platforms.

func NewManifestMismatchError 

func NewManifestMismatchError(reason string) error

Types

type CacheClass 

type CacheClass int

CacheClass is the coding-aware retention priority of a segment, coarser than SegmentKind. It is the seam a budget-aware admission/eviction policy uses to decide what to keep warm when context exceeds the window: drop higher (more-evictable) classes first, pin lower ones. Wiring a producer of rich segments + the drop policy is gated on the T3 context planner (#7); this type is the foundation it builds on. 

const (
	// ClassTaskPinned is the task-defining core (system/developer instructions,
	// tool schemas, repo conventions): pinned hardest, evicted last.
	ClassTaskPinned CacheClass = iota
	// ClassRepoMap is workspace structure (repo/symbol map, pinned files).
	ClassRepoMap
	// ClassVolatile is churning material (diff, terminal output, the user turn):
	// admitted only when likely reused, evicted first.
	ClassVolatile
)

func (CacheClass) MoreEvictableThan 

func (c CacheClass) MoreEvictableThan(other CacheClass) bool

MoreEvictableThan reports whether c should be dropped before other when trimming context to fit a budget (higher class = lower priority = evicted first).

func (CacheClass) Tag 

func (c CacheClass) Tag() string

Tag returns the stable string form used in manifests.

type ContextManifest 

type ContextManifest struct {
	ProfileID            string            `json:"profile_id,omitempty"`
	Backend              string            `json:"backend"`
	BackendVersion       string            `json:"backend_version,omitempty"`
	ModelDigest          string            `json:"model_digest,omitempty"`
	PromptFormat         string            `json:"prompt_format"`
	PromptTemplateDigest string            `json:"prompt_template_digest"`
	RuntimeDigest        string            `json:"runtime_digest"`
	AddBOS               bool              `json:"add_bos"`
	StableBytes          int               `json:"stable_bytes"`
	TotalBytes           int               `json:"total_bytes"`
	StableByteHash       string            `json:"stable_byte_hash"`
	StableTokenHash      string            `json:"stable_token_hash,omitempty"`
	VolatileTokenHash    string            `json:"volatile_token_hash,omitempty"`
	Segments             []ManifestSegment `json:"segments,omitempty"`
}

ContextManifest is the cache identity. A warm hit is valid only when the runtime identity is compatible and the token prefix still matches.

func AssembleManifest 

func AssembleManifest(segs []Segment, id ManifestIdentity) (prompt string, manifest ContextManifest)

AssembleManifest renders segments canonically and returns a manifest over the rendered logical context. Backends that render through an opaque model-native chat template may still use this as cache identity, but must not claim exact template-token segment ranges until they can prove boundaries under that template.

func (ContextManifest) CompatibleRuntime 

func (m ContextManifest) CompatibleRuntime(next ContextManifest) (bool, string)

CompatibleRuntime reports whether resident KV created for m may be considered for reuse by next. StableByteHash is deliberately excluded: if stable text changes under the same runtime identity, token LCP reuse is still correct.

func (ContextManifest) Digest 

func (m ContextManifest) Digest() string

Digest returns a stable hash of the full manifest.

func (ContextManifest) IsZero 

func (m ContextManifest) IsZero() bool

IsZero reports whether the caller supplied no manifest.

func (ContextManifest) ValidateSplitTokenization 

func (m ContextManifest) ValidateSplitTokenization(stableText, suffixText string, stableTokens, suffixTokens []int, tokenize TokenizeFunc, addBOS bool) error

ValidateSplitTokenization proves that tokenizing stable+suffix as a cold full prompt is exactly equivalent to the warm path's stable tokens plus suffix tokens.

func (ContextManifest) WithStableTokenHash 

func (m ContextManifest) WithStableTokenHash(tokenHash string) ContextManifest

WithStableTokenHash returns a copy of the manifest with the backend-resolved stable token hash attached.

func (ContextManifest) WithStableTokenization 

func (m ContextManifest) WithStableTokenization(stableText string, tokens []int, tokenize TokenizeFunc, addBOS bool) (ContextManifest, error)

WithStableTokenization fills token ranges/hashes for stable segments using the actual backend tokenizer.

func (ContextManifest) WithVolatileTokenization 

func (m ContextManifest) WithVolatileTokenization(stable ContextManifest, prefixTokens int, suffixText string, tokens []int, tokenize TokenizeFunc) (ContextManifest, error)

WithVolatileTokenization merges stable token data from the resident manifest and fills token ranges/hashes for volatile suffix segments.

type ManifestIdentity 

type ManifestIdentity struct {
	ProfileID            string
	Backend              string
	BackendVersion       string
	ModelDigest          string
	PromptFormat         string
	PromptTemplateDigest string
	RuntimeDigest        string
	AddBOS               bool
}

ManifestIdentity is the backend/profile/runtime identity attached to a manifest built from assembled context segments.

type ManifestMismatchError 

type ManifestMismatchError struct {
	Reason string
}

ManifestMismatchError carries the exact reason a suffix/prefix could not be safely paired with resident KV.

func (*ManifestMismatchError) Error 

func (e *ManifestMismatchError) Error() string

func (*ManifestMismatchError) Is 

func (e *ManifestMismatchError) Is(target error) bool

type ManifestSegment 

type ManifestSegment struct {
	Kind   string `json:"kind"`
	Stable bool   `json:"stable"`
	// CacheClass is the coding-aware retention priority (see contextasm.CacheClass):
	// "task_pinned" / "repo_map" / "volatile". Drives budget-aware admission/eviction.
	CacheClass string `json:"cache_class,omitempty"`
	// Invalidation is an optional hint for when this segment's KV must be dropped
	// (e.g. "on_edit", "on_turn"); empty until a producer sets it (gated on #7).
	Invalidation string `json:"invalidation,omitempty"`
	ByteStart    int    `json:"byte_start"`
	ByteEnd      int    `json:"byte_end"`
	ByteHash     string `json:"byte_hash"`
	TokenStart   int    `json:"token_start,omitempty"`
	TokenEnd     int    `json:"token_end,omitempty"`
	TokenHash    string `json:"token_hash,omitempty"`
	// ToolCallsJSON is a raw JSON array of tool_calls for role=="assistant" turns
	// that triggered a tool invocation. Nil/empty means a plain text assistant turn.
	ToolCallsJSON string `json:"tool_calls_json,omitempty"`
	// ToolCallID is the tool call ID for role=="tool" result turns.
	ToolCallID string `json:"tool_call_id,omitempty"`
}

ManifestSegment identifies one rendered prompt segment. Byte hashes are available before tokenization; token hashes are filled only when a backend can tokenize under the actual model/profile.

type Segment 

type Segment struct {
	Kind    SegmentKind
	Content string
}

Segment is one deterministic, hashable piece of workspace context.

type SegmentKind 

type SegmentKind int

SegmentKind classifies a context segment by how stable it is across turns. Lower kinds are more stable and render first so backend prefix caches can reuse their KV; kinds at or after KindDiff are volatile and render last. 

const (
	KindSystem    SegmentKind = iota // system / developer instructions
	KindTools                        // tool schemas
	KindRepoRules                    // AGENTS.md / project conventions
	KindRepoMap                      // repo / symbol map
	KindPinned                       // pinned files
	KindDiff                         // current diff / working changes (volatile)
	KindTerminal                     // terminal / test output (volatile)
	KindUserTurn                     // the user's message (volatile)
)

func (SegmentKind) CacheClass 

func (k SegmentKind) CacheClass() CacheClass

CacheClass maps a segment kind to its retention class.

func (SegmentKind) Tag 

func (k SegmentKind) Tag() string

Tag returns the stable string form used in manifests.

type TokenizeFunc 

type TokenizeFunc func(text string, addSpecial bool) ([]int, error)

TokenizeFunc tokenizes text under the exact backend model/profile. addSpecial must match the backend call site, because BOS policy is part of cache identity.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.