#!/usr/bin/env python3
"""Suite29 audited faculty/fold/seed summaries, for both live training and offline replay.

No learning, label fitting, or checkpoint selection happens here. Historical
F6/F7 scores are retrospective: not a pristine holdout.
"""
from __future__ import annotations
import argparse
from pathlib import Path
import json
import numpy as np
import pandas as pd
from suite25_common import print_table

PRIMARY = ('suite29_self_only', 'suite29_set')
METRICS = ('ap', 'auc', 'fbeta_at_20', 'brier', 'ece10')


def csv_optional(path):
    return pd.read_csv(path) if path.is_file() and path.stat().st_size > 0 else pd.DataFrame()


def print_and_save(title, df, out, name, max_rows=160):
    if df.empty:
        print(f'[REPORT SKIP] {name}: no applicable rows', flush=True)
        return
    df.to_csv(out/name, index=False)
    print_table(title, df, max_rows=max_rows)
    if len(df) > max_rows:
        print(f'[REPORT NOTE] Showing {max_rows} of {len(df)} rows; full table: {out/name}',flush=True)


def render_report(output_dir):
    out = Path(output_dir)
    m = csv_optional(out/'all_metrics.csv')
    if m.empty:
        raise FileNotFoundError(f'No metrics found in {out}')
    for col in ('model','faculty','fold','seed','ap'):
        if col not in m:
            raise ValueError(f'all_metrics.csv missing required column: {col}')
    print('\n' + '='*110)
    print('[SUITE29 FINAL RESEARCH REPORT] Faculty/fold/seed analysis; never select on target outcomes')
    print(f'[RESULT ROOT] {out}')
    print('='*110, flush=True)
    cols = [c for c in METRICS if c in m]
    full = m.groupby(['fold', 'seed', 'model'], as_index=False).agg(
        faculty_cells=('faculty','nunique'), rows=('rows','sum'),
        failures=('failures','sum'), **{v:(v,'mean') for v in cols})
    print_and_save('PER-FOLD/SEED MACRO METRICS — PER-FACULTY MEAN', full,
        out,'summary_fold_seed_macro.csv')
    print('[METRIC] AP/AUC/F2/Brier are averaged equally across faculties (not pooled across registrations).')
    print('[METRIC] Incomplete coverage must not be interpreted as a fair model-to-model comparison.')

    # A multi-fold macro comparison is complete only if the relevant model
    # covers every observed faculty/fold cell for EACH seed.
    all_cells=set(zip(m.fold,m.faculty))
    coverage=[]
    for (model, seed), g in m.groupby(['model','seed']):
        cells=set(zip(g.fold,g.faculty))
        coverage.append(dict(model=model,seed=seed,reported_cells=len(cells),
            expected_cells=len(all_cells),complete_coverage=(cells==all_cells)))
    coverage=pd.DataFrame(coverage)
    print_and_save('MODEL COVERAGE — FULL FACULTY/FOLD CELL REQUIREMENT',coverage,
        out,'summary_reference_coverage.csv')
    if (coverage.complete_coverage==False).any():
        print('[WARNING] Some historical references have incomplete coverage. Do NOT rank their partial macro-AP against a full-coverage model.',flush=True)

    f67=m[m.fold.isin([6,7])]
    if not f67.empty:
        ret=f67.groupby(['seed','model'], as_index=False).agg(
            cells=('faculty','size'), mean_ap=('ap','mean'),
            mean_auc=('auc','mean'),mean_f2_at20=('fbeta_at_20','mean'),
            mean_brier=('brier','mean'))
        print_and_save('RETROSPECTIVE F6/F7 MACRO — REPEATEDLY CONSULTED HOLDOUT',ret,
            out,'summary_retrospective_f6_f7.csv')
        print('[RETROSPECTIVE] F6/F7 were previously used for research decisions; they are not untouched test data.',flush=True)

    # Primary hypothesis matched on the exact faculty/fold/seed keys.
    s=m[m.model==PRIMARY[1]]
    b=m[m.model==PRIMARY[0]]
    paired=s.merge(b,on=['faculty','fold','seed'],suffixes=('_set','_self'),validate='one_to_one')
    if not paired.empty:
        for v in cols:
            paired[f'delta_{v}']=paired[f'{v}_set']-paired[f'{v}_self']
        report_cols=['fold','seed','faculty','rows_set','failures_set']+[f'delta_{v}' for v in cols]
        print_and_save('PAIRED FACULTY/FOLD/SEED DIFFERENCES — SET MINUS SELF',
            paired[report_cols],out,'summary_paired_all.csv',max_rows=200)
        agg=[]
        for (fold,seed),g in paired.groupby(['fold','seed']):
            d=g.delta_ap
            agg.append(dict(fold=fold,seed=seed,faculty_cells=len(g),
                set_wins=int((d>0).sum()),set_losses=int((d<0).sum()),ties=int((d==0).sum()),
                mean_delta_ap=float(d.mean()),median_delta_ap=float(d.median()),
                min_delta_ap=float(d.min()),max_delta_ap=float(d.max())))
        print_and_save('SET-ATTENTION WINS/LOSSES PER FOLD/SEED',pd.DataFrame(agg),
            out,'summary_paired_wins.csv')
        faculty=paired.groupby('faculty',as_index=False).agg(
            n_fold_seed_cells=('delta_ap','size'),mean_delta_ap=('delta_ap','mean'),
            median_delta_ap=('delta_ap','median'),
            win_fraction=('delta_ap',lambda s: float((s>0).mean())),
            mean_delta_f2_at20=('delta_fbeta_at_20','mean'))
        print_and_save('SET VERSUS SELF — FACULTY STABILITY ACROSS INCLUDED FOLDS/SEEDS',
            faculty.sort_values('mean_delta_ap',ascending=False),out,'summary_paired_by_faculty.csv')
        retrospective=paired[paired.fold.isin([6,7])]
        if not retrospective.empty:
            print_and_save('SET VERSUS SELF — RETROSPECTIVE F6/F7 PAIRED AP',
                retrospective.groupby('faculty',as_index=False).agg(
                  cells=('delta_ap','size'),mean_delta_ap=('delta_ap','mean'),
                  win_fraction=('delta_ap',lambda s:float((s>0).mean()))
                ).sort_values('mean_delta_ap',ascending=False),out,'summary_paired_retrospective_f6_f7.csv')
    else:
        print('[REPORT] Matched self-only/set data not available; hypothesis comparison omitted.',flush=True)

    att = csv_optional(out/'all_attention_stratified.csv')
    if not att.empty:
        att = att[att.model=='suite29_set'].copy()
        if not att.empty:
            def weighted(s, col):
                return float(np.average(s[col],weights=s['rows']))
            grouped = []
            for (faculty,size_bin), g in att.groupby(['faculty','size_bin'],sort=True):
                grouped.append(dict(faculty=faculty,size_bin=size_bin,rows=int(g.rows.sum()),
                    self_mass=weighted(g,'mean_self_mass'),
                    peer_mass=weighted(g,'mean_peer_mass'),
                    null_mass=weighted(g,'mean_null_mass')))
            print_and_save('WHERE DOES SET ATTENTION GO? FACULTY × OBSERVED SET SIZE',
                pd.DataFrame(grouped),out,'summary_set_attention_faculty_size.csv',max_rows=160)
            print('[INTERPRETATION] Attention allocation is descriptive, not causal importance.',flush=True)

    groups=csv_optional(out/'all_group_size_summaries.csv')
    if not groups.empty:
        summary=[]
        for (model,size_bin),g in groups.groupby(['model','size_bin'],sort=True,observed=True):
            weights=g.groups.clip(lower=1)
            summary.append(dict(model=model,size_bin=size_bin,groups=int(g.groups.sum()),
                registrations=int(g.registrations.sum()),
                observed_failures_per_group=float(np.average(g.mean_observed_failures,weights=weights)),
                expected_failures_per_group=float(np.average(g.mean_expected_failures,weights=weights)),
                group_count_mae=float(np.average(g.mean_absolute_count_error,weights=weights))))
        print_and_save('GROUP-SIZE DIAGNOSTICS — OBSERVED VS EXPECTED FAILURES',
            pd.DataFrame(summary),out,'summary_group_size_failure_counts.csv')
        print('[INTERPRETATION] Failure-count diagnostics describe a marginal sum; not a learned joint event distribution.',flush=True)

    audit=csv_optional(out/'all_history_coverage_audit.csv')
    if not audit.empty:
        rows=audit[['fold','faculty','partial_groups','rows_in_partial_groups',
            'fraction_retained_rows_in_partial_groups']].copy()
        print_and_save('INCOMPLETE HISTORICAL COURSE SETS — COVERAGE AUDIT',
            rows,out,'summary_history_partial_groups.csv')
        bad=rows[rows.partial_groups>0]
        if len(bad):
            print(f'[WARNING] {len(bad)} faculty/fold history cells have partially retained semester groups; this can change train-versus-target set composition.',flush=True)

    bootstrap=csv_optional(out/'all_bootstrap.csv')
    if not bootstrap.empty:
        print_and_save('PAIRED STUDENT-CLUSTER AP BOOTSTRAP INTERVALS',
            bootstrap,out,'summary_bootstrap.csv',max_rows=160)
        print('[UNCERTAINTY] These intervals are descriptive; repeated origins/seeds and prior holdout reuse remain limitations.',flush=True)

    print(f'[REPORT COMPLETE] {out}',flush=True)
    return dict(rows=len(m),faculties=int(m.faculty.nunique()),folds=int(m.fold.nunique()),
        models=int(m.model.nunique()),matched_cells=len(paired))

if __name__=='__main__':
    p=argparse.ArgumentParser()
    p.add_argument('--output-dir',required=True)
    a=p.parse_args()
    print(json.dumps(render_report(a.output_dir),indent=2))
