Struct EmbeddingClusterAnalyzer 

pub struct EmbeddingClusterAnalyzer {
    pub config: EcaAnalyzerConfig,
    pub points: Vec<EcaClusterPoint>,
    pub clusters: Vec<ClusterDescriptor>,
    pub total_analyses: u64,
    /* private fields */
}

Comprehensive cluster analysis system for embedding spaces.

Tracks points and their cluster assignments, computes quality metrics, detects outliers, estimates local density, and identifies cluster drift relative to a previous snapshot.

Fields

config: EcaAnalyzerConfig

Analyzer configuration.

points: Vec<EcaClusterPoint>

All points currently held by the analyzer.

clusters: Vec<ClusterDescriptor>

Registered cluster descriptors.

total_analyses: u64

Cumulative number of compute_cluster_quality calls.

Implementations

impl EmbeddingClusterAnalyzer

pub fn new(config: EcaAnalyzerConfig) -> Self

Create a new analyzer with the given configuration.

pub fn add_point( &mut self, id: String, embedding: Vec<f64>, cluster: Option<ClusterId>, )

Add an embedding point to the analyzer.

distance_to_centroid starts at 0.0; call set_clusters or recompute_distances to update it.

pub fn set_clusters(&mut self, descriptors: Vec<ClusterDescriptor>)

Replace the cluster descriptors and re-assign / recompute distances.

For each point whose cluster field is None, the nearest cluster (by cosine distance to centroid) is assigned. Then distance_to_centroid is recomputed for every point using L2 distance to its centroid.

pub fn l2_distance(a: &[f64], b: &[f64]) -> f64

Euclidean (L2) distance between two vectors.

Returns 0.0 if either slice is empty.

pub fn cosine_distance(a: &[f64], b: &[f64]) -> f64

Cosine distance (1 − cosine similarity) between two vectors.

Returns 1.0 if either vector has zero norm.

pub fn compute_cluster_quality(&mut self) -> ClusterQuality

Compute comprehensive cluster quality metrics.

Increments total_analyses on each call.

pub fn detect_outliers(&mut self) -> Vec<OutlierScore>

Detect outlier points using three strategies:

1. FarFromCentroid — per-cluster z-score of distance_to_centroid > threshold_sigma
2. IsolatedPoint — member of a cluster with fewer than min_cluster_size points

Results are capped at max_outlier_fraction × total_points, ordered by descending outlier score.

pub fn local_density(&self, point_idx: usize) -> f64

Estimate the local density around a point (by index).

Counts how many other points lie within density_radius (L2). Returns 0.0 for invalid indices.

pub fn cluster_evolution(&self, prev: &EmbeddingClusterAnalyzer) -> Vec<String>

Compare cluster centroids between self (current) and prev (snapshot).

For each cluster in self, finds the closest cluster in prev by L2 centroid distance. If the distance exceeds 0.1, a message is appended: "cluster {id} shifted by {dist:.3}".

pub fn top_k_by_cluster( &self, cluster: ClusterId, k: usize, ) -> Vec<&EcaClusterPoint>

Return the k points in cluster that are closest to the centroid.

Points are ordered by ascending distance_to_centroid. Returns an empty Vec if the cluster does not exist.

pub fn analyzer_stats(&self) -> EcaAnalyzerStats

Return a summary of the current analyzer state.