README
¶
vectors/clustering
service := clustering.NewClusterService("kmeans")
result, err := service.Cluster(vectors, clustering.ClusterOptions{K: 2})
vectors/clustering groups caller-supplied vectors with greedy, k-means, and
hierarchical agglomerative clustering helpers.
Cluster accepts empty input as a successful empty result. Non-empty input
must have a positive, consistent dimension and contain only finite values;
malformed input returns an error before any algorithm runs.
It never embeds text or chooses model identity. Callers own vector-space consistency, source documents, labels, and downstream policy.
Documentation
¶
Overview ¶
Package clustering performs online and offline clustering over caller-supplied vector embeddings. It never embeds content and leaves vector-space identity, labels, source documents, and downstream policy with callers.
Package clustering performs online and offline document clustering over caller-supplied [][]float64 embeddings. It never embeds anything itself, so the caller owns vector-space consistency across the whole pipeline.
K-means and silhouette helpers delegate to the root vector package so vector math has one owner. This package keeps the service API, greedy size-constrained clustering, and hierarchical clustering orchestration.
Service ¶
NewClusterService selects one of three algorithms by name — "greedy" (similarity-based, size-constrained grouping), "kmeans" (spherical k-means with optional silhouette-based auto-k), or "hac" (hierarchical agglomerative clustering) — and returns a ClusterService whose Cluster method drives them through a common ClusterOptions/ClusterResult contract.
Direct helpers ¶
The underlying primitives are also exported for callers that want finer control: FindOptimalK and AverageSilhouetteScore for k-means and silhouette scoring, and HAC with CutDendrogram for hierarchical clustering.
Index ¶
- func AverageSilhouetteScore(embeddings [][]float64, assignments []int) float64
- func ClusterSilhouetteScores(embeddings [][]float64, assignments []int) map[int]float64
- func ComputeCentroid(points [][]float64) []float64
- func CosineDistance(a, b []float64) float64
- func CutDendrogram(dendrogram []MergeStep, n int, distanceThreshold float64) []int
- func DistanceMatrix(points [][]float64, metric DistanceFunc) [][]float64
- func EuclideanDistance(a, b []float64) float64
- func NormalizeVector(vec []float64) []float64
- func SilhouetteCoefficient(pointIdx int, embeddings [][]float64, assignments []int) float64
- type ClusterOptions
- type ClusterResult
- type ClusterService
- type DistanceFunc
- type HACConfig
- type HACResult
- type KMeansConfig
- type KMeansResult
- type Linkage
- type MergeStep
- type SilhouetteConfig
- type SilhouetteResult
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AverageSilhouetteScore ¶
AverageSilhouetteScore computes the average silhouette score for a clustering.
func ClusterSilhouetteScores ¶
ClusterSilhouetteScores computes silhouette score per cluster.
func ComputeCentroid ¶
ComputeCentroid computes the mean vector of points.
func CosineDistance ¶
CosineDistance computes cosine distance from similarity.
func CutDendrogram ¶
CutDendrogram cuts the dendrogram at a specific distance threshold. Returns cluster assignments.
func DistanceMatrix ¶
func DistanceMatrix(points [][]float64, metric DistanceFunc) [][]float64
DistanceMatrix computes pairwise distance over a metric.
func EuclideanDistance ¶
EuclideanDistance computes L2 distance.
func NormalizeVector ¶
NormalizeVector normalizes a vector in place and returns it.
Types ¶
type ClusterOptions ¶
type ClusterOptions struct {
Algorithm string // "greedy", "kmeans", "hac"
K int // 0 = auto-select via silhouette
MaxK int // max k for auto-selection (default: 20)
Linkage string // for HAC: "single", "complete", "average"
// Greedy-specific options (for backward compatibility)
TargetMax int // target files per cluster (default: 8)
HardMax int // hard cap on cluster size (default: 12)
MaxSizeKB int // max total size in KB (default: 80)
FileSizes []int64 // file sizes in bytes (for greedy size constraints)
Threshold float64 // minimum similarity threshold for greedy
}
ClusterOptions configures the clustering behavior.
func DefaultClusterOptions ¶
func DefaultClusterOptions() ClusterOptions
DefaultClusterOptions returns sensible defaults.
type ClusterResult ¶
type ClusterResult struct {
Assignments []int // cluster ID for each embedding
K int // number of clusters
Centroids [][]float64 // cluster centroids (for k-means)
Silhouette float64 // average silhouette score
}
ClusterResult holds the output of clustering.
type ClusterService ¶
type ClusterService interface {
// Cluster groups embeddings into clusters. Empty input succeeds with an empty
// result; malformed non-empty embeddings return a contextual error.
Cluster(embeddings [][]float64, opts ClusterOptions) (*ClusterResult, error)
}
ClusterService defines the interface for clustering embeddings.
func NewClusterService ¶
func NewClusterService(algorithm string) ClusterService
NewClusterService creates a ClusterService for the given algorithm. Supported algorithms: "greedy" (default), "kmeans", "hac"
Example ¶
package main
import (
"fmt"
"github.com/dotcommander/reliquary/vector/clustering"
)
func main() {
service := clustering.NewClusterService("greedy")
result, err := service.Cluster([][]float64{{1, 0}, {0.9, 0.1}}, clustering.DefaultClusterOptions())
fmt.Println(result.K > 0, err == nil)
}
Output: true true
type DistanceFunc ¶
DistanceFunc computes distance between two vectors. Kept for compatibility with existing HAC internals.
type HACConfig ¶
type HACConfig struct {
K int // target number of clusters (0 = auto via silhouette)
Linkage Linkage // linkage method (default: average)
}
HACConfig holds configuration for hierarchical agglomerative clustering.
func DefaultHACConfig ¶
func DefaultHACConfig() HACConfig
DefaultHACConfig returns default HAC configuration.
type HACResult ¶
type HACResult struct {
Assignments []int // cluster ID for each point
Centroids [][]float64 // cluster centroids
K int // number of clusters
Dendrogram []MergeStep // merge history (for analysis)
}
HACResult holds the result of HAC clustering.
type KMeansConfig ¶
type KMeansConfig struct {
K int // number of clusters
MaxIterations int // maximum iterations (default: 100)
Tolerance float64 // convergence tolerance (default: 1e-4)
Seed int64 // random seed for initialization (0 = deterministic default)
}
KMeansConfig holds configuration for K-means clustering.
func DefaultKMeansConfig ¶
func DefaultKMeansConfig() KMeansConfig
DefaultKMeansConfig returns default K-means configuration.
type KMeansResult ¶
type KMeansResult struct {
Assignments []int // cluster ID for each point
Centroids [][]float64 // cluster centroids
K int // number of clusters
Iterations int // iterations until convergence
Converged bool // whether algorithm converged
}
KMeansResult holds the result of K-means clustering.
func KMeans ¶
func KMeans(embeddings [][]float64, cfg KMeansConfig) *KMeansResult
KMeans performs K-means clustering with K-means++ initialization.
type MergeStep ¶
type MergeStep struct {
ClusterA int // first cluster merged
ClusterB int // second cluster merged
Distance float64 // distance at merge
NewSize int // size of merged cluster
}
MergeStep records a merge in the dendrogram.
type SilhouetteConfig ¶
type SilhouetteConfig struct {
MinK int // minimum k to try (default: 2)
MaxK int // maximum k to try (default: 20)
Algorithm string // "kmeans" or "hac" (default: "kmeans")
}
SilhouetteConfig holds configuration for silhouette-based auto-k selection.
func DefaultSilhouetteConfig ¶
func DefaultSilhouetteConfig() SilhouetteConfig
DefaultSilhouetteConfig returns default silhouette configuration.
type SilhouetteResult ¶
type SilhouetteResult struct {
BestK int // best k (tie-break: smaller k)
BestScore float64 // silhouette score at best k
Scores []float64 // silhouette scores for each k tried
KValues []int // k values tried
Assignments []int // cluster assignments at best k
Centroids [][]float64
}
SilhouetteResult holds the result of silhouette analysis.
func FindOptimalK ¶
func FindOptimalK(embeddings [][]float64, cfg SilhouetteConfig) *SilhouetteResult
FindOptimalK sweeps k from MinK to min(MaxK, N-1) and returns the best k. Tie-break: smaller k wins (simpler model). HAC returns an empty result when that interval contains no feasible k.
Source Files