statestore

type ConversationState struct {
	ID             string                 // Unique conversation identifier
	UserID         string                 // User who owns this conversation
	Messages       []types.Message        // Message history (using unified types.Message)
	SystemPrompt   string                 // System prompt for this conversation
	Summaries      []Summary              // Compressed summaries of old turns
	TokenCount     int                    // Total tokens in messages
	LastAccessedAt time.Time              // Last time conversation was accessed
	Metadata       map[string]interface{} // Arbitrary metadata (e.g., extracted context)
}

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

type InMemoryIndexOption func(*InMemoryIndex)

type IndexResult struct {
	// TurnIndex is the position of the message in the conversation history.
	TurnIndex int

	// Message is the full message content.
	Message types.Message

	// Score is the relevance score (higher is more relevant, typically 0.0-1.0).
	Score float64
}

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

type ListOptions struct {
	// UserID filters conversations by the user who owns them.
	// If empty, all conversations are returned (subject to pagination).
	UserID string

	// Limit is the maximum number of conversation IDs to return.
	// If 0, a default limit (e.g., 100) should be applied.
	Limit int

	// Offset is the number of conversations to skip (for pagination).
	Offset int

	// SortBy specifies the field to sort by (e.g., "created_at", "updated_at").
	// If empty, implementation-specific default sorting is used.
	SortBy string

	// SortOrder specifies sort direction: "asc" or "desc".
	// If empty, defaults to "desc" (newest first).
	SortOrder string
}

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

type MemoryStoreOption func(*MemoryStore)

type MessageAppender interface {
	// AppendMessages appends messages to the conversation's message history.
	// Creates the conversation if it doesn't exist.
	AppendMessages(ctx context.Context, id string, messages []types.Message) error
}

type MessageIndex interface {
	// Index adds a message to the search index for the given conversation.
	// turnIndex is the position of the message in the conversation history.
	Index(ctx context.Context, conversationID string, turnIndex int, message types.Message) error

	// Search finds the top-k messages most relevant to the query string.
	// Results are ordered by descending relevance score.
	Search(ctx context.Context, conversationID string, query string, k int) ([]IndexResult, error)

	// Delete removes all indexed messages for a conversation.
	Delete(ctx context.Context, conversationID string) error
}

type MessageReader interface {
	// LoadRecentMessages returns the last n messages for the given conversation.
	// Returns ErrNotFound if the conversation doesn't exist.
	LoadRecentMessages(ctx context.Context, id string, n int) ([]types.Message, error)

	// MessageCount returns the total number of messages in the conversation.
	// Returns ErrNotFound if the conversation doesn't exist.
	MessageCount(ctx context.Context, id string) (int, error)
}

type MetadataAccessor interface {
	// LoadMetadata returns just the metadata map for the given conversation.
	// Returns ErrNotFound if the conversation doesn't exist.
	// The returned map is a deep copy safe for mutation by the caller.
	LoadMetadata(ctx context.Context, id string) (map[string]interface{}, error)
}

type RedisOption func(*RedisStore)

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

type Store interface {
	// Load retrieves conversation state by ID
	Load(ctx context.Context, id string) (*ConversationState, error)

	// Save persists conversation state
	Save(ctx context.Context, state *ConversationState) error

	// Fork creates a copy of an existing conversation state with a new ID
	// The original conversation is left unchanged. Returns ErrNotFound if sourceID doesn't exist.
	Fork(ctx context.Context, sourceID, newID string) error
}

type Summarizer interface {
	// Summarize compresses the given messages into a concise summary.
	Summarize(ctx context.Context, messages []types.Message) (string, error)
}

type Summary struct {
	StartTurn  int       // First turn included in this summary
	EndTurn    int       // Last turn included in this summary
	Content    string    // Summarized content
	TokenCount int       // Token count of the summary
	CreatedAt  time.Time // When this summary was created
}

type SummaryAccessor interface {
	// LoadSummaries returns all summaries for the given conversation.
	// Returns nil (not an error) if no summaries exist.
	LoadSummaries(ctx context.Context, id string) ([]Summary, error)

	// SaveSummary appends a summary to the conversation's summary list.
	SaveSummary(ctx context.Context, id string, summary Summary) error
}