fornix 0.4.0

Knowledge storage, retrieval, and graph infrastructure for cognitive systems
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

//! Error types for the vector layer.

use thiserror::Error;

/// Errors produced by vector storage adapters.
#[derive(Debug, Error)]
pub enum Error {
    /// The provided configuration is invalid.
    #[error("configuration error: {0}")]
    Configuration(String),

    /// A connection to the backend could not be established or was lost.
    #[error("connection error: {0}")]
    Connection(String),

    /// The adapter is not connected. Call `connect()` first.
    #[error("vector adapter is not connected")]
    NotConnected,

    /// A read or write operation failed.
    #[error("operation failed: {0}")]
    Operation(String),

    /// The requested record or namespace was not found.
    #[error("not found: {0}")]
    NotFound(String),

    /// The namespace does not exist or has not been initialised.
    #[error("namespace not found: {0}")]
    NamespaceNotFound(String),

    /// Vector dimension mismatch between a stored record and a query.
    #[error("dimension mismatch: expected {expected}, got {actual}")]
    DimensionMismatch { expected: usize, actual: usize },

    /// A required external dependency is missing.
    #[error("missing dependency: {0}")]
    MissingDependency(String),

    /// An error propagated from an underlying driver layer.
    #[error("backend error: {0}")]
    Backend(String),

    /// An unexpected error.
    #[error(transparent)]
    Other(#[from] Box<dyn std::error::Error + Send + Sync>),
}

impl Error {
    pub fn config(msg: impl Into<String>) -> Self {
        Self::Configuration(msg.into())
    }

    pub fn connection(msg: impl Into<String>) -> Self {
        Self::Connection(msg.into())
    }

    pub fn operation(msg: impl Into<String>) -> Self {
        Self::Operation(msg.into())
    }

    pub fn backend(msg: impl Into<String>) -> Self {
        Self::Backend(msg.into())
    }

    pub fn dimension_mismatch(expected: usize, actual: usize) -> Self {
        Self::DimensionMismatch { expected, actual }
    }
}

/// Shorthand result type for vector operations.
pub type Result<T> = std::result::Result<T, Error>;

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

    #[test]
    fn configuration_error_message() {
        let e = Error::config("dimension is required");
        assert_eq!(e.to_string(), "configuration error: dimension is required");
    }

    #[test]
    fn connection_error_message() {
        let e = Error::connection("refused");
        assert_eq!(e.to_string(), "connection error: refused");
    }

    #[test]
    fn not_connected_message() {
        assert_eq!(Error::NotConnected.to_string(), "vector adapter is not connected");
    }

    #[test]
    fn operation_error_message() {
        let e = Error::operation("upsert failed");
        assert_eq!(e.to_string(), "operation failed: upsert failed");
    }

    #[test]
    fn not_found_message() {
        let e = Error::NotFound("rec-1".to_string());
        assert_eq!(e.to_string(), "not found: rec-1");
    }

    #[test]
    fn namespace_not_found_message() {
        let e = Error::NamespaceNotFound("docs".to_string());
        assert_eq!(e.to_string(), "namespace not found: docs");
    }

    #[test]
    fn dimension_mismatch_message() {
        let e = Error::dimension_mismatch(384, 512);
        assert_eq!(e.to_string(), "dimension mismatch: expected 384, got 512");
    }

    #[test]
    fn missing_dependency_message() {
        let e = Error::MissingDependency("pgvector extension".to_string());
        assert_eq!(e.to_string(), "missing dependency: pgvector extension");
    }

    #[test]
    fn backend_error_message() {
        let e = Error::backend("driver error");
        assert_eq!(e.to_string(), "backend error: driver error");
    }

    #[test]
    fn result_ok() {
        let r: Result<i32> = Ok(42);
        assert!(matches!(r, Ok(42)));
    }

    #[test]
    fn result_err() {
        let r: Result<i32> = Err(Error::NotConnected);
        assert!(r.is_err());
    }
}