bosk 0.1.0

Pure-Rust LightGBM inference: parses the text model format directly — no FFI, zero deps. Optional ONNX Runtime and CatBoost backends behind the same small Model trait.
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

//! Error type for model loading and inference.

use std::fmt;

/// Convenience alias for results returned by this crate.
pub type Result<T> = std::result::Result<T, Error>;

/// Everything that can go wrong loading or evaluating a model.
///
/// Marked `#[non_exhaustive]`: matching on it must include a wildcard arm, so
/// new variants can be added in future releases without a breaking change.
#[derive(Debug)]
#[non_exhaustive]
pub enum Error {
    /// Reading the model file from disk failed.
    Io {
        /// The path that could not be read.
        path: std::path::PathBuf,
        /// The underlying I/O error.
        source: std::io::Error,
    },

    /// The model text could not be parsed. `line` is 1-based.
    Parse {
        /// 1-based line number the failure was found on.
        line: usize,
        /// Human-readable description of what could not be parsed.
        message: String,
    },

    /// The file parsed but contained no decision trees.
    EmptyModel,

    /// The model uses a capability this crate does not implement (e.g.
    /// multiclass output or linear trees). Refusing to load is deliberate:
    /// evaluating such a model with the supported subset would return silently
    /// wrong predictions.
    Unsupported {
        /// What the model needs that is not implemented.
        message: String,
    },

    /// The file extension is not loadable in this build. `supported` lists the
    /// extensions the current feature set can load.
    UnsupportedFormat {
        /// The extension that was requested (without the leading dot).
        ext: String,
        /// Extensions this build can load, in preferred order.
        supported: &'static [&'static str],
    },

    /// The feature vector passed to [`predict`](crate::Model::predict) has the
    /// wrong length for the model. Refusing to predict is deliberate: the
    /// model would silently treat the out-of-range features as missing and
    /// return a plausible but wrong prediction.
    FeatureCount {
        /// The number of features the model was trained on.
        expected: usize,
        /// The number of features that was passed in.
        got: usize,
    },

    /// The flat batch passed to [`predict_batch`](crate::Model::predict_batch)
    /// cannot be split into rows of `n_features`.
    BatchShape {
        /// Total length of the flat feature buffer.
        len: usize,
        /// The row width that was requested (`0` is always invalid).
        n_features: usize,
    },

    /// A native backend (ONNX Runtime or CatBoost) failed to load or predict.
    Backend {
        /// Which backend produced the error (`"onnx"` / `"catboost"`).
        backend: &'static str,
        /// The backend's own error message.
        message: String,
    },
}

impl fmt::Display for Error {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Error::Io { path, source } => {
                write!(f, "reading {}: {source}", path.display())
            }
            Error::Parse { line, message } => {
                write!(f, "parse error on line {line}: {message}")
            }
            Error::EmptyModel => write!(f, "no decision trees found in model file"),
            Error::Unsupported { message } => {
                write!(f, "unsupported model: {message}")
            }
            Error::FeatureCount { expected, got } => write!(
                f,
                "model expects {expected} features, got {got}"
            ),
            Error::BatchShape { len, n_features } => write!(
                f,
                "flat batch of length {len} cannot be split into rows of {n_features} features"
            ),
            Error::UnsupportedFormat { ext, supported } => write!(
                f,
                "unsupported model format '.{ext}' in this build (supported: {supported:?})"
            ),
            Error::Backend { backend, message } => write!(f, "{backend} backend: {message}"),
        }
    }
}

impl std::error::Error for Error {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            Error::Io { source, .. } => Some(source),
            _ => None,
        }
    }
}