# Class-aware heterogeneous failure classifier
#         ↓
# Failure probability
#         ↓
# RLGB + RandomForest + ExtraTrees
#     + HistGradientBoosting
#     + LightGBM + CatBoost
#         ↓
# MAE meta-regressor
#         ↓
# Joint RL blending
#         ↓
# Final grade

import os
import argparse
import polars as pl
import numpy as np
import pandas as pd
import random
from pathlib import Path
import xgboost as xgb
import matplotlib.pyplot as plt
from scipy.constants import yocto
from sklearn.model_selection import train_test_split
from sklearn.preprocessing import OneHotEncoder
from sklearn.metrics import mean_absolute_error, r2_score
from typing import Union
from imblearn.over_sampling import SMOTE

import pickle
from pathlib import Path
from xgboost import XGBClassifier

from class_aware_heterogeneous_stacking import (
    ClassAwareHeterogeneousStackingClassifier,
    build_standard_base_estimators,
)

from adaptive_rl_feature_subspace_boosting import (
    AdaptiveRLFeatureSubspaceBoostingClassifier,
)

from below_one_rl_grade_regressor_stacking import (
    BelowOneRLGradeRegressor,
)

from joint_failure_aware_stacking_grade_model import (
    JointRLStackingGradeRegressor,
    JointFailureAwareGradeModel,
    build_grade_regressors,
)

import os
import sys

print("Current working directory:")
print(os.getcwd())

print("\nPython executable:")
print(sys.executable)

print("\nPython search path:")
for p in sys.path:
    print(p)


N_RATE = 0.1
N_EST = 20
LOW_GRADE_THRESHOLD = 0.75
TEST_SIZE = 0.1

TARGET = "target_grade10"

ROOT = Path(__file__).resolve().parents[1]

random.seed(42)

DROP_MISSING_COLUMNS = [
    "course_key",
    "hist_same_course_attempts",
    "hist_same_course_mean_grade10",
    "hist_same_course_best_grade10",
    "hist_same_course_last_grade10",
    "hist_same_course_pass_rate",
    "prior_fail_count_in_target_course",
    "hist_same_course_component_count",
    "hist_same_course_component_mean",
    "hist_same_course_component_min",
    "hist_component_B1_mean",
    "hist_component_B1_low_rate",
]

DROP_CONSTANT_COLUMNS = [
    "course_grade_cong_nghe_phan_mem",
    "course_grade_marketing_ky_thuat_so",
    "course_grade_thuc_hanh_tieng_anh_b1",
]


# ----------------------------
# Step 2. Regression Tree Node Types
# ----------------------------
import math
import pickle
from collections import Counter
from pathlib import Path

import numpy as np


# ============================================================
# Entropy-based classification tree
# ============================================================

class ClassificationLeaf:
    """Leaf node storing class counts and class probabilities."""

    def __init__(self, class_counts, n_classes):
        self.class_counts = np.asarray(class_counts, dtype=np.float64)
        self.n_classes = int(n_classes)

        total = np.sum(self.class_counts)

        if total <= 0:
            self.probabilities = np.full(
                self.n_classes,
                1.0 / self.n_classes,
                dtype=np.float64,
            )
        else:
            self.probabilities = self.class_counts / total

        self.predicted_class = int(np.argmax(self.probabilities))

    def predict_one(self, row):
        return self.predicted_class

    def predict_proba_one(self, row):
        return self.probabilities


class ClassificationSplit:
    """Numeric binary split: X[:, feature_index] <= threshold."""

    def __init__(
        self,
        feature_index,
        threshold,
        left,
        right,
        default_class,
        default_probabilities,
    ):
        self.feature_index = int(feature_index)
        self.threshold = float(threshold)
        self.left = left
        self.right = right

        self.default_class = int(default_class)
        self.default_probabilities = np.asarray(
            default_probabilities,
            dtype=np.float64,
        )

    def predict_one(self, row):
        value = row[self.feature_index]

        if not np.isfinite(value):
            return self.default_class

        if value <= self.threshold:
            return self.left.predict_one(row)

        return self.right.predict_one(row)

    def predict_proba_one(self, row):
        value = row[self.feature_index]

        if not np.isfinite(value):
            return self.default_probabilities

        if value <= self.threshold:
            return self.left.predict_proba_one(row)

        return self.right.predict_proba_one(row)


class EntropyClassificationTree:
    """
    Numeric classification tree using entropy and information gain.

    Notes
    -----
    - All features are treated as numeric.
    - Missing and infinite values should be handled before training.
    - Sample weights are supported for boosting.
    """

    def __init__(
        self,
        min_samples=2,
        max_depth=5,
        min_gain=1e-12,
        max_thresholds=128,
        random_state=42,
    ):
        self.min_samples = int(min_samples)
        self.max_depth = int(max_depth)
        self.min_gain = float(min_gain)
        self.max_thresholds = int(max_thresholds)
        self.random_state = random_state

        self.root = None
        self.n_classes = None
        self.n_features_in_ = None
        self.feature_importances_ = None
        self.is_fitted = False

    @staticmethod
    def _weighted_class_counts(y, sample_weight, n_classes):
        return np.bincount(
            y,
            weights=sample_weight,
            minlength=n_classes,
        ).astype(np.float64)

    @staticmethod
    def _entropy_from_counts(class_counts):
        total = np.sum(class_counts)

        if total <= 0:
            return 0.0

        probabilities = class_counts / total
        probabilities = probabilities[probabilities > 0]

        return float(-np.sum(probabilities * np.log2(probabilities)))

    def _weighted_entropy(self, y, sample_weight):
        counts = self._weighted_class_counts(
            y,
            sample_weight,
            self.n_classes,
        )

        return self._entropy_from_counts(counts)

    def _candidate_thresholds(self, feature_values):
        unique_values = np.unique(feature_values)

        if unique_values.size <= 1:
            return np.empty(0, dtype=np.float64)

        thresholds = (
            unique_values[:-1] + unique_values[1:]
        ) / 2.0

        # Evaluating every possible threshold can be extremely expensive
        # for large continuous datasets. Keep evenly spaced candidates.
        if thresholds.size > self.max_thresholds:
            selected_indices = np.linspace(
                0,
                thresholds.size - 1,
                self.max_thresholds,
                dtype=int,
            )
            thresholds = thresholds[selected_indices]

        return thresholds

    def _find_best_split(self, X, y, sample_weight):
        parent_entropy = self._weighted_entropy(y, sample_weight)
        total_weight = np.sum(sample_weight)

        if total_weight <= 0:
            return None

        best_gain = -np.inf
        best_feature = None
        best_threshold = None
        best_left_mask = None

        n_samples, n_features = X.shape

        for feature_index in range(n_features):
            feature_values = X[:, feature_index]

            thresholds = self._candidate_thresholds(feature_values)

            for threshold in thresholds:
                left_mask = feature_values <= threshold
                right_mask = ~left_mask

                n_left = int(np.sum(left_mask))
                n_right = n_samples - n_left

                if n_left < self.min_samples:
                    continue

                if n_right < self.min_samples:
                    continue

                left_weight = np.sum(sample_weight[left_mask])
                right_weight = np.sum(sample_weight[right_mask])

                if left_weight <= 0 or right_weight <= 0:
                    continue

                left_entropy = self._weighted_entropy(
                    y[left_mask],
                    sample_weight[left_mask],
                )

                right_entropy = self._weighted_entropy(
                    y[right_mask],
                    sample_weight[right_mask],
                )

                weighted_child_entropy = (
                    (left_weight / total_weight) * left_entropy
                    + (right_weight / total_weight) * right_entropy
                )

                information_gain = (
                    parent_entropy - weighted_child_entropy
                )

                if information_gain > best_gain:
                    best_gain = information_gain
                    best_feature = feature_index
                    best_threshold = float(threshold)
                    best_left_mask = left_mask.copy()

        if best_feature is None:
            return None

        return {
            "feature_index": best_feature,
            "threshold": best_threshold,
            "gain": float(best_gain),
            "left_mask": best_left_mask,
        }

    def _build_tree(self, X, y, sample_weight, depth):
        class_counts = self._weighted_class_counts(
            y,
            sample_weight,
            self.n_classes,
        )

        default_probabilities = class_counts / max(
            np.sum(class_counts),
            1e-12,
        )

        default_class = int(np.argmax(class_counts))

        # Pure node
        if np.count_nonzero(class_counts > 0) <= 1:
            return ClassificationLeaf(
                class_counts,
                self.n_classes,
            )

        # Depth stopping condition
        if depth >= self.max_depth:
            return ClassificationLeaf(
                class_counts,
                self.n_classes,
            )

        # Sample stopping condition
        if len(y) < 2 * self.min_samples:
            return ClassificationLeaf(
                class_counts,
                self.n_classes,
            )

        split = self._find_best_split(
            X,
            y,
            sample_weight,
        )

        if split is None or split["gain"] <= self.min_gain:
            return ClassificationLeaf(
                class_counts,
                self.n_classes,
            )

        feature_index = split["feature_index"]
        threshold = split["threshold"]
        left_mask = split["left_mask"]
        right_mask = ~left_mask

        # Accumulate information gain as feature importance.
        self.feature_importances_[feature_index] += (
            split["gain"] * np.sum(sample_weight)
        )

        left_node = self._build_tree(
            X[left_mask],
            y[left_mask],
            sample_weight[left_mask],
            depth + 1,
        )

        right_node = self._build_tree(
            X[right_mask],
            y[right_mask],
            sample_weight[right_mask],
            depth + 1,
        )

        return ClassificationSplit(
            feature_index=feature_index,
            threshold=threshold,
            left=left_node,
            right=right_node,
            default_class=default_class,
            default_probabilities=default_probabilities,
        )

    def fit(self, X, y, sample_weight=None, n_classes=None):
        X = np.asarray(X, dtype=np.float64)
        y = np.asarray(y, dtype=np.int64).reshape(-1)

        if X.ndim != 2:
            raise ValueError(
                f"X must be two-dimensional; got {X.shape}."
            )

        if len(X) != len(y):
            raise ValueError(
                f"X and y lengths differ: {len(X)} != {len(y)}."
            )

        if len(y) == 0:
            raise ValueError("Training data is empty.")

        if sample_weight is None:
            sample_weight = np.full(
                len(y),
                1.0 / len(y),
                dtype=np.float64,
            )
        else:
            sample_weight = np.asarray(
                sample_weight,
                dtype=np.float64,
            ).reshape(-1)

        if len(sample_weight) != len(y):
            raise ValueError(
                "sample_weight and y have different lengths."
            )

        if np.any(sample_weight < 0):
            raise ValueError(
                "sample_weight cannot contain negative values."
            )

        weight_sum = np.sum(sample_weight)

        if weight_sum <= 0:
            raise ValueError(
                "The sum of sample weights must be positive."
            )

        sample_weight = sample_weight / weight_sum

        self.n_features_in_ = X.shape[1]

        if n_classes is None:
            self.n_classes = int(np.max(y)) + 1
        else:
            self.n_classes = int(n_classes)

        self.feature_importances_ = np.zeros(
            self.n_features_in_,
            dtype=np.float64,
        )

        self.root = self._build_tree(
            X,
            y,
            sample_weight,
            depth=0,
        )

        importance_sum = np.sum(self.feature_importances_)

        if importance_sum > 0:
            self.feature_importances_ /= importance_sum

        self.is_fitted = True

        return self

    def predict(self, X):
        if not self.is_fitted:
            raise RuntimeError(
                "The tree must be fitted before prediction."
            )

        X = np.asarray(X, dtype=np.float64)

        return np.asarray(
            [self.root.predict_one(row) for row in X],
            dtype=np.int64,
        )

    def predict_proba(self, X):
        if not self.is_fitted:
            raise RuntimeError(
                "The tree must be fitted before prediction."
            )

        X = np.asarray(X, dtype=np.float64)

        return np.vstack(
            [self.root.predict_proba_one(row) for row in X]
        )


# ============================================================
# RL entropy-boosting classifier
# ============================================================

import math
import pickle
from pathlib import Path

import numpy as np

class RL_GradientBoostingClassifierfromScratch:
    """
    Reinforcement-learning entropy boosting classifier designed for
    imbalanced binary and multiclass classification.

    Main improvements
    -----------------
    1. Moderated class weighting using square-root balancing.
    2. Configurable minority boosting-weight fraction.
    3. Validation-based early stopping.
    4. Best-estimator restoration.
    5. Validation-based threshold selection.
    6. Majority-recall constraint during threshold selection.
    7. Reward based on balanced loss, balanced accuracy, minority recall,
       and majority recall.
    8. Smoothed empirical prior rather than an extreme uniform or raw prior.
    """

    def __init__(
        self,
        learning_rate=0.05,
        n_estimators=100,
        min_samples=10,
        max_depth=3,
        min_gain=1e-6,
        max_thresholds=64,

        # Reinforcement-learning parameters
        actions=None,
        epsilon=0.20,
        epsilon_decay=0.98,
        min_epsilon=0.02,
        alpha_q=0.10,
        gamma_q=0.90,

        # Imbalanced-class handling
        class_weight="sqrt_balanced",
        minority_weight_fraction=0.25,
        positive_class=None,

        # Initial class-prior control
        prior_strength=0.50,

        # Threshold selection
        decision_threshold="auto",
        threshold_metric="constrained_f1",
        minimum_majority_recall=0.99,
        minimum_minority_recall=0.25,
        threshold_min=0.05,
        threshold_max=0.95,
        threshold_grid_size=181,

        # Reward components
        reward_loss_weight=0.35,
        reward_balanced_accuracy_weight=0.30,
        reward_minority_recall_weight=0.20,
        reward_majority_recall_weight=0.15,

        # Early stopping
        early_stopping_rounds=8,
        minimum_improvement=1e-4,

        random_state=42,
        verbose=True,
    ):
        # ====================================================
        # Tree and boosting parameters
        # ====================================================

        self.learning_rate = float(learning_rate)
        self.n_estimators = int(n_estimators)
        self.min_samples = int(min_samples)
        self.max_depth = int(max_depth)
        self.min_gain = float(min_gain)
        self.max_thresholds = int(max_thresholds)

        if self.learning_rate <= 0:
            raise ValueError(
                "learning_rate must be greater than zero."
            )

        if self.n_estimators <= 0:
            raise ValueError(
                "n_estimators must be greater than zero."
            )

        if self.min_samples < 1:
            raise ValueError(
                "min_samples must be at least 1."
            )

        if self.max_depth < 1:
            raise ValueError(
                "max_depth must be at least 1."
            )

        # ====================================================
        # RL parameters
        # ====================================================

        if actions is None:
            actions = [0.25, 0.50, 1.00, 1.50]

        self.actions = np.asarray(
            actions,
            dtype=np.float64,
        )

        if len(self.actions) == 0:
            raise ValueError(
                "At least one RL action is required."
            )

        if np.any(self.actions < 0):
            raise ValueError(
                "RL actions must be non-negative."
            )

        self.num_states = 5
        self.num_actions = len(self.actions)

        self.initial_epsilon = float(epsilon)
        self.epsilon = float(epsilon)
        self.epsilon_decay = float(epsilon_decay)
        self.min_epsilon = float(min_epsilon)

        self.alpha_q = float(alpha_q)
        self.gamma_q = float(gamma_q)

        if not 0 <= self.epsilon <= 1:
            raise ValueError(
                "epsilon must be between 0 and 1."
            )

        if not 0 < self.epsilon_decay <= 1:
            raise ValueError(
                "epsilon_decay must be in the interval (0, 1]."
            )

        if not 0 <= self.min_epsilon <= 1:
            raise ValueError(
                "min_epsilon must be between 0 and 1."
            )

        # ====================================================
        # Imbalanced classification parameters
        # ====================================================

        self.class_weight = class_weight
        self.minority_weight_fraction = float(
            minority_weight_fraction
        )
        self.positive_class = positive_class

        if not 0 < self.minority_weight_fraction < 1:
            raise ValueError(
                "minority_weight_fraction must be between 0 and 1."
            )

        self.prior_strength = float(prior_strength)

        if not 0 <= self.prior_strength <= 1:
            raise ValueError(
                "prior_strength must be between 0 and 1."
            )

        # ====================================================
        # Threshold parameters
        # ====================================================

        self.decision_threshold = decision_threshold
        self.threshold_metric = threshold_metric

        self.minimum_majority_recall = float(
            minimum_majority_recall
        )
        self.minimum_minority_recall = float(
            minimum_minority_recall
        )

        self.threshold_min = float(threshold_min)
        self.threshold_max = float(threshold_max)
        self.threshold_grid_size = int(
            threshold_grid_size
        )

        if not 0 <= self.minimum_majority_recall <= 1:
            raise ValueError(
                "minimum_majority_recall must be between 0 and 1."
            )

        if not 0 <= self.minimum_minority_recall <= 1:
            raise ValueError(
                "minimum_minority_recall must be between 0 and 1."
            )

        if not 0 < self.threshold_min < self.threshold_max < 1:
            raise ValueError(
                "Threshold limits must satisfy "
                "0 < threshold_min < threshold_max < 1."
            )

        if self.threshold_grid_size < 2:
            raise ValueError(
                "threshold_grid_size must be at least 2."
            )

        valid_threshold_metrics = {
            "constrained_f1",
            "balanced_accuracy",
            "f1",
            "gmean",
        }

        if self.threshold_metric not in valid_threshold_metrics:
            raise ValueError(
                "threshold_metric must be one of "
                f"{sorted(valid_threshold_metrics)}."
            )

        # ====================================================
        # Reward parameters
        # ====================================================

        self.reward_loss_weight = float(
            reward_loss_weight
        )

        self.reward_balanced_accuracy_weight = float(
            reward_balanced_accuracy_weight
        )

        self.reward_minority_recall_weight = float(
            reward_minority_recall_weight
        )

        self.reward_majority_recall_weight = float(
            reward_majority_recall_weight
        )

        reward_sum = (
            self.reward_loss_weight
            + self.reward_balanced_accuracy_weight
            + self.reward_minority_recall_weight
            + self.reward_majority_recall_weight
        )

        if not np.isclose(reward_sum, 1.0):
            raise ValueError(
                "The four reward weights must sum to 1.0."
            )

        # ====================================================
        # Early stopping
        # ====================================================

        self.early_stopping_rounds = int(
            early_stopping_rounds
        )
        self.minimum_improvement = float(
            minimum_improvement
        )

        if self.early_stopping_rounds < 1:
            raise ValueError(
                "early_stopping_rounds must be at least 1."
            )

        # ====================================================
        # Runtime objects
        # ====================================================

        self.random_state = random_state
        self.verbose = bool(verbose)

        self.rng = np.random.default_rng(
            random_state
        )

        self.Q = np.zeros(
            (
                self.num_states,
                self.num_actions,
            ),
            dtype=np.float64,
        )

        self._reset_model_state()

    # ========================================================
    # Model-state management
    # ========================================================

    def _reset_model_state(self):
        self.trees = []
        self.estimator_weights = []

        self.action_history = []
        self.state_history = []
        self.reward_history = []

        self.training_loss_history = []
        self.evaluation_loss_history = []

        self.training_accuracy_history = []
        self.evaluation_accuracy_history = []

        self.training_balanced_accuracy_history = []
        self.evaluation_balanced_accuracy_history = []

        self.training_minority_recall_history = []
        self.evaluation_minority_recall_history = []

        self.training_majority_recall_history = []
        self.evaluation_majority_recall_history = []

        self.validation_selection_score_history = []

        self.classes_ = None
        self.class_to_index_ = None
        self.n_classes_ = None
        self.n_features_in_ = None

        self.class_counts_ = None
        self.class_weights_ = None

        self.minority_class_index_ = None
        self.majority_class_index_ = None
        self.positive_class_index_ = None
        self.negative_class_index_ = None

        self.initial_scores_ = None
        self.classification_threshold_ = 0.5

        self.feature_importances_ = None

        self.best_iteration_ = None
        self.best_validation_score_ = None

        self.is_fitted = False

    # ========================================================
    # Data preparation
    # ========================================================

    @staticmethod
    def _prepare_X(X):
        X = np.asarray(
            X,
            dtype=np.float64,
        )

        if X.ndim != 2:
            raise ValueError(
                f"X must be two-dimensional; got shape {X.shape}."
            )

        return np.nan_to_num(
            X,
            nan=0.0,
            posinf=0.0,
            neginf=0.0,
        )

    @staticmethod
    def _prepare_y(y):
        y = np.asarray(y).reshape(-1)

        if len(y) == 0:
            raise ValueError(
                "y cannot be empty."
            )

        return y

    def _encode_y_fit(self, y):
        self.classes_, y_encoded = np.unique(
            y,
            return_inverse=True,
        )

        self.n_classes_ = len(
            self.classes_
        )

        if self.n_classes_ < 2:
            raise ValueError(
                "Classification requires at least two classes."
            )

        self.class_to_index_ = {
            label: index
            for index, label
            in enumerate(self.classes_)
        }

        self.class_counts_ = np.bincount(
            y_encoded,
            minlength=self.n_classes_,
        ).astype(np.int64)

        self.minority_class_index_ = int(
            np.argmin(self.class_counts_)
        )

        self.majority_class_index_ = int(
            np.argmax(self.class_counts_)
        )

        if self.positive_class is None:
            self.positive_class_index_ = (
                self.minority_class_index_
            )
        else:
            if (
                self.positive_class
                not in self.class_to_index_
            ):
                raise ValueError(
                    f"positive_class={self.positive_class!r} "
                    "does not occur in y."
                )

            self.positive_class_index_ = (
                self.class_to_index_[
                    self.positive_class
                ]
            )

        if self.n_classes_ == 2:
            self.negative_class_index_ = (
                1 - self.positive_class_index_
            )

        return y_encoded.astype(
            np.int64
        )

    def _encode_y_existing(self, y):
        encoded = np.empty(
            len(y),
            dtype=np.int64,
        )

        for index, label in enumerate(y):
            if label not in self.class_to_index_:
                raise ValueError(
                    f"Unknown class in validation data: {label!r}."
                )

            encoded[index] = (
                self.class_to_index_[label]
            )

        return encoded

    # ========================================================
    # Class weighting
    # ========================================================

    def _calculate_class_weights(self):
        if self.class_weight is None:
            return np.ones(
                self.n_classes_,
                dtype=np.float64,
            )

        total_samples = float(
            np.sum(self.class_counts_)
        )

        full_balanced_weights = (
            total_samples
            / (
                self.n_classes_
                * np.maximum(
                    self.class_counts_,
                    1,
                )
            )
        )

        if self.class_weight == "balanced":
            return full_balanced_weights.astype(
                np.float64
            )

        if self.class_weight == "sqrt_balanced":
            moderated_weights = np.sqrt(
                full_balanced_weights
            )

            moderated_weights /= np.min(
                moderated_weights
            )

            return moderated_weights.astype(
                np.float64
            )

        if isinstance(self.class_weight, dict):
            weights = np.ones(
                self.n_classes_,
                dtype=np.float64,
            )

            for original_class, weight in (
                self.class_weight.items()
            ):
                if (
                    original_class
                    not in self.class_to_index_
                ):
                    raise ValueError(
                        "Unknown class in class_weight: "
                        f"{original_class!r}."
                    )

                class_index = (
                    self.class_to_index_[
                        original_class
                    ]
                )

                weights[class_index] = float(
                    weight
                )

            return weights

        raise ValueError(
            "class_weight must be None, 'balanced', "
            "'sqrt_balanced', or a dictionary."
        )

    def _initial_sample_weights(
        self,
        y_encoded,
    ):
        self.class_weights_ = (
            self._calculate_class_weights()
        )

        sample_weights = (
            self.class_weights_[y_encoded]
            .astype(np.float64)
            .copy()
        )

        total_weight = np.sum(
            sample_weights
        )

        if (
            total_weight <= 0
            or not np.isfinite(total_weight)
        ):
            raise ValueError(
                "Invalid initial sample weights."
            )

        sample_weights /= total_weight

        return sample_weights

    def _rebalance_sample_weights(
        self,
        sample_weights,
        y_encoded,
    ):
        """
        Constrain the total boosting mass assigned to the minority class.

        Unlike exact 50/50 balancing, this preserves greater influence
        for the majority class.
        """
        sample_weights = np.asarray(
            sample_weights,
            dtype=np.float64,
        ).copy()

        if self.n_classes_ != 2:
            total = np.sum(
                sample_weights
            )

            if (
                total <= 0
                or not np.isfinite(total)
            ):
                return self._initial_sample_weights(
                    y_encoded
                )

            return sample_weights / total

        minority_mask = (
            y_encoded
            == self.minority_class_index_
        )

        majority_mask = (
            y_encoded
            == self.majority_class_index_
        )

        current_minority_mass = np.sum(
            sample_weights[minority_mask]
        )

        current_majority_mass = np.sum(
            sample_weights[majority_mask]
        )

        desired_minority_mass = (
            self.minority_weight_fraction
        )

        desired_majority_mass = (
            1.0
            - self.minority_weight_fraction
        )

        if current_minority_mass > 0:
            sample_weights[minority_mask] *= (
                desired_minority_mass
                / current_minority_mass
            )

        if current_majority_mass > 0:
            sample_weights[majority_mask] *= (
                desired_majority_mass
                / current_majority_mass
            )

        total_weight = np.sum(
            sample_weights
        )

        if (
            total_weight <= 0
            or not np.isfinite(total_weight)
        ):
            return self._initial_sample_weights(
                y_encoded
            )

        return sample_weights / total_weight

    # ========================================================
    # Initial scores and probabilities
    # ========================================================

    def _calculate_initial_scores(self):
        """
        Blend an empirical prior with a uniform prior.

        prior_strength=1:
            use the empirical class prior.

        prior_strength=0:
            use a uniform prior.

        Values around 0.4-0.7 preserve majority information without
        making the initial model overwhelmingly majority-biased.
        """
        empirical_prior = (
            self.class_counts_.astype(
                np.float64
            )
            / np.sum(self.class_counts_)
        )

        uniform_prior = np.full(
            self.n_classes_,
            1.0 / self.n_classes_,
            dtype=np.float64,
        )

        blended_prior = (
            self.prior_strength
            * empirical_prior
            + (
                1.0
                - self.prior_strength
            )
            * uniform_prior
        )

        blended_prior = np.clip(
            blended_prior,
            1e-12,
            1.0,
        )

        return np.log(
            blended_prior
        )

    @staticmethod
    def _softmax(scores):
        scores = np.asarray(
            scores,
            dtype=np.float64,
        )

        shifted_scores = (
            scores
            - np.max(
                scores,
                axis=1,
                keepdims=True,
            )
        )

        exponentials = np.exp(
            np.clip(
                shifted_scores,
                -700,
                700,
            )
        )

        denominator = np.sum(
            exponentials,
            axis=1,
            keepdims=True,
        )

        return (
            exponentials
            / np.maximum(
                denominator,
                1e-15,
            )
        )

    # ========================================================
    # Metric helpers
    # ========================================================

    def _balanced_log_loss(
        self,
        y_encoded,
        probabilities,
    ):
        probabilities = np.clip(
            np.asarray(
                probabilities,
                dtype=np.float64,
            ),
            1e-15,
            1.0 - 1e-15,
        )

        per_class_losses = []

        for class_index in range(
            self.n_classes_
        ):
            mask = (
                y_encoded
                == class_index
            )

            if not np.any(mask):
                continue

            true_probabilities = (
                probabilities[
                    mask,
                    class_index,
                ]
            )

            per_class_losses.append(
                -float(
                    np.mean(
                        np.log(
                            true_probabilities
                        )
                    )
                )
            )

        if not per_class_losses:
            return 0.0

        return float(
            np.mean(per_class_losses)
        )

    @staticmethod
    def _accuracy(
        y_true,
        y_pred,
    ):
        return float(
            np.mean(
                y_true == y_pred
            )
        )

    def _class_recalls(
        self,
        y_true,
        y_pred,
    ):
        recalls = np.full(
            self.n_classes_,
            np.nan,
            dtype=np.float64,
        )

        for class_index in range(
            self.n_classes_
        ):
            mask = (
                y_true
                == class_index
            )

            support = np.sum(mask)

            if support > 0:
                recalls[class_index] = np.mean(
                    y_pred[mask]
                    == class_index
                )

        return recalls

    def _balanced_accuracy(
        self,
        y_true,
        y_pred,
    ):
        recalls = self._class_recalls(
            y_true,
            y_pred,
        )

        valid = recalls[
            np.isfinite(recalls)
        ]

        if len(valid) == 0:
            return 0.0

        return float(
            np.mean(valid)
        )

    def _minority_recall(
        self,
        y_true,
        y_pred,
    ):
        mask = (
            y_true
            == self.minority_class_index_
        )

        if not np.any(mask):
            return 0.0

        return float(
            np.mean(
                y_pred[mask]
                == self.minority_class_index_
            )
        )

    def _majority_recall(
        self,
        y_true,
        y_pred,
    ):
        mask = (
            y_true
            == self.majority_class_index_
        )

        if not np.any(mask):
            return 0.0

        return float(
            np.mean(
                y_pred[mask]
                == self.majority_class_index_
            )
        )

    # ========================================================
    # RL state and action
    # ========================================================

    def get_state(
        self,
        y_encoded,
        probabilities,
    ):
        """
        State 0 represents a relatively good classifier.
        State 4 represents poor or highly imbalanced performance.
        """
        probabilities = np.asarray(
            probabilities,
            dtype=np.float64,
        )

        predictions = np.argmax(
            probabilities,
            axis=1,
        )

        minority_recall = (
            self._minority_recall(
                y_encoded,
                predictions,
            )
        )

        majority_recall = (
            self._majority_recall(
                y_encoded,
                predictions,
            )
        )

        balanced_accuracy = (
            self._balanced_accuracy(
                y_encoded,
                predictions,
            )
        )

        clipped_probabilities = np.clip(
            probabilities,
            1e-15,
            1.0,
        )

        entropy = -np.sum(
            clipped_probabilities
            * np.log2(
                clipped_probabilities
            ),
            axis=1,
        )

        maximum_entropy = max(
            math.log2(
                self.n_classes_
            ),
            1e-12,
        )

        normalized_entropy = float(
            np.mean(entropy)
            / maximum_entropy
        )

        minority_error = (
            1.0 - minority_recall
        )

        majority_error = (
            1.0 - majority_recall
        )

        balanced_error = (
            1.0 - balanced_accuracy
        )

        difficulty = (
            0.35 * minority_error
            + 0.25 * majority_error
            + 0.25 * balanced_error
            + 0.15 * normalized_entropy
        )

        boundaries = np.array(
            [
                0.12,
                0.25,
                0.42,
                0.62,
            ],
            dtype=np.float64,
        )

        state = np.digitize(
            difficulty,
            bins=boundaries,
            right=True,
        )

        return int(
            np.clip(
                state,
                0,
                self.num_states - 1,
            )
        )

    def select_action(
        self,
        state,
        training=True,
    ):
        if (
            training
            and self.rng.random()
            < self.epsilon
        ):
            return int(
                self.rng.integers(
                    0,
                    self.num_actions,
                )
            )

        q_values = self.Q[state]
        maximum_q = np.max(
            q_values
        )

        best_actions = np.flatnonzero(
            np.isclose(
                q_values,
                maximum_q,
            )
        )

        return int(
            self.rng.choice(
                best_actions
            )
        )

    # ========================================================
    # Score updates
    # ========================================================

    @staticmethod
    def _add_tree_to_scores(
        scores,
        tree_predictions,
        estimator_weight,
    ):
        updated_scores = scores.copy()

        rows = np.arange(
            len(tree_predictions)
        )

        updated_scores[
            rows,
            tree_predictions,
        ] += estimator_weight

        return updated_scores

    def _decision_function_from_estimators(
        self,
        X,
        number_of_estimators=None,
    ):
        X = self._prepare_X(X)

        if (
            self.n_features_in_ is not None
            and X.shape[1]
            != self.n_features_in_
        ):
            raise ValueError(
                f"Expected {self.n_features_in_} features, "
                f"but received {X.shape[1]}."
            )

        scores = np.tile(
            self.initial_scores_,
            (
                len(X),
                1,
            ),
        )

        if number_of_estimators is None:
            number_of_estimators = len(
                self.trees
            )

        for tree, weight in zip(
            self.trees[
                :number_of_estimators
            ],
            self.estimator_weights[
                :number_of_estimators
            ],
        ):
            tree_predictions = (
                tree.predict(X)
            )

            scores = self._add_tree_to_scores(
                scores,
                tree_predictions,
                weight,
            )

        return scores

    # ========================================================
    # Encoded prediction
    # ========================================================

    def _encoded_predictions_from_probabilities(
        self,
        probabilities,
        threshold=None,
    ):
        if self.n_classes_ != 2:
            return np.argmax(
                probabilities,
                axis=1,
            )

        if threshold is None:
            threshold = (
                self.classification_threshold_
            )

        positive_probabilities = (
            probabilities[
                :,
                self.positive_class_index_,
            ]
        )

        return np.where(
            positive_probabilities
            >= threshold,
            self.positive_class_index_,
            self.negative_class_index_,
        ).astype(np.int64)

    # ========================================================
    # Binary threshold metrics
    # ========================================================

    def _binary_metrics_for_threshold(
        self,
        y_encoded,
        probabilities,
        threshold,
    ):
        predictions = (
            self._encoded_predictions_from_probabilities(
                probabilities,
                threshold=threshold,
            )
        )

        positive_index = (
            self.positive_class_index_
        )

        negative_index = (
            self.negative_class_index_
        )

        true_positive = np.sum(
            (y_encoded == positive_index)
            & (predictions == positive_index)
        )

        false_positive = np.sum(
            (y_encoded == negative_index)
            & (predictions == positive_index)
        )

        false_negative = np.sum(
            (y_encoded == positive_index)
            & (predictions == negative_index)
        )

        true_negative = np.sum(
            (y_encoded == negative_index)
            & (predictions == negative_index)
        )

        minority_precision = (
            true_positive
            / max(
                true_positive
                + false_positive,
                1,
            )
        )

        minority_recall = (
            true_positive
            / max(
                true_positive
                + false_negative,
                1,
            )
        )

        majority_recall = (
            true_negative
            / max(
                true_negative
                + false_positive,
                1,
            )
        )

        minority_f1 = (
            2.0
            * minority_precision
            * minority_recall
            / max(
                minority_precision
                + minority_recall,
                1e-15,
            )
        )

        balanced_accuracy = (
            0.5
            * (
                minority_recall
                + majority_recall
            )
        )

        gmean = math.sqrt(
            max(
                minority_recall,
                0.0,
            )
            * max(
                majority_recall,
                0.0,
            )
        )

        return {
            "threshold": float(threshold),
            "minority_precision": float(
                minority_precision
            ),
            "minority_recall": float(
                minority_recall
            ),
            "majority_recall": float(
                majority_recall
            ),
            "minority_f1": float(
                minority_f1
            ),
            "balanced_accuracy": float(
                balanced_accuracy
            ),
            "gmean": float(gmean),
            "true_positive": int(
                true_positive
            ),
            "false_positive": int(
                false_positive
            ),
            "false_negative": int(
                false_negative
            ),
            "true_negative": int(
                true_negative
            ),
        }

    def _select_binary_threshold(
        self,
        y_encoded,
        probabilities,
    ):
        if self.n_classes_ != 2:
            return 0.5

        thresholds = np.linspace(
            self.threshold_min,
            self.threshold_max,
            self.threshold_grid_size,
        )

        candidates = [
            self._binary_metrics_for_threshold(
                y_encoded,
                probabilities,
                threshold,
            )
            for threshold in thresholds
        ]

        if (
            self.threshold_metric
            == "constrained_f1"
        ):
            strict_candidates = [
                candidate
                for candidate in candidates
                if (
                    candidate[
                        "majority_recall"
                    ]
                    >= self.minimum_majority_recall
                    and candidate[
                        "minority_recall"
                    ]
                    >= self.minimum_minority_recall
                )
            ]

            majority_valid_candidates = [
                candidate
                for candidate in candidates
                if (
                    candidate[
                        "majority_recall"
                    ]
                    >= self.minimum_majority_recall
                )
            ]

            if strict_candidates:
                eligible = (
                    strict_candidates
                )

            elif majority_valid_candidates:
                eligible = (
                    majority_valid_candidates
                )

                if self.verbose:
                    print(
                        "No threshold met both recall constraints. "
                        "Using thresholds satisfying the "
                        "majority-recall constraint."
                    )

            else:
                eligible = candidates

                if self.verbose:
                    print(
                        "No threshold met the majority-recall "
                        "constraint. Using the best available "
                        "trade-off."
                    )

            best = max(
                eligible,
                key=lambda item: (
                    item["minority_f1"],
                    item["balanced_accuracy"],
                    item["gmean"],
                    item["majority_recall"],
                    -abs(
                        item["threshold"]
                        - 0.5
                    ),
                ),
            )

        elif (
            self.threshold_metric
            == "balanced_accuracy"
        ):
            best = max(
                candidates,
                key=lambda item: (
                    item["balanced_accuracy"],
                    item["minority_f1"],
                    item["majority_recall"],
                ),
            )

        elif self.threshold_metric == "f1":
            best = max(
                candidates,
                key=lambda item: (
                    item["minority_f1"],
                    item["balanced_accuracy"],
                ),
            )

        else:
            best = max(
                candidates,
                key=lambda item: (
                    item["gmean"],
                    item["balanced_accuracy"],
                ),
            )

        if self.verbose:
            print(
                "Selected binary threshold: "
                f"{best['threshold']:.4f} | "
                f"majority recall="
                f"{best['majority_recall']:.4f} | "
                f"minority recall="
                f"{best['minority_recall']:.4f} | "
                f"minority precision="
                f"{best['minority_precision']:.4f} | "
                f"minority F1="
                f"{best['minority_f1']:.4f} | "
                f"balanced accuracy="
                f"{best['balanced_accuracy']:.4f}"
            )

        return best["threshold"]

    # ========================================================
    # Validation model-selection score
    # ========================================================

    def _validation_selection_score(
        self,
        y_encoded,
        probabilities,
    ):
        """
        Score used to choose the best number of estimators.

        It rewards both class recalls and penalizes models whose
        majority recall falls below the requested constraint.
        """
        predictions = np.argmax(
            probabilities,
            axis=1,
        )

        minority_recall = (
            self._minority_recall(
                y_encoded,
                predictions,
            )
        )

        majority_recall = (
            self._majority_recall(
                y_encoded,
                predictions,
            )
        )

        balanced_accuracy = (
            0.5
            * (
                minority_recall
                + majority_recall
            )
        )

        gmean = math.sqrt(
            max(
                minority_recall,
                0.0,
            )
            * max(
                majority_recall,
                0.0,
            )
        )

        score = (
            0.45 * gmean
            + 0.35 * balanced_accuracy
            + 0.20 * majority_recall
        )

        if (
            majority_recall
            < self.minimum_majority_recall
        ):
            majority_deficit = (
                self.minimum_majority_recall
                - majority_recall
            )

            score -= (
                2.0
                * majority_deficit
            )

        return float(score)

    # ========================================================
    # Fit
    # ========================================================

    def fit(
        self,
        X,
        y,
        X_val=None,
        y_val=None,
    ):
        X = self._prepare_X(X)
        y_original = self._prepare_y(y)

        if len(X) != len(y_original):
            raise ValueError(
                "X and y contain different numbers of samples."
            )

        if (
            X_val is None
        ) != (
            y_val is None
        ):
            raise ValueError(
                "X_val and y_val must either both be supplied "
                "or both be omitted."
            )

        self._reset_model_state()

        self.Q = np.zeros(
            (
                self.num_states,
                self.num_actions,
            ),
            dtype=np.float64,
        )

        self.epsilon = (
            self.initial_epsilon
        )

        self.rng = np.random.default_rng(
            self.random_state
        )

        self.n_features_in_ = (
            X.shape[1]
        )

        y_encoded = self._encode_y_fit(
            y_original
        )

        use_validation = (
            X_val is not None
        )

        if use_validation:
            X_val = self._prepare_X(
                X_val
            )

            y_val_original = (
                self._prepare_y(
                    y_val
                )
            )

            if (
                len(X_val)
                != len(y_val_original)
            ):
                raise ValueError(
                    "X_val and y_val contain different "
                    "numbers of samples."
                )

            if (
                X_val.shape[1]
                != self.n_features_in_
            ):
                raise ValueError(
                    "Training and validation feature counts differ."
                )

            y_val_encoded = (
                self._encode_y_existing(
                    y_val_original
                )
            )
        else:
            y_val_encoded = None

        sample_weights = (
            self._initial_sample_weights(
                y_encoded
            )
        )

        self.initial_scores_ = (
            self._calculate_initial_scores()
        )

        train_scores = np.tile(
            self.initial_scores_,
            (
                len(X),
                1,
            ),
        )

        if use_validation:
            validation_scores = np.tile(
                self.initial_scores_,
                (
                    len(X_val),
                    1,
                ),
            )
        else:
            validation_scores = None

        if self.verbose:
            print(
                "Class counts:",
                self.class_counts_,
            )

            print(
                "Class weights:",
                self.class_weights_,
            )

            print(
                "Minority class:",
                self.classes_[
                    self.minority_class_index_
                ],
            )

            if self.n_classes_ == 2:
                print(
                    "Minority boosting-weight fraction:",
                    f"{self.minority_weight_fraction:.4f}",
                )

        # Initial evaluation state
        if use_validation:
            initial_eval_probabilities = (
                self._softmax(
                    validation_scores
                )
            )

            evaluation_targets = (
                y_val_encoded
            )
        else:
            initial_eval_probabilities = (
                self._softmax(
                    train_scores
                )
            )

            evaluation_targets = (
                y_encoded
            )

        initial_eval_predictions = (
            np.argmax(
                initial_eval_probabilities,
                axis=1,
            )
        )

        previous_evaluation_loss = (
            self._balanced_log_loss(
                evaluation_targets,
                initial_eval_probabilities,
            )
        )

        previous_balanced_accuracy = (
            self._balanced_accuracy(
                evaluation_targets,
                initial_eval_predictions,
            )
        )

        previous_minority_recall = (
            self._minority_recall(
                evaluation_targets,
                initial_eval_predictions,
            )
        )

        previous_majority_recall = (
            self._majority_recall(
                evaluation_targets,
                initial_eval_predictions,
            )
        )

        best_validation_score = -np.inf
        best_number_of_estimators = 0
        rounds_without_improvement = 0

        maximum_allowed_error = (
            1.0
            - 1.0
            / self.n_classes_
        )

        # ====================================================
        # Boosting loop
        # ====================================================

        for estimator_index in range(
            self.n_estimators
        ):
            current_train_probabilities = (
                self._softmax(
                    train_scores
                )
            )

            state = self.get_state(
                y_encoded,
                current_train_probabilities,
            )

            action_index = (
                self.select_action(
                    state,
                    training=True,
                )
            )

            action_multiplier = float(
                self.actions[
                    action_index
                ]
            )

            tree_random_state = (
                None
                if self.random_state is None
                else (
                    self.random_state
                    + estimator_index
                )
            )

            tree = EntropyClassificationTree(
                min_samples=self.min_samples,
                max_depth=self.max_depth,
                min_gain=self.min_gain,
                max_thresholds=self.max_thresholds,
                random_state=tree_random_state,
            )

            tree.fit(
                X,
                y_encoded,
                sample_weight=sample_weights,
                n_classes=self.n_classes_,
            )

            train_tree_predictions = (
                tree.predict(X)
                .astype(np.int64)
            )

            incorrect = (
                train_tree_predictions
                != y_encoded
            )

            weighted_error = float(
                np.sum(
                    sample_weights
                    * incorrect.astype(
                        np.float64
                    )
                )
                / np.sum(
                    sample_weights
                )
            )

            weighted_error = float(
                np.clip(
                    weighted_error,
                    1e-12,
                    1.0 - 1e-12,
                )
            )

            if (
                weighted_error
                >= maximum_allowed_error
            ):
                if self.verbose:
                    print(
                        f"Estimator "
                        f"{estimator_index + 1:03d} skipped | "
                        f"weighted error="
                        f"{weighted_error:.6f} | "
                        f"required < "
                        f"{maximum_allowed_error:.6f}"
                    )

                self.epsilon = max(
                    self.min_epsilon,
                    self.epsilon
                    * self.epsilon_decay,
                )

                continue

            base_estimator_weight = (
                math.log(
                    (
                        1.0
                        - weighted_error
                    )
                    / weighted_error
                )
                + math.log(
                    self.n_classes_
                    - 1.0
                )
            )

            estimator_weight = (
                self.learning_rate
                * action_multiplier
                * base_estimator_weight
            )

            candidate_train_scores = (
                self._add_tree_to_scores(
                    train_scores,
                    train_tree_predictions,
                    estimator_weight,
                )
            )

            candidate_train_probabilities = (
                self._softmax(
                    candidate_train_scores
                )
            )

            candidate_train_predictions = (
                np.argmax(
                    candidate_train_probabilities,
                    axis=1,
                )
            )

            if use_validation:
                validation_tree_predictions = (
                    tree.predict(
                        X_val
                    ).astype(np.int64)
                )

                candidate_validation_scores = (
                    self._add_tree_to_scores(
                        validation_scores,
                        validation_tree_predictions,
                        estimator_weight,
                    )
                )

                evaluation_probabilities = (
                    self._softmax(
                        candidate_validation_scores
                    )
                )

                evaluation_targets = (
                    y_val_encoded
                )
            else:
                candidate_validation_scores = None

                evaluation_probabilities = (
                    candidate_train_probabilities
                )

                evaluation_targets = (
                    y_encoded
                )

            evaluation_predictions = (
                np.argmax(
                    evaluation_probabilities,
                    axis=1,
                )
            )

            # ================================================
            # Current metrics
            # ================================================

            training_loss = (
                self._balanced_log_loss(
                    y_encoded,
                    candidate_train_probabilities,
                )
            )

            evaluation_loss = (
                self._balanced_log_loss(
                    evaluation_targets,
                    evaluation_probabilities,
                )
            )

            training_accuracy = (
                self._accuracy(
                    y_encoded,
                    candidate_train_predictions,
                )
            )

            evaluation_accuracy = (
                self._accuracy(
                    evaluation_targets,
                    evaluation_predictions,
                )
            )

            training_balanced_accuracy = (
                self._balanced_accuracy(
                    y_encoded,
                    candidate_train_predictions,
                )
            )

            evaluation_balanced_accuracy = (
                self._balanced_accuracy(
                    evaluation_targets,
                    evaluation_predictions,
                )
            )

            training_minority_recall = (
                self._minority_recall(
                    y_encoded,
                    candidate_train_predictions,
                )
            )

            evaluation_minority_recall = (
                self._minority_recall(
                    evaluation_targets,
                    evaluation_predictions,
                )
            )

            training_majority_recall = (
                self._majority_recall(
                    y_encoded,
                    candidate_train_predictions,
                )
            )

            evaluation_majority_recall = (
                self._majority_recall(
                    evaluation_targets,
                    evaluation_predictions,
                )
            )

            # ================================================
            # Reward
            # ================================================

            loss_improvement = (
                previous_evaluation_loss
                - evaluation_loss
            ) / max(
                previous_evaluation_loss,
                1e-12,
            )

            balanced_accuracy_improvement = (
                evaluation_balanced_accuracy
                - previous_balanced_accuracy
            )

            minority_recall_improvement = (
                evaluation_minority_recall
                - previous_minority_recall
            )

            majority_recall_improvement = (
                evaluation_majority_recall
                - previous_majority_recall
            )

            reward = (
                self.reward_loss_weight
                * loss_improvement

                + self.reward_balanced_accuracy_weight
                * balanced_accuracy_improvement

                + self.reward_minority_recall_weight
                * minority_recall_improvement

                + self.reward_majority_recall_weight
                * majority_recall_improvement
            )

            # Penalize a large majority-recall violation.
            if (
                evaluation_majority_recall
                < self.minimum_majority_recall
            ):
                reward -= (
                    self.minimum_majority_recall
                    - evaluation_majority_recall
                )

            next_state = self.get_state(
                y_encoded,
                candidate_train_probabilities,
            )

            old_q = self.Q[
                state,
                action_index,
            ]

            future_q = np.max(
                self.Q[
                    next_state
                ]
            )

            temporal_difference_target = (
                reward
                + self.gamma_q
                * future_q
            )

            self.Q[
                state,
                action_index,
            ] = (
                old_q
                + self.alpha_q
                * (
                    temporal_difference_target
                    - old_q
                )
            )

            # ================================================
            # AdaBoost sample-weight update
            # ================================================

            sample_weights *= np.exp(
                np.clip(
                    estimator_weight
                    * incorrect.astype(
                        np.float64
                    ),
                    -50,
                    50,
                )
            )

            sample_weights = (
                self._rebalance_sample_weights(
                    sample_weights,
                    y_encoded,
                )
            )

            # ================================================
            # Accept estimator
            # ================================================

            self.trees.append(tree)

            self.estimator_weights.append(
                estimator_weight
            )

            self.state_history.append(
                state
            )

            self.action_history.append(
                action_index
            )

            self.reward_history.append(
                reward
            )

            self.training_loss_history.append(
                training_loss
            )

            self.evaluation_loss_history.append(
                evaluation_loss
            )

            self.training_accuracy_history.append(
                training_accuracy
            )

            self.evaluation_accuracy_history.append(
                evaluation_accuracy
            )

            self.training_balanced_accuracy_history.append(
                training_balanced_accuracy
            )

            self.evaluation_balanced_accuracy_history.append(
                evaluation_balanced_accuracy
            )

            self.training_minority_recall_history.append(
                training_minority_recall
            )

            self.evaluation_minority_recall_history.append(
                evaluation_minority_recall
            )

            self.training_majority_recall_history.append(
                training_majority_recall
            )

            self.evaluation_majority_recall_history.append(
                evaluation_majority_recall
            )

            train_scores = (
                candidate_train_scores
            )

            if use_validation:
                validation_scores = (
                    candidate_validation_scores
                )

            previous_evaluation_loss = (
                evaluation_loss
            )

            previous_balanced_accuracy = (
                evaluation_balanced_accuracy
            )

            previous_minority_recall = (
                evaluation_minority_recall
            )

            previous_majority_recall = (
                evaluation_majority_recall
            )

            self.epsilon = max(
                self.min_epsilon,
                self.epsilon
                * self.epsilon_decay,
            )

            # ================================================
            # Validation early stopping
            # ================================================

            selection_score = (
                self._validation_selection_score(
                    evaluation_targets,
                    evaluation_probabilities,
                )
            )

            self.validation_selection_score_history.append(
                selection_score
            )

            current_number_of_estimators = len(
                self.trees
            )

            if (
                selection_score
                > best_validation_score
                + self.minimum_improvement
            ):
                best_validation_score = (
                    selection_score
                )

                best_number_of_estimators = (
                    current_number_of_estimators
                )

                rounds_without_improvement = 0
            else:
                rounds_without_improvement += 1

            if self.verbose:
                print(
                    f"Estimator "
                    f"{estimator_index + 1:03d} | "
                    f"state={state} | "
                    f"action="
                    f"{action_multiplier:.2f} | "
                    f"tree error="
                    f"{weighted_error:.6f} | "
                    f"weight="
                    f"{estimator_weight:.6f} | "
                    f"train BA="
                    f"{training_balanced_accuracy:.4f} | "
                    f"eval BA="
                    f"{evaluation_balanced_accuracy:.4f} | "
                    f"eval majority recall="
                    f"{evaluation_majority_recall:.4f} | "
                    f"eval minority recall="
                    f"{evaluation_minority_recall:.4f} | "
                    f"balanced loss="
                    f"{evaluation_loss:.6f} | "
                    f"selection score="
                    f"{selection_score:.6f} | "
                    f"reward="
                    f"{reward:+.6f} | "
                    f"epsilon="
                    f"{self.epsilon:.4f}"
                )

            if (
                use_validation
                and rounds_without_improvement
                >= self.early_stopping_rounds
            ):
                if self.verbose:
                    print(
                        "Early stopping at estimator "
                        f"{estimator_index + 1}. "
                        "Best number of accepted estimators: "
                        f"{best_number_of_estimators}."
                    )

                break

        # ====================================================
        # Validate fitted ensemble
        # ====================================================

        if len(self.trees) == 0:
            raise RuntimeError(
                "No valid weak learner was produced. "
                "Try reducing min_samples or increasing max_depth."
            )

        # If no validation data were supplied, retain every tree.
        if not use_validation:
            best_number_of_estimators = (
                len(self.trees)
            )

            if self.verbose:
                print(
                    "Warning: no validation set was supplied. "
                    "All accepted estimators are retained."
                )

        if best_number_of_estimators <= 0:
            best_number_of_estimators = (
                len(self.trees)
            )

        # Restore the validation-selected ensemble.
        self.trees = self.trees[
            :best_number_of_estimators
        ]

        self.estimator_weights = (
            self.estimator_weights[
                :best_number_of_estimators
            ]
        )

        self.state_history = (
            self.state_history[
                :best_number_of_estimators
            ]
        )

        self.action_history = (
            self.action_history[
                :best_number_of_estimators
            ]
        )

        self.reward_history = (
            self.reward_history[
                :best_number_of_estimators
            ]
        )

        self.best_iteration_ = (
            best_number_of_estimators
        )

        self.best_validation_score_ = (
            best_validation_score
            if np.isfinite(
                best_validation_score
            )
            else None
        )

        # ====================================================
        # Feature importances
        # ====================================================

        self.feature_importances_ = np.zeros(
            self.n_features_in_,
            dtype=np.float64,
        )

        for tree, estimator_weight in zip(
            self.trees,
            self.estimator_weights,
        ):
            tree_importance = getattr(
                tree,
                "feature_importances_",
                None,
            )

            if tree_importance is None:
                continue

            tree_importance = np.asarray(
                tree_importance,
                dtype=np.float64,
            )

            if (
                len(tree_importance)
                != self.n_features_in_
            ):
                continue

            self.feature_importances_ += (
                abs(estimator_weight)
                * tree_importance
            )

        importance_sum = np.sum(
            self.feature_importances_
        )

        if importance_sum > 0:
            self.feature_importances_ /= (
                importance_sum
            )

        # ====================================================
        # Threshold selection
        # ====================================================

        if self.n_classes_ == 2:
            if (
                self.decision_threshold
                == "auto"
            ):
                if use_validation:
                    threshold_scores = (
                        self._decision_function_from_estimators(
                            X_val
                        )
                    )

                    threshold_probabilities = (
                        self._softmax(
                            threshold_scores
                        )
                    )

                    threshold_targets = (
                        y_val_encoded
                    )
                else:
                    threshold_scores = (
                        self._decision_function_from_estimators(
                            X
                        )
                    )

                    threshold_probabilities = (
                        self._softmax(
                            threshold_scores
                        )
                    )

                    threshold_targets = (
                        y_encoded
                    )

                    if self.verbose:
                        print(
                            "Warning: the binary threshold is being "
                            "selected using training data. A separate "
                            "validation set is strongly recommended."
                        )

                self.classification_threshold_ = (
                    self._select_binary_threshold(
                        threshold_targets,
                        threshold_probabilities,
                    )
                )

            else:
                fixed_threshold = float(
                    self.decision_threshold
                )

                if not 0 < fixed_threshold < 1:
                    raise ValueError(
                        "A fixed decision threshold must be "
                        "between 0 and 1."
                    )

                self.classification_threshold_ = (
                    fixed_threshold
                )
        else:
            self.classification_threshold_ = 0.5

        self.is_fitted = True

        if self.verbose:
            print(
                "Classifier fitted with "
                f"{len(self.trees)} estimators."
            )

            if self.n_classes_ == 2:
                print(
                    "Final classification threshold:",
                    f"{self.classification_threshold_:.4f}",
                )

        return self

    # ========================================================
    # Public prediction methods
    # ========================================================

    def decision_function(self, X):
        if not self.is_fitted:
            raise RuntimeError(
                "The model must be fitted before prediction."
            )

        return (
            self._decision_function_from_estimators(
                X
            )
        )

    def predict_proba(self, X):
        scores = self.decision_function(
            X
        )

        return self._softmax(
            scores
        )

    def predict(
        self,
        X,
        threshold=None,
    ):
        probabilities = self.predict_proba(
            X
        )

        if threshold is None:
            threshold = (
                self.classification_threshold_
            )

        encoded_predictions = (
            self._encoded_predictions_from_probabilities(
                probabilities,
                threshold=threshold,
            )
        )

        return self.classes_[
            encoded_predictions
        ]

    def score(
        self,
        X,
        y,
    ):
        y = self._prepare_y(y)
        predictions = self.predict(X)

        if len(predictions) != len(y):
            raise ValueError(
                "Prediction and target lengths differ."
            )

        return float(
            np.mean(
                predictions == y
            )
        )

    # ========================================================
    # Binary evaluation utility
    # ========================================================

    def evaluate_binary(
        self,
        X,
        y,
        threshold=None,
    ):
        if self.n_classes_ != 2:
            raise ValueError(
                "evaluate_binary is available only for "
                "binary classification."
            )

        y_original = self._prepare_y(
            y
        )

        y_encoded = (
            self._encode_y_existing(
                y_original
            )
        )

        probabilities = self.predict_proba(
            X
        )

        if threshold is None:
            threshold = (
                self.classification_threshold_
            )

        return (
            self._binary_metrics_for_threshold(
                y_encoded,
                probabilities,
                threshold,
            )
        )

    # ========================================================
    # Persistence
    # ========================================================

    def save_model(self, filepath):
        filepath = Path(filepath)

        filepath.parent.mkdir(
            parents=True,
            exist_ok=True,
        )

        with open(
            filepath,
            "wb",
        ) as file:
            pickle.dump(
                self,
                file,
            )

    @classmethod
    def load_model(
        cls,
        filepath,
    ):
        filepath = Path(filepath)

        with open(
            filepath,
            "rb",
        ) as file:
            model = pickle.load(
                file
            )

        if not isinstance(
            model,
            cls,
        ):
            raise TypeError(
                f"Expected an object of type {cls.__name__}, "
                f"but loaded {type(model).__name__}."
            )

        return model

# ----------------------------
# Node Classes
# ----------------------------
class Leaf:
    def __init__(self, value):
        self.value = value

    def predict(self, X):
        # Return a constant prediction (leaf value) for all samples
        return np.full(X.shape[0], self.value, dtype=float)


class Split:
    def __init__(self, attribute, threshold, left, right, default_value):
        self.attribute = attribute  # feature index
        self.threshold = threshold
        self.left = left
        self.right = right
        self.default_value = default_value

    def predict(self, X):
        mask = np.isfinite(X[:, self.attribute]) & (X[:, self.attribute] <= self.threshold)
        y_pred = np.full(X.shape[0], self.default_value, dtype=float)

        if mask.any():
            y_pred[mask] = self.left.predict(X[mask])
        if (~mask).any():
            y_pred[~mask] = self.right.predict(X[~mask])
        return y_pred


DecisionTree = Union[Leaf, Split]


# ----------------------------
# Robust Tree Builder
# ----------------------------
def build_tree_id3_regression(X, y, feature_indices=None, min_samples=0, max_depth=5, depth=0) -> DecisionTree:
    # Clean input
    mask = np.isfinite(y) & np.all(np.isfinite(X), axis=1)
    X, y = X[mask], y[mask]

    if len(y) == 0:
        return Leaf(0.0)

    # Stop if depth limit reached or samples too small
    if len(y) <= min_samples or np.all(y == y[0]) or depth >= max_depth:
        return Leaf(np.mean(y))

    if feature_indices is None:
        feature_indices = range(X.shape[1])

    best_feature, best_threshold, best_loss = None, None, float("inf")

    for feature in feature_indices:
        col = X[:, feature]
        if np.all(~np.isfinite(col)) or np.all(col == col[0]):
            continue

        thresholds = np.unique(col[np.isfinite(col)])

        for t in thresholds:
            left_mask = col <= t
            # print("left_mask: ", left_mask)
            right_mask = ~left_mask

            # Skip invalid splits
            if left_mask.sum() == 0 or right_mask.sum() == 0:
                continue

            left_y = y[left_mask]
            # print("left_y: ", left_y)
            right_y = y[right_mask]

            # Skip NaN targets
            if len(left_y) == 0 or len(right_y) == 0:
                continue

            # Variance-based loss
            loss = np.var(left_y) * len(left_y) + np.var(right_y) * len(right_y)
            if not np.isnan(loss) and loss < best_loss:
                best_feature, best_threshold, best_loss = feature, t, loss
                # print("best_feature: ", best_feature)
                # print("best_threshold: ", best_threshold)

    if best_feature is None:
        return Leaf(np.mean(y))

    left_mask = X[:, best_feature] <= best_threshold
    right_mask = ~left_mask

    # Recursive calls
    left_tree = build_tree_id3_regression(X[left_mask], y[left_mask],
                                          feature_indices, min_samples, max_depth, depth + 1)
    right_tree = build_tree_id3_regression(X[right_mask], y[right_mask],
                                           feature_indices, min_samples, max_depth, depth + 1)

    return Split(best_feature, best_threshold, left_tree, right_tree, np.mean(y))


# ----------------------------
# Gradient Boosting (Safe)
# ----------------------------
class RL_GradientBoostingRegressorScratch:
    """
    Gradient Boosting Regressor with a tabular Q-learning agent.

    The RL agent selects a learning-rate multiplier at each
    boosting iteration.

    State:
        Current normalized mean absolute residual.

    Action:
        Multiplier applied to the base learning rate.

    Reward:
        Relative reduction in MAE after adding the new tree.
    """

    def __init__(
            self,
            learning_rate=0.1,
            n_estimators=50,
            min_samples=2,
            max_depth=5,
            actions=None,
            epsilon=0.20,
            epsilon_decay=0.98,
            min_epsilon=0.02,
            alpha_q=0.1,
            gamma_q=0.9,
            random_state=42,
            verbose=True,
    ):
        self.learning_rate = float(learning_rate)
        self.n_estimators = int(n_estimators)
        self.min_samples = int(min_samples)
        self.max_depth = int(max_depth)

        # Learning-rate multipliers
        if actions is None:
            actions = [0.25, 0.5, 1.0, 1.5, 2.0]

        self.actions = np.asarray(actions, dtype=np.float64)

        if np.any(self.actions < 0):
            raise ValueError("All action multipliers must be non-negative.")

        self.num_states = 5
        self.num_actions = len(self.actions)

        # Q-learning parameters
        self.epsilon = float(epsilon)
        self.initial_epsilon = float(epsilon)
        self.epsilon_decay = float(epsilon_decay)
        self.min_epsilon = float(min_epsilon)
        self.alpha_q = float(alpha_q)
        self.gamma_q = float(gamma_q)

        self.random_state = random_state
        self.verbose = verbose

        self.rng = np.random.default_rng(random_state)

        # Model attributes
        self.Q = np.zeros((self.num_states, self.num_actions), dtype=np.float64)

        self.trees = []
        self.step_sizes = []
        self.action_history = []
        self.state_history = []
        self.reward_history = []
        self.training_mae_history = []
        self.evaluation_mae_history = []

        self.init_value = None
        self.target_min = None
        self.target_max = None
        self.target_range = None
        self.is_fitted = False

    def get_state(self, residuals):
        """
        Convert the current residual magnitude into one of five states.

        State 0: very low error
        State 1: low error
        State 2: moderate error
        State 3: high error
        State 4: very high error
        """
        residuals = np.asarray(residuals, dtype=np.float64)

        if residuals.size == 0:
            return 0

        mean_absolute_residual = np.mean(np.abs(residuals))

        target_range = max(float(self.target_range), 1e-12)

        normalized_error = (mean_absolute_residual / target_range)

        state_boundaries = np.array([0.025, 0.05, 0.10, 0.20], dtype=np.float64)

        state = np.digitize(normalized_error, bins=state_boundaries, right=True)

        return int(np.clip(state, 0, self.num_states - 1))

    def select_action(self, state, training=True):
        """
        Select an action using epsilon-greedy exploration.

        During prediction no action selection is needed because
        the selected step size is stored for every trained tree.
        """
        if training and self.rng.random() < self.epsilon:
            return int(self.rng.integers(0, self.num_actions))

        state_q_values = self.Q[state]
        maximum_q = np.max(state_q_values)

        # Random tie-breaking prevents action zero from always
        # being selected when all Q-values are initially equal.
        best_actions = np.flatnonzero(
            np.isclose(
                state_q_values,
                maximum_q,
            )
        )

        return int(self.rng.choice(best_actions))

    def _prepare_X(self, X):
        X = np.asarray(X, dtype=np.float64)

        if X.ndim != 2:
            raise ValueError(f"X must be two-dimensional; got {X.shape}.")

        return np.nan_to_num(X, nan=0.0, posinf=0.0, neginf=0.0)

    def _prepare_y(self, y):
        return np.asarray(y, dtype=np.float64).reshape(-1)

    def fit(self, X, y, X_val=None, y_val=None):
        """
        Fit the RL-enhanced gradient boosting model.

        When validation data is provided, the Q-learning reward is
        calculated from validation MAE. Otherwise, training MAE is used.

        Parameters
        ----------
        X : array-like
            Training features.

        y : array-like
            Training targets.

        X_val : array-like or None
            Optional validation features.

        y_val : array-like or None
            Optional validation targets.

        Returns
        -------
        self
        """
        X = self._prepare_X(X)
        y = self._prepare_y(y)

        if len(X) != len(y):
            raise ValueError(f"X and y lengths differ: {len(X)} != {len(y)}.")

        valid_mask = np.isfinite(y)

        X = X[valid_mask]
        y = y[valid_mask]

        if len(y) == 0:
            raise ValueError(
                "No valid training targets were found."
            )

        use_validation = (X_val is not None and y_val is not None)

        if use_validation:
            X_val = self._prepare_X(X_val)
            y_val = self._prepare_y(y_val)

            if len(X_val) != len(y_val):
                raise ValueError("X_val and y_val have different lengths.")

            valid_val_mask = np.isfinite(y_val)
            X_val = X_val[valid_val_mask]
            y_val = y_val[valid_val_mask]

            if len(y_val) == 0:
                raise ValueError("Validation data contains no valid targets.")

        # Reset the model when fit is called again.
        self.trees = []
        self.step_sizes = []
        self.action_history = []
        self.state_history = []
        self.reward_history = []
        self.training_mae_history = []
        self.evaluation_mae_history = []

        self.Q.fill(0.0)
        self.epsilon = self.initial_epsilon

        self.target_min = float(np.min(y))
        self.target_max = float(np.max(y))
        self.target_range = max(self.target_max - self.target_min, 1e-12, )

        # Weighted mean can be substituted here later if needed.
        self.init_value = float(np.mean(y))

        y_pred = np.full(len(y), self.init_value, dtype=np.float64)

        if use_validation:
            val_pred = np.full(len(y_val), self.init_value, dtype=np.float64)

            previous_evaluation_mae = (mean_absolute_error(y_val, val_pred))
        else:
            previous_evaluation_mae = (mean_absolute_error(y, y_pred))

        for estimator_index in range(self.n_estimators):
            # Gradient of squared-error loss corresponds to residuals.
            residuals = y - y_pred

            state = self.get_state(residuals)

            action_index = self.select_action(state, training=True)

            multiplier = float(self.actions[action_index])

            step_size = (self.learning_rate * multiplier)

            # Bootstrap indices preserve feature-target alignment.
            bootstrap_indices = self.rng.integers(low=0, high=len(X), size=len(X))

            X_bootstrap = X[bootstrap_indices]

            residuals_bootstrap = residuals[bootstrap_indices]

            tree = build_tree_id3_regression(
                X_bootstrap,
                residuals_bootstrap,
                min_samples=self.min_samples,
                max_depth=self.max_depth,
            )

            train_update = tree.predict(X)

            train_update = np.nan_to_num(train_update, nan=0.0, posinf=0.0, neginf=0.0)

            # Correct gradient boosting operation: ADD the tree.
            candidate_train_pred = (y_pred + step_size * train_update)

            # Keep predictions in the known target range.
            candidate_train_pred = np.clip(candidate_train_pred, self.target_min, self.target_max)

            if use_validation:
                val_update = tree.predict(X_val)

                val_update = np.nan_to_num(val_update, nan=0.0, posinf=0.0, neginf=0.0)

                candidate_val_pred = (val_pred + step_size * val_update)

                candidate_val_pred = np.clip(candidate_val_pred, self.target_min, self.target_max)

                current_evaluation_mae = (mean_absolute_error(y_val, candidate_val_pred))
            else:
                current_evaluation_mae = (mean_absolute_error(y, candidate_train_pred))

            # Relative improvement gives rewards a more stable scale.
            denominator = max(previous_evaluation_mae, 1e-12, )

            reward = (previous_evaluation_mae - current_evaluation_mae) / denominator

            next_residuals = (y - candidate_train_pred)

            next_state = self.get_state(next_residuals)

            old_q = self.Q[state, action_index,]

            future_q = np.max(self.Q[next_state])

            temporal_difference_target = (reward + self.gamma_q * future_q)

            self.Q[state, action_index] = (old_q + self.alpha_q * (temporal_difference_target - old_q))

            # Keep the tree and its individual step size.
            self.trees.append(tree)
            self.step_sizes.append(step_size)
            self.state_history.append(state)
            self.action_history.append(action_index)
            self.reward_history.append(reward)

            y_pred = candidate_train_pred

            if use_validation:
                val_pred = candidate_val_pred

            training_mae = mean_absolute_error(y, y_pred)

            self.training_mae_history.append(training_mae)

            self.evaluation_mae_history.append(current_evaluation_mae)

            previous_evaluation_mae = (current_evaluation_mae)

            self.epsilon = max(self.min_epsilon, self.epsilon * self.epsilon_decay)

            if self.verbose:
                print(
                    f"Estimator {estimator_index + 1:03d} | "
                    f"state={state} | "
                    f"action={multiplier:.2f} | "
                    f"step={step_size:.5f} | "
                    f"train MAE={training_mae:.6f} | "
                    f"evaluation MAE="
                    f"{current_evaluation_mae:.6f} | "
                    f"reward={reward:+.6f} | "
                    f"epsilon={self.epsilon:.4f}"
                )

        self.is_fitted = True

        return self

    def predict(self, X):
        """
        Predict using additive boosting updates.

        Each tree uses the effective step size selected by
        the RL agent during training.
        """
        if not self.is_fitted:
            raise RuntimeError("The model must be fitted before prediction.")

        X = self._prepare_X(X)

        prediction = np.full(X.shape[0], self.init_value, dtype=np.float64)

        for tree, step_size in zip(self.trees, self.step_sizes):
            update = tree.predict(X)

            update = np.nan_to_num(update, nan=0.0, posinf=0.0, neginf=0.0, )

            prediction += step_size * update

        prediction = np.clip(prediction, self.target_min, self.target_max)

        return prediction

    def save_model(self, filepath):
        filepath = Path(filepath)
        filepath.parent.mkdir(parents=True, exist_ok=True)

        with open(filepath, "wb") as file:
            pickle.dump(self, file)

    @classmethod
    def load_model(cls, filepath):
        filepath = Path(filepath)

        with open(filepath, "rb") as file:
            model = pickle.load(file)

        if not isinstance(model, cls):
            raise TypeError(
                f"Expected {cls.__name__}, got {type(model).__name__}"
            )
        return model


import numpy as np

from sklearn.ensemble import HistGradientBoostingClassifier
from sklearn.metrics import (
    mean_absolute_error,
    mean_squared_error,
    r2_score,
    accuracy_score,
    precision_score,
    recall_score,
    f1_score,
    confusion_matrix,
    classification_report,
)


def evaluate_low_grade_classifier(classifier, X, y, boundary=1.0, ):
    """
    Evaluate the binary classifier for predicting grade < boundary.

    Class 1 : grade < boundary
    Class 0 : grade >= boundary
    """

    # Binary labels
    # y_train_binary = (y_train < boundary).astype(int)
    # y_test_binary = (y_test < boundary).astype(int)

    # Predictions
    y_pred = classifier.predict(X)
    # test_pred = classifier.predict(X_test)

    # ---------- TRAIN ----------
    print("=" * 70)
    print("PERFORMANCE")
    print("=" * 70)

    print(f"Accuracy : {accuracy_score(y, y_pred):.4f}")
    print(f"Precision: {precision_score(y, y_pred, zero_division=0):.4f}")
    print(f"Recall   : {recall_score(y, y_pred, zero_division=0):.4f}")
    print(f"F1-score : {f1_score(y, y_pred, zero_division=0):.4f}")

    print("\nConfusion Matrix")
    print(confusion_matrix(y, y_pred))

    print("\nClassification Report")
    print(classification_report(y, y_pred,
                                target_names=[
                                    "Grade >= 1.5",
                                    "Grade < 1.5",
                                ],
                                digits=4,
                                zero_division=0,
                                )
          )

def compute_rmse(y_true, y_pred):
    return np.sqrt(np.mean((np.array(y_true) - np.array(y_pred)) ** 2))

def evaluate_model(y_true, y_pred):
    mae = mean_absolute_error(y_true, y_pred)
    rmse = compute_rmse(y_true, y_pred)
    r2 = r2_score(y_true, y_pred)
    return mae, rmse, r2

def convert_grade10_to_grade4(y10):
    is_scalar = np.isscalar(y10)
    y10_arr = np.atleast_1d(y10)
    y4 = np.zeros_like(y10_arr, dtype=float)
    y4 = np.where(y10_arr >= 9.0, 4.0, y4)
    y4 = np.where((y10_arr >= 8.5) & (y10_arr < 9.0), 3.7, y4)
    y4 = np.where((y10_arr >= 8.0) & (y10_arr < 8.5), 3.5, y4)
    y4 = np.where((y10_arr >= 7.0) & (y10_arr < 8.0), 3.0, y4)
    y4 = np.where((y10_arr >= 6.0) & (y10_arr < 7.0), 2.5, y4)
    y4 = np.where((y10_arr >= 5.5) & (y10_arr < 6.0), 2.0, y4)
    y4 = np.where((y10_arr >= 5.0) & (y10_arr < 5.5), 1.5, y4)
    y4 = np.where((y10_arr >= 4.0) & (y10_arr < 5.0), 1.0, y4)
    y4 = np.where(y10_arr < 4.0, 0.0, y4)
    if is_scalar:
        return float(y4[0])
    return y4


def train_on_split(train_path, test_path, args, fac_key, fold_name, models_dir, plots_dir, exclude_cols):
    if not train_path.exists() or not test_path.exists():
        print(f"Skipping {fold_name} - Split files not found.")
        return None

    train_df = pl.read_csv(train_path)
    test_df = pl.read_csv(test_path)

    # Cast target columns to Float64 explicitly, parsing empty strings or invalid strings to null
    train_df = train_df.with_columns([
        pl.col("target_grade10").cast(pl.Float64, strict=False),
        pl.col("target_grade4").cast(pl.Float64, strict=False)
    ])
    test_df = test_df.with_columns([
        pl.col("target_grade10").cast(pl.Float64, strict=False),
        pl.col("target_grade4").cast(pl.Float64, strict=False)
    ])

    # Filter out rows with null values in target column
    train_df = train_df.filter(pl.col(args.target).is_not_null() & pl.col("target_grade4").is_not_null())
    test_df = test_df.filter(pl.col(args.target).is_not_null() & pl.col("target_grade4").is_not_null())

    # Check size threshold
    if len(train_df) < 50:
        print(f"Skipping {fold_name} - Insufficient training samples ({len(train_df)}). Minimum threshold is 50.")
        return None

    # Identify feature columns
    feature_cols = [col for col in train_df.columns if col not in exclude_cols]
    print(f"  {fold_name} Size - Train: {len(train_df)} | Test: {len(test_df)} | Features: {len(feature_cols)}")

    # Cast any string/null feature columns to Float64
    for col in feature_cols:
        if train_df[col].dtype in (pl.String, pl.Null):
            train_df = train_df.with_columns(pl.col(col).cast(pl.Float64, strict=False))
            test_df = test_df.with_columns(pl.col(col).cast(pl.Float64, strict=False))

    # Detect any categorical columns
    cat_cols = [col for col in feature_cols if train_df[col].dtype in (pl.String, pl.Categorical)]

    X_train_pd = pd.DataFrame(train_df.select(feature_cols).to_dict(as_series=False))

    X_test_pd = pd.DataFrame(test_df.select(feature_cols).to_dict(as_series=False))

    # Force convert all non-categorical feature columns to float in Pandas
    for col in feature_cols:
        if col not in cat_cols:
            X_train_pd[col] = pd.to_numeric(X_train_pd[col], errors='coerce').astype(float)
            X_test_pd[col] = pd.to_numeric(X_test_pd[col], errors='coerce').astype(float)

    y_train = train_df[args.target].to_numpy()
    y_test = test_df[args.target].to_numpy()
    y_train_g4 = train_df["target_grade4"].to_numpy()
    y_test_g4 = test_df["target_grade4"].to_numpy()

    # Apply one-hot encoding if categorical features are detected
    if cat_cols:
        encoder = OneHotEncoder(handle_unknown='ignore', sparse_output=False)
        for c in cat_cols:
            X_train_pd[c] = X_train_pd[c].fillna("missing")
            X_test_pd[c] = X_test_pd[c].fillna("missing")

        encoded_train = encoder.fit_transform(X_train_pd[cat_cols])
        encoded_test = encoder.transform(X_test_pd[cat_cols])

        encoded_cols = encoder.get_feature_names_out(cat_cols)
        encoded_train_df = pd.DataFrame(encoded_train, columns=encoded_cols, index=X_train_pd.index)
        encoded_test_df = pd.DataFrame(encoded_test, columns=encoded_cols, index=X_test_pd.index)

        X_train_pd = X_train_pd.drop(columns=cat_cols).join(encoded_train_df)
        X_test_pd = X_test_pd.drop(columns=cat_cols).join(encoded_test_df)
        feature_cols = list(X_train_pd.columns)

    # ================================================================
    # Joint failure-aware classification + heterogeneous regression
    # ================================================================
    # The model supports either target scale:
    #   target_grade10: failure means grade < 4.0, output range [0, 10]
    #   target_grade4 : failure means grade < 1.0, output range [0, 4]
    if args.target == "target_grade10":
        y_model_train = np.asarray(y_train, dtype=np.float64)
        y_model_test = np.asarray(y_test, dtype=np.float64)
        failure_boundary = 4.0
        grade_minimum = 0.0
        grade_maximum = 10.0
    else:
        y_model_train = np.asarray(y_train_g4, dtype=np.float64)
        y_model_test = np.asarray(y_test_g4, dtype=np.float64)
        failure_boundary = 1.0
        grade_minimum = 0.0
        grade_maximum = 4.0

    # Always create an internal validation set from the training fold.
    # The expanding/sliding test fold remains completely untouched.
    internal_val_ratio = (
        float(args.val_ratio)
        if args.val_ratio > 0.0
        else float(TEST_SIZE)
    )
    if not 0.0 < internal_val_ratio < 1.0:
        raise ValueError(
            f"Internal validation ratio must be in (0, 1); "
            f"received {internal_val_ratio}."
        )

    failure_labels = (
        y_model_train < failure_boundary
    ).astype(np.int64)

    unique_failure_classes, failure_counts = np.unique(
        failure_labels,
        return_counts=True,
    )
    if len(unique_failure_classes) != 2:
        raise ValueError(
            f"Both failure and regular samples are required. "
            f"Observed classes={unique_failure_classes.tolist()}, "
            f"counts={failure_counts.tolist()}."
        )

    (
        X_model_train,
        X_model_val,
        y_model_train_internal,
        y_model_val,
    ) = train_test_split(
        X_train_pd,
        y_model_train,
        test_size=internal_val_ratio,
        stratify=failure_labels,
        random_state=42,
    )

    # --------------------------------------------------------------
    # Build the existing class-aware heterogeneous failure classifier.
    # BelowOneRLGradeRegressor is used only as a compatible classifier
    # factory; its old regression stage is not used by the final model.
    # --------------------------------------------------------------
    classifier_factory = BelowOneRLGradeRegressor(
        boundary=failure_boundary,
        low_grade_threshold=None,
        low_class_weight=5.0,
        low_grade_output="classifier_probability",
        classifier_feature_names=feature_cols,

        classifier_n_rounds=30,
        classifier_subspace_sizes=(0.25, 0.40, 0.55),
        classifier_correlation_threshold=0.85,
        classifier_maximum_features_per_cluster=3,
        classifier_exploration_rate=0.20,
        classifier_exploration_decay=0.97,
        classifier_feature_learning_rate=0.35,
        classifier_max_selected_models=5,
        classifier_entropy_bins=16,
        classifier_maximum_missing_fraction=0.90,
        classifier_minimum_unique_values=2,

        stacking_blender_fraction=0.50,
        stacking_include_lightgbm=True,
        stacking_include_hist_gradient_boosting=True,
        stacking_include_full_rl_classifier=True,
        stacking_minimum_majority_recall=0.985,
        stacking_minimum_minority_recall=0.20,
        stacking_reward_minority_f1_weight=0.35,
        stacking_reward_minority_recall_weight=0.30,
        stacking_reward_majority_recall_weight=0.20,
        stacking_reward_balanced_accuracy_weight=0.15,

        classifier_learning_rate=0.05,
        classifier_n_estimators=100,
        classifier_min_samples=10,
        classifier_max_depth=3,
        classifier_min_gain=1e-6,
        classifier_max_thresholds=64,
        classifier_class_weight="sqrt_balanced",
        classifier_minority_weight_fraction=0.25,
        classifier_prior_strength=0.50,
        classifier_early_stopping_rounds=8,
        classifier_minimum_improvement=1e-4,

        # Required only because the factory validates both dependencies.
        rl_learning_rate=N_RATE,
        rl_n_estimators=N_EST,
        rl_min_samples=10,
        rl_max_depth=4,
        rl_actions=[0.25, 0.50, 1.00, 1.50, 2.00],
        regression_lower_bound=failure_boundary,
        regression_upper_bound=grade_maximum,
        rl_classifier_class=RL_GradientBoostingClassifierfromScratch,
        rl_regressor_class=RL_GradientBoostingRegressorScratch,
        random_state=42,
        verbose=True,
    )

    failure_classifier = (
        classifier_factory._build_stacking_classifier()
    )

    # --------------------------------------------------------------
    # Build the original RL grade regressor used as one base expert.
    # It now learns the complete selected target range, not only regular
    # grades, because failure probability is supplied separately.
    # --------------------------------------------------------------
    rl_grade_regressor = RL_GradientBoostingRegressorScratch(
        learning_rate=N_RATE,
        n_estimators=N_EST,
        min_samples=10,
        max_depth=4,
        actions=[0.25, 0.50, 1.00, 1.50, 2.00],
        epsilon=0.20,
        epsilon_decay=0.98,
        min_epsilon=0.02,
        alpha_q=0.10,
        gamma_q=0.90,
        random_state=42,
        verbose=True,
    )

    grade_regressors = build_grade_regressors(
        rl_regressor=rl_grade_regressor,
        random_state=42,
        include_lightgbm=True,
        include_catboost=True,
    )

    print(
        "Available grade regressors:",
        list(grade_regressors.keys()),
    )

    if len(grade_regressors) < 2:
        raise RuntimeError(
            "At least two grade regressors are required. "
            "Check the scikit-learn installation."
        )

    joint_grade_regressor = JointRLStackingGradeRegressor(
        estimators=grade_regressors,
        grade_min=grade_minimum,
        grade_max=grade_maximum,
        blender_fraction=0.50,
        failure_bins=(0.20, 0.50, 0.80),
        disagreement_bins=(0.10, 0.25, 0.50),
        rl_epochs=30,
        rl_alpha=0.20,
        rl_epsilon=0.20,
        rl_epsilon_decay=0.995,
        rl_min_epsilon=0.02,
        random_state=42,
        verbose=True,
    )

    model = JointFailureAwareGradeModel(
        failure_classifier=failure_classifier,
        grade_regressor=joint_grade_regressor,
        failure_boundary=failure_boundary,
        grade_min=grade_minimum,
        grade_max=grade_maximum,
        verbose=True,
    )

    model.fit(
        X_model_train,
        y_model_train_internal,
        X_val=X_model_val,
        y_val=y_model_val,
    )

    # Predictions on internal train/validation and untouched fold test.
    y_pred_internal_train = model.predict(X_model_train)
    y_pred_val = model.predict(X_model_val)
    y_pred_tr = model.predict(X_train_pd)
    y_pred_te = model.predict(X_test_pd)

    mae_internal, rmse_internal, r2_internal = evaluate_model(
        y_model_train_internal,
        y_pred_internal_train,
    )
    mae_val, rmse_val, r2_val = evaluate_model(
        y_model_val,
        y_pred_val,
    )
    mae_tr, rmse_tr, r2_tr = evaluate_model(
        y_model_train,
        y_pred_tr,
    )
    mae_te, rmse_te, r2_te = evaluate_model(
        y_model_test,
        y_pred_te,
    )

    # Optional Grade-4 conversion when training on Grade-10.
    if args.target == "target_grade10" and args.convert_to_grade4:
        y_pred_internal_g4 = convert_grade10_to_grade4(
            y_pred_internal_train
        )
        y_pred_val_g4 = convert_grade10_to_grade4(y_pred_val)
        y_pred_tr_g4 = convert_grade10_to_grade4(y_pred_tr)
        y_pred_te_g4 = convert_grade10_to_grade4(y_pred_te)

        y_internal_g4 = convert_grade10_to_grade4(
            y_model_train_internal
        )
        y_val_g4 = convert_grade10_to_grade4(y_model_val)

        mae_internal_g4, rmse_internal_g4, r2_internal_g4 = (
            evaluate_model(y_internal_g4, y_pred_internal_g4)
        )
        mae_val_g4, rmse_val_g4, r2_val_g4 = evaluate_model(
            y_val_g4,
            y_pred_val_g4,
        )
        mae_tr_g4, rmse_tr_g4, r2_tr_g4 = evaluate_model(
            y_train_g4,
            y_pred_tr_g4,
        )
        mae_te_g4, rmse_te_g4, r2_te_g4 = evaluate_model(
            y_test_g4,
            y_pred_te_g4,
        )
    elif args.target == "target_grade4":
        # Predictions already use the Grade-4 scale.
        y_pred_internal_g4 = y_pred_internal_train
        y_pred_val_g4 = y_pred_val
        y_pred_tr_g4 = y_pred_tr
        y_pred_te_g4 = y_pred_te
        mae_internal_g4, rmse_internal_g4, r2_internal_g4 = (
            mae_internal,
            rmse_internal,
            r2_internal,
        )
        mae_val_g4, rmse_val_g4, r2_val_g4 = (
            mae_val,
            rmse_val,
            r2_val,
        )
        mae_tr_g4, rmse_tr_g4, r2_tr_g4 = (
            mae_tr,
            rmse_tr,
            r2_tr,
        )
        mae_te_g4, rmse_te_g4, r2_te_g4 = (
            mae_te,
            rmse_te,
            r2_te,
        )
    else:
        y_pred_internal_g4 = None
        y_pred_val_g4 = None
        y_pred_tr_g4 = None
        y_pred_te_g4 = None
        mae_internal_g4 = rmse_internal_g4 = r2_internal_g4 = np.nan
        mae_val_g4 = rmse_val_g4 = r2_val_g4 = np.nan
        mae_tr_g4 = rmse_tr_g4 = r2_tr_g4 = np.nan
        mae_te_g4 = rmse_te_g4 = r2_te_g4 = np.nan

    train_size = len(X_model_train)
    val_size = len(X_model_val)

    # Save diagnostic reports from the regression stack.
    base_regressor_report = pd.DataFrame(
        model.grade_regressor_.get_base_model_report()
    )
    base_regressor_report_path = (
        models_dir
        / f"{fac_key}_{fold_name}_base_regressor_report.csv"
    )
    base_regressor_report.to_csv(
        base_regressor_report_path,
        index=False,
    )

    rl_policy_report = pd.DataFrame(
        model.grade_regressor_.get_policy_report()
    )
    rl_policy_report_path = (
        models_dir
        / f"{fac_key}_{fold_name}_joint_rl_policy.csv"
    )
    rl_policy_report.to_csv(
        rl_policy_report_path,
        index=False,
    )

    print(
        "Internal train MAE:",
        f"{mae_internal:.6f}",
    )
    print(
        "Meta-regressor validation MAE:",
        f"{model.grade_regressor_.validation_mae_meta_:.6f}",
    )
    print(
        "Joint-RL validation MAE:",
        f"{model.grade_regressor_.validation_mae_joint_:.6f}",
    )

    # Save model weights
    fold_suffix = f"_{fold_name}" if fold_name != "standard" else ""
    model_path = models_dir / f"{fac_key}{fold_suffix}_joint_model.pkl"
    model.save_model(str(model_path))

    # Print metrics to console
    selected_scale = "Grade 10" if args.target == "target_grade10" else "Grade 4"
    print(f"    Evaluation Metrics for {fold_name}:")
    print(f"      Selected target: {selected_scale}")
    print(f"        Internal Train - MAE: {mae_internal:.4f} | RMSE: {rmse_internal:.4f} | R2: {r2_internal:.4f}")
    print(f"        Full Train     - MAE: {mae_tr:.4f} | RMSE: {rmse_tr:.4f} | R2: {r2_tr:.4f}")
    print(f"        Validation     - MAE: {mae_val:.4f} | RMSE: {rmse_val:.4f} | R2: {r2_val:.4f}")
    print(f"        Test           - MAE: {mae_te:.4f} | RMSE: {rmse_te:.4f} | R2: {r2_te:.4f}")

    if args.target == "target_grade10" and args.convert_to_grade4:
        print("      Converted Grade 4 Scale:")
        print(f"        Internal Train - MAE: {mae_internal_g4:.4f} | RMSE: {rmse_internal_g4:.4f} | R2: {r2_internal_g4:.4f}")
        print(f"        Full Train     - MAE: {mae_tr_g4:.4f} | RMSE: {rmse_tr_g4:.4f} | R2: {r2_tr_g4:.4f}")
        print(f"        Validation     - MAE: {mae_val_g4:.4f} | RMSE: {rmse_val_g4:.4f} | R2: {r2_val_g4:.4f}")
        print(f"        Test           - MAE: {mae_te_g4:.4f} | RMSE: {rmse_te_g4:.4f} | R2: {r2_te_g4:.4f}")

    # Generate predictions on full train set if saving or plotting train distribution
    if args.plot_train_dist or args.save_train_results:
        y_pred_tr_full = y_pred_tr
        if args.target == "target_grade10" and args.convert_to_grade4:
            y_pred_tr_full_g4 = y_pred_tr_g4

    # Plot train distribution
    if args.plot_train_dist:
        if args.target == "target_grade10" and args.convert_to_grade4:
            fig, axes = plt.subplots(2, 2, figsize=(14, 11))

            # Row 0: Grade 10
            bins10 = np.linspace(0, 10, 41)
            axes[0, 0].hist(y_train, bins=bins10, alpha=0.5, label='Actual', color='#2ca02c', edgecolor='k',
                            linewidth=0.5)
            axes[0, 0].hist(y_pred_tr_full, bins=bins10, alpha=0.5, label='Predicted', color='#1f77b4', edgecolor='k',
                            linewidth=0.5)
            axes[0, 0].set_xlabel("Grade (0-10)")
            axes[0, 0].set_ylabel("Count")
            axes[0, 0].set_title("Grade 10 Distribution Comparison (Train)", fontsize=11, fontweight='bold')
            axes[0, 0].legend()
            axes[0, 0].grid(axis='y', linestyle='--', alpha=0.5)

            axes[0, 1].scatter(y_train, y_pred_tr_full, alpha=0.3, color='#1f77b4', edgecolors='none', s=20)
            axes[0, 1].plot([0, 10], [0, 10], 'r--', label='Ideal Fit (y = x)')
            axes[0, 1].set_xlabel("Actual Grade 10")
            axes[0, 1].set_ylabel("Predicted Grade 10")
            axes[0, 1].set_xlim(-0.2, 10.2)
            axes[0, 1].set_ylim(-0.2, 10.2)
            axes[0, 1].set_title("Grade 10 Actual vs Predicted (Train)", fontsize=11, fontweight='bold')
            axes[0, 1].legend()
            axes[0, 1].grid(linestyle='--', alpha=0.5)

            # Row 1: Grade 4
            bins4 = np.linspace(0, 4, 17)
            axes[1, 0].hist(y_train_g4, bins=bins4, alpha=0.5, label='Actual', color='#2ca02c', edgecolor='k',
                            linewidth=0.5)
            axes[1, 0].hist(y_pred_tr_full_g4, bins=bins4, alpha=0.5, label='Predicted', color='#1f77b4', edgecolor='k',
                            linewidth=0.5)
            axes[1, 0].set_xlabel("Grade (0-4)")
            axes[1, 0].set_ylabel("Count")
            axes[1, 0].set_title("Grade 4 Distribution Comparison (Train)", fontsize=11, fontweight='bold')
            axes[1, 0].legend()
            axes[1, 0].grid(axis='y', linestyle='--', alpha=0.5)

            # Add small random jitter for discrete grade4 visualization
            jitter_actual = y_train_g4 + np.random.normal(0, 0.05, size=len(y_train_g4))
            jitter_pred = y_pred_tr_full_g4 + np.random.normal(0, 0.05, size=len(y_pred_tr_full_g4))
            axes[1, 1].scatter(jitter_actual, jitter_pred, alpha=0.3, color='#1f77b4', edgecolors='none', s=20)
            axes[1, 1].plot([0, 4], [0, 4], 'r--', label='Ideal Fit (y = x)')
            axes[1, 1].set_xlabel("Actual Grade 4 (Jittered)")
            axes[1, 1].set_ylabel("Predicted Grade 4 (Jittered)")
            axes[1, 1].set_xlim(-0.2, 4.2)
            axes[1, 1].set_ylim(-0.2, 4.2)
            axes[1, 1].set_title("Grade 4 Actual vs Predicted (Train)", fontsize=11, fontweight='bold')
            axes[1, 1].legend()
            axes[1, 1].grid(linestyle='--', alpha=0.5)

            plt.suptitle(
                f"Train Prediction Analysis - {fac_key} ({fold_name})\nTarget: {args.target} (with Grade 4 conversion)",
                fontsize=13, fontweight='bold')
            plt.tight_layout()
        else:
            fig, axes = plt.subplots(1, 2, figsize=(14, 6))
            target_name = args.target
            is_g10 = (target_name == "target_grade10")
            max_val = 10.0 if is_g10 else 4.0
            bins = np.linspace(0, max_val, 41)

            # Hist
            axes[0].hist(y_train, bins=bins, alpha=0.5, label='Actual', color='#2ca02c', edgecolor='k', linewidth=0.5)
            axes[0].hist(y_pred_tr_full, bins=bins, alpha=0.5, label='Predicted', color='#1f77b4', edgecolor='k',
                         linewidth=0.5)
            axes[0].set_xlabel(f"Grade ({'0-10' if is_g10 else '0-4'})")
            axes[0].set_ylabel("Count")
            axes[0].set_title("Distribution Comparison (Train)", fontsize=11, fontweight='bold')
            axes[0].legend()
            axes[0].grid(axis='y', linestyle='--', alpha=0.5)

            # Scatter
            axes[1].scatter(y_train, y_pred_tr_full, alpha=0.3, color='#1f77b4', edgecolors='none', s=20)
            axes[1].plot([0, max_val], [0, max_val], 'r--', label='Ideal Fit (y = x)')
            axes[1].set_xlabel("Actual Grade")
            axes[1].set_ylabel("Predicted Grade")
            axes[1].set_xlim(-0.2, max_val + 0.2)
            axes[1].set_ylim(-0.2, max_val + 0.2)
            axes[1].set_title("Actual vs Predicted (Train)", fontsize=11, fontweight='bold')
            axes[1].legend()
            axes[1].grid(linestyle='--', alpha=0.5)

            plt.suptitle(
                f"Train Prediction Analysis - {fac_key} ({fold_name})\nTarget: {target_name} | RMSE: {compute_rmse(y_train, y_pred_tr_full):.4f}",
                fontsize=13, fontweight='bold')
            plt.tight_layout()

        dist_plot_path = plots_dir / f"{fac_key}{fold_suffix}_train_dist.png"
        plt.savefig(dist_plot_path, dpi=150)
        plt.close()
        print(f"      Saved train distribution plot to {dist_plot_path}")

    # Save train results
    if args.save_train_results:
        train_results_df = pl.DataFrame({
            "IDSV": train_df["IDSV"],
            "IDMH": train_df["IDMH"],
            "target_NHHK": train_df["target_NHHK"],
            "target_grade10": train_df["target_grade10"],
            "target_grade4": train_df["target_grade4"]
        })
        if args.target == "target_grade10":
            train_results_df = train_results_df.with_columns([
                pl.Series("prediction_grade10", y_pred_tr_full)
            ])
            if args.convert_to_grade4:
                train_results_df = train_results_df.with_columns([
                    pl.Series("prediction_grade4", y_pred_tr_full_g4)
                ])
        else:
            train_results_df = train_results_df.with_columns([
                pl.Series("prediction_grade4", y_pred_tr_full)
            ])

        train_results_path = models_dir / f"{fac_key}{fold_suffix}_train_results.csv"
        train_results_df.write_csv(train_results_path)
        print(f"      Saved train results to {train_results_path}")

    # Save test results
    test_results_df = pl.DataFrame({
        "IDSV": test_df["IDSV"],
        "IDMH": test_df["IDMH"],
        "target_NHHK": test_df["target_NHHK"],
        "target_grade10": test_df["target_grade10"],
        "target_grade4": test_df["target_grade4"]
    })

    if args.target == "target_grade10":
        test_results_df = test_results_df.with_columns([
            pl.Series("prediction_grade10", y_pred_te)
        ])
        if args.convert_to_grade4:
            test_results_df = test_results_df.with_columns([
                pl.Series("prediction_grade4", y_pred_te_g4)
            ])
    else:
        test_results_df = test_results_df.with_columns([
            pl.Series("prediction_grade4", y_pred_te)
        ])

    test_results_path = models_dir / f"{fac_key}{fold_suffix}_test_results.csv"
    test_results_df.write_csv(test_results_path)
    print(f"      Saved test results to {test_results_path}")

    return {
        "fold": fold_name,
        "train_size": train_size,
        "val_size": val_size,
        "internal_train_mae": mae_internal,
        "internal_train_rmse": rmse_internal,
        "internal_train_r2": r2_internal,
        "meta_validation_mae": model.grade_regressor_.validation_mae_meta_,
        "joint_rl_validation_mae": model.grade_regressor_.validation_mae_joint_,
        "test_size": len(X_test_pd),
        "train_mae": mae_tr,
        "train_rmse": rmse_tr,
        "train_r2": r2_tr,
        "val_mae": mae_val,
        "val_rmse": rmse_val,
        "val_r2": r2_val,
        "test_mae": mae_te,
        "test_rmse": rmse_te,
        "test_r2": r2_te,
        "train_mae_g4": mae_tr_g4,
        "train_rmse_g4": rmse_tr_g4,
        "train_r2_g4": r2_tr_g4,
        "val_mae_g4": mae_val_g4,
        "val_rmse_g4": rmse_val_g4,
        "val_r2_g4": r2_val_g4,
        "test_mae_g4": mae_te_g4,
        "test_rmse_g4": rmse_te_g4,
        "test_r2_g4": r2_te_g4
    }


def run_training_for_config(strategy, exclude_t_minus_1, args, exclude_cols):
    t_minus_1_dir = "exclude_t_1" if exclude_t_minus_1 else "include_t_1"

    splits_base = Path(ROOT) / args.splits_dir / t_minus_1_dir / strategy
    models_dir = ROOT / args.models_dir / t_minus_1_dir / strategy
    plots_dir = ROOT / args.plots_dir / t_minus_1_dir / strategy

    os.makedirs(models_dir, exist_ok=True)
    os.makedirs(plots_dir, exist_ok=True)

    print("-" * 60)
    print(f"Executing Joint Failure-Aware Stacking configuration:")
    print(f"  Strategy: {strategy}")
    print(f"  Splits Base: {splits_base}")
    print(f"  Models Dir: {models_dir}")
    print(f"  Exclude T-1: {exclude_t_minus_1}")

    if not splits_base.exists():
        print(f"Error: Splits directory not found at {splits_base}")
        return

    # Identify all unique faculty names in splits
    fold_dirs = list(splits_base.glob("fold_*"))
    if not fold_dirs:
        print(f"No fold subdirectories found in {splits_base}")
        return
    train_files = list(fold_dirs[0].glob("*_train.csv"))
    faculties = {f.name.replace("_train.csv", "") for f in train_files}

    if args.faculty != "all":
        if args.faculty not in faculties:
            print(f"Warning: Faculty key '{args.faculty}' not found in splits. Skipping this configuration.")
            return
        faculties = {args.faculty}

    print(f"Processing faculties: {list(faculties)}")

    results = []

    for fac_key in faculties:
        print(f"  Faculty: {fac_key}")
        fac_results = []

        fold_dirs = sorted(list(splits_base.glob("fold_*")), key=lambda x: int(x.name.split("_")[1]))
        for fold_dir in fold_dirs:
            fold_name = fold_dir.name
            train_path = fold_dir / f"{fac_key}_train.csv"
            test_path = fold_dir / f"{fac_key}_test.csv"

            res = train_on_split(train_path, test_path, args, fac_key, fold_name, models_dir, plots_dir, exclude_cols)
            if res:
                fac_results.append(res)

        if not fac_results:
            continue

        df_res = pl.DataFrame(fac_results)
        metrics_path = models_dir / f"{fac_key}_metrics_summary.csv"
        df_res.write_csv(metrics_path)

        for r in fac_results:
            r["faculty"] = fac_key
            results.append(r)

    if results:
        summary_df = pl.DataFrame(results)
        summary_path = models_dir / "overall_evaluation_summary.csv"

        if summary_path.exists():
            print(f"  Existing performance summary found at {summary_path}. Performing non-destructive update...")
            try:
                existing_df = pl.read_csv(summary_path)
                trained_facs = summary_df["faculty"].unique().to_list()
                existing_df_filtered = existing_df.filter(~pl.col("faculty").is_in(trained_facs))
                summary_df = pl.concat([existing_df_filtered, summary_df], how="diagonal")
            except Exception as e:
                print(f"  Warning: Could not merge with existing summary: {e}. Overwriting instead.")

        summary_df.write_csv(summary_path)
        print(f"Consolidated performance summary saved to {summary_path}")


def parse_args():
    parser = argparse.ArgumentParser(
        description="Joint failure-aware stacking training pipeline (expanding/sliding CV)")
    parser.add_argument(
        "--strategy",
        type=str,
        default="all",
        choices=["all", "expanding", "sliding"],
        help="Temporal partitioning strategy of splits to train on or 'all' to run both."
    )
    parser.add_argument(
        "--exclude_t_minus_1",
        action="store_true",
        help="Train models on splits that excluded the T-1 semester."
    )
    parser.add_argument(
        "--splits_dir",
        type=str,
        default="dataset/splits",
        help="Input splits folder containing train/test splits."
    )
    parser.add_argument(
        "--faculty",
        type=str,
        default="all",
        help="Faculty key to train (e.g. 'khoa_cong_nghe_thong_tin') or 'all' to train for all faculties."
    )
    parser.add_argument(
        "--target",
        type=str,
        default=TARGET,
        choices=["target_grade10", "target_grade4"],
        help="Target column variable for regression."
    )
    parser.add_argument(
        "--convert_to_grade4",
        action="store_true",
        help="Convert grade 10 predictions to grade 4 and evaluate on target_grade4."
    )
    parser.add_argument(
        "--val_ratio",
        type=float,
        default=0.0,
        help="Fraction of training data to randomly hold out for validation/early stopping. Set to 0 to disable."
    )
    parser.add_argument(
        "--n_estimators",
        type=int,
        default=None,
        help="Number of trees. Defaults to 1000 if using early stopping, or 150 if not."
    )
    parser.add_argument(
        "--early_stopping",
        type=int,
        default=50,
        help="Number of early stopping rounds."
    )
    parser.add_argument(
        "--models_dir",
        type=str,
        default="results/rl_gb/" + f"{N_RATE}/{N_EST}/v11_joint_failure_aware_v1/{TEST_SIZE}/{TARGET}",
        help="Directory where trained models and summaries will be saved."
    )
    parser.add_argument(
        "--plots_dir",
        type=str,
        default="results/plots",
        help="Directory where feature importance plots will be saved."
    )
    parser.add_argument(
        "--no_run_all",
        action="store_true",
        help="Disable training models sequentially on all configurations."
    )
    parser.add_argument(
        "--plot_train_dist",
        action="store_true",
        help="Plot the distribution of actual vs predicted target values for the train data."
    )
    parser.add_argument(
        "--save_train_results",
        action="store_true",
        help="Save the numerical prediction results of the train data to a CSV file."
    )
    return parser.parse_args()


def main():
    args = parse_args()

    exclude_cols = {
        "dataset_split",
        "student_faculty_key",
        "student_faculty_name",
        "IDSV",
        "target_NHHK",
        "target_semester_ordinal",
        "is_summer_target",
        "IDKQDK",
        "IDToHoc",
        "IDMH",
        "target_IDCongDiem",
        "target_grade10",
        "target_grade4",
        "target_status",
        "base_row_id",
        "course_cluster_label"
    }

    # Check if a custom parameter was specified
    is_custom_splits = args.splits_dir != "dataset/splits"
    is_custom_models = args.models_dir != "results"
    is_custom_plots = args.plots_dir != "results/plots"
    is_single_run = args.exclude_t_minus_1 or is_custom_splits or is_custom_models or is_custom_plots or args.no_run_all or args.strategy != "all"

    if is_single_run:
        strategy_to_run = "expanding" if args.strategy == "all" else args.strategy
        run_training_for_config(
            strategy=strategy_to_run,
            exclude_t_minus_1=args.exclude_t_minus_1,
            args=args,
            exclude_cols=exclude_cols
        )
    else:
        # Run all combinations sequentially (2 strategies x 2 lag options)
        combinations = [
            ("expanding", False),
            ("expanding", True),
            ("sliding", False),
            ("sliding", True)
        ]

        for strategy, excl_t in combinations:
            print("\n" + "=" * 80)
            print(f"Executing Model Training: Strategy={strategy}, T-1={excl_t}")
            print("=" * 80)
            run_training_for_config(
                strategy=strategy,
                exclude_t_minus_1=excl_t,
                args=args,
                exclude_cols=exclude_cols
            )


if __name__ == "__main__":
    main()

