snapshot

package
v0.6.15 Latest Latest
Warning

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

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

Documentation

Overview

Package snapshot projects inspectable, provider-neutral model exchanges. Current snapshots are reconstructed from committed transcripts on demand; the file store remains only for legacy cleanup and test fixtures.

Index

Constants

View Source 
const (
	DefaultMaxSnapshots       = 200
	DefaultMaxBytes     int64 = 128 << 20
	DefaultMaxFileBytes       = 32 << 20
)
View Source 
const CurrentVersion = 4

Variables

View Source 
var (
	ErrNotFound  = errors.New("request snapshot not found")
	ErrInvalidID = errors.New("request snapshot ID is invalid")
)

Functions

This section is empty.

Types

type Attachment 

type Attachment struct {
	ID           string `json:"id"`
	Kind         string `json:"kind"`
	Placement    string `json:"placement"`
	Path         string `json:"path,omitempty"`
	Revision     string `json:"revision,omitempty"`
	MessageIndex int    `json:"messageIndex"`
}

Attachment identifies one product-generated message inside Input.Messages.

type Content 

type Content struct {
	Type       string         `json:"type"`
	Text       string         `json:"text,omitempty"`
	Thinking   string         `json:"thinking,omitempty"`
	Redacted   bool           `json:"redacted,omitempty"`
	Image      *Image         `json:"image,omitempty"`
	ToolCallID string         `json:"toolCallId,omitempty"`
	ToolName   string         `json:"toolName,omitempty"`
	Arguments  map[string]any `json:"arguments,omitempty"`
}

Content is a signature-free, provider-neutral input content block.

type DiscardCleaner added in v0.6.15 

type DiscardCleaner struct{}

DiscardCleaner keeps legacy snapshot cleanup optional and fail-open.

func (DiscardCleaner) DeleteSession added in v0.6.15 

func (DiscardCleaner) DeleteSession(string) error

type FileStore 

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

FileStore stores one private JSON file per provider request.

func NewFileStore 

func NewFileStore(dir string, options Options) (*FileStore, error)

NewFileStore creates and secures a local request snapshot directory. It is retained for legacy fixtures and cleanup; production no longer writes new request snapshot files.

func OpenLegacyFileStore added in v0.6.15 

func OpenLegacyFileStore(dir string) (*FileStore, error)

OpenLegacyFileStore opens an existing request snapshot directory without creating one. Production uses it only to cascade session deletion to files left by older releases.

func (*FileStore) DeleteSession 

func (store *FileStore) DeleteSession(sessionID string) error

DeleteSession removes every snapshot correlated with sessionID. The store lock prevents pruning, loading, or saving from racing the directory scan.

func (*FileStore) Load 

func (store *FileStore) Load(requestID string) (Snapshot, error)

Load reads one snapshot by its correlated provider request ID.

func (*FileStore) LoadForSession added in v0.6.15 

func (store *FileStore) LoadForSession(
	sessionID, requestID string,
) (Snapshot, error)

LoadForSession implements Reader while keeping file-backed fixtures and legacy cleanup scoped to the owning conversation.

func (*FileStore) Save 

func (store *FileStore) Save(snapshot Snapshot) error

Save atomically writes a snapshot and removes the oldest files as needed.

func (*FileStore) SaveOutput 

func (store *FileStore) SaveOutput(requestID string, message *llm.AssistantMessage) error

SaveOutput completes an existing request snapshot without exposing content through the privacy-safe performance event log.

type Image 

type Image struct {
	MIMEType     string `json:"mimeType"`
	EncodedBytes int    `json:"encodedBytes,omitempty"`
}

Image contains inspectable metadata without retaining base64 image bytes.

type Input 

type Input struct {
	SystemPrompt string    `json:"systemPrompt,omitempty"`
	Messages     []Message `json:"messages"`
	Tools        []Tool    `json:"tools,omitempty"`
}

Input is the complete inspectable request after context projection.

type Message 

type Message struct {
	Role              string    `json:"role"`
	Content           []Content `json:"content"`
	ProviderRequestID string    `json:"providerRequestId,omitempty"`
	ToolCallID        string    `json:"toolCallId,omitempty"`
	ToolName          string    `json:"toolName,omitempty"`
	IsError           bool      `json:"isError,omitempty"`
}

Message is one model-input message with only inspectable replay content.

type Options 

type Options struct {
	MaxSnapshots int
	MaxBytes     int64
	MaxFileBytes int64
}

Options bounds private local snapshot storage. Zero values use defaults.

type Output 

type Output struct {
	CapturedAt   time.Time `json:"capturedAt"`
	Message      Message   `json:"message"`
	StopReason   string    `json:"stopReason,omitempty"`
	ErrorMessage string    `json:"errorMessage,omitempty"`
}

Output is the terminal provider message captured after streaming completes.

type Reader 

type Reader interface {
	LoadForSession(sessionID, providerRequestID string) (Snapshot, error)
}

Reader reconstructs one session-scoped snapshot on demand for diagnostics.

type SessionCleaner 

type SessionCleaner interface {
	DeleteSession(sessionID string) error
}

SessionCleaner removes every private snapshot owned by one session.

type Snapshot 

type Snapshot struct {
	Version           int          `json:"version"`
	CapturedAt        time.Time    `json:"capturedAt"`
	SessionID         string       `json:"sessionId"`
	RunID             string       `json:"runId"`
	TurnID            string       `json:"turnId"`
	StepID            string       `json:"stepId"`
	ProviderRequestID string       `json:"providerRequestId"`
	Provider          string       `json:"provider"`
	Model             string       `json:"model"`
	Input             Input        `json:"input"`
	Output            *Output      `json:"output,omitempty"`
	Attachments       []Attachment `json:"attachments,omitempty"`
}

Snapshot correlates a provider-neutral exchange with the performance timeline.

func FromTranscript added in v0.6.15 

func FromTranscript(
	sessionID, providerRequestID string,
	entries []transcript.Entry,
) (Snapshot, error)

FromTranscript builds the inspectable diagnostic view of one committed provider request without consulting live agent state or a secondary store.

func NewSnapshot 

func NewSnapshot(
	sessionID, runID, turnID, stepID, requestID, provider, model string,
	input llm.Context,
	attachments []Attachment,
) Snapshot

NewSnapshot removes replay-only signatures and image payloads while keeping every piece of content a person can meaningfully inspect.

type Tool 

type Tool struct {
	Name        string          `json:"name"`
	Description string          `json:"description"`
	Parameters  json.RawMessage `json:"parameters"`
	Strict      *bool           `json:"strict,omitempty"`
}

Tool is one tool definition advertised to the model.

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.