Documentation
¶
Overview ¶
Package checkpoint provides state snapshotting and restoration for Thane.
Index ¶
- func ParseUUID(s string) uuid.UUID
- type Checkpoint
- type Checkpointer
- func (c *Checkpointer) Create(trigger Trigger, note string) (*Checkpoint, error)
- func (c *Checkpointer) CreatePreFailover(fromModel, toModel string) (*Checkpoint, error)
- func (c *Checkpointer) CreateShutdown() (*Checkpoint, error)
- func (c *Checkpointer) Delete(id uuid.UUID) error
- func (c *Checkpointer) Get(id uuid.UUID) (*Checkpoint, error)
- func (c *Checkpointer) GetStartupStatus() (*StartupStatus, error)
- func (c *Checkpointer) Latest() (*Checkpoint, error)
- func (c *Checkpointer) List(limit int) ([]*Checkpoint, error)
- func (c *Checkpointer) LogStartupStatus()
- func (c *Checkpointer) OnFailover(ctx context.Context, fromModel, toModel, reason string) error
- func (c *Checkpointer) OnMessage()
- func (c *Checkpointer) Prune(olderThan time.Duration, minKeep int) (int, error)
- func (c *Checkpointer) Restore(id uuid.UUID) error
- func (c *Checkpointer) SetProviders(conv ConversationFunc, facts FactFunc, tasks TaskFunc)
- type Config
- type ConfigSnapshot
- type Conversation
- type ConversationFunc
- type Fact
- type FactFunc
- type Message
- type SourceMessage
- type StartupStatus
- type State
- type Store
- func (s *Store) Create(trigger Trigger, note string, state *State) (*Checkpoint, error)
- func (s *Store) Delete(id uuid.UUID) error
- func (s *Store) Get(id uuid.UUID) (*Checkpoint, error)
- func (s *Store) Latest() (*Checkpoint, error)
- func (s *Store) List(limit int) ([]*Checkpoint, error)
- func (s *Store) Prune(olderThan time.Duration, minKeep int) (int, error)
- type Task
- type TaskFunc
- type ToolCall
- type Trigger
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
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 ¶
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) 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 ¶
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 ¶
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 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 ¶
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 (*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.
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 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 )