Struct SemanticClusterLabeler 

pub struct SemanticClusterLabeler { /* private fields */ }

Automatic labeler that assigns human-readable strings to embedding clusters.

Example

use ipfrs_semantic::semantic_cluster_labeler::{
    SemanticClusterLabeler, SclLabelerConfig, SclLabelingMethod,
};

let config = SclLabelerConfig {
    min_confidence: 0.05,
    ..Default::default()
};
let mut labeler = SemanticClusterLabeler::new(config);

// Register labelled prototypes
labeler.add_prototype("science", vec![0.9, 0.1, 0.0]);
labeler.add_prototype("sports",  vec![0.0, 0.9, 0.1]);

// Create a cluster
let id = labeler.add_cluster(vec![0.85, 0.15, 0.0], vec![1, 2, 3]);

// Assign a label
let candidate = labeler.label_cluster(id, SclLabelingMethod::CentroidNearest).unwrap();
assert_eq!(candidate.label, "science");

Implementations

impl SemanticClusterLabeler

pub fn new(config: SclLabelerConfig) -> Self

Create a new labeler with the supplied configuration.

pub fn with_defaults() -> Self

Create a labeler with default configuration.

pub fn add_cluster( &mut self, centroid: Vec<f64>, members: Vec<u64>, ) -> SclClusterId

Register a new cluster and return its id.

Errors

Returns SclError::EmptyCentroid when centroid is empty.

pub fn remove_cluster(&mut self, id: SclClusterId) -> bool

Remove a cluster by id. Returns true if the cluster existed.

pub fn merge_clusters( &mut self, a: SclClusterId, b: SclClusterId, ) -> Result<SclClusterId, SclError>

Merge cluster b into cluster a, returning a’s id on success.

The centroid is recomputed as the mean of both centroids weighted by member count. Cluster b is removed.

Errors

• SclError::SelfMerge when a == b
• SclError::ClusterNotFound when a is not found
• SclError::MergeTargetNotFound when b is not found

pub fn add_prototype(&mut self, label: &str, embedding: Vec<f64>)

Register a named prototype embedding. If a prototype with the same label already exists it is replaced.

pub fn add_keyword_doc(&mut self, text: &str, embedding_id: u64)

Attach a text document to an embedding id for TF-IDF keyword extraction.

Whitespace tokenisation is applied; tokens are lower-cased and non-alphabetic characters are stripped.

pub fn label_cluster( &mut self, id: SclClusterId, method: SclLabelingMethod, ) -> Result<SclLabelCandidate, SclError>

Assign a label to a single cluster using the specified method.

On success the cluster’s label and confidence fields are updated, the vocabulary statistics are refreshed, and a SclLabelingRecord is appended to the history.

pub fn label_all( &mut self, method: SclLabelingMethod, ) -> HashMap<SclClusterId, SclLabelCandidate>

Label every cluster using the given method. Clusters that fail to meet min_confidence are silently skipped.

pub fn relabel_if_drifted(&mut self, threshold: f64) -> usize

Re-label any cluster whose centroid has drifted more than threshold (cosine distance) since it was last labeled.

Returns the number of clusters re-labeled.

pub fn cluster_summary(&self, id: SclClusterId) -> Option<String>

Return a human-readable one-line summary for a cluster.

pub fn labeler_stats(&self) -> SclLabelerStats

Return a snapshot of labeler-wide statistics.

pub fn clusters(&self) -> &HashMap<SclClusterId, SclCluster>

Return immutable access to all clusters.

pub fn vocab(&self) -> &HashMap<String, SclLabelStats>

Return immutable access to the vocabulary.

pub fn history(&self) -> &VecDeque<SclLabelingRecord>

Return a slice of the labeling history (oldest first).

pub fn get_cluster(&self, id: SclClusterId) -> Option<&SclCluster>

Look up a cluster by id.

pub fn config(&self) -> &SclLabelerConfig

Return the current configuration.

pub fn set_config(&mut self, config: SclLabelerConfig)

Update the configuration (does not relabel existing clusters).

pub fn update_centroid(&mut self, id: SclClusterId, centroid: Vec<f64>) -> bool

Update only the centroid of a cluster. Clears labeled_centroid so the next call to relabel_if_drifted will detect the change.

Returns true if the cluster was found and updated.

pub fn add_members(&mut self, id: SclClusterId, new_members: &[u64]) -> bool

Add additional member ids to an existing cluster.

Returns true when the cluster was found.