builtin

type AnalyzeRequest struct {
	ExistingMemory  *UserMemory
	HistoryMessages []*ConversationMessage
	// RecentEvents 已落库的近期事件，作为 LLM 去重参考。仅在事件检索模式下使用。
	RecentEvents []*UserMemoryEvent
	// UseEventSearch 启用后使用事件检索模式 prompt 并解析事件增量。
	// 留空时回退到 analyzer 的 useEventSearchPrompt 配置。
	UseEventSearch *bool
}

type AsyncTaskContextBuilder func(taskType, userID, sessionID string) context.Context

type CleanupConfig struct {
	// 会话状态清理间隔（小时），默认24小时
	SessionCleanupInterval int `json:"sessionCleanupInterval"`
	// 会话状态保留时间（小时），默认168小时（7天）
	SessionRetentionTime int `json:"sessionRetentionTime"`
	// 消息历史保留数量限制，默认1000条
	MessageHistoryLimit int `json:"messageHistoryLimit"`
	// 定期清理间隔（小时），默认12小时
	CleanupInterval int `json:"cleanupInterval"`
}

type ConversationMessage struct {
	// 消息ID
	ID string `json:"id"`
	// 会话ID
	SessionID string `json:"sessionId"`
	// 用户ID
	UserID string `json:"userId"`
	// 角色 (user/assistant/system)
	Role string `json:"role"`
	// 消息内容（简单文本消息）
	Content string `json:"content,omitempty"`
	// 多部分内容，支持文本、图片、音频、视频、文件等
	Parts []schema.MessageInputPart `json:"parts,omitempty"`
	// 创建时间
	CreatedAt time.Time `json:"createdAt"`
}

type CursorMessageStorage interface {
	// GetMessagesAfter 获取游标之后的会话消息。
	// afterMessageID/afterTime 同时存在时，先按时间筛，再按消息ID打破同时间戳顺序。
	// 仅 afterTime 存在时，返回 created_at 晚于 afterTime 的消息。
	// 仅 afterMessageID 存在时，返回 ID 晚于 afterMessageID 的消息。
	// 两者都为空时，等价于 GetMessages(..., limit)。
	GetMessagesAfter(ctx context.Context, sessionID string, userID string, afterMessageID string, afterTime time.Time, limit int) ([]*ConversationMessage, error)

	// GetMessageCountAfter 获取游标之后的会话消息数量（避免加载完整消息列表）。
	// 语义与 GetMessagesAfter 相同，但只返回数量。
	GetMessageCountAfter(ctx context.Context, sessionID string, userID string, afterMessageID string, afterTime time.Time) (int, error)
}

type GormConversationStorage interface {
	ConversationDB() *gorm.DB
	ConversationMessageTableName() string
}

type HybridConfig = builtinsearch.HybridConfig

type MemoryAnalysisResult struct {
	NeedUpdate bool
	Memory     string
	Events     []*UserMemoryEvent
}

type MemoryConfig struct {
	// 是否启用用户记忆
	EnableUserMemories bool `json:"enableUserMemories"`
	// 是否启用会话摘要
	EnableSessionSummary bool `json:"enableSessionSummary"`
	// 是否启用“事件检索”模式：
	//   true  - 用户记忆拆为“常驻短文档（核心约定+基础信息）”和“事件检索表”，
	//           Retrieve 仅注入短文档 + 最近 RecentEventLimit 条事件；
	//           更早的事件需通过 search_user_memory 工具按关键词/时间检索。
	//   false - 兼容旧行为，整篇 UserMemory.Memory 全量注入模型上下文。
	// 仅当 EnableUserMemories=true 时生效。
	EnableEventSearch bool `json:"enableEventSearch"`
	// 常驻注入的最近事件条数，默认 20，仅在 EnableEventSearch=true 时生效。
	// 设为 0 表示不注入任何事件，全部交给检索工具。
	RecentEventLimit int `json:"recentEventLimit,omitempty"`
	// 用户记忆检索方式 EnableUserMemories开启采生效
	Retrieval MemoryRetrieval `json:"retrieval"`
	// 记忆数量限制
	MemoryLimit int `json:"memoryLimit"`
	// 启用会话摘要时，除摘要游标之后的消息外，额外保留最近N条原始消息作为短期上下文。
	// 默认为0，表示保持仅注入摘要游标之后消息的旧行为。
	SummaryRecentMessageLimit int `json:"summaryRecentMessageLimit,omitempty"`
	// 异步处理的goroutine池大小
	AsyncWorkerPoolSize int `json:"asyncWorkerPoolSize"`
	// 记忆任务聚合窗口（秒），同一用户+会话在该窗口内的多次请求只执行一次记忆分析
	// 默认30秒，设为0则每次回复后立即执行（向后兼容）
	DebounceWindowSeconds *int `json:"debounceWindowSeconds,omitempty"`
	// 异步任务执行超时时间（秒），用于用户记忆分析、会话摘要和索引任务。
	// 默认120秒；设为0或负数时使用默认值。
	AsyncTaskTimeoutSeconds int `json:"asyncTaskTimeoutSeconds,omitempty"`

	// 摘要触发配置
	SummaryTrigger SummaryTriggerConfig `json:"summaryTrigger"`

	// 会话摘要缓存配置
	SummaryCache SummaryCacheConfig `json:"summaryCache"`

	// 清理配置
	Cleanup CleanupConfig `json:"cleanup"`

	// 搜索配置。nil 时按 keyword 默认行为初始化。
	Search *SearchConfig `json:"search,omitempty"`
}

type MemoryManager struct {

	// 外部注入的清理函数
	CleanupOldMessagesFunc     func(ctx context.Context) error // 按时间清理旧消息
	CleanupMessagesByLimitFunc func(ctx context.Context) error // 按数量限制清理消息
	// contains filtered or unexported fields
}

type MemoryRetrieval string

type MemoryStorage interface {
	AutoMigrate() error

	// UpsertUserMemory 创建或更新用户记忆（每个用户一条记录）
	UpsertUserMemory(ctx context.Context, memory *UserMemory) error

	// GetUserMemory 获取用户的记忆
	GetUserMemory(ctx context.Context, userID string) (*UserMemory, error)

	// ClearUserMemory 清空用户记忆
	ClearUserMemory(ctx context.Context, userID string) error

	// SaveSessionSummary 保存会话摘要
	SaveSessionSummary(ctx context.Context, summary *SessionSummary) error

	// GetSessionSummary 获取会话摘要
	GetSessionSummary(ctx context.Context, sessionID string, userID string) (*SessionSummary, error)

	// UpdateSessionSummary 更新会话摘要
	UpdateSessionSummary(ctx context.Context, summary *SessionSummary) error

	// DeleteSessionSummary 删除会话摘要
	DeleteSessionSummary(ctx context.Context, sessionID string, userID string) error

	// SaveMessage 保存对话消息
	SaveMessage(ctx context.Context, message *ConversationMessage) error

	// GetMessages 获取会话的消息历史
	// sessionID: 会话ID
	// userID: 用户ID
	// limit: 限制返回数量，0表示不限制
	GetMessages(ctx context.Context, sessionID string, userID string, limit int) ([]*ConversationMessage, error)

	// DeleteMessages 删除会话的消息历史
	DeleteMessages(ctx context.Context, sessionID string, userID string) error

	// Close 关闭存储连接
	Close() error

	// CleanupOldMessages 清理指定时间之前的消息
	CleanupOldMessages(ctx context.Context, userID string, before time.Time) error

	// CleanupMessagesByLimit 按数量限制清理消息，保留最新的N条
	CleanupMessagesByLimit(ctx context.Context, userID, sessionID string, keepLimit int) error

	// GetMessageCount 获取消息总数
	GetMessageCount(ctx context.Context, userID, sessionID string) (int, error)
}

type ProviderConfig struct {
	ChatModel    model.AgenticModel
	Storage      MemoryStorage
	MemoryConfig *MemoryConfig

	AsyncTaskContextBuilder AsyncTaskContextBuilder
}

type SearchConfig struct {
	Mode        builtinsearch.SearchMode
	Embedder    embedding.Embedder
	VectorStore builtinsearch.VectorStore
	Hybrid      HybridConfig
	AsyncIndex  bool
}

type SearchMessageStorage interface {
	SearchMessagesByKeywords(ctx context.Context, q *builtinsearch.SearchQuery) ([]*ConversationMessage, error)
}

type SessionState struct {
	// 上次摘要更新时间
	LastSummaryTime time.Time
	// 上次摘要后新增的消息数量
	MessagesSinceLastSummary int
	// 会话的总消息数量
	TotalMessages int
}

type SessionSummary struct {
	// 会话ID
	SessionID string `json:"sessionId"`
	// 用户ID
	UserID string `json:"userId"`
	// 摘要内容
	Summary string `json:"summary"`
	// 上次已纳入摘要的最后一条消息ID
	LastSummarizedMessageID string `json:"lastSummarizedMessageId,omitempty"`
	// 上次已纳入摘要的最后一条消息时间
	LastSummarizedMessageAt time.Time `json:"lastSummarizedMessageAt,omitempty"`
	// 创建时间
	CreatedAt time.Time `json:"createdAt"`
	// 最后更新时间
	UpdatedAt time.Time `json:"updatedAt"`
}

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

type SummaryCacheConfig struct {
	// TTLSeconds 表示单条摘要缓存 TTL，单位秒
	TTLSeconds int `json:"ttlSeconds"`
	// MaxEntries 表示缓存最多保留多少条会话摘要
	MaxEntries int `json:"maxEntries"`
}

type SummaryTriggerConfig struct {
	// 触发策略类型
	Strategy SummaryTriggerStrategy `json:"strategy"`
	// 基于消息数量触发的阈值
	MessageThreshold int `json:"messageThreshold"`
	// 最小触发间隔（秒）
	MinInterval int `json:"minInterval"`
}

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

type SummaryTriggerStrategy string

type TaskQueueStats struct {
	// 队列大小
	QueueSize int `json:"queueSize"`
	// 队列容量
	QueueCapacity int `json:"queueCapacity"`
	// 已处理任务数
	ProcessedTasks int64 `json:"processedTasks"`
	// 丢弃任务数
	DroppedTasks int64 `json:"droppedTasks"`
	// 当前工作goroutine数
	ActiveWorkers int `json:"activeWorkers"`
	// 队列使用率
	QueueUtilization float64 `json:"queueUtilization"`
}

type UserMemory struct {
	// 用户ID（主键）
	UserID string `json:"userId"`
	// 记忆内容（Markdown格式）
	Memory string `json:"memory"`
	// 创建时间
	CreatedAt time.Time `json:"createdAt"`
	// 最后更新时间
	UpdatedAt time.Time `json:"updatedAt"`
}

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

type UserMemoryAnalyzerParam struct {
	// 操作类型: update(更新记忆)、noop(无需更新)
	Op string `json:"op"`
	// 记忆内容（完整Markdown文档，op为update时有效）
	Memory string `json:"memory"`
}

type UserMemoryEvent = memoryevent.Event

type UserMemoryEventQuery = memoryevent.Query

type UserMemoryEventStorage interface {
	// SaveUserMemoryEvent 新增一条用户记忆事件。事件 ID 未填写时由实现侧生成（建议 ULID 单调递增）。
	SaveUserMemoryEvent(ctx context.Context, event *UserMemoryEvent) error

	// ListRecentUserMemoryEvents 返回该用户最近的 N 条事件，按 EventDate 倒序、同日按 CreatedAt 倒序。
	// limit <= 0 时由实现侧选取一个安全的默认值（建议返回空切片以避免误注入大量数据）。
	ListRecentUserMemoryEvents(ctx context.Context, userID string, limit int) ([]*UserMemoryEvent, error)

	// SearchUserMemoryEvents 按 UserMemoryEventQuery 过滤事件，返回按 EventDate 倒序的命中列表。
	SearchUserMemoryEvents(ctx context.Context, query *UserMemoryEventQuery) ([]*UserMemoryEvent, error)

	// DeleteUserMemoryEvent 删除指定事件。eventID 为空时返回错误。
	DeleteUserMemoryEvent(ctx context.Context, userID, eventID string) error

	// ClearUserMemoryEvents 清空用户的所有事件。迁移脚本和单元测试需要。
	ClearUserMemoryEvents(ctx context.Context, userID string) error
}