gbrt_rs/objective/

factory.rs

#![allow(dead_code)]

//! Objective Function Factory and Registry
//! 
//! This module provides factory patterns for creating objective functions used
//! in gradient boosting. It supports both regression and binary classification
//! tasks with configurable parameters.
//! 
//! # Architecture
//! 
//! - [`ObjectiveFactory`]: Static factory for creating objective instances
//! - [`ObjectiveBuilder`]: Fluent builder for configuring objectives
//! - [`ObjectiveRegistry`]: Validation and discovery of available objectives
//! - [`ObjectiveType`]: Enum distinguishing regression vs classification
//! 
//! # Supported Objectives
//! 
//! **Regression:**
//! - `mse` / `mean_squared_error`
//! - `mae` / `mean_absolute_error`
//! - `huber` (with `delta` parameter)
//! 
//! **Binary Classification:**
//! - `log_loss` / `binary_crossentropy`
//! 

use super::{
    Objective, ObjectiveError, ObjectiveResult, ObjectiveConfig,
    RegressionObjective, BinaryClassificationObjective,
    MSEObjective, MAEObjective, HuberObjective, LogLossObjective
};
use serde::{Deserialize, Serialize};
use std::collections::HashMap;

/// Type of machine learning task for objective selection.
/// 
/// Used to categorize objectives and validate compatibility with
/// gradient booster configuration.
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
pub enum ObjectiveType {
    /// Regression objectives predict continuous values.
    Regression,
    /// Binary classification objectives predict probabilities for two classes.
    BinaryClassification,
}

impl std::fmt::Display for ObjectiveType {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            ObjectiveType::Regression => write!(f, "regression"),
            ObjectiveType::BinaryClassification => write!(f, "binary_classification"),
        }
    }
}

/// Factory for creating objective function instances.
/// 
/// `ObjectiveFactory` provides static methods to instantiate objective
/// functions with appropriate types and parameters. It handles validation
/// and configuration of objective-specific hyperparameters.
pub struct ObjectiveFactory;

impl ObjectiveFactory {
    /// Creates a regression objective function by name.
    /// 
    /// # Supported Names
    /// - `mse`, `mean_squared_error`
    /// - `mae`, `mean_absolute_error`
    /// - `huber` (creates with delta=1.0)
    /// 
    /// # Parameters
    /// - `name`: Objective function name (case-insensitive)
    /// 
    /// # Returns
    /// Boxed trait object implementing [`RegressionObjective`]
    /// 
    /// # Errors
    /// - `ObjectiveError::ConfigError` if `name` is not a valid regression objective    
    pub fn create_regression_objective(name: &str) -> ObjectiveResult<Box<dyn RegressionObjective>> {
        match name.to_lowercase().as_str() {
            "mse" | "mean_squared_error" => Ok(Box::new(MSEObjective::new())),
            "mae" | "mean_absolute_error" => Ok(Box::new(MAEObjective::new())),
            "huber" => Ok(Box::new(HuberObjective::new(1.0))),
            _ => Err(ObjectiveError::ConfigError(
                format!("Unknown regression objective: {}", name)
            )),
        }
    }
    
    /// Creates a binary classification objective function by name.
    /// 
    /// # Supported Names
    /// - `log_loss`, `binary_crossentropy`, `binary_cross_entropy`
    /// 
    /// # Parameters
    /// - `name`: Objective function name (case-insensitive)
    /// 
    /// # Returns
    /// Boxed trait object implementing [`BinaryClassificationObjective`]
    /// 
    /// # Errors
    /// - `ObjectiveError::ConfigError` if `name` is not a valid classification objective    
    pub fn create_binary_classification_objective(name: &str) -> ObjectiveResult<Box<dyn BinaryClassificationObjective>> {
        match name.to_lowercase().as_str() {
            "log_loss" | "binary_crossentropy" | "binary_cross_entropy" => {
                Ok(Box::new(LogLossObjective::new()))
            },
            _ => Err(ObjectiveError::ConfigError(
                format!("Unknown binary classification objective: {}", name)
            )),
        }
    }
    
    /// Creates an objective from a configuration struct.
    /// 
    /// # Parameters
    /// - `config`: [`ObjectiveConfig`] with name and parameters
    /// 
    /// # Returns
    /// Boxed trait object implementing [`Objective`]
    /// 
    /// # Supported Configurations
    /// - `mse`: No parameters
    /// - `mae`: No parameters
    /// - `huber`: `delta` parameter (default: 1.0)
    /// - `log_loss`: `epsilon` parameter (default: 1e-15)
    /// 
    /// # Errors
    /// - `ObjectiveError::ConfigError` if objective name is unknown
    /// - `ObjectiveError::ConfigError` if parameters are invalid    
    pub fn create_objective_from_config(config: &ObjectiveConfig) -> ObjectiveResult<Box<dyn Objective>> {
        let name = config.name.to_lowercase();
        
        match name.as_str() {
            // Regression objectives
            "mse" | "mean_squared_error" => Ok(Box::new(MSEObjective::new())),
            "mae" | "mean_absolute_error" => Ok(Box::new(MAEObjective::new())),
            "huber" => {
                let delta = config.get_param("delta").unwrap_or(1.0);
                Ok(Box::new(HuberObjective::new(delta)))
            },
            
            // Binary classification objectives
            "log_loss" | "binary_crossentropy" | "binary_cross_entropy" => {
                let epsilon = config.get_param("epsilon").unwrap_or(1e-15);
                Ok(Box::new(LogLossObjective::new().with_epsilon(epsilon)))
            },
            
            _ => Err(ObjectiveError::ConfigError(
                format!("Unknown objective: {}", config.name)
            )),
        }
    }
    
    /// Determines the task type for a given objective name.
    /// 
    /// # Parameters
    /// - `name`: Objective name (case-insensitive)
    /// 
    /// # Returns
    /// [`ObjectiveType`] indicating regression or classification
    /// 
    /// # Errors
    /// - `ObjectiveError::ConfigError` if objective name is unknown    
    pub fn get_objective_type(name: &str) -> ObjectiveResult<ObjectiveType> {
        match name.to_lowercase().as_str() {
            "mse" | "mean_squared_error" | "mae" | "mean_absolute_error" | "huber" => {
                Ok(ObjectiveType::Regression)
            },
            "log_loss" | "binary_crossentropy" | "binary_cross_entropy" => {
                Ok(ObjectiveType::BinaryClassification)
            },
            _ => Err(ObjectiveError::ConfigError(
                format!("Unknown objective: {}", name)
            )),
        }
    }
    
    /// Returns a list of all available objective names.
    /// 
    /// # Returns
    /// Vector of lowercase objective names
    pub fn available_objectives() -> Vec<&'static str> {
        vec![
            "mse",
            "mae", 
            "huber",
            "log_loss",
        ]
    }
    
    /// Gets default parameters for an objective.
    /// 
    /// # Parameters
    /// - `name`: Objective name (case-insensitive)
    /// 
    /// # Returns
    /// HashMap of parameter names to default values
    /// 
    /// # Errors
    /// - `ObjectiveError::ConfigError` if objective name is unknown
    pub fn get_default_params(name: &str) -> ObjectiveResult<HashMap<String, f64>> {
        let mut params = HashMap::new();
        
        match name.to_lowercase().as_str() {
            "huber" => {
                params.insert("delta".to_string(), 1.0);
            },
            "log_loss" => {
                params.insert("epsilon".to_string(), 1e-15);
            },
            "mse" | "mae" => {
                // No parameters for these
            },
            _ => return Err(ObjectiveError::ConfigError(
                format!("Unknown objective: {}", name)
            )),
        }
        
        Ok(params)
    }
}

/// Convenience function to create an objective by name with default parameters.
/// 
/// # Parameters
/// - `name`: Objective name (case-insensitive)
/// 
/// # Returns
/// Boxed trait object implementing [`Objective`]
pub fn create_objective(name: &str) -> ObjectiveResult<Box<dyn Objective>> {
    let config = ObjectiveConfig::new(name);
    ObjectiveFactory::create_objective_from_config(&config)
}

/// Fluent builder for constructing [`ObjectiveConfig`].
/// 
/// Provides a convenient API for configuring objective functions with parameters.
pub struct ObjectiveBuilder {
    name: String,
    params: HashMap<String, f64>,
}

impl ObjectiveBuilder {
    /// Creates a new builder for the specified objective.
    /// 
    /// # Parameters
    /// - `name`: Objective name (case-insensitive)
    pub fn new(name: &str) -> Self {
        Self {
            name: name.to_string(),
            params: HashMap::new(),
        }
    }
    
    /// Adds a parameter to the objective configuration.
    /// 
    /// # Parameters
    /// - `key`: Parameter name (e.g., "delta" for Huber)
    /// - `value`: Parameter value
    pub fn with_param(mut self, key: &str, value: f64) -> Self {
        self.params.insert(key.to_string(), value);
        self
    }

    /// Builds the final ObjectiveConfig.
    /// 
    /// # Returns
    /// Configured ObjectiveConfig ready for factory consumption
    pub fn build(self) -> ObjectiveConfig {
        ObjectiveConfig {
            name: self.name,
            params: self.params,
        }
    }
}

/// Registry for objective discovery and validation.
/// 
/// Provides utilities for checking objective availability, exploring options,
/// and validating configurations before instantiation.
pub struct ObjectiveRegistry;

impl ObjectiveRegistry {
    /// Checks if an objective name is valid and supported.
    /// 
    /// # Parameters
    /// - `name`: Objective name (case-insensitive)
    /// 
    /// # Returns
    /// `true` if objective exists, `false` otherwise
    pub fn is_valid_objective(name: &str) -> bool {
        ObjectiveFactory::available_objectives().contains(&name)
    }
    
    /// Returns all regression objective names.
    pub fn regression_objectives() -> Vec<&'static str> {
        vec!["mse", "mae", "huber"]
    }
    
    /// Returns all classification objective names.
    pub fn classification_objectives() -> Vec<&'static str> {
        vec!["log_loss"]
    }
    
    /// Validates an objective configuration before instantiation.
    /// 
    /// Checks that:
    /// - Objective name is valid
    /// - All parameters are recognized
    /// - Parameter values are valid (positive for numerical params)
    /// 
    /// # Parameters
    /// - `config`: ObjectiveConfig to validate
    /// 
    /// # Returns
    /// `Ok(())` if configuration is valid
    /// 
    /// # Errors
    /// - `ObjectiveError::ConfigError` if objective name is unknown
    /// - `ObjectiveError::ConfigError` if parameters are invalid 
    pub fn validate_config(config: &ObjectiveConfig) -> ObjectiveResult<()> {
        if !Self::is_valid_objective(&config.name) {
            return Err(ObjectiveError::ConfigError(
                format!("Invalid objective name: {}", config.name)
            ));
        }
        
        // Validate parameters
        let default_params = ObjectiveFactory::get_default_params(&config.name)?;
        for (key, value) in &config.params {
            if !default_params.contains_key(key) {
                return Err(ObjectiveError::ConfigError(
                    format!("Unknown parameter '{}' for objective '{}'", key, config.name)
                ));
            }
            
            // Validate parameter values
            match key.as_str() {
                "delta" | "alpha" | "epsilon" => {
                    if *value <= 0.0 {
                        return Err(ObjectiveError::ConfigError(
                            format!("Parameter '{}' must be positive, got {}", key, value)
                        ));
                    }
                },
                _ => {}
            }
        }
        
        Ok(())
    }
}