ferrolearn_core/
lib.rs

1//! # ferrolearn-core
2//!
3//! Core traits, error types, dataset abstractions, and pipeline infrastructure
4//! for the ferrolearn machine learning framework.
5//!
6//! This crate defines the foundational abstractions that all other ferrolearn
7//! crates depend on:
8//!
9//! - **[`Fit`]**, **[`Predict`]**, **[`Transform`]**, **[`FitTransform`]** --
10//!   the core ML traits with compile-time enforcement that `predict()` cannot
11//!   be called on an unfitted model.
12//! - **[`FerroError`]** -- the unified error type with rich diagnostic context.
13//! - **[`Dataset`]** -- a trait for querying tabular data shape, with
14//!   implementations for `ndarray::Array2<f32>` and `ndarray::Array2<f64>`.
15//! - **[`pipeline::Pipeline`]** -- a dynamic-dispatch pipeline that composes
16//!   transformers and a final estimator (requires `std` feature).
17//! - **Introspection traits** -- [`HasCoefficients`], [`HasFeatureImportances`],
18//!   [`HasClasses`] for inspecting fitted model internals.
19//!
20//! # Features
21//!
22//! - `std` (default) -- Enables `std`-dependent functionality (I/O errors,
23//!   pipelines, `std::error::Error` impls).
24//! - `faer` (default) -- Enables the [`NdarrayFaerBackend`] using the `faer`
25//!   crate for pure-Rust linear algebra.
26//! - `blas` -- Enables the [`BLASBackend`](backend_blas::BLASBackend) using
27//!   system BLAS/LAPACK via `ndarray-linalg`.
28//!
29//! # Design Principles
30//!
31//! ## Compile-Time Safety (AC-3)
32//!
33//! The unfitted configuration struct (e.g., `LinearRegression`) implements
34//! [`Fit`] but **not** [`Predict`]. Calling `fit()` returns a *new fitted
35//! type* (e.g., `FittedLinearRegression`) that implements [`Predict`].
36//! Attempting to call `predict()` on an unfitted model is a compile error.
37//!
38//! ## Float Generics (REQ-15)
39//!
40//! All algorithms are generic over `F: num_traits::Float + Send + Sync + 'static`.
41//!
42//! ## Error Handling
43//!
44//! All public functions return `Result<T, FerroError>`. Library code never panics.
45//!
46//! ## Pluggable Backends (REQ-19)
47//!
48//! The [`Backend`] trait abstracts linear algebra operations (SVD, QR, Cholesky,
49//! etc.), allowing algorithms to be generic over the backend implementation.
50//! The default backend [`NdarrayFaerBackend`] delegates to the `faer` crate.
51
52#![cfg_attr(not(feature = "std"), no_std)]
53
54#[cfg(not(feature = "std"))]
55extern crate alloc;
56
57pub mod backend;
58#[cfg(feature = "blas")]
59pub mod backend_blas;
60#[cfg(feature = "faer")]
61pub mod backend_faer;
62pub mod dataset;
63pub mod error;
64pub mod introspection;
65#[cfg(feature = "std")]
66pub mod pipeline;
67pub mod streaming;
68pub mod traits;
69#[cfg(feature = "std")]
70pub mod typed_pipeline;
71
72// Re-export the most commonly used items at the crate root.
73pub use backend::Backend;
74#[cfg(feature = "blas")]
75pub use backend_blas::BLASBackend;
76#[cfg(feature = "faer")]
77pub use backend_faer::NdarrayFaerBackend;
78pub use dataset::Dataset;
79pub use error::{FerroError, FerroResult};
80pub use introspection::{HasClasses, HasCoefficients, HasFeatureImportances};
81pub use streaming::StreamingFitter;
82pub use traits::{Fit, FitTransform, PartialFit, Predict, Transform};
83
84/// The default linear algebra backend.
85///
86/// Algorithms generic over [`Backend`] can use `DefaultBackend` as a sensible
87/// default that delegates to the `faer` crate for high-performance pure-Rust
88/// implementations of SVD, QR, Cholesky, and other decompositions.
89#[cfg(feature = "faer")]
90pub type DefaultBackend = NdarrayFaerBackend;
ferrolearn_core/lib.rs

ferrolearn_core/
lib.rs
