cache

package
v0.3.9 Latest Latest
Warning

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

 Go to latest Published: Jun 14, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package cache records provider-visible prompt segments and request ledgers.

Stores must be safe for concurrent BuildPlan, toolset, request, and response operations across different prompt scopes. A prompt scope is the explicit boundary for prompt segment reuse; durable threads normally use ThreadID as PromptScopeID, while standalone runs use RunID. Prompt cache ledgers may retain raw prompt text for provider reuse and debugging, so public host views must sanitize observations before exposing them.

Index

Constants

View Source 
const (
	FragmentOpenAIMessage    = "openai.message"
	FragmentOpenAITool       = "openai.tool"
	FragmentAnthropicSystem  = "anthropic.system"
	FragmentAnthropicMessage = "anthropic.message"
	FragmentAnthropicTool    = "anthropic.tool"
	FragmentGenericMessage   = "generic.message"
	FragmentGenericToolset   = "generic.toolset"
)
View Source 
const Version = "cache.v1"

Variables

This section is empty.

Functions

func CanonicalJSON 

func CanonicalJSON(value any) (string, error)

func DefaultNamespace 

func DefaultNamespace(promptScopeID, provider, model string) string

func HashStrings 

func HashStrings(values ...string) string

func Messages 

func Messages(plan RawPlan) []session.Message

func NormalizeToolsetChecked 

func NormalizeToolsetChecked(defs []ToolDefinition, hosted []HostedToolDefinition, options ToolsetOptions) ([]ToolDefinition, []HostedToolDefinition, error)

func StableHash 

func StableHash(value string) string

Types

type BuildInput 

type BuildInput struct {
	PromptScopeID  string
	RunID          string
	ThreadID       string
	TurnID         string
	Provider       string
	Model          string
	AdapterVersion string
	CacheNamespace string
	SystemPrompt   string
	History        []session.Message
	Toolset        ToolsetSnapshot
	HostedTools    []HostedToolDefinition
	Renderer       Renderer
	Now            time.Time
}

type CachePolicy 

type CachePolicy struct {
	Enabled            bool      `json:"enabled"`
	Namespace          string    `json:"namespace,omitempty"`
	Retention          Retention `json:"retention,omitempty"`
	PreferContinuation bool      `json:"prefer_continuation,omitempty"`
}

type Deleter 

type Deleter interface {
	DeletePromptScopes(context.Context, ...string) error
}

type FileStore 

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

func NewFileStore 

func NewFileStore(root string) *FileStore

func (*FileStore) ActiveToolset 

func (s *FileStore) ActiveToolset(ctx context.Context, promptScopeID, provider, model string) (ToolsetSnapshot, bool, error)

func (*FileStore) AppendProviderRequest 

func (s *FileStore) AppendProviderRequest(ctx context.Context, req ProviderRequestRecord) error

func (*FileStore) AppendProviderResponse 

func (s *FileStore) AppendProviderResponse(ctx context.Context, resp ProviderResponseRecord) error

func (*FileStore) AppendSegment 

func (s *FileStore) AppendSegment(ctx context.Context, seg Segment) error

func (*FileStore) AppendToolset 

func (s *FileStore) AppendToolset(ctx context.Context, snap ToolsetSnapshot) error

func (*FileStore) DeletePromptScopes 

func (s *FileStore) DeletePromptScopes(ctx context.Context, promptScopeIDs ...string) error

func (*FileStore) LatestPressureAnchor 

func (s *FileStore) LatestPressureAnchor(ctx context.Context, promptScopeID, providerName, model string) (PressureAnchorState, bool, error)

func (*FileStore) ProviderRequests 

func (s *FileStore) ProviderRequests(ctx context.Context, promptScopeID string) ([]ProviderRequestRecord, error)

func (*FileStore) ProviderResponses 

func (s *FileStore) ProviderResponses(ctx context.Context, promptScopeID string) ([]ProviderResponseRecord, error)

func (*FileStore) Segments 

func (s *FileStore) Segments(ctx context.Context, promptScopeID, provider, model string) ([]Segment, error)

type HostedToolDefinition 

type HostedToolDefinition struct {
	Name        string         `json:"name"`
	Type        string         `json:"type"`
	Description string         `json:"description,omitempty"`
	Parameters  map[string]any `json:"parameters,omitempty"`
	Options     map[string]any `json:"options,omitempty"`
}

func NormalizeHostedTools 

func NormalizeHostedTools(defs []HostedToolDefinition) []HostedToolDefinition

func NormalizeHostedToolsChecked 

func NormalizeHostedToolsChecked(defs []HostedToolDefinition) ([]HostedToolDefinition, error)

type MemoryStore 

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

func NewMemoryStore 

func NewMemoryStore() *MemoryStore

func (*MemoryStore) ActiveToolset 

func (s *MemoryStore) ActiveToolset(_ context.Context, promptScopeID, provider, model string) (ToolsetSnapshot, bool, error)

func (*MemoryStore) AppendProviderRequest 

func (s *MemoryStore) AppendProviderRequest(_ context.Context, req ProviderRequestRecord) error

func (*MemoryStore) AppendProviderResponse 

func (s *MemoryStore) AppendProviderResponse(_ context.Context, resp ProviderResponseRecord) error

func (*MemoryStore) AppendSegment 

func (s *MemoryStore) AppendSegment(_ context.Context, seg Segment) error

func (*MemoryStore) AppendToolset 

func (s *MemoryStore) AppendToolset(_ context.Context, snap ToolsetSnapshot) error

func (*MemoryStore) DeletePromptScopes 

func (s *MemoryStore) DeletePromptScopes(_ context.Context, promptScopeIDs ...string) error

func (*MemoryStore) LatestPressureAnchor 

func (s *MemoryStore) LatestPressureAnchor(_ context.Context, promptScopeID, providerName, model string) (PressureAnchorState, bool, error)

func (*MemoryStore) ProviderRequests 

func (s *MemoryStore) ProviderRequests(_ context.Context, promptScopeID string) ([]ProviderRequestRecord, error)

func (*MemoryStore) ProviderResponses 

func (s *MemoryStore) ProviderResponses(_ context.Context, promptScopeID string) ([]ProviderResponseRecord, error)

func (*MemoryStore) Segments 

func (s *MemoryStore) Segments(_ context.Context, promptScopeID, provider, model string) ([]Segment, error)

type MessageSnapshot 

type MessageSnapshot struct {
	Role       string `json:"role,omitempty"`
	Content    string `json:"content,omitempty"`
	Reasoning  string `json:"reasoning,omitempty"`
	ToolCallID string `json:"tool_call_id,omitempty"`
	ToolName   string `json:"tool_name,omitempty"`
	ToolArgs   string `json:"tool_args,omitempty"`
	Kind       string `json:"kind,omitempty"`
}

type PressureAnchorState 

type PressureAnchorState struct {
	PromptScopeID        string                           `json:"prompt_scope_id,omitempty"`
	ThreadID             string                           `json:"thread_id,omitempty"`
	Provider             string                           `json:"provider,omitempty"`
	Model                string                           `json:"model,omitempty"`
	AdapterVersion       string                           `json:"adapter_version,omitempty"`
	RequestID            string                           `json:"request_id,omitempty"`
	RunID                string                           `json:"run_id,omitempty"`
	LogicalRequestID     string                           `json:"logical_request_id,omitempty"`
	LastMessageEntryID   string                           `json:"last_message_entry_id,omitempty"`
	LastMessageIndex     int                              `json:"last_message_index,omitempty"`
	CompactionGeneration int                              `json:"compaction_generation,omitempty"`
	CompactionWindowID   string                           `json:"compaction_window_id,omitempty"`
	Shape                RequestShapeHashes               `json:"shape,omitempty"`
	WindowInputTokens    int64                            `json:"window_input_tokens,omitempty"`
	PrefixTokens         int64                            `json:"prefix_tokens,omitempty"`
	MessageTokens        int64                            `json:"message_tokens,omitempty"`
	ToolDefinitionTokens int64                            `json:"tool_definition_tokens,omitempty"`
	ContextWindowTokens  int64                            `json:"context_window_tokens,omitempty"`
	EstimateSource       string                           `json:"estimate_source,omitempty"`
	EstimateMethod       contextpolicy.EstimateMethod     `json:"estimate_method,omitempty"`
	Confidence           contextpolicy.EstimateConfidence `json:"confidence,omitempty"`
	PressureSource       contextpolicy.PressureSource     `json:"pressure_source,omitempty"`
	CreatedAt            time.Time                        `json:"created_at,omitempty"`
}

type PromptScopeRef 

type PromptScopeRef struct {
	PromptScopeID string
	RunID         string
	ThreadID      string
	TurnID        string
}

type ProviderRequestRecord 

type ProviderRequestRecord struct {
	ID                   string                        `json:"id"`
	PromptScopeID        string                        `json:"prompt_scope_id"`
	RunID                string                        `json:"run_id"`
	ThreadID             string                        `json:"thread_id,omitempty"`
	TurnID               string                        `json:"turn_id,omitempty"`
	Step                 int                           `json:"step"`
	LogicalRequestID     string                        `json:"logical_request_id,omitempty"`
	Attempt              int                           `json:"attempt,omitempty"`
	OverflowRetried      bool                          `json:"overflow_retried,omitempty"`
	Provider             string                        `json:"provider"`
	Model                string                        `json:"model"`
	CacheNamespace       string                        `json:"cache_namespace,omitempty"`
	CacheRetention       Retention                     `json:"cache_retention,omitempty"`
	SegmentIDs           []string                      `json:"segment_ids"`
	ProviderPayloadHash  string                        `json:"provider_payload_hash"`
	PrefixRawHash        string                        `json:"prefix_raw_hash"`
	PreviousResponseID   string                        `json:"previous_response_id,omitempty"`
	CompactionGeneration int                           `json:"compaction_generation,omitempty"`
	CompactionWindowID   string                        `json:"compaction_window_id,omitempty"`
	CompactionEntryID    string                        `json:"compaction_entry_id,omitempty"`
	RequestEstimate      contextpolicy.RequestEstimate `json:"request_estimate,omitempty"`
	ProjectedPressure    contextpolicy.ContextPressure `json:"projected_context_pressure,omitempty"`
	RequestShape         RequestShapeHashes            `json:"request_shape,omitempty"`
	CreatedAt            time.Time                     `json:"created_at"`
}

func RecordProviderRequest 

func RecordProviderRequest(ctx context.Context, store Store, req ProviderRequestSnapshot) (ProviderRequestRecord, error)

func RecordRequest 

func RecordRequest(ctx context.Context, store Store, ref PromptScopeRef, step int, providerName, model string, policy CachePolicy, plan RawPlan) (ProviderRequestRecord, error)

type ProviderRequestSnapshot 

type ProviderRequestSnapshot struct {
	PromptScopeID    string
	RunID            string
	ThreadID         string
	TurnID           string
	Step             int
	LogicalRequestID string
	Attempt          int
	OverflowRetried  bool
	Provider         string
	Model            string
	Cache            CachePolicy
	RawPlan          RawPlan
}

type ProviderResponseRecord 

type ProviderResponseRecord struct {
	RequestID          string                        `json:"request_id"`
	PromptScopeID      string                        `json:"prompt_scope_id"`
	RunID              string                        `json:"run_id,omitempty"`
	ThreadID           string                        `json:"thread_id,omitempty"`
	TurnID             string                        `json:"turn_id,omitempty"`
	ProviderResponseID string                        `json:"provider_response_id,omitempty"`
	StopReason         string                        `json:"stop_reason,omitempty"`
	InputTokens        int64                         `json:"input_tokens,omitempty"`
	WindowInputTokens  int64                         `json:"window_input_tokens,omitempty"`
	OutputTokens       int64                         `json:"output_tokens,omitempty"`
	ReasoningTokens    int64                         `json:"reasoning_tokens,omitempty"`
	CacheReadTokens    int64                         `json:"cache_read_tokens,omitempty"`
	CacheWriteTokens   int64                         `json:"cache_write_tokens,omitempty"`
	TotalTokens        int64                         `json:"total_tokens,omitempty"`
	UsageSource        string                        `json:"usage_source,omitempty"`
	UsageAvailable     bool                          `json:"usage_available,omitempty"`
	NativePressure     contextpolicy.ContextPressure `json:"native_context_pressure,omitempty"`
	PressureAnchor     PressureAnchorState           `json:"pressure_anchor,omitempty"`
	CreatedAt          time.Time                     `json:"created_at"`
}

type RawPlan 

type RawPlan struct {
	Version              string                        `json:"version"`
	SegmentIDs           []string                      `json:"segment_ids"`
	Segments             []Segment                     `json:"segments"`
	ToolsetID            string                        `json:"toolset_id,omitempty"`
	ToolsetEpoch         int                           `json:"toolset_epoch,omitempty"`
	HostedToolsetHash    string                        `json:"hosted_toolset_hash,omitempty"`
	PrefixHash           string                        `json:"prefix_hash"`
	PayloadHash          string                        `json:"payload_hash"`
	CacheNamespace       string                        `json:"cache_namespace,omitempty"`
	PreviousResponseID   string                        `json:"previous_response_id,omitempty"`
	CompactionGeneration int                           `json:"compaction_generation,omitempty"`
	CompactionWindowID   string                        `json:"compaction_window_id,omitempty"`
	CompactionEntryID    string                        `json:"compaction_entry_id,omitempty"`
	RequestEstimate      contextpolicy.RequestEstimate `json:"request_estimate,omitempty"`
	ProjectedPressure    contextpolicy.ContextPressure `json:"projected_context_pressure,omitempty"`
	RequestShape         RequestShapeHashes            `json:"request_shape,omitempty"`
	ReusedSegments       int                           `json:"reused_segments"`
	NewSegments          int                           `json:"new_segments"`
	SegmentStates        []string                      `json:"segment_states,omitempty"`
}

func BuildPlan 

func BuildPlan(ctx context.Context, store Store, input BuildInput) (RawPlan, []session.Message, error)

type Renderer 

type Renderer interface {
	MessageRaw(SegmentKind, session.Message) (string, string, error)
	ToolRaw(ToolDefinition) (string, string, error)
}

type RequestShapeHashes 

type RequestShapeHashes struct {
	SystemPrefixHash    string `json:"system_prefix_hash,omitempty"`
	MessagePayloadHash  string `json:"message_payload_hash,omitempty"`
	LocalToolsetHash    string `json:"local_toolset_hash,omitempty"`
	HostedToolsetHash   string `json:"hosted_toolset_hash,omitempty"`
	ProviderPayloadHash string `json:"provider_payload_hash,omitempty"`
	CacheShapeHash      string `json:"cache_shape_hash,omitempty"`
}

type Retention 

type Retention string
const (
	RetentionNone     Retention = "none"
	RetentionInMemory Retention = "in_memory"
	RetentionShort    Retention = "5m"
	RetentionLong     Retention = "1h"
	RetentionDay      Retention = "24h"
)

type Segment 

type Segment struct {
	ID                   string          `json:"id"`
	PromptScopeID        string          `json:"prompt_scope_id"`
	CreatedByRunID       string          `json:"created_by_run_id,omitempty"`
	CreatedByTurnID      string          `json:"created_by_turn_id,omitempty"`
	ThreadID             string          `json:"thread_id,omitempty"`
	EntryID              string          `json:"entry_id,omitempty"`
	ParentEntryID        string          `json:"parent_entry_id,omitempty"`
	Provider             string          `json:"provider"`
	Model                string          `json:"model"`
	AdapterVersion       string          `json:"adapter_version"`
	SchemaVersion        string          `json:"schema_version"`
	Kind                 SegmentKind     `json:"kind"`
	Role                 string          `json:"role,omitempty"`
	Epoch                int             `json:"epoch,omitempty"`
	Sequence             int64           `json:"sequence"`
	StructuredRefID      string          `json:"structured_ref_id,omitempty"`
	CompactionGeneration int             `json:"compaction_generation,omitempty"`
	CompactionWindowID   string          `json:"compaction_window_id,omitempty"`
	CompactionEntryID    string          `json:"compaction_entry_id,omitempty"`
	Fingerprint          string          `json:"fingerprint"`
	FragmentType         string          `json:"fragment_type,omitempty"`
	Raw                  string          `json:"raw"`
	SHA256               string          `json:"sha256"`
	ByteLength           int             `json:"byte_length"`
	Message              MessageSnapshot `json:"message,omitempty"`
	CreatedAt            time.Time       `json:"created_at"`
}

type SegmentKind 

type SegmentKind string
const (
	SegmentSystem      SegmentKind = "system"
	SegmentToolset     SegmentKind = "toolset"
	SegmentUserMessage SegmentKind = "user_message"
	SegmentAssistant   SegmentKind = "assistant_message"
	SegmentToolCall    SegmentKind = "tool_call"
	SegmentToolResult  SegmentKind = "tool_result"
	SegmentCompaction  SegmentKind = "compaction"
)

type Store 

type Store interface {
	AppendSegment(context.Context, Segment) error
	Segments(context.Context, string, string, string) ([]Segment, error)
	AppendToolset(context.Context, ToolsetSnapshot) error
	ActiveToolset(context.Context, string, string, string) (ToolsetSnapshot, bool, error)
	AppendProviderRequest(context.Context, ProviderRequestRecord) error
	ProviderRequests(context.Context, string) ([]ProviderRequestRecord, error)
	AppendProviderResponse(context.Context, ProviderResponseRecord) error
	ProviderResponses(context.Context, string) ([]ProviderResponseRecord, error)
	LatestPressureAnchor(context.Context, string, string, string) (PressureAnchorState, bool, error)
}

type ToolDefinition 

type ToolDefinition struct {
	Name         string         `json:"name"`
	Title        string         `json:"title,omitempty"`
	Description  string         `json:"description,omitempty"`
	InputSchema  map[string]any `json:"input_schema,omitempty"`
	OutputSchema map[string]any `json:"output_schema,omitempty"`
	Strict       bool           `json:"strict,omitempty"`
	Annotations  map[string]any `json:"annotations,omitempty"`
}

func NormalizeTools 

func NormalizeTools(defs []ToolDefinition) []ToolDefinition

func NormalizeToolsChecked 

func NormalizeToolsChecked(defs []ToolDefinition, options ToolsetOptions) ([]ToolDefinition, error)

type ToolsetOptions 

type ToolsetOptions struct {
	AllowControlTools bool
}

type ToolsetSnapshot 

type ToolsetSnapshot struct {
	ID              string                 `json:"id"`
	PromptScopeID   string                 `json:"prompt_scope_id"`
	CreatedByRunID  string                 `json:"created_by_run_id,omitempty"`
	CreatedByTurnID string                 `json:"created_by_turn_id,omitempty"`
	ThreadID        string                 `json:"thread_id,omitempty"`
	Provider        string                 `json:"provider"`
	Model           string                 `json:"model"`
	Epoch           int                    `json:"epoch"`
	Tools           []ToolDefinition       `json:"tools"`
	HostedTools     []HostedToolDefinition `json:"hosted_tools,omitempty"`
	RawSegmentID    string                 `json:"raw_segment_id"`
	Fingerprint     string                 `json:"fingerprint"`
	CreatedAt       time.Time              `json:"created_at"`
}

func ActivateToolset 

func ActivateToolset(ctx context.Context, store Store, promptScopeID, runID, threadID, turnID, provider, model string, defs []ToolDefinition, hosted []HostedToolDefinition, now time.Time) (ToolsetSnapshot, error)

func ActivateToolsetWithOptions 

func ActivateToolsetWithOptions(ctx context.Context, store Store, promptScopeID, runID, threadID, turnID, provider, model string, defs []ToolDefinition, hosted []HostedToolDefinition, now time.Time, options ToolsetOptions) (ToolsetSnapshot, error)

func EnsureCurrentToolset 

func EnsureCurrentToolset(ctx context.Context, store Store, promptScopeID, runID, threadID, turnID, provider, model string, defs []ToolDefinition, hosted []HostedToolDefinition, now time.Time) (ToolsetSnapshot, bool, error)

func EnsureCurrentToolsetWithOptions 

func EnsureCurrentToolsetWithOptions(ctx context.Context, store Store, promptScopeID, runID, threadID, turnID, provider, model string, defs []ToolDefinition, hosted []HostedToolDefinition, now time.Time, options ToolsetOptions) (ToolsetSnapshot, bool, error)

func EnsureToolset 

func EnsureToolset(ctx context.Context, store Store, promptScopeID, runID, threadID, turnID, provider, model string, defs []ToolDefinition, hosted []HostedToolDefinition, now time.Time) (ToolsetSnapshot, bool, error)

func EnsureToolsetWithOptions 

func EnsureToolsetWithOptions(ctx context.Context, store Store, promptScopeID, runID, threadID, turnID, provider, model string, defs []ToolDefinition, hosted []HostedToolDefinition, now time.Time, options ToolsetOptions) (ToolsetSnapshot, bool, error)

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.