clustering

package
v0.14.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 29, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package clustering computes exact duplicate-thread clusters from caller-owned candidate snapshots.

Computation is deterministic, cancellable, bounded by a ComparisonBudget, and free of storage and network side effects. Durable projection lifecycle, governance, and stale-safe atomic persistence belong to the corpus and clusterprojection packages.

Index

Constants

View Source 
const (
	DefaultNeighborsLimit = 10
	MaxNeighborsLimit     = 1000
)

Neighbor defaults and hard limits.

Variables

This section is empty.

Functions

func SourceRevision 

func SourceRevision(candidates []Candidate) string

SourceRevision returns a full SHA-256 digest of every candidate field that can affect duplicate scoring or the stored projection. Candidate and label ordering do not affect the digest.

func SourceWindow 

func SourceWindow(candidates []Candidate) (time.Time, time.Time)

SourceWindow returns the minimum and maximum UpdatedAt of the candidates.

Types

type Candidate 

type Candidate struct {
	ThreadID  int64
	Repo      domain.RepoRef
	Kind      string
	Number    int
	State     string
	Title     string
	Body      string
	Author    string
	Labels    []string
	CreatedAt time.Time
	UpdatedAt time.Time
}

Candidate is a thread considered for duplicate-candidate clustering.

func (Candidate) Ref 

func (c Candidate) Ref() MemberRef

Ref returns the member identity for the candidate.

type CapacityError added in v0.8.0 

type CapacityError struct {
	CandidateCount int
	PossiblePairs  uint64
	AllowedPairs   uint64
}

CapacityError reports a population whose worst-case work exceeds the budget.

func (*CapacityError) Error added in v0.8.0 

func (e *CapacityError) Error() string

Error describes the rejected scoring request.

type Cluster 

type Cluster struct {
	ID          int64
	StableID    string
	State       ClusterState
	Repo        domain.RepoRef
	Canonical   MemberRef
	Revision    string
	WindowStart time.Time
	WindowEnd   time.Time
	Members     []Member
	CreatedAt   time.Time
	UpdatedAt   time.Time
}

Cluster is a group of duplicate-candidate threads.

func ReconcileProjection added in v0.8.0 

func ReconcileProjection(
	ctx context.Context,
	raw []Cluster,
	existing []Cluster,
	overridesByStable map[string][]MembershipOverride,
	candidates []Candidate,
	repo domain.RepoRef,
	revision string,
	now time.Time,
) ([]Cluster, error)

ReconcileProjection applies durable governance and projection metadata to a pure engine computation. All existing clusters, members, overrides, and candidates must come from the same storage snapshot. StableID remains tied to the engine-selected canonical member even when governance changes the displayed canonical member, so later refreshes can find the same history.

type ClusterState 

type ClusterState string

ClusterState is the local lifecycle of a cluster. 

const (
	ClusterOpen   ClusterState = "open"
	ClusterClosed ClusterState = "closed"
	// ClusterRetired preserves governance history for a cluster that is no
	// longer present in the latest computation.
	ClusterRetired ClusterState = "retired"
)

type ComparisonBudget added in v0.13.0 

type ComparisonBudget uint64

ComparisonBudget bounds the worst-case exact scores in one clustering run.

func DefaultComparisonBudget added in v0.13.0 

func DefaultComparisonBudget() ComparisonBudget

DefaultComparisonBudget returns the repository's supported scoring budget.

func (ComparisonBudget) MaxCandidates added in v0.13.0 

func (b ComparisonBudget) MaxCandidates() int

MaxCandidates returns the greatest population whose worst-case work fits the budget.

func (ComparisonBudget) Possible added in v0.13.0 

func (b ComparisonBudget) Possible(candidateCount int) (uint64, error)

Possible returns the population's possible pair count or a CapacityError when worst-case scoring would exceed the budget.

type Computation added in v0.8.0 

type Computation struct {
	Clusters       []Cluster
	CandidateCount int
	PossiblePairs  uint64
	ScoredPairs    uint64
	RuleVersion    similarity.RuleVersion
}

Computation describes one complete lossless clustering result.

type Engine added in v0.8.0 

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

Engine performs bounded, cancellable duplicate clustering with lossless candidate pruning and exact scoring.

func NewEngine added in v0.8.0 

func NewEngine(rule similarity.DuplicateRule, budget ComparisonBudget) (Engine, error)

NewEngine constructs a clustering engine from a valid rule and nonzero budget.

func (Engine) Cluster added in v0.8.0 

func (e Engine) Cluster(ctx context.Context, candidates []Candidate) (Computation, error)

Cluster computes duplicate clusters without storage side effects. Candidate pruning is lossless for the configured scoring rule and threshold.

func (Engine) MaxCandidates added in v0.8.0 

func (e Engine) MaxCandidates() int

MaxCandidates returns the population bound derived from worst-case scoring.

func (Engine) RuleVersion added in v0.8.0 

func (e Engine) RuleVersion() similarity.RuleVersion

RuleVersion identifies the exact scoring rule used by the engine.

type Member 

type Member struct {
	ThreadID int64
	Ref      MemberRef
	Title    string
	State    string
	Score    float64
	Reason   string
	Included bool
}

Member is one thread inside a cluster.

type MemberRef 

type MemberRef struct {
	Owner  string
	Repo   string
	Kind   string
	Number int
}

MemberRef identifies a thread across repositories and kinds.

func ExtractMemberRefs added in v0.8.0 

func ExtractMemberRefs(text string, defaultRepo domain.RepoRef) []MemberRef

ExtractMemberRefs adapts exact GitHub references to cluster member values.

func (MemberRef) Less 

func (m MemberRef) Less(other MemberRef) bool

Less defines a deterministic total order for canonical selection.

func (MemberRef) String 

func (m MemberRef) String() string

type MembershipOverride 

type MembershipOverride struct {
	ID        int64
	ClusterID int64
	Ref       MemberRef
	Action    OverrideAction
	Reason    string
	CreatedAt time.Time
}

MembershipOverride records an explicit local include/exclude/canonical decision.

type Neighbor 

type Neighbor struct {
	ThreadID int64
	Ref      MemberRef
	Title    string
	State    string
	Score    float64
	Reason   string
}

Neighbor is a scored thread near a query candidate.

func Neighbors 

func Neighbors(ctx context.Context, query Candidate, candidates []Candidate, limit int) ([]Neighbor, error)

Neighbors scores every candidate against the query using deterministic local signals and returns the top limit results with stable tie ordering.

The query itself is excluded from the returned set. Scores and reasons are produced by the same versioned duplicate rule used for clustering.

type OverrideAction 

type OverrideAction string

OverrideAction is a local governance instruction for a cluster member. 

const (
	OverrideInclude      OverrideAction = "include"
	OverrideExclude      OverrideAction = "exclude"
	OverrideSetCanonical OverrideAction = "set_canonical"
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.