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
use thiserror::Error;
use crate::DocumentId;
/// Failure at a provider-neutral embedding or retrieval boundary.
#[derive(Clone, Debug, Eq, Error, PartialEq)]
#[non_exhaustive]
pub enum RetrievalError {
/// A document identity was empty.
#[error("document id cannot be empty")]
EmptyDocumentId,
/// A document contained no usable text.
#[error("document `{id}` cannot have empty text")]
EmptyDocumentText {
/// Invalid document identity.
id: DocumentId,
},
/// A query contained no usable text.
#[error("retrieval query cannot be empty")]
EmptyQuery,
/// A query requested no results.
#[error("retrieval limit must be greater than zero")]
ZeroLimit,
/// An embedding contained no dimensions.
#[error("embedding cannot be empty")]
EmptyEmbedding,
/// An embedding contained a non-finite coordinate.
#[error("embedding coordinate {index} must be finite")]
NonFiniteEmbedding {
/// Zero-based invalid coordinate.
index: usize,
},
/// An embedding coordinate exceeded a backend numeric representation.
#[error("embedding coordinate {index} is outside the backend numeric range")]
EmbeddingCoordinateOutOfRange {
/// Zero-based invalid coordinate.
index: usize,
},
/// Cosine similarity is undefined for a zero vector.
#[error("embedding must have a non-zero norm")]
ZeroNormEmbedding,
/// Embeddings with different dimensions cannot share an index.
#[error("embedding dimension mismatch: expected {expected}, received {actual}")]
DimensionMismatch {
/// Index or batch dimension.
expected: usize,
/// Received dimension.
actual: usize,
},
/// A provider returned a different number of vectors than inputs.
#[error("embedding count mismatch: expected {expected}, received {actual}")]
EmbeddingCountMismatch {
/// Input count.
expected: usize,
/// Returned vector count.
actual: usize,
},
/// One item in an embedding request was blank.
#[error("embedding input {index} cannot be empty")]
EmptyEmbeddingInput {
/// Zero-based invalid input index.
index: usize,
},
/// A document identity appeared more than once.
#[error("duplicate document id `{0}`")]
DuplicateDocument(DocumentId),
/// A run did not grant the retriever capability.
#[error("retriever capability `{name}` is not granted")]
CapabilityDenied {
/// Retriever name.
name: String,
},
/// The owning run was cancelled.
#[error("retrieval was cancelled")]
Cancelled,
/// The owning run deadline elapsed.
#[error("retrieval deadline exceeded")]
DeadlineExceeded,
/// An embedding provider or retrieval backend failed.
#[error("retrieval provider failed: {message}")]
Provider {
/// Safe provider diagnostic.
message: String,
},
/// Retrieval usage counters could not be combined without overflow.
#[error("retrieval usage counter overflow")]
UsageOverflow,
}
impl RetrievalError {
/// Creates a provider/backend failure without imposing an adapter error
/// representation.
pub fn provider(message: impl Into<String>) -> Self {
Self::Provider {
message: message.into(),
}
}
}