hiffi-artist-intelligence/exporters/excel_workbook.py

"""
exporters/excel_workbook.py
Generates an executive Excel audit workbook containing:
1. Sheet 1: 'Executive_Summary_&_Governance' (Methodology, sources, zero-imputation policy).
2. Sheet 2: 'Commercial_Sales_Catalog' (Verified CSPC metrics, EAS units, provenance URLs).
3. Sheet 3: 'Simulated_Rerankings' (Side-by-side Published vs Simulated ranks and deltas).
4. Sheet 4: 'Sensitivity_Analysis' (Rankings across 0%, 5%, 10%, 15%, 20% weights).
"""

from datetime import datetime, timezone
import io
from pathlib import Path
from typing import Optional
import openpyxl
from openpyxl.styles import Alignment, Border, Font, PatternFill, Side
import pandas as pd

from core.cpi_engine import CommercialPowerEngine


def generate_executive_sales_workbook(
    df: pd.DataFrame,
    commercial_weight: float = 0.15,
    mode: str = "matched_only",
) -> bytes:
    """Generates an in-memory, styled multi-tab Excel workbook."""
    engine = CommercialPowerEngine()

    df_copy = df.copy()
    if "commercial_power_index" not in df_copy.columns:
        df_copy["commercial_power_index"] = engine.calculate_cpi(df_copy)

    sim_df = engine.simulate_ranking(df_copy, commercial_weight=commercial_weight, mode=mode)
    sensitivity_df = engine.run_sensitivity_matrix(df_copy, mode=mode)
    metrics = engine.compute_simulation_metrics(sim_df)

    output = io.BytesIO()
    with pd.ExcelWriter(output, engine="openpyxl") as writer:
        meta_data = {
            "Parameter / Metric": [
                "Report Title",
                "Generated At (UTC)",
                "Telemetry Source",
                "Source Methodology",
                "Unit of Measurement",
                "Zero-Imputation Policy",
                "Total Monitored Cohort",
                "Verified Cataloged Artists",
                "Coverage Ratio",
                "Simulation Mode",
                "Commercial Signal Weight",
                "Top Gainer (Rank Delta)",
                "Top Loser (Rank Delta)",
                "Mean Absolute Rank Shift",
            ],
            "Value": [
                "HIFFI Commercial Record Sales & Simulation Audit",
                datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
                "ChartMasters (Best Selling Artists of All Time)",
                "CSPC (Commensurate Sales to Popularity Concept)",
                "EAS (Equivalent Album Sales)",
                "Enforced (Strict NaN retention; 0 synthetic zeroes)",
                len(df),
                metrics["matched_coverage"],
                f"{metrics['matched_coverage'] / len(df):.1%}",
                mode.replace("_", " ").title(),
                f"{int(commercial_weight * 100)}% Commercial / {int((1 - commercial_weight) * 100)}% Baseline",
                f"{metrics['top_gainer_name']} (▲ +{metrics['top_gainer_delta']})",
                f"{metrics['top_loser_name']} (▼ {metrics['top_loser_delta']})",
                f"± {metrics['mean_abs_delta']} positions",
            ],
        }
        pd.DataFrame(meta_data).to_excel(writer, sheet_name="Executive_Summary", index=False)

        sales_cols = {
            "cohort_sales_rank": "Cohort Sales Rank",
            "chartmasters_sales_rank": "ChartMasters Global Rank",
            "name": "Artist Name",
            "total_eas_cspc": "Total Equivalent Album Sales (EAS)",
            "pure_album_sales": "Traditional Album Sales",
            "physical_singles_sales": "Physical Singles Sales",
            "digital_singles_sales": "Digital Track Downloads",
            "streaming_eas": "Streaming-Equivalent Album Sales (EAS)",
            "commercial_power_index": "Commercial Power Index (0-100)",
            "sales_data_status": "Provenance Status",
            "sales_collected_at": "Collected Timestamp",
            "sales_source_url": "Source Audit URL",
        }
        matched_catalog = (
            df_copy[df_copy["sales_data_status"] == "VERIFIED_CSPC"]
            .sort_values(by="total_eas_cspc", ascending=False)
            .copy()
        )
        export_catalog = matched_catalog[[c for c in sales_cols.keys() if c in matched_catalog.columns]].rename(
            columns=sales_cols
        )
        export_catalog.to_excel(writer, sheet_name="Commercial_Sales_Catalog", index=False)

        sim_cols = {
            "simulated_rank": "Simulated Rank",
            ("baseline_matched_rank" if mode == "matched_only" else "hiffi_xp_published_rank"): "Published / Baseline Rank",
            "simulation_rank_delta": "Simulated Rank Delta (Signed)",
            "name": "Artist Name",
            "simulated_hiffi_score": "Simulated Composite Score",
            "hiffi_xp_score": "Published HIFFI-XP Score",
            "commercial_power_index": "Commercial Power Index",
            "total_eas_cspc": "Total Equivalent Album Sales",
            "sales_data_status": "Status",
        }
        export_sim = sim_df[[c for c in sim_cols.keys() if c in sim_df.columns]].rename(columns=sim_cols)
        export_sim.to_excel(writer, sheet_name="Simulated_Rerankings", index=False)

        sensitivity_df.to_excel(writer, sheet_name="Sensitivity_Analysis", index=False)

    wb = openpyxl.load_workbook(output)
    header_fill = PatternFill(start_color="111827", end_color="111827", fill_type="solid")
    header_font = Font(name="Calibri", size=11, bold=True, color="FFFFFF")
    thin_border = Border(
        left=Side(style="thin", color="E5E7EB"),
        right=Side(style="thin", color="E5E7EB"),
        top=Side(style="thin", color="E5E7EB"),
        bottom=Side(style="thin", color="E5E7EB"),
    )

    for sheet in wb.worksheets:
        sheet.views.sheetView[0].showGridLines = True
        for col_idx, col_cells in enumerate(sheet.columns, 1):
            max_len = max(len(str(cell.value or "")) for cell in col_cells)
            col_letter = openpyxl.utils.get_column_letter(col_idx)
            sheet.column_dimensions[col_letter].width = max(max_len + 4, 14)

            header_cell = col_cells[0]
            header_cell.fill = header_fill
            header_cell.font = header_font
            header_cell.alignment = Alignment(horizontal="center", vertical="center")

            for cell in col_cells[1:]:
                cell.border = thin_border
                if isinstance(cell.value, float):
                    cell.number_format = "#,##0.00"
                elif isinstance(cell.value, int) and cell.value > 999:
                    cell.number_format = "#,##0"

    styled_output = io.BytesIO()
    wb.save(styled_output)
    return styled_output.getvalue()


def write_disk_workbook(output_path: Path, df: pd.DataFrame) -> None:
    """Utility to generate the workbook to local disk for repository artifacts."""
    content = generate_executive_sales_workbook(df)
    output_path.parent.mkdir(parents=True, exist_ok=True)
    output_path.write_bytes(content)
    print(f"[Excel] Generated verified executive workbook at {output_path}")