nabled-embeddings 0.0.11

Lightweight ndarray-native compute and rerank layer for embedding vectors
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149

//! Error taxonomy for embedding retrieval compute.

use nabled_core::errors::{IntoNabledError, NabledError, ShapeError};
use nabled_linalg::matrix::MatrixError;
use nabled_linalg::vector::VectorError;
use nabled_ml::pca::PCAError;
use thiserror::Error;

/// Errors produced by `nabled-embeddings` retrieval compute.
#[derive(Debug, Clone, PartialEq, Eq, Error)]
pub enum EmbeddingError {
    /// Input matrix or vector is empty.
    #[error("input cannot be empty")]
    EmptyInput,
    /// Query and corpus feature dimensions are incompatible, or an output buffer is mis-sized.
    #[error("input dimensions are incompatible")]
    DimensionMismatch,
    /// A metric that requires non-zero norms encountered a zero-norm row.
    #[error("operation is undefined for zero-norm vectors")]
    ZeroNorm,
    /// Caller-provided argument is invalid (for example a non-positive component count).
    #[error("invalid input: {0}")]
    InvalidInput(String),
    /// The underlying matrix decomposition failed to converge.
    #[error("decomposition failed")]
    DecompositionFailed,
}

impl From<VectorError> for EmbeddingError {
    fn from(value: VectorError) -> Self {
        match value {
            VectorError::EmptyInput => EmbeddingError::EmptyInput,
            VectorError::DimensionMismatch => EmbeddingError::DimensionMismatch,
            VectorError::ZeroNorm => EmbeddingError::ZeroNorm,
        }
    }
}

impl From<MatrixError> for EmbeddingError {
    fn from(value: MatrixError) -> Self {
        match value {
            MatrixError::EmptyInput => EmbeddingError::EmptyInput,
            MatrixError::DimensionMismatch => EmbeddingError::DimensionMismatch,
        }
    }
}

impl From<PCAError> for EmbeddingError {
    fn from(value: PCAError) -> Self {
        match value {
            PCAError::EmptyMatrix => EmbeddingError::EmptyInput,
            PCAError::InvalidInput(message) => EmbeddingError::InvalidInput(message),
            PCAError::DecompositionFailed => EmbeddingError::DecompositionFailed,
        }
    }
}

impl IntoNabledError for EmbeddingError {
    fn into_nabled_error(self) -> NabledError {
        match self {
            EmbeddingError::EmptyInput => NabledError::Shape(ShapeError::EmptyInput),
            EmbeddingError::DimensionMismatch => NabledError::Shape(ShapeError::DimensionMismatch),
            EmbeddingError::ZeroNorm => NabledError::InvalidInput(
                "operation is undefined for zero-norm vectors".to_string(),
            ),
            EmbeddingError::InvalidInput(message) => NabledError::InvalidInput(message),
            EmbeddingError::DecompositionFailed => NabledError::ConvergenceFailed,
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn vector_error_maps_to_embedding_error() {
        assert_eq!(EmbeddingError::from(VectorError::EmptyInput), EmbeddingError::EmptyInput);
        assert_eq!(
            EmbeddingError::from(VectorError::DimensionMismatch),
            EmbeddingError::DimensionMismatch
        );
        assert_eq!(EmbeddingError::from(VectorError::ZeroNorm), EmbeddingError::ZeroNorm);
    }

    #[test]
    fn matrix_error_maps_to_embedding_error() {
        assert_eq!(EmbeddingError::from(MatrixError::EmptyInput), EmbeddingError::EmptyInput);
        assert_eq!(
            EmbeddingError::from(MatrixError::DimensionMismatch),
            EmbeddingError::DimensionMismatch
        );
    }

    #[test]
    fn pca_error_maps_to_embedding_error() {
        assert_eq!(EmbeddingError::from(PCAError::EmptyMatrix), EmbeddingError::EmptyInput);
        assert_eq!(
            EmbeddingError::from(PCAError::InvalidInput("x".to_string())),
            EmbeddingError::InvalidInput("x".to_string())
        );
        assert_eq!(
            EmbeddingError::from(PCAError::DecompositionFailed),
            EmbeddingError::DecompositionFailed
        );
    }

    #[test]
    fn embedding_error_maps_to_shared_taxonomy() {
        assert!(matches!(
            EmbeddingError::EmptyInput.into_nabled_error(),
            NabledError::Shape(ShapeError::EmptyInput)
        ));
        assert!(matches!(
            EmbeddingError::DimensionMismatch.into_nabled_error(),
            NabledError::Shape(ShapeError::DimensionMismatch)
        ));
        assert!(matches!(
            EmbeddingError::ZeroNorm.into_nabled_error(),
            NabledError::InvalidInput(_)
        ));
        assert!(matches!(
            EmbeddingError::InvalidInput("x".to_string()).into_nabled_error(),
            NabledError::InvalidInput(_)
        ));
        assert!(matches!(
            EmbeddingError::DecompositionFailed.into_nabled_error(),
            NabledError::ConvergenceFailed
        ));
    }

    #[test]
    fn embedding_error_displays_messages() {
        assert_eq!(EmbeddingError::EmptyInput.to_string(), "input cannot be empty");
        assert_eq!(
            EmbeddingError::DimensionMismatch.to_string(),
            "input dimensions are incompatible"
        );
        assert_eq!(
            EmbeddingError::ZeroNorm.to_string(),
            "operation is undefined for zero-norm vectors"
        );
        assert_eq!(
            EmbeddingError::InvalidInput("oops".to_string()).to_string(),
            "invalid input: oops"
        );
        assert_eq!(EmbeddingError::DecompositionFailed.to_string(), "decomposition failed");
    }
}