Struct SemanticVersioningTracker 

pub struct SemanticVersioningTracker { /* private fields */ }

Tracks semantic drift of concept embeddings across model versions.

Overview

The tracker maintains a registry of named model/embedding versions and a set of anchor concepts — representative items whose embeddings should be stable between compatible versions. For each concept that exists in two versions the tracker computes the cosine distance of their embeddings, which it calls the drift score.

Example

use ipfrs_semantic::semantic_versioning_tracker::{
    SemanticVersioningTracker, SvtTrackerConfig,
};

let config = SvtTrackerConfig { drift_threshold: 0.1, ..Default::default() };
let mut tracker = SemanticVersioningTracker::new(config);

let v1 = tracker.register_version("bert-v1", 3).unwrap();
let v2 = tracker.register_version("bert-v2", 3).unwrap();

tracker.add_anchor("cat", v1, vec![1.0, 0.0, 0.0]).unwrap();
tracker.add_anchor("cat", v2, vec![0.98, 0.1, 0.05]).unwrap();

let report = tracker.compute_drift(v1, v2).unwrap();
assert!(report.overall_drift < 0.1);

Implementations

impl SemanticVersioningTracker

pub fn new(config: SvtTrackerConfig) -> Self

Creates a new tracker with the supplied configuration.

pub fn with_defaults() -> Self

Creates a tracker with default configuration.

pub fn register_version( &mut self, name: impl Into<String>, dim: usize, ) -> Result<SvtVersionId, SvtError>

Registers a new version and returns its assigned SvtVersionId.

Errors

Returns SvtError::DimMismatch (with expected = 0) if dim == 0.

pub fn deprecate_version(&mut self, id: SvtVersionId) -> Result<(), SvtError>

Marks a version as deprecated (inactive).

Errors

Returns SvtError::VersionNotFound if the ID is unknown.

pub fn activate_version(&mut self, id: SvtVersionId) -> Result<(), SvtError>

Re-activates a previously deprecated version.

Errors

Returns SvtError::VersionNotFound if the ID is unknown.

pub fn get_version(&self, id: SvtVersionId) -> Result<&SvtVersion, SvtError>

Returns an immutable reference to the version metadata.

Errors

Returns SvtError::VersionNotFound if the ID is unknown.

pub fn list_versions(&self) -> Vec<&SvtVersion>

Returns all registered versions sorted by ID (ascending).

pub fn active_versions(&self) -> Vec<&SvtVersion>

Returns only active versions sorted by ID (ascending).

pub fn add_anchor( &mut self, concept: &str, version_id: SvtVersionId, embedding: Vec<f64>, ) -> Result<(), SvtError>

Registers a concept embedding for a specific version.

If an anchor for this (concept, version_id) pair already exists it is replaced.

Errors

• SvtError::InvalidConcept – concept name is empty.
• SvtError::VersionNotFound – version ID unknown.
• SvtError::DimMismatch – embedding.len() differs from the version’s declared embedding_dim.

pub fn get_anchor( &self, concept: &str, version_id: SvtVersionId, ) -> Result<&[f64], SvtError>

Returns the embedding for a specific (concept, version) pair.

Errors

• SvtError::AnchorNotFound if no such pair exists.

pub fn concepts_for_version(&self, version_id: SvtVersionId) -> Vec<&str>

Returns all concepts that have anchors registered in the given version.

pub fn compute_drift( &mut self, ver_a: SvtVersionId, ver_b: SvtVersionId, ) -> Result<SvtDriftReport, SvtError>

Computes a full drift report between two versions.

For each concept present in both versions the method computes the cosine distance and records it in the drift log.

Errors

• SvtError::VersionNotFound if either version ID is unknown.
• SvtError::InsufficientAnchors if fewer than config.min_anchors shared concepts exist.

pub fn find_drifted_concepts( &self, ver_a: SvtVersionId, ver_b: SvtVersionId, threshold: f64, ) -> Result<Vec<(String, f64)>, SvtError>

Returns concepts whose drift between the two versions exceeds threshold, sorted by score descending.

Errors

Returns SvtError::VersionNotFound if either ID is unknown.

pub fn semantic_similarity_over_time( &self, concept: &str, ) -> Result<Vec<(SvtVersionId, SvtVersionId, f64)>, SvtError>

Computes pairwise cosine similarity (not distance) between consecutive version pairs that share an anchor for concept.

Pairs are ordered by (version_a_id, version_b_id) ascending. At most config.window_size pairs are returned.

Errors

• SvtError::InvalidConcept if concept is empty.
• SvtError::InsufficientAnchors if fewer than 2 versions have the anchor.

pub fn stability_score(&self, concept: &str) -> Result<f64, SvtError>

Computes a stability score in [0, 1] for a concept across all its consecutive version pairs.

stability = 1 – mean_drift where mean_drift is the mean cosine distance over all consecutive pairs. Returns 1.0 if fewer than 2 versions have the anchor (no drift measured).

Errors

• SvtError::InvalidConcept if concept is empty.

pub fn recommend_migration( &self, from: SvtVersionId, to: SvtVersionId, ) -> Result<Vec<String>, SvtError>

Returns a list of concept names that should be re-verified when migrating from from to to.

A concept is flagged for re-verification when its drift score between the two versions exceeds config.drift_threshold.

Errors

Returns SvtError::VersionNotFound if either ID is unknown.

pub fn tracker_stats(&self) -> SvtTrackerStats

Returns aggregate statistics for this tracker instance.

pub fn drift_log(&self) -> &VecDeque<SvtDriftEvent>

Returns a read-only slice of the drift log (oldest first).

pub fn clear_drift_log(&mut self)

Clears all recorded drift events.

pub fn config(&self) -> &SvtTrackerConfig

Returns the current tracker configuration.

pub fn config_mut(&mut self) -> &mut SvtTrackerConfig

Returns a mutable reference to the configuration.

pub fn add_anchors_batch( &mut self, items: impl IntoIterator<Item = (String, SvtVersionId, Vec<f64>)>, ) -> Vec<SvtError>

Registers multiple anchors at once.

Returns a Vec of errors (one per failed anchor); successful insertions are committed even if some fail.

pub fn compute_all_consecutive_drifts( &mut self, ) -> Vec<Result<SvtDriftReport, SvtError>>

Computes drift reports for all consecutive active-version pairs, returning (report_or_error) for each pair.

Pairs are ordered by ascending version IDs.

pub fn global_stability(&self) -> f64

Returns the mean stability score across all registered concepts.

Concepts with fewer than two version anchors contribute 1.0.

pub fn concepts_by_stability(&self) -> Vec<(String, f64)>

Returns all concepts sorted by stability score descending (most stable first).

Errors

This function only returns Err variants from internal calls; in practice they are suppressed and the concept is scored as 1.0.

pub fn top_drifted_concepts( &self, ver_a: SvtVersionId, ver_b: SvtVersionId, n: usize, ) -> Result<Vec<(String, f64)>, SvtError>

Returns the n most drifted concepts between two versions.

Errors

Returns SvtError::VersionNotFound if either ID is unknown.

pub fn are_compatible( &mut self, ver_a: SvtVersionId, ver_b: SvtVersionId, ) -> Result<bool, SvtError>

Returns true if the two versions are semantically compatible, i.e. their overall drift is strictly below drift_threshold.

Errors

Returns SvtError::VersionNotFound if either ID is unknown, or SvtError::InsufficientAnchors if not enough shared concepts exist.

pub fn remove_version_anchors( &mut self, version_id: SvtVersionId, ) -> Result<usize, SvtError>

Removes all anchors for a given version ID and decrements anchor_count.

Errors

Returns SvtError::VersionNotFound if the version is unknown.

pub fn concept_drift_matrix( &self, ver_a: SvtVersionId, ver_b: SvtVersionId, ) -> Result<HashMap<String, f64>, SvtError>

Computes per-concept drift scores between two versions for all shared concepts, without recording to the drift log.

Errors

Returns SvtError::VersionNotFound if either ID is unknown.

Trait Implementations

impl Debug for SemanticVersioningTracker

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.