knowledge

type Cluster struct {
	ID          uuid.UUID
	UserID      string
	Label       string
	Keywords    []string
	Centroid    []float64
	MemberCount int
	Trend       int // 0=growing, 1=stable, 2=decaying
	SourceType  int // 0=entries, 1=memories, 2=mixed
	Members     []ClusterMember
}

type ClusterBirth struct {
	Members  []int // indices in the new embedding set
	Centroid []float64
}

type ClusterMember struct {
	SourceID   uuid.UUID
	SourceType int // 0=entry, 1=memory
}

type ClusterResult struct {
	// Clusters maps cluster label (0-based) to the set of member indices.
	Clusters map[int][]int
	// Noise contains indices of points classified as noise by DBSCAN.
	Noise []int
}

type ClusterRunStats struct {
	UsersProcessed  int `json:"users_processed"`
	Clustersborn    int `json:"clusters_born"`
	ClustersUpdated int `json:"clusters_updated"`
	ClustersDied    int `json:"clusters_died"`
	Failures        int `json:"failures"`
}

type ClusterTexts map[int]string

type ClusterUpdate struct {
	ClusterID    uuid.UUID
	NewMembers   []int // indices in the new embedding set
	NewCentroid  []float64
	OverlapRatio float64 // fraction of new cluster members that were in the old cluster
}

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

type DBSCANConfig struct {
	// Epsilon is the maximum cosine distance between two points to be
	// considered neighbors. Range: 0.0 (identical) to 2.0 (opposite).
	Epsilon float64
	// MinPoints is the minimum number of points required to form a dense region.
	MinPoints int
}

type DiffResult struct {
	// Updated clusters: existing cluster matched to new DBSCAN output.
	Updated []ClusterUpdate
	// Born clusters: new DBSCAN clusters that don't match any existing cluster.
	Born []ClusterBirth
	// Died clusters: existing clusters with no matching new DBSCAN cluster.
	Died []uuid.UUID
}

type EmbeddingRecord struct {
	SourceID   uuid.UUID // entry_id or memory_id
	SourceType int       // 0=entry, 1=memory
	UserID     string    // owner of the data
	Embedding  []float64
}

type KeywordResult struct {
	ClusterLabel int
	Keywords     []ScoredKeyword
}

type KnowledgeStore interface {
	// ListUsersWithEmbeddings returns distinct user IDs that have embeddings.
	ListUsersWithEmbeddings(ctx context.Context) ([]string, error)

	// LoadEmbeddingsForUser returns all embeddings belonging to a user.
	LoadEmbeddingsForUser(ctx context.Context, userID string) ([]EmbeddingRecord, error)

	// LoadClustersForUser returns all stored clusters (with members) for a user.
	LoadClustersForUser(ctx context.Context, userID string) ([]StoredCluster, error)

	// SaveCluster creates a new cluster with its members.
	SaveCluster(ctx context.Context, cluster StoredCluster, members []StoredClusterMember) error

	// UpdateCluster updates an existing cluster's metadata and replaces its members.
	UpdateCluster(ctx context.Context, cluster StoredCluster, members []StoredClusterMember) error

	// DeleteCluster removes a cluster and its members.
	DeleteCluster(ctx context.Context, clusterID uuid.UUID) error

	// LoadTextsForSourceIDs returns the indexed text content for the given source IDs.
	// Used for c-TF-IDF keyword extraction after clustering.
	LoadTextsForSourceIDs(ctx context.Context, sourceIDs []uuid.UUID) (map[uuid.UUID]string, error)

	// ResolveOwnersByConversationGroupIDs returns distinct owner user IDs for the
	// given conversation group IDs. Used by the indexer to determine which users
	// need re-clustering after new embeddings are created.
	ResolveOwnersByConversationGroupIDs(ctx context.Context, groupIDs []uuid.UUID) ([]string, error)
}

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

type ScoredKeyword struct {
	Term  string
	Score float64
}

type StoredCluster struct {
	ID          uuid.UUID
	UserID      string
	Label       string
	Keywords    []string
	Centroid    []float64
	MemberCount int
	Trend       int // 0=growing, 1=stable, 2=decaying
	SourceType  int // 0=entries, 1=memories, 2=mixed
	CreatedAt   time.Time
	UpdatedAt   time.Time
	Members     []StoredClusterMember
}

type StoredClusterMember struct {
	ClusterID  uuid.UUID
	SourceID   uuid.UUID
	SourceType int
	Distance   float32
}