Struct EmbeddingFinetuner 

pub struct EmbeddingFinetuner {
    pub config: FinetunerConfig,
    pub layer: ProjectionLayer,
    pub training_history: Vec<TrainingStats>,
    pub total_pairs_seen: u64,
    pub rng_state: u64,
}

Contrastive embedding fine-tuner using triplet loss.

Example

use ipfrs_semantic::embedding_finetuner::{
    EmbeddingFinetuner, FinetunerConfig, TrainingPair,
};

let config = FinetunerConfig::new(4, 4);
let mut finetuner = EmbeddingFinetuner::new(config);

let pairs = vec![
    TrainingPair::new(vec![1.0, 0.0, 0.0, 0.0],
                      vec![0.9, 0.1, 0.0, 0.0],
                      vec![0.0, 0.0, 1.0, 0.0]),
];
let history = finetuner.train(&pairs);
assert!(!history.is_empty());

Fields

config: FinetunerConfig

Hyper-parameters.

layer: ProjectionLayer

Linear projection layer.

training_history: Vec<TrainingStats>

Epoch-level statistics accumulated across all train calls.

total_pairs_seen: u64

Running count of training pairs consumed.

rng_state: u64

Internal xorshift64 PRNG state.

Implementations

impl EmbeddingFinetuner

pub fn new(config: FinetunerConfig) -> Self

Construct a new fine-tuner, initialising weights with Xavier uniform.

pub fn project(&self, embedding: &[f64]) -> Result<Vec<f64>, FinetunerError>

Project a single embedding through the linear layer.

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

Squared L2 distance between two equal-length slices.

Panics in debug if lengths differ; silently stops at the shorter length in release (caller must ensure equal lengths).

pub fn train_step(&mut self, pairs: &[TrainingPair]) -> TrainingStats

Run a single mini-batch training step and return statistics.

For each pair in pairs:

1. Project anchor, positive, negative.
2. Compute triplet loss.
3. If loss > 0, compute simplified gradient and update weights.
4. Apply L2 regularisation: w ← w - l2_reg * w.

pub fn train(&mut self, pairs: &[TrainingPair]) -> Vec<TrainingStats>

Full training loop over max_epochs, processing batch_size pairs per step.

Pairs are shuffled at the start of each epoch using Fisher-Yates with the internal xorshift64 PRNG.

Returns the per-epoch TrainingStats (also appended to self.training_history).

pub fn encode_batch( &self, embeddings: &[Vec<f64>], ) -> Result<Vec<Vec<f64>>, FinetunerError>

Project a batch of embeddings.

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

Cosine similarity between the projected versions of a and b.

Falls back to the cosine of the raw vectors if projection fails.

pub fn evaluate_pairs(&self, pairs: &[TrainingPair]) -> (f64, f64)

Evaluate a set of triplets, returning (avg_loss, fraction_correct).

A triplet is “correct” when d(proj_a, proj_p) < d(proj_a, proj_n).

pub fn training_history(&self) -> &[TrainingStats]

Read-only view of accumulated per-epoch statistics.

Trait Implementations

impl Clone for EmbeddingFinetuner

fn clone(&self) -> EmbeddingFinetuner

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for EmbeddingFinetuner

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

Formats the value using the given formatter.