checkpoint

package
v0.9.1 Latest Latest
Warning

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

Go to latest
Published: Apr 23, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Overview

Package checkpoint provides state snapshotting and restoration for Thane.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ParseUUID

func ParseUUID(s string) uuid.UUID

ParseUUID parses a string to UUID, returning zero UUID on error.

Types

type Checkpoint

type Checkpoint struct {
	ID        uuid.UUID `json:"id"`
	CreatedAt time.Time `json:"created_at"`
	Trigger   Trigger   `json:"trigger"`
	Note      string    `json:"note,omitempty"` // Optional human description

	// Captured state
	State *State `json:"state"`

	// Metadata
	ByteSize     int64 `json:"byte_size"`     // Compressed size
	MessageCount int   `json:"message_count"` // Total messages captured
	FactCount    int   `json:"fact_count"`    // Total facts captured
}

Checkpoint represents a point-in-time snapshot of agent state.

func (*Checkpoint) Summary

func (c *Checkpoint) Summary() string

Summary returns a human-readable summary of the checkpoint.

type Checkpointer

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

Checkpointer manages automatic and manual checkpointing.

func NewCheckpointer

func NewCheckpointer(db *sql.DB, cfg Config, log *slog.Logger) (*Checkpointer, error)

NewCheckpointer creates a new checkpointer.

func (*Checkpointer) Create

func (c *Checkpointer) Create(trigger Trigger, note string) (*Checkpoint, error)

Create makes a new checkpoint with the given trigger and optional note.

func (*Checkpointer) CreatePreFailover

func (c *Checkpointer) CreatePreFailover(fromModel, toModel string) (*Checkpoint, error)

CreatePreFailover creates a checkpoint before switching models.

func (*Checkpointer) CreateShutdown

func (c *Checkpointer) CreateShutdown() (*Checkpoint, error)

CreateShutdown creates a checkpoint during graceful shutdown.

func (*Checkpointer) Delete

func (c *Checkpointer) Delete(id uuid.UUID) error

Delete removes a checkpoint.

func (*Checkpointer) Get

func (c *Checkpointer) Get(id uuid.UUID) (*Checkpoint, error)

Get retrieves a checkpoint by ID.

func (*Checkpointer) GetStartupStatus

func (c *Checkpointer) GetStartupStatus() (*StartupStatus, error)

GetStartupStatus collects state info for startup logging.

func (*Checkpointer) Latest

func (c *Checkpointer) Latest() (*Checkpoint, error)

Latest returns the most recent checkpoint.

func (*Checkpointer) List

func (c *Checkpointer) List(limit int) ([]*Checkpoint, error)

List returns recent checkpoints.

func (*Checkpointer) LogStartupStatus

func (c *Checkpointer) LogStartupStatus()

LogStartupStatus logs the current persisted state.

func (*Checkpointer) OnFailover

func (c *Checkpointer) OnFailover(ctx context.Context, fromModel, toModel, reason string) error

OnFailover implements agent.FailoverHandler for checkpoint creation before model switches.

func (*Checkpointer) OnMessage

func (c *Checkpointer) OnMessage()

OnMessage should be called after each message is processed. It triggers periodic checkpointing if configured.

func (*Checkpointer) Prune

func (c *Checkpointer) Prune(olderThan time.Duration, minKeep int) (int, error)

Prune removes old checkpoints.

func (*Checkpointer) Restore

func (c *Checkpointer) Restore(id uuid.UUID) error

Restore applies a checkpoint's state to the providers. This is a placeholder — actual restoration depends on provider implementations.

func (*Checkpointer) SetProviders

func (c *Checkpointer) SetProviders(conv ConversationFunc, facts FactFunc, tasks TaskFunc)

SetProviders configures the functions that supply state for snapshots.

type Config

type Config struct {
	PeriodicMessages int // Checkpoint every N messages (0 = disabled)
}

Config for the checkpointer.

type ConfigSnapshot

type ConfigSnapshot struct {
	DefaultModel string `json:"default_model"`
	HAConfigured bool   `json:"ha_configured"`
	TalentCount  int    `json:"talent_count"`
}

ConfigSnapshot captures relevant config at checkpoint time.

type Conversation

type Conversation struct {
	ID        string    `json:"id"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
	Messages  []Message `json:"messages"`
}

Conversation represents a chat session.

func ConvertConversation added in v0.9.1

func ConvertConversation(id string, createdAt, updatedAt time.Time, msgs []SourceMessage) (Conversation, error)

ConvertConversation builds a checkpoint Conversation from external data, generating fresh UUIDs for each message. Returns an error if UUID generation fails.

type ConversationFunc added in v0.9.1

type ConversationFunc func() ([]Conversation, error)

ConversationFunc returns conversations for checkpointing.

type Fact

type Fact struct {
	ID         uuid.UUID `json:"id"`
	Category   string    `json:"category"` // "user", "home", "preference", etc.
	Key        string    `json:"key"`
	Value      string    `json:"value"`
	Source     string    `json:"source,omitempty"` // Where this fact came from
	CreatedAt  time.Time `json:"created_at"`
	UpdatedAt  time.Time `json:"updated_at"`
	Confidence float64   `json:"confidence,omitempty"` // 0-1, how sure we are
}

Fact is a piece of long-term memory.

type FactFunc added in v0.9.1

type FactFunc func() ([]Fact, error)

FactFunc returns facts for checkpointing.

type Message

type Message struct {
	ID        uuid.UUID `json:"id"`
	Role      string    `json:"role"` // "system", "user", "assistant", "tool"
	Content   string    `json:"content"`
	Timestamp time.Time `json:"timestamp"`

	// Tool-specific fields
	ToolCalls []ToolCall `json:"tool_calls,omitempty"`
	ToolID    string     `json:"tool_id,omitempty"`   // For tool responses
	ToolName  string     `json:"tool_name,omitempty"` // For tool responses
}

Message is a single turn in a conversation.

type SourceMessage added in v0.9.1

type SourceMessage struct {
	Role      string
	Content   string
	Timestamp time.Time
}

SourceMessage holds the minimal fields needed to convert an external message into a checkpoint Message. This avoids import cycles between checkpoint and memory packages.

type StartupStatus

type StartupStatus struct {
	Conversations  int        `json:"conversations"`
	Messages       int        `json:"messages"`
	Facts          int        `json:"facts"`
	LastCheckpoint *time.Time `json:"last_checkpoint,omitempty"`
}

StartupStatus returns info about persisted state for logging at startup. Since SQLite persists automatically, this just reports what exists.

type State

type State struct {
	// Conversations with full message history
	Conversations []Conversation `json:"conversations"`

	// Long-term memory facts
	Facts []Fact `json:"facts"`

	// Pending scheduled tasks
	Tasks []Task `json:"tasks,omitempty"`

	// Agent configuration at checkpoint time
	Config *ConfigSnapshot `json:"config,omitempty"`
}

State holds the actual restorable data.

type Store

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

Store handles checkpoint persistence.

func NewStore

func NewStore(db *sql.DB) (*Store, error)

NewStore creates a checkpoint store using the given database.

func (*Store) Create

func (s *Store) Create(trigger Trigger, note string, state *State) (*Checkpoint, error)

Create saves a new checkpoint and returns it with ID populated.

func (*Store) Delete

func (s *Store) Delete(id uuid.UUID) error

Delete removes a checkpoint by ID.

func (*Store) Get

func (s *Store) Get(id uuid.UUID) (*Checkpoint, error)

Get retrieves a checkpoint by ID, including full state.

func (*Store) Latest

func (s *Store) Latest() (*Checkpoint, error)

Latest returns the most recent checkpoint, or nil if none exist.

func (*Store) List

func (s *Store) List(limit int) ([]*Checkpoint, error)

List returns checkpoints ordered by creation time (newest first). Does not include full state to keep response small.

func (*Store) Prune

func (s *Store) Prune(olderThan time.Duration, minKeep int) (int, error)

Prune removes checkpoints older than the given duration, keeping at least minKeep.

type Task

type Task struct {
	ID          uuid.UUID `json:"id"`
	Name        string    `json:"name"`
	Description string    `json:"description,omitempty"`
	Schedule    string    `json:"schedule"` // Cron expression or timestamp
	Action      string    `json:"action"`   // What to do
	Enabled     bool      `json:"enabled"`
	CreatedAt   time.Time `json:"created_at"`
}

Task is a scheduled action.

type TaskFunc added in v0.9.1

type TaskFunc func() ([]Task, error)

TaskFunc returns tasks for checkpointing.

type ToolCall

type ToolCall struct {
	ID        string `json:"id"`
	Name      string `json:"name"`
	Arguments string `json:"arguments"` // JSON string
}

ToolCall represents a function call made by the assistant.

type Trigger

type Trigger string

Trigger describes what caused a checkpoint to be created.

const (
	TriggerManual      Trigger = "manual"       // Explicit API call
	TriggerPeriodic    Trigger = "periodic"     // Every N messages
	TriggerPreFailover Trigger = "pre-failover" // Before model switch
	TriggerShutdown    Trigger = "shutdown"     // Graceful shutdown
	TriggerPreCompact  Trigger = "pre-compact"  // Before memory compaction
)

Jump to

Keyboard shortcuts

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