# -*- coding: utf-8 -*-
"""
final_train.py

Final failure-aware grade training pipeline. The model architecture is preserved
from 11_train_joint_failure_aware_v1.py. This driver is adapted to the fold
layout used by test2.py:

    data/splits/<strategy>/fold_<n>/<faculty>_{train,test}.csv

Operational warning definition:
    target_grade10 < 5.0  (failure/warning)
    target_grade10 >= 5.0 (normal)

When target_grade4 is selected, the equivalent boundary is 1.5.

The script reports two warning signals for every fold:
  1. Regression-derived warning: predicted grade < the failure boundary.
  2. Failure-classifier warning: P(failure) >= the model's learned threshold.

Both reports include AP, ROC-AUC, accuracy, precision, recall, specificity, F1,
flag rate, and a labelled confusion matrix. Predictions and metrics are saved.
"""

# 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 numpy as np
import pandas as pd
import random
from pathlib import Path
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

import pickle
from pathlib import Path

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



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

TARGET = "target_grade10"

ROOT = Path(__file__).resolve().parent

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


# ============================================================================
# Runnable fold driver and test2-style warning evaluation
# ============================================================================

from dataclasses import dataclass
from typing import Dict, Iterable, List, Optional, Sequence, Tuple

from sklearn.metrics import (
    average_precision_score,
    confusion_matrix,
    mean_absolute_error,
    precision_recall_fscore_support,
    r2_score,
    roc_auc_score,
)


DEFAULT_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",
}

IDENTIFIER_COLUMNS = [
    "IDSV",
    "IDMH",
    "IDKQDK",
    "IDToHoc",
    "target_NHHK",
    "target_semester_ordinal",
    "student_faculty_key",
    "student_faculty_name",
]


@dataclass
class LoadedFold:
    X_train: pd.DataFrame
    X_test: pd.DataFrame
    y_train: np.ndarray
    y_test: np.ndarray
    train_frame: pd.DataFrame
    test_frame: pd.DataFrame
    feature_names: List[str]


@dataclass
class FoldWarningRecord:
    fold: int
    y_failure: np.ndarray
    regression_score: np.ndarray
    regression_warning: np.ndarray
    classifier_score: np.ndarray
    classifier_warning: np.ndarray
    classifier_threshold: float


def seed_everything(seed: int = 42) -> None:
    """Seed all random generators used directly by this script."""
    random.seed(seed)
    np.random.seed(seed)


def failure_boundary_for_target(target: str) -> float:
    """Return the project warning boundary for the selected target scale."""
    if target == "target_grade10":
        return 5.0
    if target == "target_grade4":
        return 1.5
    raise ValueError(
        f"Unsupported target {target!r}. Expected target_grade10 or target_grade4."
    )


def grade_range_for_target(target: str) -> Tuple[float, float]:
    if target == "target_grade10":
        return 0.0, 10.0
    if target == "target_grade4":
        return 0.0, 4.0
    raise ValueError(f"Unsupported target {target!r}.")


def resolve_splits_dir(path: Union[str, Path], strategy: str) -> Path:
    """Resolve either a direct strategy directory, a splits root, or a repo root."""
    raw = Path(path).expanduser()
    candidates = [
        raw,
        raw / strategy,
        raw / "data" / "splits" / strategy,
    ]
    for candidate in candidates:
        if candidate.exists() and candidate.is_dir():
            # Prefer a directory that is already a strategy folder or contains folds.
            if candidate.name == strategy or any(candidate.glob("fold_*")):
                return candidate.resolve()
    # Return the most natural strategy path in the error message.
    return (raw / strategy).resolve() if raw.name != strategy else raw.resolve()


def list_faculties(splits_dir: Path) -> List[str]:
    faculties = set()
    for fold_dir in sorted(splits_dir.glob("fold_*")):
        for path in fold_dir.glob("*_train.csv"):
            faculties.add(path.name[: -len("_train.csv")])
    return sorted(faculties)


def parse_folds(spec: str, splits_dir: Path) -> List[int]:
    if spec.strip().lower() == "all":
        folds = []
        for path in splits_dir.glob("fold_*"):
            try:
                folds.append(int(path.name.split("_", 1)[1]))
            except (IndexError, ValueError):
                continue
        return sorted(folds)

    folds: List[int] = []
    for value in spec.split(","):
        value = value.strip()
        if not value:
            continue
        fold = int(value)
        if fold <= 0:
            raise ValueError(f"Fold numbers must be positive; received {fold}.")
        folds.append(fold)
    if not folds:
        raise ValueError("No folds were selected.")
    return folds


def _coerce_target_columns(frame: pd.DataFrame) -> pd.DataFrame:
    frame = frame.copy()
    for column in ("target_grade10", "target_grade4"):
        if column in frame.columns:
            frame[column] = pd.to_numeric(frame[column], errors="coerce")
    return frame


def _prepare_features(
    train_frame: pd.DataFrame,
    test_frame: pd.DataFrame,
    feature_names: Sequence[str],
) -> Tuple[pd.DataFrame, pd.DataFrame, List[str]]:
    """Fit all feature transformations on train only and apply them to test."""
    X_train = train_frame.loc[:, feature_names].copy()
    X_test = test_frame.reindex(columns=feature_names).copy()

    categorical = [
        column
        for column in feature_names
        if (
            pd.api.types.is_object_dtype(X_train[column])
            or isinstance(X_train[column].dtype, pd.CategoricalDtype)
            or pd.api.types.is_string_dtype(X_train[column])
        )
    ]
    numeric = [column for column in feature_names if column not in categorical]

    for column in numeric:
        X_train[column] = pd.to_numeric(X_train[column], errors="coerce")
        X_test[column] = pd.to_numeric(X_test[column], errors="coerce")

    if categorical:
        encoder = OneHotEncoder(
            handle_unknown="ignore",
            sparse_output=False,
            dtype=np.float64,
        )
        train_cat = X_train[categorical].astype("string").fillna("__MISSING__")
        test_cat = X_test[categorical].astype("string").fillna("__MISSING__")
        encoded_train = encoder.fit_transform(train_cat)
        encoded_test = encoder.transform(test_cat)
        encoded_names = encoder.get_feature_names_out(categorical).tolist()

        X_train_numeric = X_train[numeric].reset_index(drop=True)
        X_test_numeric = X_test[numeric].reset_index(drop=True)
        X_train_encoded = pd.DataFrame(encoded_train, columns=encoded_names)
        X_test_encoded = pd.DataFrame(encoded_test, columns=encoded_names)
        X_train = pd.concat([X_train_numeric, X_train_encoded], axis=1)
        X_test = pd.concat([X_test_numeric, X_test_encoded], axis=1)
    else:
        X_train = X_train[numeric].reset_index(drop=True)
        X_test = X_test[numeric].reset_index(drop=True)

    # Match test2.py: train-mean imputation, then zero for all-null train columns.
    train_means = X_train.mean(axis=0, numeric_only=True)
    X_train = X_train.fillna(train_means).fillna(0.0)
    X_test = X_test.fillna(train_means).fillna(0.0)

    X_train = X_train.astype(np.float64)
    X_test = X_test.astype(np.float64)

    if list(X_train.columns) != list(X_test.columns):
        raise RuntimeError("Train and test feature columns are not aligned.")
    if not np.isfinite(X_train.to_numpy()).all():
        raise ValueError("Non-finite values remain in training features.")
    if not np.isfinite(X_test.to_numpy()).all():
        raise ValueError("Non-finite values remain in test features.")

    return X_train, X_test, list(X_train.columns)


def load_fold_data(
    faculty: str,
    fold: int,
    splits_dir: Path,
    target: str,
    exclude_cols: Iterable[str] = DEFAULT_EXCLUDE_COLS,
) -> Optional[LoadedFold]:
    """Load one fold using the exact directory structure used by test2.py."""
    fold_dir = Path(splits_dir) / f"fold_{fold}"
    train_path = fold_dir / f"{faculty}_train.csv"
    test_path = fold_dir / f"{faculty}_test.csv"
    if not train_path.exists() or not test_path.exists():
        return None

    train_frame = _coerce_target_columns(
        pd.read_csv(train_path, low_memory=False)
    )
    test_frame = _coerce_target_columns(
        pd.read_csv(test_path, low_memory=False)
    )

    if target not in train_frame.columns or target not in test_frame.columns:
        raise KeyError(f"Target column {target!r} is missing from fold {fold}.")

    required_targets = [target]
    if "target_grade4" in train_frame.columns and "target_grade4" in test_frame.columns:
        required_targets.append("target_grade4")

    train_frame = train_frame.dropna(subset=required_targets).reset_index(drop=True)
    test_frame = test_frame.dropna(subset=required_targets).reset_index(drop=True)

    if len(train_frame) < 50:
        return None

    excluded = set(exclude_cols)
    feature_names = [
        column for column in train_frame.columns if column not in excluded
    ]
    if not feature_names:
        raise ValueError(f"No feature columns remain for fold {fold}.")

    X_train, X_test, transformed_names = _prepare_features(
        train_frame,
        test_frame,
        feature_names,
    )

    y_train = train_frame[target].to_numpy(dtype=np.float64)
    y_test = test_frame[target].to_numpy(dtype=np.float64)
    if not np.isfinite(y_train).all() or not np.isfinite(y_test).all():
        raise ValueError(f"Non-finite target values remain in fold {fold}.")

    return LoadedFold(
        X_train=X_train,
        X_test=X_test,
        y_train=y_train,
        y_test=y_test,
        train_frame=train_frame,
        test_frame=test_frame,
        feature_names=transformed_names,
    )


def compute_rmse(y_true: np.ndarray, y_pred: np.ndarray) -> float:
    y_true = np.asarray(y_true, dtype=np.float64)
    y_pred = np.asarray(y_pred, dtype=np.float64)
    return float(np.sqrt(np.mean((y_true - y_pred) ** 2)))


def regression_metrics(y_true: np.ndarray, y_pred: np.ndarray) -> Dict[str, float]:
    return {
        "mae": float(mean_absolute_error(y_true, y_pred)),
        "rmse": compute_rmse(y_true, y_pred),
        "r2": float(r2_score(y_true, y_pred)),
    }


def safe_average_precision(y_failure: np.ndarray, score: np.ndarray) -> float:
    y_failure = np.asarray(y_failure, dtype=np.int64).reshape(-1)
    score = np.asarray(score, dtype=np.float64).reshape(-1)
    if np.unique(y_failure).size < 2:
        return float("nan")
    return float(average_precision_score(y_failure, score))


def safe_roc_auc(y_failure: np.ndarray, score: np.ndarray) -> float:
    y_failure = np.asarray(y_failure, dtype=np.int64).reshape(-1)
    score = np.asarray(score, dtype=np.float64).reshape(-1)
    if np.unique(y_failure).size < 2:
        return float("nan")
    return float(roc_auc_score(y_failure, score))


def binary_warning_metrics(
    y_failure: np.ndarray,
    warning: np.ndarray,
) -> Dict[str, float]:
    """Compute failure-positive metrics with matrix order [[TN, FP], [FN, TP]]."""
    y_failure = np.asarray(y_failure, dtype=np.int64).reshape(-1)
    warning = np.asarray(warning, dtype=np.int64).reshape(-1)
    if y_failure.shape != warning.shape:
        raise ValueError("y_failure and warning must have identical shapes.")

    tn, fp, fn, tp = confusion_matrix(
        y_failure,
        warning,
        labels=[0, 1],
    ).ravel()
    precision, recall, f1, _ = precision_recall_fscore_support(
        y_failure,
        warning,
        average="binary",
        pos_label=1,
        zero_division=0,
    )
    total = int(tn + fp + fn + tp)
    specificity = float(tn / (tn + fp)) if (tn + fp) else float("nan")
    accuracy = float((tn + tp) / total) if total else float("nan")
    flag_rate = float((tp + fp) / total) if total else float("nan")

    return {
        "tn": int(tn),
        "fp": int(fp),
        "fn": int(fn),
        "tp": int(tp),
        "accuracy": accuracy,
        "precision": float(precision),
        "recall": float(recall),
        "specificity": specificity,
        "f1": float(f1),
        "flag_rate": flag_rate,
    }


def warning_report(
    y_failure: np.ndarray,
    score: np.ndarray,
    warning: np.ndarray,
) -> Dict[str, float]:
    report = binary_warning_metrics(y_failure, warning)
    report["average_precision"] = safe_average_precision(y_failure, score)
    report["roc_auc"] = safe_roc_auc(y_failure, score)
    report["prevalence"] = float(np.mean(np.asarray(y_failure, dtype=np.float64)))
    report["n_samples"] = int(len(y_failure))
    return report


def _fmt(value: float) -> str:
    return "nan" if not np.isfinite(value) else f"{value:.4f}"


def print_confusion_matrix(
    title: str,
    metrics: Dict[str, float],
    boundary_label: str = "5",
) -> None:
    tn = int(metrics["tn"])
    fp = int(metrics["fp"])
    fn = int(metrics["fn"])
    tp = int(metrics["tp"])
    normal_total = tn + fp
    failure_total = fn + tp
    normal_correct = 100.0 * tn / normal_total if normal_total else float("nan")
    failure_detected = 100.0 * tp / failure_total if failure_total else float("nan")

    print(f"\n  Confusion matrix — {title}")
    print("  " + "-" * 66)
    print(
        f"  {'Actual / Predicted':<24}"
        f"{f'Normal >={boundary_label}':>16}"
        f"{f'Failure <{boundary_label}':>16}"
    )
    print("  " + "-" * 66)
    print(f"  {f'Normal >={boundary_label}':<24}{tn:>16,d}{fp:>16,d}")
    print(f"  {f'Failure <{boundary_label}':<24}{fn:>16,d}{tp:>16,d}")
    print("  " + "-" * 66)
    print(f"  Normal correctly rejected: {normal_correct:.2f}%")
    print(f"  Failures successfully detected: {failure_detected:.2f}%")


def print_warning_report(
    title: str,
    report: Dict[str, float],
    boundary_label: str,
    threshold_description: str,
) -> None:
    print("\n" + "=" * 92)
    print(title)
    print("=" * 92)
    print(f"  Decision rule : {threshold_description}")
    print(f"  Samples       : {int(report['n_samples']):,}")
    print(f"  Failure base  : {100.0 * report['prevalence']:.2f}%")
    print(f"  Flag rate     : {100.0 * report['flag_rate']:.2f}%")
    print(f"  AP            : {_fmt(report['average_precision'])}")
    print(f"  ROC-AUC       : {_fmt(report['roc_auc'])}")
    print(f"  Accuracy      : {_fmt(report['accuracy'])}")
    print(f"  Precision     : {_fmt(report['precision'])}")
    print(f"  Recall        : {_fmt(report['recall'])}")
    print(f"  Specificity   : {_fmt(report['specificity'])}")
    print(f"  F1-score      : {_fmt(report['f1'])}")
    print_confusion_matrix(title, report, boundary_label=boundary_label)


def convert_grade10_to_grade4(y10: Union[float, np.ndarray]) -> Union[float, np.ndarray]:
    is_scalar = np.isscalar(y10)
    y10_arr = np.atleast_1d(np.asarray(y10, dtype=np.float64))
    y4 = np.zeros_like(y10_arr, dtype=np.float64)
    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)
    return float(y4[0]) if is_scalar else y4


def build_final_model(
    feature_names: Sequence[str],
    target: str,
    random_state: int,
    include_lightgbm: bool = True,
    include_catboost: bool = True,
) -> JointFailureAwareGradeModel:
    """Construct the unchanged heterogeneous architecture with the corrected boundary."""
    failure_boundary = failure_boundary_for_target(target)
    grade_minimum, grade_maximum = grade_range_for_target(target)

    classifier_factory = BelowOneRLGradeRegressor(
        boundary=failure_boundary,
        low_grade_threshold=None,
        low_class_weight=5.0,
        low_grade_output="classifier_probability",
        classifier_feature_names=list(feature_names),
        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=include_lightgbm,
        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,
        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=random_state,
        verbose=True,
    )
    failure_classifier = classifier_factory._build_stacking_classifier()

    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=random_state,
        verbose=True,
    )

    grade_regressors = build_grade_regressors(
        rl_regressor=rl_grade_regressor,
        random_state=random_state,
        include_lightgbm=include_lightgbm,
        include_catboost=include_catboost,
    )
    print("Available grade regressors:", list(grade_regressors.keys()))
    if len(grade_regressors) < 2:
        raise RuntimeError("At least two grade regressors are required.")

    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=random_state,
        verbose=True,
    )

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


def _summary_with_prefix(prefix: str, values: Dict[str, float]) -> Dict[str, float]:
    return {f"{prefix}_{key}": value for key, value in values.items()}


def _save_prediction_frame(
    path: Path,
    source_frame: pd.DataFrame,
    target: str,
    prediction: np.ndarray,
    failure_probability: np.ndarray,
    failure_threshold: float,
    boundary: float,
) -> None:
    columns = [column for column in IDENTIFIER_COLUMNS if column in source_frame.columns]
    for column in ("target_grade10", "target_grade4"):
        if column in source_frame.columns and column not in columns:
            columns.append(column)

    output = source_frame.loc[:, columns].copy()
    output[f"prediction_{target.removeprefix('target_')}"] = prediction
    if target == "target_grade10":
        output["prediction_grade4"] = convert_grade10_to_grade4(prediction)

    actual = source_frame[target].to_numpy(dtype=np.float64)
    output["actual_failure_lt5"] = (actual < boundary).astype(np.int8)
    output["regression_failure_risk"] = boundary - prediction
    output["regression_warning_lt5"] = (prediction < boundary).astype(np.int8)
    output["failure_probability_lt5"] = failure_probability
    output["failure_probability_threshold"] = failure_threshold
    output["classifier_warning_lt5"] = (
        failure_probability >= failure_threshold
    ).astype(np.int8)
    output.to_csv(path, index=False)


def train_on_fold(
    loaded: LoadedFold,
    fold: int,
    faculty: str,
    args: argparse.Namespace,
    models_dir: Path,
) -> Tuple[Dict[str, float], FoldWarningRecord]:
    boundary = failure_boundary_for_target(args.target)
    boundary_label = "5" if args.target == "target_grade10" else "1.5"
    y_failure_full = (loaded.y_train < boundary).astype(np.int64)
    classes, counts = np.unique(y_failure_full, return_counts=True)
    if classes.size != 2:
        raise ValueError(
            f"Fold {fold} requires both classes under boundary {boundary}. "
            f"Observed classes={classes.tolist()}, counts={counts.tolist()}."
        )

    (
        X_model_train,
        X_model_val,
        y_model_train,
        y_model_val,
    ) = train_test_split(
        loaded.X_train,
        loaded.y_train,
        test_size=args.val_ratio,
        stratify=y_failure_full,
        random_state=args.seed,
    )

    print("\n" + "#" * 100)
    print(
        f"FOLD {fold} | faculty={faculty} | target={args.target} | "
        f"failure=grade<{boundary:g}"
    )
    print(
        f"Rows: internal_train={len(X_model_train):,} | "
        f"internal_val={len(X_model_val):,} | full_train={len(loaded.X_train):,} | "
        f"test={len(loaded.X_test):,} | features={loaded.X_train.shape[1]:,}"
    )
    print(
        f"Failure prevalence: train={100.0 * y_failure_full.mean():.2f}% | "
        f"test={100.0 * np.mean(loaded.y_test < boundary):.2f}%"
    )
    print("#" * 100)

    model = build_final_model(
        feature_names=loaded.feature_names,
        target=args.target,
        random_state=args.seed,
        include_lightgbm=not args.no_lightgbm,
        include_catboost=not args.no_catboost,
    )
    model.fit(
        X_model_train,
        y_model_train,
        X_val=X_model_val,
        y_val=y_model_val,
    )

    pred_internal = np.asarray(model.predict(X_model_train), dtype=np.float64)
    pred_val = np.asarray(model.predict(X_model_val), dtype=np.float64)
    pred_train = np.asarray(model.predict(loaded.X_train), dtype=np.float64)
    pred_test = np.asarray(model.predict(loaded.X_test), dtype=np.float64)

    p_train = np.asarray(
        model.predict_failure_probability(loaded.X_train), dtype=np.float64
    )
    p_test = np.asarray(
        model.predict_failure_probability(loaded.X_test), dtype=np.float64
    )
    classifier_threshold = float(model.failure_threshold_)

    internal_regression = regression_metrics(y_model_train, pred_internal)
    validation_regression = regression_metrics(y_model_val, pred_val)
    full_train_regression = regression_metrics(loaded.y_train, pred_train)
    test_regression = regression_metrics(loaded.y_test, pred_test)

    print("\nRegression metrics")
    for name, metrics in (
        ("Internal train", internal_regression),
        ("Validation", validation_regression),
        ("Full train", full_train_regression),
        ("Test", test_regression),
    ):
        print(
            f"  {name:<15} MAE={metrics['mae']:.4f} | "
            f"RMSE={metrics['rmse']:.4f} | R2={metrics['r2']:.4f}"
        )

    y_failure_test = (loaded.y_test < boundary).astype(np.int64)
    regression_score = boundary - pred_test
    regression_warning = (pred_test < boundary).astype(np.int64)
    classifier_warning = (p_test >= classifier_threshold).astype(np.int64)

    regression_warning_report = warning_report(
        y_failure_test,
        regression_score,
        regression_warning,
    )
    classifier_warning_report = warning_report(
        y_failure_test,
        p_test,
        classifier_warning,
    )

    print_warning_report(
        title=f"FOLD {fold} — REGRESSION OUTPUT",
        report=regression_warning_report,
        boundary_label=boundary_label,
        threshold_description=f"predicted grade < {boundary:g}",
    )
    print_warning_report(
        title=f"FOLD {fold} — FAILURE CLASSIFIER P(grade<{boundary:g})",
        report=classifier_warning_report,
        boundary_label=boundary_label,
        threshold_description=(
            f"P(failure) >= learned threshold {classifier_threshold:.5f}"
        ),
    )

    fold_tag = f"fold_{fold}"
    model_path = models_dir / f"{faculty}_{fold_tag}_joint_model.pkl"
    model.save_model(str(model_path))

    pd.DataFrame(model.grade_regressor_.get_base_model_report()).to_csv(
        models_dir / f"{faculty}_{fold_tag}_base_regressor_report.csv",
        index=False,
    )
    pd.DataFrame(model.grade_regressor_.get_policy_report()).to_csv(
        models_dir / f"{faculty}_{fold_tag}_joint_rl_policy.csv",
        index=False,
    )

    _save_prediction_frame(
        models_dir / f"{faculty}_{fold_tag}_test_results.csv",
        loaded.test_frame,
        args.target,
        pred_test,
        p_test,
        classifier_threshold,
        boundary,
    )
    if args.save_train_results:
        _save_prediction_frame(
            models_dir / f"{faculty}_{fold_tag}_train_results.csv",
            loaded.train_frame,
            args.target,
            pred_train,
            p_train,
            classifier_threshold,
            boundary,
        )

    summary: Dict[str, float] = {
        "fold": fold,
        "train_size": len(loaded.X_train),
        "internal_train_size": len(X_model_train),
        "validation_size": len(X_model_val),
        "test_size": len(loaded.X_test),
        "n_features": loaded.X_train.shape[1],
        "failure_boundary": boundary,
        "train_failure_prevalence": float(y_failure_full.mean()),
        "test_failure_prevalence": float(y_failure_test.mean()),
        "classifier_threshold": classifier_threshold,
        "meta_validation_mae": float(model.grade_regressor_.validation_mae_meta_),
        "joint_rl_validation_mae": float(model.grade_regressor_.validation_mae_joint_),
    }
    summary.update(_summary_with_prefix("internal_train", internal_regression))
    summary.update(_summary_with_prefix("validation", validation_regression))
    summary.update(_summary_with_prefix("full_train", full_train_regression))
    summary.update(_summary_with_prefix("test", test_regression))
    summary.update(_summary_with_prefix("regression_warning", regression_warning_report))
    summary.update(_summary_with_prefix("classifier_warning", classifier_warning_report))

    record = FoldWarningRecord(
        fold=fold,
        y_failure=y_failure_test,
        regression_score=regression_score,
        regression_warning=regression_warning,
        classifier_score=p_test,
        classifier_warning=classifier_warning,
        classifier_threshold=classifier_threshold,
    )
    print(f"\nSaved fold outputs to: {models_dir}")
    return summary, record


def print_pooled_reports(
    records: Sequence[FoldWarningRecord],
    target: str,
) -> Dict[str, float]:
    boundary = failure_boundary_for_target(target)
    boundary_label = "5" if target == "target_grade10" else "1.5"
    y_failure = np.concatenate([record.y_failure for record in records])
    regression_score = np.concatenate([record.regression_score for record in records])
    regression_warning = np.concatenate(
        [record.regression_warning for record in records]
    )
    classifier_score = np.concatenate([record.classifier_score for record in records])
    classifier_warning = np.concatenate(
        [record.classifier_warning for record in records]
    )

    regression = warning_report(y_failure, regression_score, regression_warning)
    classifier = warning_report(y_failure, classifier_score, classifier_warning)

    print("\n" + "!" * 100)
    print("POOLED TEST METRICS (micro-average across all selected folds)")
    print("!" * 100)
    print_warning_report(
        title="POOLED — REGRESSION OUTPUT",
        report=regression,
        boundary_label=boundary_label,
        threshold_description=f"predicted grade < {boundary:g}",
    )
    print_warning_report(
        title=f"POOLED — FAILURE CLASSIFIER P(grade<{boundary:g})",
        report=classifier,
        boundary_label=boundary_label,
        threshold_description="each fold's learned internal-validation threshold",
    )

    pooled = {}
    pooled.update(_summary_with_prefix("regression_warning", regression))
    pooled.update(_summary_with_prefix("classifier_warning", classifier))
    return pooled


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(
        description=(
            "Failure-aware heterogeneous grade model on test2.py-style temporal folds. "
            "Failure is target_grade10 < 5.0."
        )
    )
    parser.add_argument(
        "--faculty",
        default="khoa_cong_nghe_thong_tin",
        help="Faculty key, or use --list to display available faculties.",
    )
    parser.add_argument(
        "--folds",
        default="all",
        help="Comma-separated folds such as 1,2,3,4,5 or 'all'.",
    )
    parser.add_argument(
        "--strategy",
        default="expanding",
        choices=["expanding", "sliding"],
        help="Split strategy when --splits_dir points to a splits root/repository root.",
    )
    parser.add_argument(
        "--splits_dir",
        default="/root/disk_3tb/earlywarning/data/splits/expanding",
        help=(
            "Direct strategy directory (for example data/splits/expanding), "
            "a data/splits root, or a repository root. Default: "
            "<final_train.py directory>/data/splits/<strategy>."
        ),
    )
    parser.add_argument(
        "--models_dir",
        default="results/final_train",
        help="Output directory. Relative paths are resolved beside final_train.py.",
    )
    parser.add_argument(
        "--target",
        default="target_grade10",
        choices=["target_grade10", "target_grade4"],
    )
    parser.add_argument(
        "--val_ratio",
        type=float,
        default=0.10,
        help="Internal validation fraction used for stacking and threshold learning.",
    )
    parser.add_argument("--seed", type=int, default=42)
    parser.add_argument("--list", action="store_true", help="List faculties and exit.")
    parser.add_argument(
        "--save_train_results",
        action="store_true",
        help="Also save full-training-set predictions and warning outputs.",
    )
    parser.add_argument(
        "--no_lightgbm",
        action="store_true",
        help="Disable optional LightGBM base estimators.",
    )
    parser.add_argument(
        "--no_catboost",
        action="store_true",
        help="Disable optional CatBoost grade regressor.",
    )
    return parser.parse_args()


def main() -> None:
    args = parse_args()
    if not 0.0 < args.val_ratio < 1.0:
        raise ValueError(f"--val_ratio must be in (0, 1); received {args.val_ratio}.")

    seed_everything(args.seed)
    script_dir = Path(__file__).resolve().parent
    split_input = (
        Path(args.splits_dir)
        if args.splits_dir
        else script_dir / "data" / "splits" / args.strategy
    )
    splits_dir = resolve_splits_dir(split_input, args.strategy)
    if not splits_dir.exists():
        raise SystemExit(f"[ERROR] Splits directory does not exist: {splits_dir}")

    faculties = list_faculties(splits_dir)
    if args.list:
        print(f"Splits directory: {splits_dir}")
        for faculty in faculties:
            print("  ", faculty)
        return
    if args.faculty not in faculties:
        available = "\n  ".join(faculties) if faculties else "(none)"
        raise SystemExit(
            f"[ERROR] Faculty {args.faculty!r} was not found in {splits_dir}.\n"
            f"Available:\n  {available}"
        )

    folds = parse_folds(args.folds, splits_dir)
    models_dir = Path(args.models_dir).expanduser()
    if not models_dir.is_absolute():
        models_dir = script_dir / models_dir
    models_dir = models_dir.resolve()
    models_dir.mkdir(parents=True, exist_ok=True)

    boundary = failure_boundary_for_target(args.target)
    print("=" * 100)
    print("FINAL FAILURE-AWARE TRAINING PIPELINE")
    print(f"Faculty       : {args.faculty}")
    print(f"Splits        : {splits_dir}")
    print(f"Folds         : {folds}")
    print(f"Target        : {args.target}")
    print(f"Failure label : grade < {boundary:g}; normal = grade >= {boundary:g}")
    print(f"Outputs       : {models_dir}")
    print("=" * 100)

    summaries: List[Dict[str, float]] = []
    records: List[FoldWarningRecord] = []
    for fold in folds:
        loaded = load_fold_data(
            faculty=args.faculty,
            fold=fold,
            splits_dir=splits_dir,
            target=args.target,
            exclude_cols=DEFAULT_EXCLUDE_COLS,
        )
        if loaded is None:
            print(f"Fold {fold}: skipped (missing files or fewer than 50 train rows).")
            continue
        summary, record = train_on_fold(
            loaded=loaded,
            fold=fold,
            faculty=args.faculty,
            args=args,
            models_dir=models_dir,
        )
        summaries.append(summary)
        records.append(record)
        pd.DataFrame(summaries).to_csv(
            models_dir / f"{args.faculty}_metrics_summary.csv",
            index=False,
        )

    if not summaries:
        raise SystemExit("[ERROR] No valid folds were trained.")

    pooled = print_pooled_reports(records, args.target)
    pooled_row = {
        "faculty": args.faculty,
        "folds": ",".join(str(record.fold) for record in records),
        "failure_boundary": boundary,
        **pooled,
    }
    pd.DataFrame([pooled_row]).to_csv(
        models_dir / f"{args.faculty}_pooled_warning_metrics.csv",
        index=False,
    )
    print("\n" + "=" * 100)
    print(f"Completed {len(summaries)} fold(s). Outputs saved to {models_dir}")
    print("=" * 100)


if __name__ == "__main__":
    main()
