rustyml 0.12.0

//! # RustyML - A Machine Learning and Deep Learning Library in Pure Rust
//!
//! RustyML is a machine learning and deep learning library written entirely in Rust,
//! using Rust's memory safety, concurrency features, and zero-cost abstractions to provide
//! implementations of classical ML algorithms, neural networks, and data processing utilities
//!
//! ## Overview
//!
//! This crate covers machine learning tasks from data preprocessing and feature engineering
//! to model training and evaluation. Implementations feature error handling, parallel processing,
//! and input validation
//!
//! ## Architecture
//!
//! The library is organized into 5 main modules, each gated by feature flags:
//!
//! ### [`machine_learning`]
//! Classical machine learning algorithms for supervised and unsupervised learning:
//! - **Regression**: Linear Regression with L1/L2 regularization
//! - **Classification**: Logistic Regression, KNN, Decision Tree, SVC, Linear SVC, LDA
//! - **Clustering**: KMeans, DBSCAN, MeanShift
//! - **Anomaly Detection**: Isolation Forest
//!
//! ### [`neural_network`]
//! Complete neural network framework with flexible architecture design:
//! - **Layers**: Dense, RNN, LSTM, Convolution, Pooling, Dropout
//! - **Optimizers**: SGD, Adam, AdamW, RMSProp, AdaGrad
//! - **Loss Functions**: MSE, MAE, Binary/Categorical Cross-Entropy
//! - **Models**: Sequential architecture for feed-forward networks
//!
//! ### [`utils`]
//! Data preprocessing and dimensionality reduction utilities:
//! - **Dimensionality Reduction**: PCA, Kernel PCA, t-SNE
//! - **Preprocessing**: Standardization, train-test splitting
//! - **Kernel Functions**: RBF, Linear, Polynomial, Sigmoid, Cosine
//!
//! ### [`metrics`]
//! Evaluation metrics for model performance assessment:
//! - **Regression**: MSE, RMSE, MAE, R^2 score
//! - **Classification**: Accuracy, Confusion Matrix, AUC-ROC, F1-score
//! - **Clustering**: Adjusted Rand Index, Normalized/Adjusted Mutual Information, Silhouette Score
//!
//! ### [`math`]
//! Mathematical utilities and statistical functions:
//! - **Distance Metrics**: Euclidean, Manhattan, Minkowski
//! - **Impurity Measures**: Entropy, Gini, Information Gain
//! - **Statistical Functions**: Variance, standard deviation, SST, SSE
//! - **Activation Functions**: Sigmoid, logistic loss
//!
//! ## Quick Start
//!
//! ### Machine Learning Example
//!
//! Add RustyML to your `Cargo.toml`:
//! ```toml
//! [dependencies]
//! rustyml = { version = "*", features = ["machine_learning"] }
//! # Or use features = ["full"] to enable all modules
//! # Or use `features = ["default"]` to enable default modules (`machine_learning` and `neural_network`)
//! # Add `"show_progress"` in `features` to show progress bars when training
//! ```
//!
//! In your Rust code, write:
//! ```ignored
//! use rustyml::machine_learning::LinearRegression;
//! use ndarray::{Array1, Array2};
//!
//! // Create a linear regression model
//! let mut model = LinearRegression::new(true, 0.01, 1000, 1e-6).unwrap();
//!
//! // Prepare training data
//! let raw_x = vec![vec![1.0, 2.0], vec![2.0, 3.0], vec![3.0, 4.0]];
//! let raw_y = vec![6.0, 9.0, 12.0];
//!
//! // Convert Vec to ndarray types
//! let x = Array2::from_shape_vec((3, 2), raw_x.into_iter().flatten().collect()).unwrap();
//! let y = Array1::from_vec(raw_y);
//!
//! // Train the model
//! model.fit(&x.view(), &y.view()).unwrap();
//!
//! // Make predictions
//! let new_data = Array2::from_shape_vec((1, 2), vec![4.0, 5.0]).unwrap();
//! let _predictions = model.predict(&new_data.view());
//!
//! // Save the trained model to a file
//! model.save_to_path("linear_regression_model.json").unwrap();
//!
//! // Load the model from the file
//! let loaded_model = LinearRegression::load_from_path("linear_regression_model.json").unwrap();
//!
//! // Use the loaded model for predictions
//! let _loaded_predictions = loaded_model.predict(&new_data.view());
//!
//! // Clone is implemented
//! let _model_copy = model.clone();
//!
//! // Debug is implemented
//! println!("{:?}", model);
//! ```
//!
//! ## Neural Network Example
//!
//! Add RustyML to your `Cargo.toml`:
//! ```toml
//! [dependencies]
//! rustyml = { version = "*", features = ["neural_network"] }
//! # Or use `features = ["full"]` to enable all modules
//! # Or use `features = ["default"]` to enable default modules (`machine_learning` and `neural_network`)
//! # Add `"show_progress"` in `features` to show progress bars when training
//! ```
//!
//! In your Rust code, write:
//! ```ignored
//! use rustyml::neural_network::{
//!     sequential::Sequential,
//!     layers::{Dense, ReLU, Softmax},
//!     optimizers::Adam,
//!     losses::CategoricalCrossEntropy,
//! };
//! use ndarray::Array;
//!
//! // Create training data
//! let x = Array::ones((32, 784)).into_dyn(); // 32 samples, 784 features
//! let y = Array::ones((32, 10)).into_dyn();  // 32 samples, 10 classes
//!
//! // Build a neural network
//! let mut model = Sequential::new();
//! model
//!     .add(Dense::new(784, 128, ReLU::new()).unwrap())
//!     .add(Dense::new(128, 64, ReLU::new()).unwrap())
//!     .add(Dense::new(64, 10, Softmax::new()).unwrap())
//!     .compile(Adam::new(0.001, 0.9, 0.999, 1e-8, 0.0).unwrap(), CategoricalCrossEntropy::new(false));
//!
//! // Display model structure
//! model.summary();
//!
//! // Train the model
//! model.fit(&x, &y, 10).unwrap();
//!
//! // Save model weights to file
//! model.save_to_path("model.json").unwrap();
//!
//! // Create a new model with the same architecture
//! let mut new_model = Sequential::new();
//! new_model
//!     .add(Dense::new(784, 128, ReLU::new()).unwrap())
//!     .add(Dense::new(128, 64, ReLU::new()).unwrap())
//!     .add(Dense::new(64, 10, Softmax::new()).unwrap());
//!
//! // Load weights from file
//! new_model.load_from_path("model.json").unwrap();
//!
//! // Compile before using (required for training, optional for prediction)
//! new_model.compile(Adam::new(0.001, 0.9, 0.999, 1e-8, 0.0).unwrap(), CategoricalCrossEntropy::new(false));
//!
//! // Make predictions with loaded model
//! let predictions = new_model.predict(&x).unwrap();
//! println!("Predictions shape: {:?}", predictions.shape());
//! ```
//!
//! ## Feature Flags
//!
//! The crate uses feature flags for modular compilation:
//!
//! | Feature | Description |
//! |---------|-------------|
//! | `machine_learning` | Classical ML algorithms (depends on `math`) |
//! | `neural_network` | Neural network framework |
//! | `utils` | Data preprocessing and dimensionality reduction |
//! | `metrics` | Evaluation metrics |
//! | `math` | Mathematical utilities |
//! | `default` | Enables `machine_learning` and `neural_network` |
//! | `full` | Enables all features |
//! | `show_progress` | Show progress bars when training |

#[cfg(any(
    feature = "machine_learning",
    feature = "utils",
    feature = "neural_network"
))]
use serde::{Deserialize, Serialize};

/// Shared configuration types (kernels, distance metrics, regularization)
#[cfg(any(feature = "machine_learning", feature = "utils", feature = "metrics"))]
pub mod types;

#[cfg(feature = "show_progress")]
use indicatif::{ProgressBar, ProgressStyle};

/// Creates a progress bar with a consistent style across the crate
///
/// The progress bar is only created when the `show_progress` feature is enabled
///
/// # Parameters
///
/// - `total` - The total number of iterations or items to process
/// - `template` - A custom template string for the progress bar format,
///   using placeholders {elapsed_precise}, {bar:40}, {pos}, {len}, {msg};
///   example: "\[{elapsed_precise}\] {bar:40} {pos}/{len} | Cost: {msg}"
///
/// # Returns
///
/// - `ProgressBar` - A configured progress bar instance
///
/// # Notes
///
/// Example templates:
/// - For iterations with cost: `"[{elapsed_precise}] {bar:40} {pos}/{len} | Cost: {msg}"`
/// - For iterations with loss: `"[{elapsed_precise}] {bar:40} {pos}/{len} | Loss: {msg}"`
/// - For node counting: `"[{elapsed_precise}] {bar:40} {pos} nodes | Depth: {msg}"`
/// - For general progress: `"[{elapsed_precise}] {bar:40} {pos}/{len} | Stage: {msg}"`
///
/// All progress bars use the unified style with:
/// - Progress characters: `"#>-"` (completed, current, remaining)
/// - Bar width: 40 characters
/// - Time display: precise elapsed time
#[cfg(feature = "show_progress")]
#[allow(dead_code)]
fn create_progress_bar(total: u64, template: &str) -> ProgressBar {
    let progress_bar = ProgressBar::new(total);
    progress_bar.set_style(
        ProgressStyle::default_bar()
            .template(template)
            .expect("Failed to set progress bar template")
            .progress_chars("#>-"),
    );
    progress_bar
}

/// Generates a public getter method that returns a field by value
///
/// The generated method includes documentation describing the field being accessed
///
/// # Parameters
///
/// - `$method_name` - The name of the getter method (e.g. get_fit_intercept)
/// - `$field_name` - The name of the field to access (e.g. fit_intercept)
/// - `$return_type` - The return type of the getter method
#[cfg(any(feature = "machine_learning", feature = "utils"))]
macro_rules! get_field {
    ($method_name:ident, $field_name:ident, $return_type:ty) => {
        #[doc = concat!("Gets the `", stringify!($field_name), "` field.\n\n")]
        #[doc = "# Returns\n\n"]
        #[doc = concat!("* `", stringify!($return_type), "` - The value of the `", stringify!($field_name), "` field")]
        pub fn $method_name(&self) -> $return_type {
            self.$field_name
        }
    };
}

/// Generates a public getter method returning an immutable reference to a field
///
/// The generated method includes documentation describing the field being accessed
///
/// # Parameters
///
/// - `$method_name` - The identifier for the generated getter method name
/// - `$field_name` - The identifier of the struct field to access
/// - `$return_type` - The type for the return value (typically a reference type like `&Type`)
#[cfg(any(feature = "machine_learning", feature = "utils"))]
macro_rules! get_field_as_ref {
    ($method_name:ident, $field_name:ident, $return_type:ty) => {
        #[doc = concat!("Gets the `", stringify!($field_name), "` field.\n\n")]
        #[doc = "# Returns\n\n"]
        #[doc = concat!("* `", stringify!($return_type), "` - The value of the `", stringify!($field_name), "` field as a reference")]
        pub fn $method_name(&self) -> $return_type {
            self.$field_name.as_ref()
        }
    };
}

/// Generates `save_to_path` and `load_from_path` methods for model structs
///
/// - `save_to_path` - Saves the model to a JSON file at the specified path
/// - `load_from_path` - Loads a model from a JSON file at the specified path
///
/// # Parameters
///
/// - `$model_type` - The type of the model struct (e.g. LinearRegression, LogisticRegression)
#[cfg(any(feature = "machine_learning", feature = "utils"))]
macro_rules! model_save_and_load_methods {
    ($model_type:ty) => {
        /// Saves the trained model to a JSON file at the specified path
        ///
        /// Serializes the entire model state including coefficients, intercept,
        /// hyperparameters, and training metadata to JSON format using serde_json
        ///
        /// # Parameters
        ///
        /// - `path` - File path where the model will be saved (e.g. "stored_model.json")
        ///
        /// # Returns
        ///
        /// - `Ok(())` - Model successfully saved to file
        /// - `Err(Error::Io)` - File creation/write failed, or serialization to JSON failed
        pub fn save_to_path(&self, path: &str) -> Result<(), crate::error::Error> {
            use serde_json::to_writer_pretty;
            use std::fs::File;
            use std::io::{BufWriter, Write};

            let file = File::create(path)?;
            let mut writer = BufWriter::new(file);

            to_writer_pretty(&mut writer, self)?;

            writer.flush()?;

            Ok(())
        }

        /// Loads a trained model from a JSON file at the specified path
        ///
        /// Deserializes a previously saved model from JSON format, restoring all
        /// model parameters, hyperparameters, and training state
        ///
        /// # Parameters
        ///
        /// - `path` - File path from which to load the model (e.g. "stored_model.json")
        ///
        /// # Returns
        ///
        /// - `Ok(Self)` - Successfully loaded model instance
        /// - `Err(Error::Io)` - File not found/read failed, or deserialization from JSON failed
        ///   (invalid format or corrupted data)
        pub fn load_from_path(path: &str) -> Result<Self, crate::error::Error> {
            use serde_json::from_reader;

            let reader = crate::error::IoError::load_in_buf_reader(path)?;

            let model: $model_type = from_reader(reader)?;

            Ok(model)
        }
    };
}

/// Error handling module containing the crate's unified error type and its result alias
///
/// Every fallible operation returns [`error::RustymlResult<T>`](crate::error::RustymlResult),
/// an alias for `Result<T, error::Error>`. [`error::Error`] is structured into category variants
/// and groups domain-specific failures into
/// the nested [`error::NnError`], [`error::TreeError`], and [`error::IoError`] sub-enums. Prefer the
/// smart constructors (`Error::dimension_mismatch`, `Error::invalid_parameter`, ...) and
/// [`error::Context::context`] for wrapping foreign errors. See the module docs for the full
/// category breakdown and conventions
#[cfg(any(
    feature = "machine_learning",
    feature = "neural_network",
    feature = "utils"
))]
pub mod error;

/// Crate-wide control of pseudo-random number generation for reproducibility
///
/// Exposes [`set_global_seed`](random::set_global_seed) / [`clear_global_seed`](random::clear_global_seed)
/// (re-exported at the crate root) to fix a thread-local global seed. All randomized components
/// resolve their `random_state: Option<u64>` against this global through a shared entry point, so a
/// single `set_global_seed` call makes the crate reproducible. See the module docs for the
/// local-vs-global-vs-entropy resolution rules and the threading contract
#[cfg(any(
    feature = "machine_learning",
    feature = "neural_network",
    feature = "utils"
))]
pub mod random;

/// Re-export of the global-seed controls; canonical home is the [`random`] module
#[cfg(any(
    feature = "machine_learning",
    feature = "neural_network",
    feature = "utils"
))]
pub use random::{clear_global_seed, set_global_seed};

/// Crate-internal parallel/serial gate thresholds, one constant per calibrated kernel cost
/// class (`f32` classes for the neural-network layers, `f64` classes for ML/utils)
#[cfg(any(
    feature = "machine_learning",
    feature = "neural_network",
    feature = "utils"
))]
pub(crate) mod parallel_gates;

/// Module `math` contains mathematical utility functions for statistical operations and model evaluation
///
/// Functions include impurity measures for decision trees, distance calculations for clustering,
/// statistical measures for evaluation, and other utilities for data processing
///
/// # What belongs here
///
/// A function lives in `math` only if it is **(1)** pure and stateless, **(2)**
/// model-agnostic (it encodes no single algorithm's policy), and **(3)** is - or
/// plausibly could be - shared by more than one caller. Per-algorithm solvers live
/// next to their model; post-hoc evaluation metrics live in [`crate::metrics`] and
/// call these primitives; trainable, gradient-aware losses live in
/// `neural_network::losses`
///
/// # Core Functions
///
/// ## Decision Tree Mathematics
/// - `entropy` - Calculates the entropy of a label set for information-based splitting
/// - `gini` - Calculates the Gini impurity for CART-based splitting
///
/// ## Distance Calculations
/// - `squared_euclidean_distance_row` - Squared Euclidean distance between two vectors
/// - `manhattan_distance_row` - Manhattan (L1) distance between two vectors
/// - `minkowski_distance_row` - Generalized Minkowski distance with parameter p
///
/// ## Parallel Matrix Products ([`math::matmul`])
/// - `gemm` / `gemv` - Rayon-block-parallel matrix products with a caller-supplied
///   serial/parallel FLOPs threshold, bitwise identical to the serial `dot` at any
///   thread count and any threshold
///
/// ## Statistical Functions
/// - `sum_of_square_total` - Total variability measurement (SST)
/// - `sum_of_squared_errors` - Sum of squared prediction errors (SSE)
/// - `variance` - Mean squared error or variance of a dataset
/// - `standard_deviation` - Population standard deviation calculation
/// - `average_path_length_factor` - Adjustment factor for isolation forest algorithms
///
/// ## Activation and Loss Functions
/// - `sigmoid` - Sigmoid activation function for neural networks and logistic regression
/// - `logistic_loss` - Cross-entropy loss for binary classification
/// - `hinge_loss` - Mean hinge loss for margin-based classifiers (e.g. SVM)
///
/// # Example
/// ```rust
/// use rustyml::math::{entropy, gini, sigmoid, squared_euclidean_distance_row};
/// use ndarray::array;
///
/// // Decision tree impurity measures
/// let labels = array![0.0, 1.0, 1.0, 0.0];
/// let ent = entropy(&labels);
/// let gini_val = gini(&labels);
///
/// // Distance calculations
/// let v1 = array![1.0, 2.0];
/// let v2 = array![4.0, 6.0];
/// let dist = squared_euclidean_distance_row(&v1, &v2);
///
/// // Activation function
/// let activated = sigmoid(0.5);
/// ```
#[cfg(feature = "math")]
pub mod math;

/// Module `machine_learning` provides implementations of machine learning algorithms and models
///
/// Includes supervised and unsupervised learning algorithms with parallel processing and error handling
///
/// # Supervised Learning Algorithms
///
/// ## Classification
/// - **LogisticRegression**: Binary classification with gradient descent optimization and regularization support
/// - **KNN**: K-Nearest Neighbors with customizable distance metrics (Euclidean, Manhattan, Minkowski) and weighting strategies
/// - **DecisionTree**: Decision tree classifier supporting ID3, C4.5, and CART algorithms with pruning options
/// - **SVC**: Support Vector Classifier using Sequential Minimal Optimization (SMO) algorithm with kernel support
/// - **LinearSVC**: Linear Support Vector Classifier optimized for large datasets with hinge loss
/// - **LinearDiscriminantAnalysis**: LDA for classification and dimensionality reduction with class separability preservation
///
/// ## Regression
/// - **LinearRegression**: Simple and multivariate linear regression with L1/L2 regularization options
///
/// # Unsupervised Learning Algorithms
///
/// ## Clustering
/// - **KMeans**: K-means clustering with K-means++ initialization and parallel processing
/// - **DBSCAN**: Density-based clustering for discovering clusters of arbitrary shapes with noise detection
/// - **MeanShift**: Non-parametric clustering that automatically determines cluster centers
///
/// ## Anomaly Detection
/// - **IsolationForest**: Ensemble method for efficient anomaly detection in high-dimensional data
///
/// # Distance Metrics and Utilities
/// - `DistanceCalculationMetric` - Enum defining Euclidean, Manhattan, and Minkowski distance metrics
/// - `RegularizationType` - L1 and L2 regularization options for preventing overfitting
/// - Helper macros and validation functions for consistent model interfaces
///
/// # Examples
/// ```rust
/// use rustyml::machine_learning::LinearRegression;
/// use ndarray::{Array1, Array2, array};
///
/// // Linear regression example
/// let mut model = LinearRegression::new(true, 0.01, 1000, 1e-6).unwrap();
/// let x = array![[1.0, 2.0], [2.0, 3.0], [3.0, 4.0]];
/// let y = array![6.0, 9.0, 12.0];
/// model.fit(&x, &y).unwrap();
/// ```
#[cfg(feature = "machine_learning")]
pub mod machine_learning;

/// Module `prelude` re-exports the most commonly used types and traits from this crate
///
/// Provides a single import point for frequently used items through one `use` statement
///
/// # Available Components
///
/// ## Machine Learning Models
/// - Classification algorithms (KNN, DecisionTree, LogisticRegression, SVC, LinearSVC, LinearDiscriminantAnalysis)
/// - Regression algorithms (LinearRegression)
/// - Clustering algorithms (KMeans, DBSCAN, MeanShift)
/// - Anomaly detection (IsolationForest)
///
/// ## Data Processing and Utilities
/// - Dimensionality reduction (PCA, kernel PCA, t-SNE)
/// - Data preprocessing (standardize, train_test_split)
/// - Feature engineering utilities
/// - and more (See details at documentation in utility module)
///
/// ## Evaluation Metrics
/// - Classification metrics (ConfusionMatrix, accuracy, roc_auc)
/// - Regression metrics (mean_squared_error, r2_score, mean_absolute_error)
/// - Clustering metrics (adjusted_rand_index, silhouette_score)
/// - and more (See details at documentation in metric module)
///
/// ## Neural Network Components
/// - Complete neural network framework with layers, optimizers, loss functions
/// - Sequential model architecture for building feed-forward networks
/// - and more (See details at documentation in neural_network module)
///
/// # Examples
/// ```rust
/// // Brings every category's items (traits, models, metrics, ...) into scope at once:
/// use rustyml::prelude::*;
///
/// // Or import a single category:
/// // `use rustyml::prelude::machine_learning::*;` for the machine learning models
/// // `use rustyml::prelude::utils::*;`            for the utility functions
/// // `use rustyml::prelude::metrics::*;`          for the metric functions
/// ```
pub mod prelude;

/// Module `utils` provides utility functions and data processing tools for machine learning operations
///
/// Covers data transformation and preprocessing that complement the main algorithms, including
/// dimensionality reduction, data splitting, and other preprocessing functions
///
/// # Dimensionality Reduction Techniques
///
/// ## Linear Methods
/// - **PCA (Principal Component Analysis)**: Linear dimensionality reduction for feature extraction and data visualization
///
/// ## Non-linear Methods
/// - **Kernel PCA**: Non-linear dimensionality reduction using kernel methods for complex data patterns
/// - **t-SNE**: t-Distributed Stochastic Neighbor Embedding for high-dimensional data visualization
///
/// # Data Preprocessing
/// - **train_test_split**: Utility for splitting datasets into training and testing sets with configurable ratios
/// - **standardize**: Data standardization (z-score normalization) for feature scaling
/// - **KernelType**: Enumeration of supported kernel functions (RBF, Linear, Polynomial, Sigmoid, Cosine)
///
/// # Key Features
/// - **Parallel Processing**: Rayon-based parallel computation for performance optimization
/// - **Flexible Configuration**: Customizable parameters for all algorithms
/// - **Memory Efficient**: Optimized implementations for large datasets
/// - **Robust Error Handling**: Comprehensive input validation and error reporting
///
/// # Examples
/// ```rust
/// use rustyml::utils::pca::PCA;
/// use ndarray::array;
///
/// let mut pca = PCA::new(2).unwrap();
/// let x = array![[1.0, 2.0], [2.0, 3.0], [3.0, 4.0]];
/// pca.fit(&x).unwrap();
/// let projected = pca.transform(&x).unwrap();
/// assert_eq!(projected.ncols(), 2);
/// ```
#[cfg(feature = "utils")]
pub mod utils;

/// Module `metrics` provides evaluation metrics for statistical analysis and model performance assessment
///
/// Contains evaluation functions and structures for measuring model performance across
/// regression, classification, and clustering tasks
///
/// # Regression Metrics
/// - **mean_squared_error**: Average of squared differences between predicted and actual values
/// - **root_mean_squared_error**: Square root of MSE, providing error in original data units
/// - **mean_absolute_error**: Average magnitude of prediction errors without considering direction
/// - **r2_score**: Coefficient of determination measuring explained variance (R^2 score)
/// - **explained_variance_score**: Variance of the residuals relative to the data (ignores constant bias)
/// - **median_absolute_error**: Median of the absolute errors, robust to outliers
/// - **mean_absolute_percentage_error**: Mean relative error as a fraction of the true values
///
/// # Classification Metrics
///
/// ## ConfusionMatrix Structure
/// Comprehensive binary classification evaluation with:
/// - True/False Positive and Negative counts (TP, FP, TN, FN)
/// - Derived metrics: accuracy, precision, recall, specificity, F1-score, error rate, balanced accuracy, MCC
/// - Formatted summary generation for detailed performance reporting
///
/// ## MulticlassConfusionMatrix Structure
/// KxK confusion matrix for multi-class evaluation:
/// - Per-class precision, recall, F1, and support
/// - Macro / micro / weighted aggregation via the `Average` enum
/// - `classification_report`-style text summary
///
/// ## Classification Functions
/// - **accuracy**: Standalone accuracy calculation for multi-class and binary classification
/// - **roc_auc**: Area Under ROC Curve using Mann-Whitney U statistic for binary classification
/// - **log_loss**: Multi-class logarithmic loss (cross-entropy) of predicted probabilities
/// - **cohen_kappa**: Inter-labeling agreement corrected for chance
/// - **top_k_accuracy**: Fraction of samples whose true class is among the top-k predictions
/// - **average_precision**: Area under the precision-recall curve
/// - **roc_curve** / **precision_recall_curve**: Curve points across decision thresholds
///
/// # Clustering Evaluation Metrics
/// - **adjusted_rand_index**: Adjusted Rand Index for clustering similarity measurement with chance correction
/// - **normalized_mutual_info**: Normalized Mutual Information measuring clustering agreement
/// - **adjusted_mutual_info**: Mutual information adjusted for chance agreement between clusterings
/// - **homogeneity_score** / **completeness_score** / **v_measure_score**: Entropy-based clustering quality and their harmonic mean
/// - **fowlkes_mallows_score**: Geometric mean of pairwise precision and recall over sample pairs
/// - **silhouette_score**: Mean silhouette coefficient measuring cluster cohesion and separation
/// - **davies_bouldin_score** / **calinski_harabasz_score**: Internal cluster-validity indices (no ground truth needed)
///
/// # Key Features
/// - **Input Validation**: Error checking with informative messages
/// - **Numerical Stability**: Epsilon handling and stable algorithms for edge cases
/// - **Single-pass calculations**: Efficient implementations
/// - **Statistical Rigor**: Implementations with sound mathematical foundations
///
/// # Conventions
///
/// - **Panics instead of returning `Result`**. `metrics` is a lightweight leaf module - pure
///   `array -> scalar` functions pulling only `ndarray` and `ahash` - so, like `ndarray` and
///   `nalgebra` on a dimension mismatch, the metrics panic on precondition violations (mismatched
///   lengths, empty input) rather than returning the crate's `Error`. The panic messages mirror
///   that type's wording (`dimension mismatch: ...`, `input is empty: ...`) for consistency
/// - **Arguments are `(y_true, y_pred)`** - ground truth first, matching scikit-learn and the
///   clustering metrics' `(labels_true, labels_pred)`. The order is irrelevant for the symmetric
///   metrics (MSE, MAE, accuracy) but significant for `r2_score`, `ConfusionMatrix::new`, and
///   `roc_auc`
///
/// # Examples
/// ```rust
/// use rustyml::metrics::*;
/// use ndarray::array;
///
/// // Regression evaluation - arguments are (y_true, y_pred)
/// let y_true = array![2.8, 2.1, 3.3, 4.2];
/// let y_pred = array![3.0, 2.0, 3.5, 4.1];
/// let mse = mean_squared_error(&y_true.view(), &y_pred.view());
/// let r2 = r2_score(&y_true.view(), &y_pred.view());
///
/// // Classification evaluation with confusion matrix
/// let y_true = array![1.0, 0.0, 0.0, 1.0, 1.0];
/// let y_pred = array![1.0, 0.0, 1.0, 1.0, 0.0];
/// let cm = ConfusionMatrix::new(&y_true.view(), &y_pred.view());
/// println!("F1 Score: {:.3}", cm.f1_score());
///
/// // ROC AUC for binary classification
/// let labels = array![false, true, false, true];
/// let scores = array![0.1, 0.4, 0.35, 0.8];
/// let auc = roc_auc(&labels.view(), &scores.view());
/// ```
#[cfg(feature = "metrics")]
pub mod metrics;

/// Module `neural_network` provides components for building and training neural networks
///
/// A framework for constructing, training, and deploying neural networks with support for
/// various layer types, optimization algorithms, loss functions, and model architectures
///
/// # Core Components
///
/// ## Layer Types
/// - **Dense**: Fully connected layers with customizable activation functions
/// - **Activation**: Standalone activation layers (ReLU, Sigmoid, Tanh, Softmax, Linear, etc.)
/// - **Pooling Layers**: Max pooling and average pooling operations for 1D, 2D, and 3D data
/// - **Global Pooling**: Global max pooling and global average pooling for 1D, 2D, and 3D tensors
/// - **Recurrent Layers**: Sequential Modeling Layers like RNN, LSTM, and GRU
/// - **Regularization layers**: Regularization layer to prevent overfitting during training
///
/// ## Optimization Algorithms
/// - **SGD**: Stochastic Gradient Descent with momentum support
/// - **Adam**: Adaptive moment estimation optimizer (classic coupled L2 weight decay)
/// - **AdamW**: Adam with decoupled weight decay
/// - **RMSProp**: Root Mean Square Propagation optimizer
/// - **AdaGrad**: Adaptive gradient algorithm
///
/// ## Loss Functions
/// - **MeanSquaredError**: For regression tasks
/// - **BinaryCrossEntropy**: For binary classification
/// - **CategoricalCrossEntropy**: For multi-class classification
/// - **SparseCategoricalCrossEntropy**: For multi-class with integer labels
///
/// ## Model Architecture
/// - **Sequential**: Linear stack of layers for feed-forward neural networks
/// - **Tensor**: Type alias for n-dimensional arrays used throughout the framework
///
/// # Key Features
/// - **Flexible Architecture**: Easy model construction with intuitive API
/// - **Automatic Differentiation**: Built-in backpropagation implementation
/// - **Training Loop**: Integrated training with loss tracking and convergence monitoring
/// - **Prediction Interface**: Simple prediction methods for inference
///
/// # Examples
/// ```rust
/// use rustyml::neural_network::{
///     sequential::Sequential,
///     layers::{Activation, Dense},
///     optimizers::Adam,
///     losses::MeanSquaredError,
/// };
/// use ndarray::Array;
///
/// // Create input and target tensors
/// let x = Array::ones((2, 4)).into_dyn();  // 2 samples, 4 features
/// let y = Array::ones((2, 1)).into_dyn();  // 2 samples, 1 output
///
/// // Build sequential model
/// let mut model = Sequential::new();
/// model.add(Dense::new(4, 8, Activation::ReLU).unwrap())   // Input layer: 4 -> 8
///      .add(Dense::new(8, 3, Activation::ReLU).unwrap())   // Hidden layer: 8 -> 3
///      .add(Dense::new(3, 1, Activation::Linear).unwrap()); // Output layer: 3 -> 1
///
/// // Compile with optimizer and loss function
/// model.compile(Adam::new(0.001, 0.9, 0.999, 1e-8, 0.0).unwrap(), MeanSquaredError::new());
///
/// // Display model architecture
/// model.summary();
///
/// // Train the model
/// model.fit(&x, &y, 100).unwrap();
///
/// // Make predictions
/// let predictions = model.predict(&x);
/// ```
#[cfg(feature = "neural_network")]
pub mod neural_network;

/// Internal hooks for the `benches/` targets - not part of the public API, no stability guarantees
#[cfg(any(feature = "machine_learning", feature = "neural_network"))]
#[doc(hidden)]
pub mod bench_internals;