irithyll_core/lib.rs
1//! Core types and inference engine for irithyll streaming ML models.
2//!
3//! `irithyll-core` provides loss functions, observation traits, a compact binary
4//! format, and branch-free traversal for deploying trained SGBT models on
5//! embedded targets (Cortex-M0+, 32KB flash).
6//!
7//! # Features
8//!
9//! - **Loss functions** — squared, logistic, Huber, softmax, expectile, quantile
10//! - **Observation trait** — zero-copy training interface with `SampleRef`
11//! - **12-byte packed nodes** — 5 nodes per 64-byte cache line
12//! - **Zero-copy `EnsembleView`** — constructed from `&[u8]`, no allocation after validation
13//! - **Branch-free traversal** — `cmov`/`csel` child selection, no pipeline stalls
14//! - **`#![no_std]`** — zero mandatory dependencies, runs on bare metal
15//!
16//! # Usage
17//!
18//! ```ignore
19//! use irithyll_core::{EnsembleView, FormatError};
20//!
21//! // Load packed binary (e.g. from flash, file, or network)
22//! let packed_bytes: &[u8] = &[/* exported via irithyll::export_embedded() */];
23//! let view = EnsembleView::from_bytes(packed_bytes)?;
24//! let prediction = view.predict(&[1.0f32, 2.0, 3.0]);
25//! ```
26
27#![no_std]
28#![deny(unsafe_op_in_unsafe_fn)]
29#![cfg_attr(docsrs, feature(doc_cfg))]
30
31#[cfg(feature = "alloc")]
32extern crate alloc;
33
34#[cfg(feature = "std")]
35extern crate std;
36
37#[cfg(all(test, not(feature = "alloc")))]
38extern crate alloc;
39
40pub mod drift;
41pub mod error;
42pub mod loss;
43pub mod math;
44pub mod packed;
45pub mod packed_i16;
46pub mod quantize;
47pub mod sample;
48pub mod traverse;
49pub mod traverse_i16;
50pub mod view;
51pub mod view_i16;
52
53// Convenience re-exports -- inference
54pub use error::FormatError;
55pub use packed::{EnsembleHeader, PackedNode, TreeEntry};
56pub use packed_i16::{PackedNodeI16, QuantizedEnsembleHeader};
57pub use view::EnsembleView;
58pub use view_i16::QuantizedEnsembleView;
59
60// Convenience re-exports -- training core types
61pub use loss::{Loss, LossType};
62pub use sample::{Observation, SampleRef};
63
64// Convenience re-exports -- drift detection
65pub use drift::DriftSignal;
66#[cfg(feature = "alloc")]
67pub use drift::{DriftDetector, DriftDetectorState};
68
69// Convenience re-exports -- config/error (requires alloc)
70#[cfg(feature = "alloc")]
71pub use error::{ConfigError, IrithyllError, Result};