runifold_retrieval/
error.rs

1use thiserror::Error;
2
3use crate::DocumentId;
4
5/// Failure at a provider-neutral embedding or retrieval boundary.
6#[derive(Clone, Debug, Eq, Error, PartialEq)]
7#[non_exhaustive]
8pub enum RetrievalError {
9    /// A document identity was empty.
10    #[error("document id cannot be empty")]
11    EmptyDocumentId,
12    /// A document contained no usable text.
13    #[error("document `{id}` cannot have empty text")]
14    EmptyDocumentText {
15        /// Invalid document identity.
16        id: DocumentId,
17    },
18    /// A query contained no usable text.
19    #[error("retrieval query cannot be empty")]
20    EmptyQuery,
21    /// A query requested no results.
22    #[error("retrieval limit must be greater than zero")]
23    ZeroLimit,
24    /// An embedding contained no dimensions.
25    #[error("embedding cannot be empty")]
26    EmptyEmbedding,
27    /// An embedding contained a non-finite coordinate.
28    #[error("embedding coordinate {index} must be finite")]
29    NonFiniteEmbedding {
30        /// Zero-based invalid coordinate.
31        index: usize,
32    },
33    /// An embedding coordinate exceeded a backend numeric representation.
34    #[error("embedding coordinate {index} is outside the backend numeric range")]
35    EmbeddingCoordinateOutOfRange {
36        /// Zero-based invalid coordinate.
37        index: usize,
38    },
39    /// Cosine similarity is undefined for a zero vector.
40    #[error("embedding must have a non-zero norm")]
41    ZeroNormEmbedding,
42    /// Embeddings with different dimensions cannot share an index.
43    #[error("embedding dimension mismatch: expected {expected}, received {actual}")]
44    DimensionMismatch {
45        /// Index or batch dimension.
46        expected: usize,
47        /// Received dimension.
48        actual: usize,
49    },
50    /// A provider returned a different number of vectors than inputs.
51    #[error("embedding count mismatch: expected {expected}, received {actual}")]
52    EmbeddingCountMismatch {
53        /// Input count.
54        expected: usize,
55        /// Returned vector count.
56        actual: usize,
57    },
58    /// One item in an embedding request was blank.
59    #[error("embedding input {index} cannot be empty")]
60    EmptyEmbeddingInput {
61        /// Zero-based invalid input index.
62        index: usize,
63    },
64    /// A document identity appeared more than once.
65    #[error("duplicate document id `{0}`")]
66    DuplicateDocument(DocumentId),
67    /// A reranker candidate multiplier was zero or overflowed the query limit.
68    #[error("reranker candidate multiplier must produce between 1 and 1000 candidates")]
69    InvalidRerankCandidateLimit,
70    /// A reranker returned invalid, duplicate, or foreign documents.
71    #[error("reranker returned an invalid result: {message}")]
72    InvalidRerankOutput {
73        /// Safe validation diagnostic.
74        message: String,
75    },
76    /// Hybrid retrieval configuration cannot produce a stable bounded fusion.
77    #[error("hybrid retrieval weights and rank constant must be finite and positive")]
78    InvalidHybridConfiguration,
79    /// A hybrid retriever returned duplicate documents within one source.
80    #[error("hybrid source returned duplicate document id `{0}`")]
81    DuplicateHybridResult(DocumentId),
82    /// A run did not grant the retriever capability.
83    #[error("retriever capability `{name}` is not granted")]
84    CapabilityDenied {
85        /// Retriever name.
86        name: String,
87    },
88    /// The owning run was cancelled.
89    #[error("retrieval was cancelled")]
90    Cancelled,
91    /// The owning run deadline elapsed.
92    #[error("retrieval deadline exceeded")]
93    DeadlineExceeded,
94    /// An embedding provider or retrieval backend failed.
95    #[error("retrieval provider failed: {message}")]
96    Provider {
97        /// Safe provider diagnostic.
98        message: String,
99    },
100    /// Retrieval usage counters could not be combined without overflow.
101    #[error("retrieval usage counter overflow")]
102    UsageOverflow,
103}
104
105impl RetrievalError {
106    /// Creates a provider/backend failure without imposing an adapter error
107    /// representation.
108    pub fn provider(message: impl Into<String>) -> Self {
109        Self::Provider {
110            message: message.into(),
111        }
112    }
113}
runifold_retrieval/error.rs

runifold_retrieval/
error.rs
