Struct EmbeddingVector 

pub struct EmbeddingVector<State> { /* private fields */ }

An embedding vector tagged with a normalization-state marker.

The type parameter encodes whether the vector is L2-normalized:

• EmbeddingVector<Unnormalized> — raw model output; must be normalized before passing to cosine-distance Qdrant searches.
• EmbeddingVector<Normalized> — unit-length vector, safe to pass directly to Qdrant gRPC cosine queries.

Using Normalized as a required parameter type at the Qdrant search boundary turns dimension/normalization mismatches into compile-time errors rather than silent near-zero similarity scores (see bugs #3421, #3382, #3420, #3422).

Construction

use zeph_common::math::{EmbeddingVector, Normalized, Unnormalized};

// Wrap a raw model vector and normalize it.
let raw = EmbeddingVector::<Unnormalized>::new(vec![3.0_f32, 4.0]);
let normalized = raw.normalize();
let slice = normalized.as_slice();
// A normalized vector has unit L2 length.
let norm: f32 = slice.iter().map(|x| x * x).sum::<f32>().sqrt();
assert!((norm - 1.0).abs() < 1e-6);

// Trust-caller constructor for models that always return unit vectors.
let trusted = EmbeddingVector::<Normalized>::new_normalized(vec![0.6_f32, 0.8]);
assert_eq!(trusted.as_slice(), &[0.6_f32, 0.8]);

Implementations

impl EmbeddingVector<Unnormalized>

pub fn new(inner: Vec<f32>) -> Self

Wrap a raw embedding vector from a model or storage.

The returned vector is tagged Unnormalized. Call normalize before passing it to functions that require Normalized.

Examples

use zeph_common::math::{EmbeddingVector, Unnormalized};

let v = EmbeddingVector::<Unnormalized>::new(vec![1.0_f32, 0.0]);
assert_eq!(v.as_slice(), &[1.0_f32, 0.0]);

pub fn normalize(self) -> EmbeddingVector<Normalized>

L2-normalize this vector and return an EmbeddingVector<Normalized>.

If the vector is a zero vector (L2 norm is zero), all elements are set to zero to avoid division by zero; the result is technically invalid for cosine search but is safe and consistent with the behavior of cosine_similarity.

Examples

use zeph_common::math::{EmbeddingVector, Unnormalized};

let raw = EmbeddingVector::<Unnormalized>::new(vec![3.0_f32, 4.0]);
let norm = raw.normalize();
let sum_sq: f32 = norm.as_slice().iter().map(|x| x * x).sum();
assert!((sum_sq - 1.0).abs() < 1e-6, "must be unit length");

impl EmbeddingVector<Normalized>

pub fn new_normalized(inner: Vec<f32>) -> Self

Construct a normalized embedding vector, trusting the caller that inner is already L2-unit-length.

Use this constructor only when the source guarantees unit-length output (e.g., a model that always normalizes, or a vector loaded from a store known to hold normalized data). Incorrect use does not cause UB but will produce wrong cosine scores.

Examples

use zeph_common::math::{EmbeddingVector, Normalized};

// Suppose the model always returns unit vectors.
let v = EmbeddingVector::<Normalized>::new_normalized(vec![0.6_f32, 0.8]);
assert_eq!(v.as_slice(), &[0.6_f32, 0.8]);

impl<State> EmbeddingVector<State>

pub fn as_slice(&self) -> &[f32]

Return a borrowed slice of the vector elements.

Examples

use zeph_common::math::{EmbeddingVector, Unnormalized};

let v = EmbeddingVector::<Unnormalized>::new(vec![1.0_f32, 2.0]);
assert_eq!(v.as_slice(), &[1.0_f32, 2.0]);

pub fn into_inner(self) -> Vec<f32>

Consume the wrapper and return the underlying Vec<f32>.

Examples

use zeph_common::math::{EmbeddingVector, Unnormalized};

let v = EmbeddingVector::<Unnormalized>::new(vec![1.0_f32, 2.0]);
assert_eq!(v.into_inner(), vec![1.0_f32, 2.0]);

pub fn len(&self) -> usize

Return the number of dimensions in this vector.

Examples

use zeph_common::math::{EmbeddingVector, Unnormalized};

let v = EmbeddingVector::<Unnormalized>::new(vec![1.0_f32, 2.0, 3.0]);
assert_eq!(v.len(), 3);

pub fn is_empty(&self) -> bool

Returns true if the vector has no elements.

Examples

use zeph_common::math::{EmbeddingVector, Unnormalized};

let v = EmbeddingVector::<Unnormalized>::new(vec![]);
assert!(v.is_empty());

Trait Implementations

impl<State: Clone> Clone for EmbeddingVector<State>

fn clone(&self) -> EmbeddingVector<State>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<State: Debug> Debug for EmbeddingVector<State>

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

Formats the value using the given formatter.

impl From<Vec<f32>> for EmbeddingVector<Unnormalized>

fn from(v: Vec<f32>) -> Self

Converts to this type from the input type.