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

Failure-aware student-course grade pipeline with a leakage-safe operational
warning protocol.

Model fitting
-------------
Each fold still uses an internal stratified validation split for fitting the
heterogeneous failure stack and the grade stack. The active failure classifiers
are balanced Random Forest, balanced Extra Trees, Histogram Gradient Boosting,
and optional LightGBM. The former ARL feature-subspace booster and custom RL
classification booster have been removed.

Operational warning policy
--------------------------
The warning threshold is NOT selected independently on each fold. Instead:

  1. Train/predict the temporal development folds (default 1-5).
  2. Pool their out-of-time test predictions.
  3. Tune one threshold using F-beta (default beta=2 for recall priority).
  4. Freeze that threshold and apply it to holdout folds (default 6-7).
  5. Also report a leak-safe drift-aware top-K policy whose warning rate is
     scaled from the previous completed semester's observed prevalence.

The script evaluates two continuous warning signals:

  * classifier: P(target grade < 5)
  * regression: failure boundary - predicted grade

``--warning_signal auto`` chooses the signal with the higher development AP,
matching the signal-selection logic used by test2.py.
"""

from __future__ import annotations

import argparse
import math
import os
import pickle
import random
import sys
from dataclasses import dataclass
from pathlib import Path
from typing import Dict, Iterable, List, Optional, Sequence, Tuple, Union

import numpy as np
import pandas as pd
from sklearn.metrics import (
    average_precision_score,
    confusion_matrix,
    mean_absolute_error,
    precision_recall_fscore_support,
    r2_score,
    roc_auc_score,
)
from sklearn.model_selection import train_test_split
from sklearn.preprocessing import OneHotEncoder

from class_aware_heterogeneous_stacking import (
    ClassAwareHeterogeneousStackingClassifier,
    build_standard_base_estimators,
)
from joint_failure_aware_stacking_grade_model import (
    JointFailureAwareGradeModel,
    JointRLStackingGradeRegressor,
    build_grade_regressors,
)


N_RATE = 0.1
N_EST = 20
DEFAULT_TARGET = "target_grade10"

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

# ============================================================================
# Fold loading, metrics, threshold tuning, and execution protocol
# ============================================================================

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",
]

SIGNALS = ("classifier", "regression")


@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_grade: np.ndarray
    y_failure: np.ndarray
    predicted_grade: np.ndarray
    classifier_score: np.ndarray
    regression_score: np.ndarray
    internal_classifier_threshold: float
    test_prevalence: float
    result_path: Path


@dataclass
class ThresholdPolicy:
    signal: str
    threshold: float
    beta: float
    development_ap: float
    development_auc: float
    development_prevalence: float
    flag_rate: float
    warning_ratio: float
    precision: float
    recall: float
    f1: float
    fbeta: float
    constraints_relaxed: str


def seed_everything(seed: int = 42) -> None:
    random.seed(seed)
    np.random.seed(seed)


def failure_boundary_for_target(target: str) -> float:
    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 convert_grade10_to_grade4(y10: Union[float, np.ndarray]) -> Union[float, np.ndarray]:
    scalar = np.isscalar(y10)
    values = np.atleast_1d(np.asarray(y10, dtype=np.float64))
    y4 = np.zeros_like(values, dtype=np.float64)
    y4 = np.where(values >= 9.0, 4.0, y4)
    y4 = np.where((values >= 8.5) & (values < 9.0), 3.7, y4)
    y4 = np.where((values >= 8.0) & (values < 8.5), 3.5, y4)
    y4 = np.where((values >= 7.0) & (values < 8.0), 3.0, y4)
    y4 = np.where((values >= 6.0) & (values < 7.0), 2.5, y4)
    y4 = np.where((values >= 5.5) & (values < 6.0), 2.0, y4)
    y4 = np.where((values >= 5.0) & (values < 5.5), 1.5, y4)
    y4 = np.where((values >= 4.0) & (values < 5.0), 1.0, y4)
    y4 = np.where(values < 4.0, 0.0, y4)
    return float(y4[0]) if scalar else y4


def resolve_splits_dir(path: Path, strategy: str) -> Path:
    path = Path(path).expanduser().resolve()
    candidates = [
        path,
        path / strategy,
        path / "splits" / strategy,
        path / "data" / "splits" / strategy,
    ]
    for candidate in candidates:
        if candidate.exists() and any(candidate.glob("fold_*")):
            return candidate
    return path


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


def available_folds(splits_dir: Path) -> List[int]:
    folds = []
    for path in Path(splits_dir).glob("fold_*"):
        try:
            folds.append(int(path.name.split("_", 1)[1]))
        except (IndexError, ValueError):
            continue
    return sorted(set(folds))


def parse_fold_spec(spec: str, splits_dir: Path) -> List[int]:
    if spec.strip().lower() == "all":
        return available_folds(splits_dir)
    return sorted({int(item.strip()) for item in spec.split(",") if item.strip()})


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


def _prepare_features(
    train_frame: pd.DataFrame,
    test_frame: pd.DataFrame,
    feature_names: Sequence[str],
) -> Tuple[pd.DataFrame, pd.DataFrame, List[str]]:
    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 = pd.concat(
            [
                X_train[numeric].reset_index(drop=True),
                pd.DataFrame(encoded_train, columns=encoded_names),
            ],
            axis=1,
        )
        X_test = pd.concat(
            [
                X_test[numeric].reset_index(drop=True),
                pd.DataFrame(encoded_test, columns=encoded_names),
            ],
            axis=1,
        )
    else:
        X_train = X_train[numeric].reset_index(drop=True)
        X_test = X_test[numeric].reset_index(drop=True)

    train_means = X_train.mean(axis=0, numeric_only=True)
    X_train = X_train.fillna(train_means).fillna(0.0).astype(np.float64)
    X_test = X_test.fillna(train_means).fillna(0.0).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]:
    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:
    return float(np.sqrt(np.mean((np.asarray(y_true) - np.asarray(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)
    if np.unique(y_failure).size < 2:
        return float("nan")
    return float(average_precision_score(y_failure, np.asarray(score, dtype=float)))


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


def binary_warning_metrics(y_failure: np.ndarray, warning: np.ndarray) -> Dict[str, float]:
    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)
    return {
        "tn": int(tn),
        "fp": int(fp),
        "fn": int(fn),
        "tp": int(tp),
        "accuracy": float((tn + tp) / total) if total else float("nan"),
        "precision": float(precision),
        "recall": float(recall),
        "specificity": float(tn / (tn + fp)) if (tn + fp) else float("nan"),
        "f1": float(f1),
        "flag_rate": float((tp + fp) / total) if total else float("nan"),
    }


def fbeta_from_metrics(metrics: Dict[str, float], beta: float) -> float:
    precision = float(metrics["precision"])
    recall = float(metrics["recall"])
    beta_sq = beta ** 2
    denominator = beta_sq * precision + recall
    if denominator <= 0.0:
        return 0.0
    return float((1.0 + beta_sq) * precision * recall / denominator)


def warning_report(
    y_failure: np.ndarray,
    score: np.ndarray,
    warning: np.ndarray,
    beta: float = 2.0,
) -> 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))
    report["fbeta"] = fbeta_from_metrics(report, beta)
    return report


def _threshold_candidates(score: np.ndarray, maximum: int = 1000) -> np.ndarray:
    score = np.asarray(score, dtype=np.float64).reshape(-1)
    unique = np.unique(score)
    if len(unique) <= maximum:
        return unique
    return np.unique(np.quantile(score, np.linspace(0.001, 0.999, maximum)))


def tune_operational_threshold(
    y_failure: np.ndarray,
    score: np.ndarray,
    signal: str,
    beta: float,
    min_precision: float,
    max_warning_ratio: float,
    min_flags: int = 5,
) -> ThresholdPolicy:
    """Tune a single recall-aware threshold on pooled temporal development data."""
    y_failure = np.asarray(y_failure, dtype=np.int64).reshape(-1)
    score = np.asarray(score, dtype=np.float64).reshape(-1)
    if y_failure.shape != score.shape:
        raise ValueError("y_failure and score must have identical shapes")
    if np.unique(y_failure).size < 2:
        raise ValueError("Both classes are required to tune a threshold")

    prevalence = float(y_failure.mean())
    max_flag_rate = min(0.99, max_warning_ratio * max(prevalence, 1e-8))
    candidates = []
    for threshold in _threshold_candidates(score):
        metrics = warning_report(
            y_failure,
            score,
            score >= threshold,
            beta=beta,
        )
        candidates.append((float(threshold), metrics))

    enough = [
        item for item in candidates
        if item[1]["flag_rate"] * len(y_failure) >= min_flags
    ]
    strict = [
        item for item in enough
        if item[1]["precision"] >= min_precision
        and item[1]["flag_rate"] <= max_flag_rate
    ]
    ratio_only = [
        item for item in enough if item[1]["flag_rate"] <= max_flag_rate
    ]
    if strict:
        eligible = strict
        relaxed = "none"
    elif ratio_only:
        eligible = ratio_only
        relaxed = "minimum precision"
    elif enough:
        eligible = enough
        relaxed = "minimum precision and maximum warning ratio"
    else:
        eligible = candidates
        relaxed = "all constraints"

    threshold, best = max(
        eligible,
        key=lambda item: (
            item[1]["fbeta"],
            item[1]["recall"],
            item[1]["precision"],
            -item[1]["flag_rate"],
        ),
    )
    warning_ratio = best["flag_rate"] / max(prevalence, 1e-8)
    return ThresholdPolicy(
        signal=signal,
        threshold=float(threshold),
        beta=float(beta),
        development_ap=float(best["average_precision"]),
        development_auc=float(best["roc_auc"]),
        development_prevalence=prevalence,
        flag_rate=float(best["flag_rate"]),
        warning_ratio=float(warning_ratio),
        precision=float(best["precision"]),
        recall=float(best["recall"]),
        f1=float(best["f1"]),
        fbeta=float(best["fbeta"]),
        constraints_relaxed=relaxed,
    )


def warn_by_rate(score: np.ndarray, rate: float) -> np.ndarray:
    score = np.asarray(score, dtype=np.float64).reshape(-1)
    if len(score) == 0 or rate <= 0.0:
        return np.zeros(len(score), dtype=np.int64)
    k = min(len(score), max(1, int(round(float(rate) * len(score)))))
    indices = np.argpartition(score, -k)[-k:]
    warning = np.zeros(len(score), dtype=np.int64)
    warning[indices] = 1
    return warning


def record_score(record: FoldWarningRecord, signal: str) -> np.ndarray:
    if signal == "classifier":
        return record.classifier_score
    if signal == "regression":
        return record.regression_score
    raise ValueError(f"Unsupported warning signal: {signal}")


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) -> None:
    tn, fp, fn, tp = (
        int(metrics["tn"]),
        int(metrics["fp"]),
        int(metrics["fn"]),
        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_policy_summary(policy: ThresholdPolicy, chosen: bool = False) -> None:
    marker = " <= SELECTED" if chosen else ""
    print(
        f"  {policy.signal:10s}: AP={policy.development_ap:.4f} | "
        f"AUC={policy.development_auc:.4f} | F{policy.beta:g}-opt tau={policy.threshold:.6f} | "
        f"flag={100.0 * policy.flag_rate:.2f}% "
        f"(ratio={policy.warning_ratio:.3f}) | P={policy.precision:.4f} "
        f"R={policy.recall:.4f} F1={policy.f1:.4f} "
        f"F{policy.beta:g}={policy.fbeta:.4f}{marker}"
    )
    if policy.constraints_relaxed != "none":
        print(f"    threshold fallback relaxed: {policy.constraints_relaxed}")


def _pooled_arrays(records: Sequence[FoldWarningRecord], signal: str):
    y = np.concatenate([record.y_failure for record in records])
    score = np.concatenate([record_score(record, signal) for record in records])
    return y, score


def report_policy_block(
    title: str,
    records: Sequence[FoldWarningRecord],
    policy: ThresholdPolicy,
    prevalence_map: Dict[int, float],
    default_previous_prevalence: float,
    boundary_label: str,
    show_confusion: bool,
) -> Dict[str, float]:
    print(f"\n### {title} [signal={policy.signal}, beta={policy.beta:g}]")
    print(
        f"{'fold':>6} {'test':>7} {'base%':>7} | {'AP':>7} {'AUC':>7} | "
        f"{'P@t':>7} {'R@t':>7} {'F1@t':>7} {'Fβ@t':>7} {'rate@t':>8} | "
        f"{'P@r':>7} {'R@r':>7} {'F1@r':>7} {'Fβ@r':>7} {'rate@r':>8}"
    )

    all_y, all_score, all_fixed, all_drift = [], [], [], []
    for record in records:
        score = record_score(record, policy.signal)
        previous_prevalence = prevalence_map.get(
            record.fold - 1,
            default_previous_prevalence,
        )
        drift_rate = float(
            np.clip(policy.warning_ratio * previous_prevalence, 1e-4, 0.99)
        )
        fixed_warning = (score >= policy.threshold).astype(np.int64)
        drift_warning = warn_by_rate(score, drift_rate)
        fixed = warning_report(record.y_failure, score, fixed_warning, policy.beta)
        drift = warning_report(record.y_failure, score, drift_warning, policy.beta)

        print(
            f"{record.fold:>6} {len(record.y_failure):>7} "
            f"{100.0 * record.test_prevalence:6.2f}% | "
            f"{fixed['average_precision']:7.4f} {fixed['roc_auc']:7.4f} | "
            f"{fixed['precision']:7.4f} {fixed['recall']:7.4f} "
            f"{fixed['f1']:7.4f} {fixed['fbeta']:7.4f} "
            f"{100.0 * fixed['flag_rate']:7.2f}% | "
            f"{drift['precision']:7.4f} {drift['recall']:7.4f} "
            f"{drift['f1']:7.4f} {drift['fbeta']:7.4f} "
            f"{100.0 * drift['flag_rate']:7.2f}%"
        )
        if show_confusion:
            print_confusion_matrix(
                f"fold {record.fold} — fixed development threshold {policy.threshold:.6f}",
                fixed,
                boundary_label,
            )
            print_confusion_matrix(
                f"fold {record.fold} — drift-aware rate {drift_rate:.3%}",
                drift,
                boundary_label,
            )

        all_y.append(record.y_failure)
        all_score.append(score)
        all_fixed.append(fixed_warning)
        all_drift.append(drift_warning)

    y = np.concatenate(all_y)
    score = np.concatenate(all_score)
    fixed_warning = np.concatenate(all_fixed)
    drift_warning = np.concatenate(all_drift)
    fixed = warning_report(y, score, fixed_warning, policy.beta)
    drift = warning_report(y, score, drift_warning, policy.beta)
    print("-" * 132)
    print(
        f"{'POOLED':>6} {len(y):>7} {100.0 * y.mean():6.2f}% | "
        f"{fixed['average_precision']:7.4f} {fixed['roc_auc']:7.4f} | "
        f"{fixed['precision']:7.4f} {fixed['recall']:7.4f} "
        f"{fixed['f1']:7.4f} {fixed['fbeta']:7.4f} "
        f"{100.0 * fixed['flag_rate']:7.2f}% | "
        f"{drift['precision']:7.4f} {drift['recall']:7.4f} "
        f"{drift['f1']:7.4f} {drift['fbeta']:7.4f} "
        f"{100.0 * drift['flag_rate']:7.2f}%"
    )
    if show_confusion:
        print_confusion_matrix("POOLED — fixed development threshold", fixed, boundary_label)
        print_confusion_matrix("POOLED — drift-aware warning policy", drift, boundary_label)

    result = {f"fixed_{key}": value for key, value in fixed.items()}
    result.update({f"drift_{key}": value for key, value in drift.items()})
    return result


def build_final_model(
    feature_names: Sequence[str],
    target: str,
    random_state: int,
    include_lightgbm: bool,
    include_catboost: bool,
    include_rl_grade_regressor: bool,
    internal_threshold_beta: float,
    internal_min_precision: float,
    internal_max_warning_ratio: float,
) -> JointFailureAwareGradeModel:
    del feature_names  # retained in the interface for backwards compatibility
    failure_boundary = failure_boundary_for_target(target)
    grade_minimum, grade_maximum = grade_range_for_target(target)

    failure_estimators = build_standard_base_estimators(
        random_state=random_state,
        include_lightgbm=include_lightgbm,
    )
    print("Available failure classifiers:", list(failure_estimators.keys()))
    failure_classifier = ClassAwareHeterogeneousStackingClassifier(
        estimators=failure_estimators,
        positive_class=1,
        blender_fraction=0.50,
        threshold_beta=internal_threshold_beta,
        threshold_min_precision=internal_min_precision,
        threshold_max_warning_ratio=internal_max_warning_ratio,
        random_state=random_state,
        verbose=True,
    )

    rl_grade_regressor = None
    if include_rl_grade_regressor:
        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 _save_raw_prediction_frame(
    path: Path,
    source_frame: pd.DataFrame,
    target: str,
    prediction: np.ndarray,
    classifier_probability: np.ndarray,
    internal_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["failure_probability_lt5"] = classifier_probability
    output["internal_classifier_threshold"] = internal_threshold
    output["internal_classifier_warning"] = (
        classifier_probability >= internal_threshold
    ).astype(np.int8)
    output.to_csv(path, index=False)


def add_operational_policy_columns(
    record: FoldWarningRecord,
    policies: Dict[str, ThresholdPolicy],
    prevalence_map: Dict[int, float],
    default_previous_prevalence: float,
    selected_signal: str,
) -> None:
    frame = pd.read_csv(record.result_path, low_memory=False)
    for signal, policy in policies.items():
        score = record_score(record, signal)
        previous_prevalence = prevalence_map.get(
            record.fold - 1,
            default_previous_prevalence,
        )
        drift_rate = float(
            np.clip(policy.warning_ratio * previous_prevalence, 1e-4, 0.99)
        )
        frame[f"{signal}_operational_score"] = score
        frame[f"{signal}_fixed_threshold"] = policy.threshold
        frame[f"{signal}_warning_fixed"] = (score >= policy.threshold).astype(np.int8)
        frame[f"{signal}_drift_rate"] = drift_rate
        frame[f"{signal}_warning_drift"] = warn_by_rate(score, drift_rate).astype(np.int8)
    frame["selected_warning_signal"] = selected_signal
    frame["selected_warning_fixed"] = frame[f"{selected_signal}_warning_fixed"]
    frame["selected_warning_drift"] = frame[f"{selected_signal}_warning_drift"]
    frame.to_csv(record.result_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)
    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,
        include_rl_grade_regressor=not args.no_rl_grade_regressor,
        internal_threshold_beta=args.internal_threshold_beta,
        internal_min_precision=args.internal_min_precision,
        internal_max_warning_ratio=args.internal_max_warning_ratio,
    )
    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_test = np.asarray(model.predict_failure_probability(loaded.X_test), dtype=np.float64)
    internal_threshold = float(model.failure_threshold_)

    internal_metrics = regression_metrics(y_model_train, pred_internal)
    validation_metrics = regression_metrics(y_model_val, pred_val)
    full_train_metrics = regression_metrics(loaded.y_train, pred_train)
    test_metrics = regression_metrics(loaded.y_test, pred_test)
    print("\nRegression metrics")
    for name, metrics in (
        ("Internal train", internal_metrics),
        ("Validation", validation_metrics),
        ("Full train", full_train_metrics),
        ("Test", test_metrics),
    ):
        print(
            f"  {name:<15} MAE={metrics['mae']:.4f} | "
            f"RMSE={metrics['rmse']:.4f} | R2={metrics['r2']:.4f}"
        )
    print(
        f"Internal classifier threshold (model feature only): {internal_threshold:.6f}. "
        "Operational warning threshold will be tuned on pooled development folds."
    )

    fold_tag = f"fold_{fold}"
    model.save_model(str(models_dir / f"{faculty}_{fold_tag}_joint_model.pkl"))
    pd.DataFrame(model.failure_classifier_.get_base_model_report()).to_csv(
        models_dir / f"{faculty}_{fold_tag}_failure_classifier_report.csv",
        index=False,
    )
    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,
    )

    result_path = models_dir / f"{faculty}_{fold_tag}_test_results.csv"
    _save_raw_prediction_frame(
        result_path,
        loaded.test_frame,
        args.target,
        pred_test,
        p_test,
        internal_threshold,
        boundary,
    )

    y_failure_test = (loaded.y_test < boundary).astype(np.int64)
    record = FoldWarningRecord(
        fold=fold,
        y_grade=loaded.y_test.copy(),
        y_failure=y_failure_test,
        predicted_grade=pred_test,
        classifier_score=p_test,
        regression_score=boundary - pred_test,
        internal_classifier_threshold=internal_threshold,
        test_prevalence=float(y_failure_test.mean()),
        result_path=result_path,
    )
    summary = {
        "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()),
        "internal_classifier_threshold": internal_threshold,
        "meta_validation_mae": float(model.grade_regressor_.validation_mae_meta_),
        "joint_rl_validation_mae": float(model.grade_regressor_.validation_mae_joint_),
        **{f"internal_train_{key}": value for key, value in internal_metrics.items()},
        **{f"validation_{key}": value for key, value in validation_metrics.items()},
        **{f"full_train_{key}": value for key, value in full_train_metrics.items()},
        **{f"test_{key}": value for key, value in test_metrics.items()},
        "classifier_ap": safe_average_precision(y_failure_test, p_test),
        "classifier_auc": safe_roc_auc(y_failure_test, p_test),
        "regression_ap": safe_average_precision(y_failure_test, boundary - pred_test),
        "regression_auc": safe_roc_auc(y_failure_test, boundary - pred_test),
    }
    print(f"Saved raw fold outputs to: {result_path}")
    return summary, record


def train_fold_group(
    folds: Sequence[int],
    faculty: str,
    args: argparse.Namespace,
    splits_dir: Path,
    models_dir: Path,
    summaries: List[Dict[str, float]],
) -> List[FoldWarningRecord]:
    records = []
    for fold in folds:
        loaded = load_fold_data(
            faculty=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, fold, faculty, args, models_dir)
        summaries.append(summary)
        records.append(record)
        pd.DataFrame(summaries).to_csv(
            models_dir / f"{faculty}_metrics_summary.csv",
            index=False,
        )
    return records


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(
        description=(
            "Reduced failure-aware ensemble with pooled development threshold tuning. "
            "Failure is target_grade10 < 5."
        )
    )
    parser.add_argument("--faculty", default="khoa_cong_nghe_thong_tin")
    parser.add_argument("--strategy", default="expanding", choices=["expanding", "sliding"])
    parser.add_argument("--splits_dir", default=None)
    parser.add_argument("--models_dir", default="results/final_train_v2")
    parser.add_argument("--target", default=DEFAULT_TARGET, choices=["target_grade10", "target_grade4"])
    parser.add_argument("--dev_folds", default="1,2,3,4,5")
    parser.add_argument("--holdout_folds", default="6,7")
    parser.add_argument(
        "--folds",
        default=None,
        help=(
            "Optional compatibility filter such as 'all' or '1,2,3'. The dev/holdout "
            "roles still come from --dev_folds and --holdout_folds."
        ),
    )
    parser.add_argument("--val_ratio", type=float, default=0.10)
    parser.add_argument("--seed", type=int, default=42)
    parser.add_argument("--list", action="store_true")

    parser.add_argument(
        "--warning_signal",
        default="auto",
        choices=["auto", "classifier", "regression"],
        help="Operational signal; auto selects the higher development AP.",
    )
    parser.add_argument(
        "--threshold_beta",
        type=float,
        default=2.0,
        help="F-beta objective for the pooled operational threshold. Use 1 for test2-style F1.",
    )
    parser.add_argument(
        "--min_precision",
        type=float,
        default=0.15,
        help="Preferred minimum development precision during threshold tuning.",
    )
    parser.add_argument(
        "--max_warning_ratio",
        type=float,
        default=2.5,
        help="Preferred maximum warning rate divided by development prevalence.",
    )
    parser.add_argument("--min_flags", type=int, default=5)

    parser.add_argument("--internal_threshold_beta", type=float, default=2.0)
    parser.add_argument("--internal_min_precision", type=float, default=0.10)
    parser.add_argument("--internal_max_warning_ratio", type=float, default=3.0)

    parser.add_argument("--no_lightgbm", action="store_true")
    parser.add_argument("--no_catboost", action="store_true")
    parser.add_argument(
        "--no_rl_grade_regressor",
        action="store_true",
        help="Also remove the separate RL grade-regression expert. It is retained by default.",
    )
    return parser.parse_args()


def validate_args(args: argparse.Namespace) -> None:
    if not 0.0 < args.val_ratio < 1.0:
        raise ValueError("--val_ratio must be in (0, 1)")
    if args.threshold_beta <= 0.0 or args.internal_threshold_beta <= 0.0:
        raise ValueError("F-beta values must be positive")
    if not 0.0 <= args.min_precision <= 1.0:
        raise ValueError("--min_precision must be in [0, 1]")
    if not 0.0 <= args.internal_min_precision <= 1.0:
        raise ValueError("--internal_min_precision must be in [0, 1]")
    if args.max_warning_ratio <= 0.0 or args.internal_max_warning_ratio <= 0.0:
        raise ValueError("warning-ratio limits must be positive")
    if args.min_flags < 1:
        raise ValueError("--min_flags must be >= 1")


def main() -> None:
    args = parse_args()
    validate_args(args)
    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}"
        )

    dev_folds = parse_fold_spec(args.dev_folds, splits_dir)
    holdout_folds = parse_fold_spec(args.holdout_folds, splits_dir)
    if set(dev_folds) & set(holdout_folds):
        raise ValueError("Development and holdout folds must not overlap")
    if args.folds is not None:
        selected = set(parse_fold_spec(args.folds, splits_dir))
        dev_folds = [fold for fold in dev_folds if fold in selected]
        holdout_folds = [fold for fold in holdout_folds if fold in selected]
    if not dev_folds:
        raise SystemExit("[ERROR] At least one development fold is required")

    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)
    boundary_label = "5" if args.target == "target_grade10" else "1.5"
    print("=" * 104)
    print("REDUCED FAILURE-AWARE TRAINING PIPELINE")
    print(f"Faculty                 : {args.faculty}")
    print(f"Splits                  : {splits_dir}")
    print(f"Development folds       : {dev_folds}")
    print(f"Holdout folds           : {holdout_folds}")
    print(f"Target                  : {args.target}")
    print(f"Failure label           : grade < {boundary:g}; normal = grade >= {boundary:g}")
    print("Failure classifiers     : balanced RF + balanced ExtraTrees + HistGB (+ optional LightGBM)")
    print("Removed classifiers     : ARL feature-subspace booster + custom RL gradient booster")
    print(f"Operational objective   : F{args.threshold_beta:g}")
    print(f"Operational signal      : {args.warning_signal}")
    print(f"Outputs                 : {models_dir}")
    print("=" * 104)

    summaries: List[Dict[str, float]] = []
    print("\n>>> DEVELOPMENT FOLDS: fit models and collect temporal predictions")
    dev_records = train_fold_group(
        dev_folds,
        args.faculty,
        args,
        splits_dir,
        models_dir,
        summaries,
    )
    if not dev_records:
        raise SystemExit("[ERROR] No valid development folds were trained")

    policies = {}
    for signal in SIGNALS:
        y_dev, score_dev = _pooled_arrays(dev_records, signal)
        policies[signal] = tune_operational_threshold(
            y_failure=y_dev,
            score=score_dev,
            signal=signal,
            beta=args.threshold_beta,
            min_precision=args.min_precision,
            max_warning_ratio=args.max_warning_ratio,
            min_flags=args.min_flags,
        )

    if args.warning_signal == "auto":
        selected_signal = max(
            SIGNALS,
            key=lambda signal: (
                policies[signal].development_ap
                if np.isfinite(policies[signal].development_ap)
                else -1.0
            ),
        )
    else:
        selected_signal = args.warning_signal

    print("\n>>> POOLED DEVELOPMENT THRESHOLD SELECTION")
    for signal in SIGNALS:
        print_policy_summary(policies[signal], chosen=(signal == selected_signal))

    prevalence_map = {
        record.fold: record.test_prevalence for record in dev_records
    }
    dev_prevalence = float(
        np.concatenate([record.y_failure for record in dev_records]).mean()
    )

    development_rows = []
    for signal in SIGNALS:
        metrics = report_policy_block(
            title="DEVELOPMENT (temporal validation)",
            records=dev_records,
            policy=policies[signal],
            prevalence_map=prevalence_map,
            default_previous_prevalence=dev_prevalence,
            boundary_label=boundary_label,
            show_confusion=False,
        )
        development_rows.append({
            "split": "development",
            "signal": signal,
            "selected": signal == selected_signal,
            **policies[signal].__dict__,
            **metrics,
        })

    holdout_records: List[FoldWarningRecord] = []
    holdout_rows = []
    if holdout_folds:
        print("\n" + "!" * 104)
        print(
            "HOLDOUT: the pooled development thresholds and warning ratios are frozen. "
            "No holdout labels are used for threshold tuning."
        )
        print("!" * 104)
        holdout_records = train_fold_group(
            holdout_folds,
            args.faculty,
            args,
            splits_dir,
            models_dir,
            summaries,
        )
        for record in holdout_records:
            prevalence_map[record.fold] = record.test_prevalence

        for signal in SIGNALS:
            metrics = report_policy_block(
                title="HOLDOUT (test)",
                records=holdout_records,
                policy=policies[signal],
                prevalence_map=prevalence_map,
                default_previous_prevalence=dev_prevalence,
                boundary_label=boundary_label,
                show_confusion=True,
            )
            holdout_rows.append({
                "split": "holdout",
                "signal": signal,
                "selected": signal == selected_signal,
                **policies[signal].__dict__,
                **metrics,
            })

    for record in [*dev_records, *holdout_records]:
        add_operational_policy_columns(
            record=record,
            policies=policies,
            prevalence_map=prevalence_map,
            default_previous_prevalence=dev_prevalence,
            selected_signal=selected_signal,
        )

    pd.DataFrame(development_rows + holdout_rows).to_csv(
        models_dir / f"{args.faculty}_operational_warning_metrics.csv",
        index=False,
    )
    pd.DataFrame([
        {
            **policy.__dict__,
            "selected": signal == selected_signal,
        }
        for signal, policy in policies.items()
    ]).to_csv(
        models_dir / f"{args.faculty}_development_threshold_policies.csv",
        index=False,
    )

    print("\n" + "=" * 104)
    print(f"Selected operational warning signal: {selected_signal}")
    print(
        f"Frozen threshold: {policies[selected_signal].threshold:.6f} | "
        f"warning ratio: {policies[selected_signal].warning_ratio:.3f}"
    )
    print(f"Completed {len(summaries)} fold(s). Outputs saved to {models_dir}")
    print("=" * 104)


if __name__ == "__main__":
    main()
