Skip to main content

lattice_embed/
error.rs

1//! Errors returned by embedding, model configuration, and prepared SIMD-dispatch operations.
2//!
3//! See `docs/service.md` for error boundaries and caller recovery guidance.
4
5use thiserror::Error;
6
7/// **Stable**: external consumers may depend on this; breaking changes require a SemVer bump.
8///
9/// Errors that can occur during embedding operations.
10#[derive(Error, Debug)]
11#[non_exhaustive]
12pub enum EmbedError {
13    /// Model not loaded (needs initialization).
14    #[error("model not loaded: {0}")]
15    ModelNotLoaded(String),
16
17    /// Wrong model loaded (concurrent model switch in progress).
18    ///
19    /// This can happen when multiple tasks request different models concurrently.
20    /// The caller should retry with backoff.
21    #[error("wrong model loaded: expected {expected}, got {actual}")]
22    WrongModelLoaded {
23        /// Model that was expected.
24        expected: String,
25        /// Model that was actually loaded.
26        actual: String,
27    },
28
29    /// Model initialization failed.
30    #[error("model initialization failed: {0}")]
31    ModelInitialization(String),
32
33    /// Embedding inference failed.
34    #[error("embedding inference failed: {0}")]
35    InferenceFailed(String),
36
37    /// Blocking task failed (panic or cancellation).
38    ///
39    /// The model cache may be lost; next call will reinitialize.
40    #[error("task execution failed: {0}")]
41    TaskFailed(String),
42
43    /// Invalid input provided.
44    #[error("invalid input: {0}")]
45    InvalidInput(String),
46
47    /// Input text exceeds maximum allowed length.
48    #[error("text too long: {length} bytes exceeds maximum {max} bytes")]
49    TextTooLong {
50        /// Actual length in UTF-8 bytes.
51        length: usize,
52        /// Maximum allowed length in UTF-8 bytes.
53        max: usize,
54    },
55
56    /// Dimension mismatch between expected and actual.
57    #[error("dimension mismatch: expected {expected}, got {actual}")]
58    DimensionMismatch {
59        /// Expected dimension.
60        expected: usize,
61        /// Actual dimension.
62        actual: usize,
63    },
64
65    /// Model not supported by this service.
66    #[error("model not supported: {0}")]
67    UnsupportedModel(String),
68
69    /// Operation not implemented by this service.
70    ///
71    /// Returned by the default bodies of trait methods that an implementation has not
72    /// overridden. The message names the service and the operation.
73    #[error("operation not supported: {0}")]
74    Unsupported(String),
75
76    /// Internal logic error (count mismatch, unexpected state).
77    #[error("internal error: {0}")]
78    Internal(String),
79
80    /// A prepared SIMD operation received data at a different quantization tier.
81    /// See [`docs/design.md`](../docs/design.md#prepared-dispatch-errors) for recovery and failure semantics.
82    #[error("tier mismatch in {op}: expected {expected:?}, got {actual:?}")]
83    TierMismatch {
84        /// Name of the operation where the mismatch was detected.
85        op: &'static str,
86        /// Tier the operation required.
87        expected: crate::simd::QuantizationTier,
88        /// Tier actually supplied.
89        actual: crate::simd::QuantizationTier,
90    },
91}
92
93impl From<crate::simd::SimdError> for EmbedError {
94    fn from(err: crate::simd::SimdError) -> Self {
95        match err {
96            crate::simd::SimdError::TierMismatch {
97                op,
98                expected,
99                actual,
100            } => Self::TierMismatch {
101                op,
102                expected,
103                actual,
104            },
105            crate::simd::SimdError::Internal(msg) => Self::Internal(msg),
106            other => Self::Internal(other.to_string()),
107        }
108    }
109}
110
111/// **Stable**: result type alias for embedding operations.
112pub type Result<T> = std::result::Result<T, EmbedError>;
113
114#[cfg(test)]
115mod tests {
116    use super::*;
117
118    #[test]
119    fn simd_error_converts_to_the_matching_embed_variant() {
120        use crate::simd::{QuantizationTier, SimdError};
121
122        let err: EmbedError = SimdError::TierMismatch {
123            op: "probe",
124            expected: QuantizationTier::Int8,
125            actual: QuantizationTier::Int4,
126        }
127        .into();
128        assert!(matches!(
129            err,
130            EmbedError::TierMismatch {
131                op: "probe",
132                expected: QuantizationTier::Int8,
133                actual: QuantizationTier::Int4,
134            }
135        ));
136
137        let err: EmbedError = SimdError::Internal("count".into()).into();
138        assert!(matches!(err, EmbedError::Internal(ref msg) if msg == "count"));
139    }
140
141    #[test]
142    fn test_error_display() {
143        let err = EmbedError::DimensionMismatch {
144            expected: 384,
145            actual: 768,
146        };
147        assert_eq!(err.to_string(), "dimension mismatch: expected 384, got 768");
148    }
149
150    #[test]
151    fn test_error_variants() {
152        let err = EmbedError::ModelNotLoaded("test".into());
153        assert_eq!(err.to_string(), "model not loaded: test");
154
155        let err = EmbedError::WrongModelLoaded {
156            expected: "small".into(),
157            actual: "large".into(),
158        };
159        assert!(err.to_string().contains("expected small"));
160
161        let err = EmbedError::ModelInitialization("failed".into());
162        assert!(err.to_string().contains("initialization"));
163
164        let err = EmbedError::InferenceFailed("oom".into());
165        assert!(err.to_string().contains("inference"));
166
167        let err = EmbedError::TaskFailed("panic".into());
168        assert!(err.to_string().contains("task"));
169
170        let err = EmbedError::InvalidInput("empty".into());
171        assert!(err.to_string().contains("invalid input"));
172
173        let err = EmbedError::UnsupportedModel("gpt4".into());
174        assert!(err.to_string().contains("not supported"));
175
176        let err = EmbedError::Unsupported("probe does not implement count_tokens".into());
177        assert_eq!(
178            err.to_string(),
179            "operation not supported: probe does not implement count_tokens"
180        );
181
182        let err = EmbedError::Internal("bug".into());
183        assert!(err.to_string().contains("internal"));
184
185        let err = EmbedError::TextTooLong {
186            length: 50000,
187            max: 32768,
188        };
189        assert!(err.to_string().contains("50000"));
190        assert!(err.to_string().contains("32768"));
191    }
192}