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.
17//! - **Introspection traits** — [`HasCoefficients`], [`HasFeatureImportances`],
18//! [`HasClasses`] for inspecting fitted model internals.
19//!
20//! # Design Principles
21//!
22//! ## Compile-Time Safety (AC-3)
23//!
24//! The unfitted configuration struct (e.g., `LinearRegression`) implements
25//! [`Fit`] but **not** [`Predict`]. Calling `fit()` returns a *new fitted
26//! type* (e.g., `FittedLinearRegression`) that implements [`Predict`].
27//! Attempting to call `predict()` on an unfitted model is a compile error.
28//!
29//! ## Float Generics (REQ-15)
30//!
31//! All algorithms are generic over `F: num_traits::Float + Send + Sync + 'static`.
32//!
33//! ## Error Handling
34//!
35//! All public functions return `Result<T, FerroError>`. Library code never panics.
36//!
37//! ## Pluggable Backends (REQ-19)
38//!
39//! The [`Backend`] trait abstracts linear algebra operations (SVD, QR, Cholesky,
40//! etc.), allowing algorithms to be generic over the backend implementation.
41//! The default backend [`NdarrayFaerBackend`] delegates to the `faer` crate.
42
43pub mod backend;
44pub mod backend_faer;
45pub mod dataset;
46pub mod error;
47pub mod introspection;
48pub mod pipeline;
49pub mod traits;
50pub mod typed_pipeline;
51
52// Re-export the most commonly used items at the crate root.
53pub use backend::Backend;
54pub use backend_faer::NdarrayFaerBackend;
55pub use dataset::Dataset;
56pub use error::{FerroError, FerroResult};
57pub use introspection::{HasClasses, HasCoefficients, HasFeatureImportances};
58pub use traits::{Fit, FitTransform, PartialFit, Predict, Transform};
59
60/// The default linear algebra backend.
61///
62/// Algorithms generic over [`Backend`] can use `DefaultBackend` as a sensible
63/// default that delegates to the `faer` crate for high-performance pure-Rust
64/// implementations of SVD, QR, Cholesky, and other decompositions.
65pub type DefaultBackend = NdarrayFaerBackend;