# -*- coding: utf-8 -*-
"""Suite6: target-only residual MoE diagnostic on four faculties.

Purpose
-------
Hold architecture, features, frozen Committee, losses, and operational evaluation
fixed relative to Suite5.  Change only the source of residual-training data:
  * Suite5 shared model: all faculties jointly.
  * Suite6 target-only model: one faculty at a time.

The previous Suite5 shared predictions and feature schema are read from disk rather
than retrained, so the experiment directly diagnoses positive/negative transfer.
"""
from __future__ import annotations

import argparse
from pathlib import Path

import joblib
import numpy as np
import pandas as pd
import torch
from torch.utils.data import DataLoader, TensorDataset, WeightedRandomSampler

from suite2_common import safe_ap, safe_auc, equal_budget_metrics
from suite6_common import (
    FeatureStandardizer,
    build_historical_bundle,
    build_target_bundle,
    faculty_class_sampling_weights,
    latest_block_split,
    per_faculty_validation_rows,
    model_selection_score,
    save_json,
)
from suite6_eval import evaluate_faculty
from suite6_residual_moe import (
    ResidualMoE,
    residual_moe_loss,
    router_diagnostics,
    seed_everything,
    choose_device,
)
from suite6_reporting import (
    load_shared_feature_schema,
    load_shared_fold_frame,
    summarize_router_frame,
    build_transfer_diagnostic,
    merge_external_references,
)

DEFAULT_FACULTIES = [
    "khoa_cong_nghe_thong_tin",
    "khoa_quan_tri_kinh_doanh_va_du_lich",
    "khoa_tieng_duc",
    "khoa_quoc_te_hoc",
]
BUDGETS = (0.10, 0.15, 0.20, 0.25)


def _tensor_loader(bundle, scaler, mask, args, seed, sampled=True):
    mask = np.asarray(mask, bool)
    X = scaler.transform(bundle.X[mask])
    y = bundle.y[mask].astype(np.float32)
    q = bundle.q[mask].astype(np.float32)
    f = bundle.faculty_idx[mask].astype(np.int64)
    ds = TensorDataset(torch.from_numpy(X), torch.from_numpy(f), torch.from_numpy(q), torch.from_numpy(y))
    if not sampled:
        return DataLoader(ds, batch_size=args.predict_batch_size, shuffle=False, num_workers=0)
    w, diag = faculty_class_sampling_weights(
        bundle.y[mask], bundle.faculty_idx[mask], bundle.faculty_names, args.sampling_beta
    )
    gen = torch.Generator()
    gen.manual_seed(int(seed))
    n = len(ds) if args.samples_per_epoch <= 0 else int(args.samples_per_epoch)
    sampler = WeightedRandomSampler(
        torch.as_tensor(w, dtype=torch.double), num_samples=n, replacement=True, generator=gen
    )
    return DataLoader(ds, batch_size=args.batch_size, sampler=sampler, num_workers=0), diag


def _make_model(input_dim, n_faculties, args):
    return ResidualMoE(
        input_dim=input_dim,
        n_faculties=n_faculties,
        n_experts=args.n_experts,
        faculty_dim=args.faculty_dim,
        encoder_hidden=args.encoder_hidden,
        representation_dim=args.representation_dim,
        expert_hidden=args.expert_hidden,
        delta_max=args.delta_max,
        dropout=args.dropout,
        router_temperature=args.router_temperature,
    )


def train_epoch(model, loader, optimizer, device, args):
    model.train()
    acc = {"total": 0.0, "prediction": 0.0, "router": 0.0, "specialization_mi": 0.0, "magnitude": 0.0}
    n = 0
    for X, f, q, y in loader:
        X, f, q, y = X.to(device), f.to(device), q.to(device), y.to(device)
        optimizer.zero_grad(set_to_none=True)
        out = model(X, f, q)
        losses = residual_moe_loss(
            out,
            y,
            q,
            router_lambda=args.router_lambda,
            specialization_lambda=args.specialization_lambda,
            magnitude_lambda=args.magnitude_lambda,
            utility_temperature=args.utility_temperature,
        )
        losses["total"].backward()
        torch.nn.utils.clip_grad_norm_(model.parameters(), args.grad_clip)
        optimizer.step()
        b = len(y)
        n += b
        for key in acc:
            acc[key] += float(losses[key].detach().cpu()) * b
    return {k: v / max(n, 1) for k, v in acc.items()}


@torch.no_grad()
def predict_bundle(model, bundle, scaler, mask, device, args):
    model.eval()
    loader = _tensor_loader(bundle, scaler, mask, args, seed=0, sampled=False)
    ps, ws, rs, cs = [], [], [], []
    for X, f, q, _ in loader:
        out = model(X.to(device), f.to(device), q.to(device))
        ps.append(out["final_prob"].cpu().numpy())
        ws.append(out["weights"].cpu().numpy())
        rs.append(out["residuals"].cpu().numpy())
        cs.append(out["correction"].cpu().numpy())
    if not ps:
        return (
            np.array([]),
            np.empty((0, args.n_experts + 1)),
            np.empty((0, args.n_experts)),
            np.array([]),
        )
    return np.concatenate(ps), np.concatenate(ws), np.concatenate(rs), np.concatenate(cs)


def fit_with_temporal_validation(bundle, args, seed, label):
    tr, va = latest_block_split(bundle.faculty_idx, bundle.blocks, args.val_blocks)
    if tr.sum() < args.min_train_rows:
        raise RuntimeError(f"{label}: only {tr.sum()} chronological training rows")
    if int(bundle.y[tr].sum()) < args.min_target_only_failures:
        raise RuntimeError(
            f"{label}: only {int(bundle.y[tr].sum())} chronological training failures; "
            f"minimum={args.min_target_only_failures}"
        )
    if va.sum() < args.min_val_rows:
        print(
            f"[{label}] validation rows={va.sum():,} < {args.min_val_rows}; "
            f"using fixed {args.fallback_epochs} epochs"
        )
        return int(args.fallback_epochs), pd.DataFrame(), pd.DataFrame([
            {"epoch": 0, "selection_score": np.nan, "note": "no_validation"}
        ]), tr, va

    scaler = FeatureStandardizer.fit(bundle.X[tr])
    seed_everything(seed)
    device = choose_device(args.device)
    model = _make_model(bundle.X.shape[1], 1, args).to(device)
    opt = torch.optim.AdamW(model.parameters(), lr=args.lr, weight_decay=args.weight_decay)
    best_score, best_epoch, patience = -np.inf, 1, 0
    best_rows = pd.DataFrame()
    history = []

    print(
        f"[{label}] chronological train={tr.sum():,} failures={int(bundle.y[tr].sum()):,} "
        f"val={va.sum():,} val_failures={int(bundle.y[va].sum()):,} "
        f"input_dim={bundle.X.shape[1]} device={device}"
    )
    for epoch in range(1, args.epochs + 1):
        loader, sampling = _tensor_loader(bundle, scaler, tr, args, seed + epoch * 997, sampled=True)
        losses = train_epoch(model, loader, opt, device, args)
        p, w, r, correction = predict_bundle(model, bundle, scaler, va, device, args)
        rows = per_faculty_validation_rows(
            bundle.y[va], bundle.q[va], p, bundle.faculty_idx[va], bundle.faculty_names,
            args.threshold_beta, 0.20
        )
        score, macro = model_selection_score(rows, args.macro_f2_weight)
        diag = router_diagnostics(w, r)
        hist = {
            "epoch": epoch,
            "selection_score": score,
            **losses,
            **macro,
            **diag,
            "mean_abs_correction": float(np.mean(np.abs(correction))) if len(correction) else np.nan,
            "train_rows": int(tr.sum()),
            "train_failures": int(bundle.y[tr].sum()),
            "val_rows": int(va.sum()),
            "val_failures": int(bundle.y[va].sum()),
            "positive_sampling_weight": sampling[bundle.faculty_names[0]]["positive_weight"],
            "negative_sampling_weight": sampling[bundle.faculty_names[0]]["negative_weight"],
        }
        history.append(hist)
        if epoch == 1 or epoch % args.print_every == 0:
            print(
                f"[{label}] epoch={epoch:03d} loss={losses['total']:.5f} sel={score:+.5f} "
                f"ΔAP={macro['median_delta_ap']:+.4f} ΔF2@20={macro['median_delta_f2_20']:+.4f} "
                f"NULL={diag['mean_null_weight']:.3f} H={diag['normalized_entropy']:.3f} "
                f"maxW={diag['mean_max_weight']:.3f} |corr|={hist['mean_abs_correction']:.3f}"
            )
        if np.isfinite(score) and score > best_score + args.min_selection_improvement:
            best_score, best_epoch, best_rows, patience = score, epoch, rows.copy(), 0
        else:
            patience += 1
        if epoch >= args.min_epochs and patience >= args.patience:
            break
    print(f"[{label}] selected epoch={best_epoch} selection score={best_score:+.5f}")
    return best_epoch, best_rows, pd.DataFrame(history), tr, va


def refit_full(bundle, args, seed, epochs, label):
    mask = np.ones(len(bundle.y), bool)
    scaler = FeatureStandardizer.fit(bundle.X)
    seed_everything(seed)
    device = choose_device(args.device)
    model = _make_model(bundle.X.shape[1], 1, args).to(device)
    opt = torch.optim.AdamW(model.parameters(), lr=args.lr, weight_decay=args.weight_decay)
    for epoch in range(1, max(int(epochs), 1) + 1):
        loader, _ = _tensor_loader(bundle, scaler, mask, args, seed + epoch * 1543, sampled=True)
        losses = train_epoch(model, loader, opt, device, args)
        if epoch == 1 or epoch == epochs or epoch % args.print_every == 0:
            print(f"[{label} refit] epoch={epoch:03d}/{epochs} loss={losses['total']:.5f}")
    return model, scaler, device


def budget_metrics(y, score, beta=2.0):
    row = {"ap": safe_ap(y, score), "auc": safe_auc(y, score)}
    for b in BUDGETS:
        z = equal_budget_metrics(y, score, b, beta)
        tag = int(b * 100)
        row[f"precision_at_{tag}"] = z["precision"]
        row[f"recall_at_{tag}"] = z["recall"]
        row[f"f1_at_{tag}"] = z["f1"]
        row[f"f2_at_{tag}"] = z["fbeta"]
    return row


def specialization_rows(fold, faculty, target, w, residuals, correction):
    base = np.ones(len(target.y), bool)
    groups = [
        ("all", base),
        ("failures", target.y == 1),
        ("normals", target.y == 0),
        ("history0", target.support_history_semesters <= 0),
        ("history1_2", (target.support_history_semesters >= 1) & (target.support_history_semesters <= 2)),
        ("history3plus", target.support_history_semesters >= 3),
    ]
    rows = []
    for group, mask in groups:
        if not np.any(mask):
            continue
        d = router_diagnostics(w[mask], residuals[mask])
        d.update(
            {
                "fold": fold,
                "faculty": faculty,
                "group": group,
                "rows": int(mask.sum()),
                "failures": int(target.y[mask].sum()),
                "prevalence": float(target.y[mask].mean()),
                "mean_correction": float(np.mean(correction[mask])),
                "mean_abs_correction": float(np.mean(np.abs(correction[mask]))),
            }
        )
        rows.append(d)
    return rows


def residual_correlation_rows(fold, faculty, residuals):
    if len(residuals) < 3:
        return []
    corr = np.corrcoef(residuals, rowvar=False)
    rows = []
    for i in range(corr.shape[0]):
        for j in range(i + 1, corr.shape[1]):
            rows.append(
                {
                    "fold": fold,
                    "faculty": faculty,
                    "expert_i": i + 1,
                    "expert_j": j + 1,
                    "correlation": float(corr[i, j]) if np.isfinite(corr[i, j]) else np.nan,
                }
            )
    return rows


def load_single_cache(cache_dir, faculty, fold):
    path = Path(cache_dir) / f"{faculty}_fold_{int(fold)}.joblib"
    if not path.exists():
        raise FileNotFoundError(f"missing Suite5 canonical cache: {path}")
    return joblib.load(path)


def run_faculty_fold(cache_dir, shared_results_dir, faculty, fold, args, out):
    print("\n" + "=" * 150)
    print(f"SUITE6 TARGET-ONLY RESIDUAL MoE | faculty={faculty} | TARGET FOLD {fold}")
    print("=" * 150)

    schema = load_shared_feature_schema(shared_results_dir, fold)
    common = list(schema["common_raw_features"])
    cache = load_single_cache(cache_dir, faculty, fold)
    caches = {faculty: cache}
    hist = build_historical_bundle(caches, [faculty], common)
    target = build_target_bundle(caches, [faculty], common)
    if len(hist.y) < args.min_train_rows or int(hist.y.sum()) < args.min_target_only_failures:
        raise RuntimeError(
            f"{faculty} fold {fold}: insufficient target-only history rows={len(hist.y):,} "
            f"failures={int(hist.y.sum())}"
        )

    shared_frame = load_shared_fold_frame(
        shared_results_dir,
        fold,
        faculty,
        expected_y=target.y,
        expected_committee=target.q,
        atol=args.shared_alignment_atol,
    )
    shared_score = shared_frame["residual_moe_shared"].to_numpy(float)
    shared_router_diag = summarize_router_frame(shared_frame)

    print(
        f"[DATA] historical OOF rows={len(hist.y):,} failures={int(hist.y.sum()):,} ({hist.y.mean():.2%}) | "
        f"target rows={len(target.y):,} failures={int(target.y.sum()):,} ({target.y.mean():.2%}) | "
        f"raw schema={len(common)} final inputs={hist.X.shape[1]}"
    )

    fold_dir = out / f"fold_{fold}"
    fold_dir.mkdir(parents=True, exist_ok=True)
    shared_faculties = list(schema.get("faculties", []))
    if faculty not in shared_faculties:
        raise ValueError(f"{faculty} not present in Suite5 shared schema for fold {fold}")
    # Exact seed convention used by the target-only path embedded in Suite5.
    seed = args.seed + fold * 200003 + shared_faculties.index(faculty)
    label = f"target-only:{faculty}:F{fold}"
    best_epoch, val_rows, history, tr, va = fit_with_temporal_validation(hist, args, seed, label)
    model, scaler, device = refit_full(hist, args, seed, best_epoch, label)
    p, w, residuals, correction = predict_bundle(
        model, target, scaler, np.ones(len(target.y), bool), device, args
    )

    scaler.save(fold_dir / f"{faculty}_target_only_scaler.npz")
    history.to_csv(fold_dir / f"{faculty}_target_only_training_history.csv", index=False)
    val_rows.to_csv(fold_dir / f"{faculty}_target_only_best_validation.csv", index=False)
    torch.save(
        {
            "state_dict": model.state_dict(),
            "selected_epoch": best_epoch,
            "model_config": {
                "input_dim": hist.X.shape[1],
                "n_faculties": 1,
                "n_experts": args.n_experts,
                "faculty_dim": args.faculty_dim,
                "encoder_hidden": args.encoder_hidden,
                "representation_dim": args.representation_dim,
                "expert_hidden": args.expert_hidden,
                "delta_max": args.delta_max,
                "dropout": args.dropout,
                "router_temperature": args.router_temperature,
            },
            "faculty": faculty,
            "common_raw_features": common,
            "source_shared_schema": str(Path(shared_results_dir) / f"fold_{fold}" / "feature_schema.json"),
        },
        fold_dir / f"{faculty}_target_only_model.pt",
    )

    cm = budget_metrics(target.y, target.q, args.threshold_beta)
    sm = budget_metrics(target.y, shared_score, args.threshold_beta)
    lm = budget_metrics(target.y, p, args.threshold_beta)
    print(
        f"[RESULT {faculty} F{fold}] AP committee/shared/local = {cm['ap']:.4f}/{sm['ap']:.4f}/{lm['ap']:.4f} "
        f"| local-committee={lm['ap']-cm['ap']:+.4f} local-shared={lm['ap']-sm['ap']:+.4f}"
    )
    print(
        f"[RESULT {faculty} F{fold}] AUC committee/shared/local = {cm['auc']:.4f}/{sm['auc']:.4f}/{lm['auc']:.4f} "
        f"| F2@20={cm['f2_at_20']:.4f}/{sm['f2_at_20']:.4f}/{lm['f2_at_20']:.4f} "
        f"local-shared={lm['f2_at_20']-sm['f2_at_20']:+.4f}"
    )

    all_diag = router_diagnostics(w, residuals)
    corr_rows = residual_correlation_rows(fold, faculty, residuals)
    mean_pair_corr = float(np.nanmean([r["correlation"] for r in corr_rows])) if corr_rows else np.nan
    print(
        f"[ROUTER {faculty} F{fold}] LOCAL epoch={best_epoch} NULL={all_diag['mean_null_weight']:.3f} "
        f"H={all_diag['normalized_entropy']:.3f} maxW={all_diag['mean_max_weight']:.3f} "
        f"|corr|={np.mean(np.abs(correction)):.3f} pairCorr={mean_pair_corr:.3f}"
    )
    print(
        f"[ROUTER {faculty} F{fold}] SHARED NULL={shared_router_diag['mean_null_weight']:.3f} "
        f"H={shared_router_diag['normalized_entropy']:.3f} maxW={shared_router_diag['mean_max_weight']:.3f} "
        f"|corr|={shared_router_diag['mean_abs_correction']:.3f} "
        f"pairCorr={shared_router_diag['mean_pairwise_residual_correlation']:.3f}"
    )

    score_df = pd.DataFrame(
        {
            "actual": target.y,
            "committee": target.q,
            "residual_moe_shared": shared_score,
            "residual_moe_target_only": p,
            "correction_logit_target_only": correction,
            "history_semesters": target.support_history_semesters,
        }
    )
    for j in range(w.shape[1]):
        score_df[f"target_only_weight_{'null' if j == 0 else f'expert_{j}'}"] = w[:, j]
    for j in range(residuals.shape[1]):
        score_df[f"target_only_residual_expert_{j+1}"] = residuals[:, j]
    score_df.to_csv(fold_dir / f"{faculty}_suite6_scores.csv", index=False)

    spec = specialization_rows(fold, faculty, target, w, residuals, correction)
    pd.DataFrame(spec).to_csv(fold_dir / f"{faculty}_target_only_specialization.csv", index=False)
    pd.DataFrame(corr_rows).to_csv(fold_dir / f"{faculty}_target_only_residual_correlations.csv", index=False)

    metrics = []
    for model_name, score in [
        ("committee", target.q),
        ("residual_moe_shared", shared_score),
        ("residual_moe_target_only", p),
    ]:
        m = budget_metrics(target.y, score, args.threshold_beta)
        metrics.append(
            {
                "fold": fold,
                "faculty": faculty,
                "model": model_name,
                "rows": len(target.y),
                "failures": int(target.y.sum()),
                "prevalence": float(target.y.mean()),
                **m,
            }
        )

    shared_selected_epoch = np.nan
    shared_model_path = Path(shared_results_dir) / f"fold_{fold}" / "shared_model.pt"
    if shared_model_path.exists():
        try:
            try:
                ckpt = torch.load(shared_model_path, map_location="cpu", weights_only=False)
            except TypeError:  # compatibility with older torch versions
                ckpt = torch.load(shared_model_path, map_location="cpu")
            shared_selected_epoch = float(ckpt.get("selected_epoch", np.nan))
        except Exception as exc:
            print(f"[WARN] could not read shared selected epoch from {shared_model_path}: {exc}")

    training_row = {
        "fold": fold,
        "faculty": faculty,
        "historical_rows": len(hist.y),
        "historical_failures": int(hist.y.sum()),
        "historical_prevalence": float(hist.y.mean()),
        "chronological_train_rows": int(tr.sum()),
        "chronological_train_failures": int(hist.y[tr].sum()),
        "validation_rows": int(va.sum()),
        "validation_failures": int(hist.y[va].sum()),
        "selected_epoch": int(best_epoch),
        "shared_selected_epoch": shared_selected_epoch,
        "target_null_weight": all_diag["mean_null_weight"],
        "shared_null_weight": shared_router_diag["mean_null_weight"],
        "shared_normalized_entropy": shared_router_diag["normalized_entropy"],
        "shared_mean_max_weight": shared_router_diag["mean_max_weight"],
        "shared_mean_abs_correction": shared_router_diag["mean_abs_correction"],
        "shared_mean_pairwise_residual_correlation": shared_router_diag["mean_pairwise_residual_correlation"],
        "target_normalized_entropy": all_diag["normalized_entropy"],
        "target_mean_max_weight": all_diag["mean_max_weight"],
        "target_mean_abs_correction": float(np.mean(np.abs(correction))),
        "target_mean_pairwise_residual_correlation": mean_pair_corr,
    }

    record = {
        "faculty": faculty,
        "fold": fold,
        "y": target.y,
        "scores": {
            "committee": target.q,
            "residual_moe_shared": shared_score,
            "residual_moe_target_only": p,
        },
    }
    return record, metrics, spec, corr_rows, training_row


def pooled_ranking_rows(records, holdout_folds, beta):
    rows = []
    for faculty in sorted({r["faculty"] for r in records}):
        rr = [r for r in records if r["faculty"] == faculty and r["fold"] in holdout_folds]
        y = np.concatenate([r["y"] for r in rr])
        models = set.intersection(*[set(r["scores"]) for r in rr])
        for model in sorted(models):
            score = np.concatenate([r["scores"][model] for r in rr])
            row = {
                "faculty": faculty,
                "model": model,
                "rows": len(y),
                "failures": int(y.sum()),
                "prevalence": float(y.mean()),
                "ap": safe_ap(y, score),
                "auc": safe_auc(y, score),
            }
            for b in BUDGETS:
                z = equal_budget_metrics(y, score, b, beta)
                tag = int(b * 100)
                row[f"precision_at_{tag}"] = z["precision"]
                row[f"recall_at_{tag}"] = z["recall"]
                row[f"f1_at_{tag}"] = z["f1"]
                row[f"f2_at_{tag}"] = z["fbeta"]
            rows.append(row)
    return pd.DataFrame(rows)


def print_pooled_table(pooled):
    print("\n" + "=" * 150)
    print("SUITE6 HOLDOUT POOLED — COMMITTEE vs SHARED RESIDUAL MoE vs TARGET-ONLY RESIDUAL MoE")
    print("=" * 150)
    for faculty in sorted(pooled.faculty.unique()):
        f = pooled[pooled.faculty == faculty].set_index("model")
        c, s, l = f.loc["committee"], f.loc["residual_moe_shared"], f.loc["residual_moe_target_only"]
        print(
            f"{faculty:46s} | AP {c.ap:.4f} / {s.ap:.4f} / {l.ap:.4f} "
            f"(local-shared {l.ap-s.ap:+.4f}) | AUC {c.auc:.4f}/{s.auc:.4f}/{l.auc:.4f} "
            f"| F2@20 {c.f2_at_20:.4f}/{s.f2_at_20:.4f}/{l.f2_at_20:.4f} "
            f"(local-shared {l.f2_at_20-s.f2_at_20:+.4f})"
        )


def operational_summary(records, faculties, args, out):
    models = ["committee", "residual_moe_shared", "residual_moe_target_only"]
    all_rows, policies = [], []
    print("\n" + "=" * 150)
    print("OFFICIAL OPERATIONAL EVALUATION — EACH MODEL TUNED ON THE SAME DEVELOPMENT FOLDS, THEN FROZEN")
    print("=" * 150)
    for faculty in faculties:
        for model in models:
            policy, rows = evaluate_faculty(
                records,
                faculty,
                model,
                args.dev_folds,
                args.holdout_folds,
                args.threshold_beta,
                args.min_precision,
                args.max_warning_ratio,
                args.min_flags,
                verbose=True,
            )
            policies.append(
                {
                    "faculty": faculty,
                    "model": model,
                    "threshold": policy.threshold,
                    "warning_ratio": policy.warning_ratio,
                    "development_ap": policy.development_ap,
                    "development_auc": policy.development_auc,
                    "development_prevalence": policy.development_prevalence,
                    "development_flag_rate": policy.flag_rate,
                    "development_precision": policy.precision,
                    "development_recall": policy.recall,
                    "development_f1": policy.f1,
                    "development_f2": policy.fbeta,
                    "constraints_relaxed": policy.constraints_relaxed,
                }
            )
            all_rows.extend(rows)
    wdf = pd.DataFrame(all_rows)
    pdf = pd.DataFrame(policies)
    wdf.to_csv(out / "suite6_warning_metrics.csv", index=False)
    pdf.to_csv(out / "suite6_threshold_policies.csv", index=False)
    return wdf, pdf


def print_transfer_diagnostic(diag):
    print("\n" + "=" * 150)
    print("LOCAL-vs-SHARED TRANSFER DIAGNOSTIC")
    print("Evidence pattern is descriptive only: majority preference across pooled AP, F2@20, and drift-aware F2.")
    print("=" * 150)
    cols = [
        "faculty",
        "shared_minus_committee_ap",
        "local_minus_committee_ap",
        "local_minus_shared_ap",
        "local_minus_shared_f2_20",
        "local_minus_shared_fixed_f2",
        "local_minus_shared_drift_f2",
        "ap_prefers",
        "f2_20_prefers",
        "drift_f2_prefers",
        "evidence_pattern",
    ]
    fmt = {
        "shared_minus_committee_ap": "{:+.4f}".format,
        "local_minus_committee_ap": "{:+.4f}".format,
        "local_minus_shared_ap": "{:+.4f}".format,
        "local_minus_shared_f2_20": "{:+.4f}".format,
        "local_minus_shared_fixed_f2": "{:+.4f}".format,
        "local_minus_shared_drift_f2": "{:+.4f}".format,
    }
    print(diag[cols].to_string(index=False, formatters=fmt))


def parse_args():
    p = argparse.ArgumentParser(description="Suite6 target-only Residual-MoE ablation")
    p.add_argument("--cache_dir", required=True, help="Reuse the completed Suite5 canonical cache directory")
    p.add_argument("--shared_results_dir", required=True, help="Completed Suite5 shared Residual-MoE result directory")
    p.add_argument("--models_dir", required=True, help="Suite6 output directory")
    p.add_argument("--faculties", default=",".join(DEFAULT_FACULTIES))
    p.add_argument("--dev_folds", default="1,2,3,4,5")
    p.add_argument("--holdout_folds", default="6,7")
    p.add_argument("--reference_metrics", default=None, help="Optional V2/Council reference CSV from collect_reference_metrics.py")
    p.add_argument("--seed", type=int, default=42)
    p.add_argument("--device", choices=["auto", "cpu", "cuda"], default="auto")
    p.add_argument("--n_experts", type=int, default=4)
    p.add_argument("--faculty_dim", type=int, default=8)
    p.add_argument("--encoder_hidden", type=int, default=256)
    p.add_argument("--representation_dim", type=int, default=128)
    p.add_argument("--expert_hidden", type=int, default=64)
    p.add_argument("--delta_max", type=float, default=2.0)
    p.add_argument("--dropout", type=float, default=0.10)
    p.add_argument("--router_temperature", type=float, default=1.0)
    p.add_argument("--epochs", type=int, default=60)
    p.add_argument("--min_epochs", type=int, default=8)
    p.add_argument("--patience", type=int, default=8)
    p.add_argument("--fallback_epochs", type=int, default=20)
    p.add_argument("--val_blocks", type=int, default=2)
    p.add_argument("--min_train_rows", type=int, default=800)
    p.add_argument("--min_val_rows", type=int, default=200)
    p.add_argument("--min_target_only_failures", type=int, default=20)
    p.add_argument("--batch_size", type=int, default=1024)
    p.add_argument("--predict_batch_size", type=int, default=4096)
    p.add_argument("--samples_per_epoch", type=int, default=0)
    p.add_argument("--lr", type=float, default=1e-3)
    p.add_argument("--weight_decay", type=float, default=1e-4)
    p.add_argument("--grad_clip", type=float, default=5.0)
    p.add_argument("--print_every", type=int, default=5)
    p.add_argument("--router_lambda", type=float, default=0.5)
    p.add_argument("--specialization_lambda", type=float, default=0.01)
    p.add_argument("--magnitude_lambda", type=float, default=0.01)
    p.add_argument("--utility_temperature", type=float, default=0.25)
    p.add_argument("--sampling_beta", type=float, default=0.9999)
    p.add_argument("--macro_f2_weight", type=float, default=1.0)
    p.add_argument("--min_selection_improvement", type=float, default=1e-5)
    p.add_argument("--threshold_beta", type=float, default=2.0)
    p.add_argument("--min_precision", type=float, default=0.15)
    p.add_argument("--max_warning_ratio", type=float, default=2.5)
    p.add_argument("--min_flags", type=int, default=5)
    p.add_argument("--shared_alignment_atol", type=float, default=1e-6)
    args = p.parse_args()
    args.faculties = [x.strip() for x in args.faculties.split(",") if x.strip()]
    args.dev_folds = [int(x) for x in args.dev_folds.split(",") if x.strip()]
    args.holdout_folds = [int(x) for x in args.holdout_folds.split(",") if x.strip()]
    return args


def main():
    args = parse_args()
    out = Path(args.models_dir)
    out.mkdir(parents=True, exist_ok=True)

    unsupported = [f for f in args.faculties if f not in DEFAULT_FACULTIES]
    if unsupported:
        print(f"[NOTE] running non-default diagnostic faculties: {unsupported}")

    print("=" * 150)
    print("SUITE6 — TARGET-ONLY RESIDUAL MoE ABLATION")
    print("Shared Suite5 predictions are READ-ONLY references; only target-only models are trained.")
    print("=" * 150)
    print(f"faculties={args.faculties}")
    print(f"folds={args.dev_folds + args.holdout_folds} device={args.device} experts={args.n_experts}")
    print(f"cache_dir={args.cache_dir}")
    print(f"shared_results_dir={args.shared_results_dir}")
    save_json({"args": vars(args), "default_faculties": DEFAULT_FACULTIES}, out / "suite6_run_config.json")

    records, metrics, spec, corr_rows, training_rows = [], [], [], [], []
    for fold in args.dev_folds + args.holdout_folds:
        for faculty in args.faculties:
            record, mm, ss, cc, tt = run_faculty_fold(
                args.cache_dir, args.shared_results_dir, faculty, fold, args, out
            )
            records.append(record)
            metrics.extend(mm)
            spec.extend(ss)
            corr_rows.extend(cc)
            training_rows.append(tt)

    metric_df = pd.DataFrame(metrics)
    spec_df = pd.DataFrame(spec)
    corr_df = pd.DataFrame(corr_rows)
    training_df = pd.DataFrame(training_rows)
    metric_df.to_csv(out / "suite6_fold_metrics.csv", index=False)
    spec_df.to_csv(out / "suite6_target_only_specialization.csv", index=False)
    corr_df.to_csv(out / "suite6_target_only_residual_correlations.csv", index=False)
    training_df.to_csv(out / "suite6_training_summary.csv", index=False)

    pooled = pooled_ranking_rows(records, args.holdout_folds, args.threshold_beta)
    pooled.to_csv(out / "suite6_holdout_pooled.csv", index=False)
    print_pooled_table(pooled)

    warning_df, policy_df = operational_summary(records, args.faculties, args, out)
    diag = build_transfer_diagnostic(pooled, warning_df)
    diag.to_csv(out / "suite6_local_vs_shared_transfer_diagnostic.csv", index=False)
    print_transfer_diagnostic(diag)

    # Router/specialization summary on the two holdout folds.
    hold_spec = spec_df[spec_df.fold.isin(args.holdout_folds)] if len(spec_df) else spec_df
    if len(hold_spec):
        summary_rows = []
        for faculty in args.faculties:
            for group in ["all", "failures", "normals", "history0", "history1_2", "history3plus"]:
                d = hold_spec[(hold_spec.faculty == faculty) & (hold_spec.group == group)]
                if d.empty:
                    continue
                summary_rows.append(
                    {
                        "faculty": faculty,
                        "group": group,
                        "mean_null_weight": d.mean_null_weight.mean(),
                        "normalized_entropy": d.normalized_entropy.mean(),
                        "mean_max_weight": d.mean_max_weight.mean(),
                        "mean_abs_correction": d.mean_abs_correction.mean(),
                    }
                )
        router_summary = pd.DataFrame(summary_rows)
        router_summary.to_csv(out / "suite6_holdout_router_summary.csv", index=False)
        print("\n" + "=" * 150)
        print("TARGET-ONLY ROUTER / SPECIALIZATION SUMMARY — HOLDOUT FOLDS")
        print("=" * 150)
        print(router_summary.to_string(index=False, float_format=lambda x: f"{x:.4f}"))

    if len(corr_df):
        hold_corr = corr_df[corr_df.fold.isin(args.holdout_folds)]
        corr_summary = hold_corr.groupby("faculty")["correlation"].agg(
            mean="mean", median="median", min="min", max="max"
        ).reset_index()
        corr_summary.to_csv(out / "suite6_holdout_residual_correlation_summary.csv", index=False)

    hold_train = training_df[training_df.fold.isin(args.holdout_folds)].copy()
    if len(hold_train):
        gate_rows = []
        for faculty in args.faculties:
            d = hold_train[hold_train.faculty == faculty]
            if d.empty:
                continue
            gate_rows.append({
                "faculty": faculty,
                "local_selected_epoch_mean": float(d.selected_epoch.mean()),
                "shared_selected_epoch_mean": float(d.shared_selected_epoch.mean()) if d.shared_selected_epoch.notna().any() else np.nan,
                "local_null_weight": float(d.target_null_weight.mean()),
                "shared_null_weight": float(d.shared_null_weight.mean()),
                "delta_null_local_minus_shared": float(d.target_null_weight.mean()-d.shared_null_weight.mean()),
                "local_entropy": float(d.target_normalized_entropy.mean()),
                "shared_entropy": float(d.shared_normalized_entropy.mean()),
                "delta_entropy_local_minus_shared": float(d.target_normalized_entropy.mean()-d.shared_normalized_entropy.mean()),
                "local_mean_max_weight": float(d.target_mean_max_weight.mean()),
                "shared_mean_max_weight": float(d.shared_mean_max_weight.mean()),
                "local_abs_correction": float(d.target_mean_abs_correction.mean()),
                "shared_abs_correction": float(d.shared_mean_abs_correction.mean()),
                "local_pairwise_residual_corr": float(d.target_mean_pairwise_residual_correlation.mean()),
                "shared_pairwise_residual_corr": float(d.shared_mean_pairwise_residual_correlation.mean()),
            })
        gate_df = pd.DataFrame(gate_rows)
        gate_df.to_csv(out / "suite6_shared_vs_local_router_diagnostic.csv", index=False)
        print("\n" + "=" * 150)
        print("SHARED-vs-LOCAL ROUTER DIAGNOSTIC — HOLDOUT AVERAGE")
        print("Lower entropy / lower residual correlation can indicate stronger specialization; higher NULL can indicate more abstention. Interpret jointly with performance.")
        print("=" * 150)
        print(gate_df.to_string(index=False, float_format=lambda x: f"{x:.4f}"))

    final = merge_external_references(diag, args.reference_metrics)
    final.to_csv(out / "suite6_official_comparison.csv", index=False)
    if args.reference_metrics:
        print("\n" + "=" * 150)
        print("OFFICIAL COMPARISON WITH PROVIDED V2 / COUNCIL REFERENCES")
        print("=" * 150)
        print(final.to_string(index=False))

    print("\n" + "=" * 150)
    print("EXPERIMENTAL QUESTION")
    print("If LOCAL is stronger on IT/Business while SHARED is stronger on German/International Studies, that is direct evidence for a shared-private next architecture.")
    print("Do not interpret evidence_pattern as proof by itself; inspect AP, F2@20, drift F2, selected epochs, NULL weights, and residual correlations together.")
    print("=" * 150)
    print(f"Completed. Results: {out}")


if __name__ == "__main__":
    main()
