#!/usr/bin/env python3
"""
Step 5: Results Interpretation

This script automatically interprets statistical regression results and generates
natural language summaries for the final report.

Input: results/model_results.csv (from Step 4)
Output: results/interpretation_summary.txt

Author: K-Dense Coding Agent
Date: 2025-12-29
"""

import sys
from pathlib import Path
import pandas as pd

# Set up paths
SESSION_DIR = Path("/app/sandbox/session_20251229_112053_41c35bf38d4f")
RESULTS_DIR = SESSION_DIR / "results"
MODEL_RESULTS_FILE = RESULTS_DIR / "model_results.csv"
OUTPUT_FILE = RESULTS_DIR / "interpretation_summary.txt"


def validate_inputs():
    """
    Check if required input files exist.

    Returns:
        bool: True if inputs are valid, False otherwise
    """
    if not MODEL_RESULTS_FILE.exists():
        print("=" * 80)
        print("⏳ WAITING FOR ANALYSIS RESULTS")
        print("=" * 80)
        print(f"\nRequired file not found: {MODEL_RESULTS_FILE}")
        print("\nThis script requires the statistical modeling step to be completed first.")
        print("Please run workflow/04_statistical_modeling.py with valid data before")
        print("running this interpretation script.")
        print("\nExpected workflow:")
        print("  1. Upload raw data to user_data/ or data/raw/")
        print("  2. Run 02_data_preprocessing.py")
        print("  3. Run 03_eda.py")
        print("  4. Run 04_statistical_modeling.py")
        print("  5. Run this script (05_results_interpretation.py)")
        print("=" * 80)
        return False

    return True


def interpret_coefficient(row):
    """
    Generate natural language interpretation for a single model result.

    Parameters:
        row (pd.Series): A row from model_results.csv with columns:
                        Model, Outcome, Coefficient, Std_Error, P_Value, CI_Lower, CI_Upper

    Returns:
        str: Natural language interpretation
    """
    model = row['Model']
    outcome = row['Outcome']
    coef = row['Coefficient']
    p_value = row['P_Value']
    ci_lower = row['CI_Lower']
    ci_upper = row['CI_Upper']

    # Determine direction
    if coef > 0:
        direction = "positive"
    elif coef < 0:
        direction = "negative"
    else:
        direction = "null"

    # Determine significance
    significance_level = 0.05
    is_significant = p_value < significance_level

    if is_significant:
        significance_text = "statistically significant"
    else:
        significance_text = "not statistically significant"

    # Format the interpretation
    interpretation = (
        f"Infrastructure Development has a {significance_text} {direction} "
        f"association with {outcome} (Coefficient: {coef:.4f}, "
        f"95% CI: [{ci_lower:.4f}, {ci_upper:.4f}], p-value: {p_value:.4f})."
    )

    # Add contextual interpretation
    if is_significant:
        if coef > 0:
            interpretation += (
                f"\n  → For every one-unit increase in Infrastructure Development, "
                f"{outcome} is expected to increase by {coef:.4f} units, holding "
                f"other factors constant."
            )
        else:
            interpretation += (
                f"\n  → For every one-unit increase in Infrastructure Development, "
                f"{outcome} is expected to decrease by {abs(coef):.4f} units, holding "
                f"other factors constant."
            )
    else:
        interpretation += (
            "\n  → The data does not provide sufficient evidence of a relationship "
            f"between Infrastructure Development and {outcome} at the {significance_level} significance level."
        )

    return interpretation


def generate_summary(df):
    """
    Generate comprehensive interpretation summary from all model results.

    Parameters:
        df (pd.DataFrame): Model results dataframe

    Returns:
        str: Formatted interpretation summary
    """
    summary_lines = []

    # Header
    summary_lines.append("=" * 80)
    summary_lines.append("STATISTICAL RESULTS INTERPRETATION")
    summary_lines.append("Infrastructure Development Impact on Gender Outcomes in India")
    summary_lines.append("=" * 80)
    summary_lines.append("")

    # Metadata
    summary_lines.append(f"Number of models analyzed: {len(df)}")
    summary_lines.append(f"Significance threshold: α = 0.05")
    summary_lines.append("")

    # Count significant results
    significant_count = (df['P_Value'] < 0.05).sum()
    summary_lines.append(f"Significant associations found: {significant_count}/{len(df)}")
    summary_lines.append("")

    # Section: Individual Model Interpretations
    summary_lines.append("-" * 80)
    summary_lines.append("INDIVIDUAL MODEL RESULTS")
    summary_lines.append("-" * 80)
    summary_lines.append("")

    for idx, row in df.iterrows():
        summary_lines.append(f"Model {idx + 1}: {row['Model']}")
        summary_lines.append("")
        interpretation = interpret_coefficient(row)
        summary_lines.append(interpretation)
        summary_lines.append("")
        summary_lines.append("-" * 80)
        summary_lines.append("")

    # Section: Summary of Findings
    summary_lines.append("SUMMARY OF KEY FINDINGS")
    summary_lines.append("-" * 80)
    summary_lines.append("")

    # Identify significant positive effects
    sig_positive = df[(df['P_Value'] < 0.05) & (df['Coefficient'] > 0)]
    if len(sig_positive) > 0:
        summary_lines.append("Significant Positive Associations:")
        for _, row in sig_positive.iterrows():
            summary_lines.append(f"  • {row['Outcome']}: β = {row['Coefficient']:.4f}, p = {row['P_Value']:.4f}")
        summary_lines.append("")

    # Identify significant negative effects
    sig_negative = df[(df['P_Value'] < 0.05) & (df['Coefficient'] < 0)]
    if len(sig_negative) > 0:
        summary_lines.append("Significant Negative Associations:")
        for _, row in sig_negative.iterrows():
            summary_lines.append(f"  • {row['Outcome']}: β = {row['Coefficient']:.4f}, p = {row['P_Value']:.4f}")
        summary_lines.append("")

    # Identify non-significant results
    non_sig = df[df['P_Value'] >= 0.05]
    if len(non_sig) > 0:
        summary_lines.append("Non-Significant Associations:")
        for _, row in non_sig.iterrows():
            summary_lines.append(f"  • {row['Outcome']}: β = {row['Coefficient']:.4f}, p = {row['P_Value']:.4f}")
        summary_lines.append("")

    # Overall conclusion
    summary_lines.append("-" * 80)
    summary_lines.append("OVERALL INTERPRETATION")
    summary_lines.append("-" * 80)
    summary_lines.append("")

    if significant_count > 0:
        summary_lines.append(
            f"The analysis found {significant_count} statistically significant association(s) "
            f"between Infrastructure Development and gender outcomes. These findings suggest "
            f"that infrastructure improvements may play a meaningful role in shaping gender "
            f"equality indicators, though the direction and magnitude vary by outcome measure."
        )
    else:
        summary_lines.append(
            "The analysis did not find statistically significant associations between "
            "Infrastructure Development and the examined gender outcomes at the α = 0.05 level. "
            "This may indicate that: (1) infrastructure's effects on gender outcomes are mediated "
            "by other factors not included in the models, (2) the sample size or measurement "
            "precision is insufficient to detect existing effects, or (3) the relationship is "
            "genuinely weak or absent."
        )

    summary_lines.append("")
    summary_lines.append("-" * 80)
    summary_lines.append("NOTES")
    summary_lines.append("-" * 80)
    summary_lines.append("")
    summary_lines.append("• All models control for literacy rate and urbanization percentage.")
    summary_lines.append("• Coefficients represent the change in the outcome variable for a ")
    summary_lines.append("  one-unit increase in Infrastructure Development, holding controls constant.")
    summary_lines.append("• 95% confidence intervals provide a range of plausible effect sizes.")
    summary_lines.append("• Statistical significance does not necessarily imply practical significance.")
    summary_lines.append("• Causal interpretation requires additional assumptions (e.g., no unmeasured confounding).")
    summary_lines.append("")
    summary_lines.append("=" * 80)
    summary_lines.append("END OF INTERPRETATION")
    summary_lines.append("=" * 80)

    return "\n".join(summary_lines)


def main():
    """
    Main execution function for results interpretation.
    """
    print("=" * 80)
    print("STEP 5: RESULTS INTERPRETATION")
    print("=" * 80)
    print()

    # Step 1: Validate inputs
    print("[1/3] Validating inputs...")
    if not validate_inputs():
        print("\n❌ Input validation failed. Exiting gracefully.")
        sys.exit(0)  # Exit gracefully, not an error
    print("✓ Input validation passed")
    print()

    # Step 2: Load model results
    print("[2/3] Loading model results...")
    try:
        df = pd.read_csv(MODEL_RESULTS_FILE)
        print(f"✓ Loaded {len(df)} model results from {MODEL_RESULTS_FILE.name}")
        print(f"  Columns: {list(df.columns)}")
        print()
    except Exception as e:
        print(f"❌ Error loading model results: {e}")
        sys.exit(1)

    # Step 3: Generate interpretation summary
    print("[3/3] Generating interpretation summary...")
    try:
        summary = generate_summary(df)

        # Save to file
        OUTPUT_FILE.parent.mkdir(parents=True, exist_ok=True)
        with open(OUTPUT_FILE, 'w', encoding='utf-8') as f:
            f.write(summary)

        print(f"✓ Interpretation summary saved to: {OUTPUT_FILE}")
        print()

        # Print preview of summary
        print("-" * 80)
        print("PREVIEW OF INTERPRETATION SUMMARY")
        print("-" * 80)
        print()
        summary_lines = summary.split('\n')
        # Print first 30 lines as preview
        for line in summary_lines[:30]:
            print(line)
        print()
        print(f"... (Full summary saved to {OUTPUT_FILE.name})")
        print()

    except Exception as e:
        print(f"❌ Error generating interpretation: {e}")
        import traceback
        traceback.print_exc()
        sys.exit(1)

    # Success
    print("=" * 80)
    print("✓ RESULTS INTERPRETATION COMPLETED SUCCESSFULLY")
    print("=" * 80)
    print()
    print("Generated outputs:")
    print(f"  • {OUTPUT_FILE}")
    print()
    print("Next steps:")
    print("  • Review the interpretation summary")
    print("  • Use findings for final report writing")
    print("  • Consider additional robustness checks or sensitivity analyses")
    print()


if __name__ == "__main__":
    main()