Documentation
¶
Overview ¶
Package analysis provides LLM-powered signal clustering and bead generation. It groups related signals by theme, module, or intent, using an LLM provider for semantic understanding, and produces structured beads for backlog import.
Index ¶
- Constants
- func ApplyDepsToSignals(signals []signal.RawSignal, deps []BeadDependency, idPrefix string)
- func BeadsToSignals(beads []AnalysisBead) []signal.RawSignal
- func InferPriorities(ctx context.Context, signals []signal.RawSignal, provider llm.Provider, ...) ([]signal.RawSignal, error)
- type AnalysisBead
- type BeadDependency
- type Cluster
- type ClusterConfig
- type ClusterResult
- type PriorityOverride
- type SignalGroup
Constants ¶
const DefaultSimilarityThreshold = 0.7
DefaultSimilarityThreshold is the default Jaccard similarity threshold used for pre-filtering signals into groups.
const EpicThreshold = 5
EpicThreshold is the minimum number of signals in a cluster before an epic hierarchy is created. Clusters at or below this size produce flat beads.
Variables ¶
This section is empty.
Functions ¶
func ApplyDepsToSignals ¶
func ApplyDepsToSignals(signals []signal.RawSignal, deps []BeadDependency, idPrefix string)
ApplyDepsToSignals populates Blocks and DependsOn fields on signals based on inferred dependencies.
func BeadsToSignals ¶
func BeadsToSignals(beads []AnalysisBead) []signal.RawSignal
BeadsToSignals converts AnalysisBeads back to RawSignals for output formatting. This bridges the analysis results back into the existing pipeline output flow.
func InferPriorities ¶
func InferPriorities(ctx context.Context, signals []signal.RawSignal, provider llm.Provider, overrides []PriorityOverride) ([]signal.RawSignal, error)
InferPriorities uses an LLM to assign P1-P4 priorities to signals based on their content and context. Overrides are applied after LLM inference. On LLM error, signals are returned unchanged (fallback to confidence-based mapping).
Types ¶
type AnalysisBead ¶
type AnalysisBead struct {
// ID is a generated identifier for this bead.
ID string
// Title is the bead title.
Title string
// Description is the full bead description.
Description string
// Type is the bead type (e.g., "task", "epic").
Type string
// Confidence is the confidence level (0.0-1.0).
Confidence float64
// Tags are labels for the bead.
Tags []string
// ParentID links child beads to their parent epic. Empty for top-level beads.
ParentID string
// SourceSignals references the original signals that contributed to this bead.
SourceSignals []signal.RawSignal
}
AnalysisBead represents a bead produced by the clustering analysis. It extends the basic signal with cluster metadata and parent-child relationships.
func CreateEpicHierarchy ¶
func CreateEpicHierarchy(ctx context.Context, cluster Cluster, signals []signal.RawSignal, provider llm.Provider) ([]AnalysisBead, error)
CreateEpicHierarchy generates a parent epic bead with child task beads for clusters that exceed EpicThreshold signals. It uses the LLM to generate an appropriate epic title and description. For clusters with 5 or fewer signals, it falls back to MergeClusterToBeads.
func MergeClusterToBeads ¶
func MergeClusterToBeads(cluster Cluster, signals []signal.RawSignal) []AnalysisBead
MergeClusterToBeads converts a Cluster and its member signals into AnalysisBeads. Single-signal clusters produce one bead directly. Multi-signal clusters produce one bead with a rich description listing all member signals.
type BeadDependency ¶
type BeadDependency struct {
FromID string // Source signal's bead ID.
ToID string // Target signal's bead ID.
Type string // Relationship type: "blocks", "parent", "relates-to".
Confidence float64 // LLM confidence in this relationship (0.0-1.0).
}
BeadDependency represents a dependency relationship between two signals.
func InferDependencies ¶
func InferDependencies(ctx context.Context, signals []signal.RawSignal, provider llm.Provider, idPrefix string) ([]BeadDependency, error)
InferDependencies uses an LLM to identify blocking, parent-child, and relates-to relationships between signals. On LLM error, returns empty deps.
type Cluster ¶
type Cluster struct {
// ID is a unique identifier for this cluster.
ID string
// Name is a short human-readable name for the cluster theme.
Name string
// Description summarizes what the clustered signals have in common.
Description string
// SignalIDs are the indices (as string keys) of signals in the input slice.
SignalIDs []string
// Confidence is the highest confidence among all member signals.
Confidence float64
// Tags are combined unique tags from all member signals.
Tags []string
}
Cluster represents a group of related signals identified by the LLM.
type ClusterConfig ¶
type ClusterConfig struct {
// SimilarityThreshold is the Jaccard similarity threshold for pre-filtering.
// Signals with similarity above this threshold are grouped together before
// being sent to the LLM. Default: 0.7.
SimilarityThreshold float64
// MinClusterSize is the minimum number of signals required to form a cluster.
// Clusters below this size are added to the unclustered list. Default: 1.
MinClusterSize int
// MaxClusterSize caps the number of signals in a single cluster.
// Larger clusters are split. Default: 20.
MaxClusterSize int
}
ClusterConfig controls clustering behavior.
func DefaultClusterConfig ¶
func DefaultClusterConfig() ClusterConfig
DefaultClusterConfig returns a ClusterConfig with sensible defaults.
type ClusterResult ¶
type ClusterResult struct {
// Clusters are the signal groups identified by the LLM.
Clusters []Cluster
// Unclustered contains signal IDs that did not fit any cluster.
Unclustered []string
}
ClusterResult holds the output of a clustering operation.
func ClusterSignals ¶
func ClusterSignals(ctx context.Context, signals []signal.RawSignal, provider llm.Provider, cfg ClusterConfig) (*ClusterResult, error)
ClusterSignals is the main entry point for signal clustering. It pre-filters signals by similarity, sends them to the LLM for semantic clustering, and returns the structured result. On LLM failure, it falls back to treating each signal as its own cluster.
type PriorityOverride ¶
PriorityOverride maps a file-path glob to a fixed priority value.
type SignalGroup ¶
type SignalGroup struct {
// Representative is the first signal in the group, used as the exemplar.
Representative signal.RawSignal
// Members contains all signals in the group, including the representative.
Members []signal.RawSignal
// MemberIndices tracks the original indices of member signals in the
// input slice, used for mapping back to signal IDs.
MemberIndices []int
}
SignalGroup represents a set of signals that are similar enough to be considered together for LLM clustering. The representative signal is the first signal added to the group.
func PreFilterSignals ¶
func PreFilterSignals(signals []signal.RawSignal, threshold float64) []SignalGroup
PreFilterSignals groups signals by similarity to reduce the number of items sent to the LLM. Signals are grouped when they share a common collector source AND either their file paths share a directory prefix OR their titles have a Jaccard similarity above the given threshold.
Source Files