People Analytics

#!/usr/bin/env python3
"""
Attrition Predictor - Score employees for attrition risk using rule-based heuristics.

Reads employee data CSV and computes a flight risk score (0-100) for each employee
based on weighted factors: tenure, compensation ratio, engagement, promotion recency,
manager tenure, and performance rating. No ML libraries required.

Usage:
    python attrition_predictor.py --file employees.csv
    python attrition_predictor.py --file employees.csv --threshold 70 --json
    python attrition_predictor.py --file employees.csv --top 20

Input CSV columns:
    employee_id             - Unique employee identifier
    department              - Department name
    tenure_months           - Months of employment
    salary_ratio_to_market  - Ratio of salary to market median (e.g., 0.92 = 8% below)
    performance_rating      - Last performance rating (1-5 scale)
    months_since_promotion  - Months since last promotion
    engagement_score        - Last engagement survey score (1-5)
    manager_tenure_months   - Months the current manager has been in role
    training_hours_ytd      - Training hours year-to-date
    level                   - Job level (optional)
    location                - Location (optional)

Output: Per-employee risk scores with risk factors and organizational summary.
"""

import argparse
import csv
import json
import os
import sys
from collections import defaultdict


# --- Risk factor weights and thresholds ---

WEIGHTS = {
    "compensation": 25,
    "promotion_stagnation": 20,
    "engagement": 20,
    "tenure_risk": 15,
    "manager_instability": 10,
    "development_gap": 10,
}

TENURE_RISK_BANDS = [
    # (min_months, max_months, risk_score, label)
    (0, 6, 30, "New hire - settling in"),
    (6, 18, 60, "High-risk window - 6-18 months"),
    (18, 36, 40, "Moderate - building career capital"),
    (36, 60, 50, "Moderate - may seek growth externally"),
    (60, 120, 35, "Established - lower base risk"),
    (120, 999, 25, "Long-tenure - low mobility risk"),
]


def read_csv(path: str) -> list:
    """Read CSV file and return list of dicts."""
    if not os.path.isfile(path):
        print(f"Error: File not found: {path}", file=sys.stderr)
        sys.exit(1)
    with open(path, "r", encoding="utf-8") as f:
        reader = csv.DictReader(f)
        rows = list(reader)
    required = {"employee_id", "tenure_months", "salary_ratio_to_market", "engagement_score"}
    if rows:
        missing = required - set(rows[0].keys())
        if missing:
            print(f"Error: Missing required columns: {', '.join(missing)}", file=sys.stderr)
            sys.exit(1)
    return rows


def safe_float(val: str, default: float = 0.0) -> float:
    """Safely parse float."""
    try:
        return float(val)
    except (ValueError, TypeError):
        return default


def score_compensation(ratio: float) -> tuple:
    """Score compensation risk (0-100). Lower ratio = higher risk."""
    if ratio >= 1.05:
        return 10, "Above market"
    elif ratio >= 0.95:
        return 25, "At market"
    elif ratio >= 0.90:
        return 55, "Slightly below market"
    elif ratio >= 0.85:
        return 75, "Below market"
    else:
        return 95, "Significantly below market"


def score_promotion(months_since: float) -> tuple:
    """Score promotion stagnation risk (0-100)."""
    if months_since <= 12:
        return 10, "Recently promoted"
    elif months_since <= 24:
        return 30, "Within normal cycle"
    elif months_since <= 36:
        return 55, "Approaching stagnation"
    elif months_since <= 48:
        return 75, "Promotion overdue"
    else:
        return 90, "Significant stagnation"


def score_engagement(score: float) -> tuple:
    """Score engagement risk (0-100). Lower engagement = higher risk."""
    if score >= 4.5:
        return 10, "Highly engaged"
    elif score >= 4.0:
        return 25, "Engaged"
    elif score >= 3.5:
        return 45, "Neutral"
    elif score >= 3.0:
        return 70, "Disengaged"
    else:
        return 90, "Highly disengaged"


def score_tenure(months: float) -> tuple:
    """Score tenure-based risk (0-100)."""
    for min_m, max_m, risk, label in TENURE_RISK_BANDS:
        if min_m <= months < max_m:
            return risk, label
    return 30, "Unknown tenure band"


def score_manager_instability(months: float) -> tuple:
    """Score manager instability risk (0-100). New managers = higher risk."""
    if months >= 24:
        return 15, "Stable manager relationship"
    elif months >= 12:
        return 30, "Moderate manager tenure"
    elif months >= 6:
        return 55, "Recent manager change"
    else:
        return 80, "Very new manager"


def score_development(training_hours: float) -> tuple:
    """Score development investment risk (0-100). Low training = higher risk."""
    if training_hours >= 40:
        return 10, "Strong development investment"
    elif training_hours >= 20:
        return 30, "Adequate development"
    elif training_hours >= 10:
        return 55, "Below average development"
    else:
        return 80, "Minimal development investment"


def compute_risk_score(row: dict) -> dict:
    """Compute overall risk score for an employee."""
    tenure = safe_float(row.get("tenure_months", 0))
    comp_ratio = safe_float(row.get("salary_ratio_to_market", 1.0))
    engagement = safe_float(row.get("engagement_score", 3.5))
    months_promo = safe_float(row.get("months_since_promotion", 24))
    mgr_tenure = safe_float(row.get("manager_tenure_months", 12))
    training = safe_float(row.get("training_hours_ytd", 20))
    perf = safe_float(row.get("performance_rating", 3.0))

    comp_score, comp_label = score_compensation(comp_ratio)
    promo_score, promo_label = score_promotion(months_promo)
    eng_score, eng_label = score_engagement(engagement)
    tenure_score, tenure_label = score_tenure(tenure)
    mgr_score, mgr_label = score_manager_instability(mgr_tenure)
    dev_score, dev_label = score_development(training)

    # Weighted overall score
    overall = (
        comp_score * WEIGHTS["compensation"]
        + promo_score * WEIGHTS["promotion_stagnation"]
        + eng_score * WEIGHTS["engagement"]
        + tenure_score * WEIGHTS["tenure_risk"]
        + mgr_score * WEIGHTS["manager_instability"]
        + dev_score * WEIGHTS["development_gap"]
    ) / 100

    # Adjust for high performers (higher risk when other factors are negative)
    if perf >= 4.0 and overall > 50:
        overall = min(100, overall * 1.1)  # High performers at risk are extra costly

    overall = round(min(100, max(0, overall)), 1)

    # Risk level
    if overall >= 75:
        risk_level = "CRITICAL"
    elif overall >= 50:
        risk_level = "HIGH"
    elif overall >= 30:
        risk_level = "MEDIUM"
    else:
        risk_level = "LOW"

    # Top risk factors (sorted by contribution)
    factors = [
        {"factor": "Compensation", "score": comp_score, "weight": WEIGHTS["compensation"], "detail": f"{comp_label} (ratio: {comp_ratio:.2f})"},
        {"factor": "Promotion", "score": promo_score, "weight": WEIGHTS["promotion_stagnation"], "detail": f"{promo_label} ({months_promo:.0f} months)"},
        {"factor": "Engagement", "score": eng_score, "weight": WEIGHTS["engagement"], "detail": f"{eng_label} (score: {engagement:.1f})"},
        {"factor": "Tenure", "score": tenure_score, "weight": WEIGHTS["tenure_risk"], "detail": f"{tenure_label} ({tenure:.0f} months)"},
        {"factor": "Manager", "score": mgr_score, "weight": WEIGHTS["manager_instability"], "detail": f"{mgr_label} ({mgr_tenure:.0f} months)"},
        {"factor": "Development", "score": dev_score, "weight": WEIGHTS["development_gap"], "detail": f"{dev_label} ({training:.0f} hrs YTD)"},
    ]
    factors.sort(key=lambda x: x["score"] * x["weight"], reverse=True)

    return {
        "employee_id": row["employee_id"],
        "department": row.get("department", ""),
        "level": row.get("level", ""),
        "risk_score": overall,
        "risk_level": risk_level,
        "performance_rating": perf,
        "top_risk_factors": factors[:3],
        "all_factors": factors,
    }


def compute_summary(results: list) -> dict:
    """Compute organizational summary statistics."""
    total = len(results)
    if total == 0:
        return {}

    critical = sum(1 for r in results if r["risk_level"] == "CRITICAL")
    high = sum(1 for r in results if r["risk_level"] == "HIGH")
    medium = sum(1 for r in results if r["risk_level"] == "MEDIUM")
    low = sum(1 for r in results if r["risk_level"] == "LOW")

    scores = [r["risk_score"] for r in results]
    avg_score = sum(scores) / len(scores)

    # High performers at risk
    high_perf_at_risk = [r for r in results if r["performance_rating"] >= 4.0 and r["risk_level"] in ("CRITICAL", "HIGH")]

    # Department breakdown
    dept_risk = defaultdict(list)
    for r in results:
        dept = r.get("department", "Unknown") or "Unknown"
        dept_risk[dept].append(r["risk_score"])

    dept_summary = []
    for dept, scores_list in sorted(dept_risk.items()):
        dept_avg = sum(scores_list) / len(scores_list)
        dept_critical = sum(1 for s in scores_list if s >= 75)
        dept_summary.append({
            "department": dept,
            "employee_count": len(scores_list),
            "avg_risk_score": round(dept_avg, 1),
            "critical_count": dept_critical,
        })
    dept_summary.sort(key=lambda x: x["avg_risk_score"], reverse=True)

    return {
        "total_employees": total,
        "risk_distribution": {
            "critical": critical,
            "high": high,
            "medium": medium,
            "low": low,
        },
        "avg_risk_score": round(avg_score, 1),
        "high_performers_at_risk": len(high_perf_at_risk),
        "department_summary": dept_summary,
    }


def format_human(results: list, summary: dict, threshold: float) -> str:
    """Format results for human-readable output."""
    lines = []
    lines.append("=" * 70)
    lines.append("ATTRITION RISK ASSESSMENT REPORT")
    lines.append("=" * 70)
    lines.append("")

    dist = summary["risk_distribution"]
    lines.append(f"  Total Employees Scored:    {summary['total_employees']}")
    lines.append(f"  Average Risk Score:        {summary['avg_risk_score']}/100")
    lines.append(f"  High Performers at Risk:   {summary['high_performers_at_risk']}")
    lines.append("")
    lines.append(f"  Risk Distribution:")
    lines.append(f"    CRITICAL (75+): {dist['critical']:>4} ({dist['critical']/summary['total_employees']*100:.1f}%)")
    lines.append(f"    HIGH (50-74):   {dist['high']:>4} ({dist['high']/summary['total_employees']*100:.1f}%)")
    lines.append(f"    MEDIUM (30-49): {dist['medium']:>4} ({dist['medium']/summary['total_employees']*100:.1f}%)")
    lines.append(f"    LOW (0-29):     {dist['low']:>4} ({dist['low']/summary['total_employees']*100:.1f}%)")

    # Department summary
    if summary["department_summary"]:
        lines.append("")
        lines.append("-" * 70)
        lines.append("DEPARTMENT RISK SUMMARY")
        lines.append("-" * 70)
        lines.append(f"  {'Department':<25} {'Employees':>10} {'Avg Risk':>10} {'Critical':>10}")
        lines.append(f"  {'-'*25} {'-'*10} {'-'*10} {'-'*10}")
        for dept in summary["department_summary"]:
            lines.append(f"  {dept['department']:<25} {dept['employee_count']:>10} {dept['avg_risk_score']:>10.1f} {dept['critical_count']:>10}")

    # Individual results above threshold
    flagged = [r for r in results if r["risk_score"] >= threshold]
    flagged.sort(key=lambda x: x["risk_score"], reverse=True)

    if flagged:
        lines.append("")
        lines.append("-" * 70)
        lines.append(f"EMPLOYEES ABOVE RISK THRESHOLD ({threshold})")
        lines.append("-" * 70)
        for r in flagged[:30]:
            perf_tag = " [HIGH PERFORMER]" if r["performance_rating"] >= 4.0 else ""
            lines.append(f"\n  {r['employee_id']} | {r['department']} | Risk: {r['risk_score']}/100 ({r['risk_level']}){perf_tag}")
            for f in r["top_risk_factors"]:
                lines.append(f"    - {f['factor']}: {f['detail']}")

    lines.append("")
    return "\n".join(lines)


def main():
    parser = argparse.ArgumentParser(
        description="Score employees for attrition risk using rule-based heuristics."
    )
    parser.add_argument("--file", required=True, help="Path to employee data CSV")
    parser.add_argument("--threshold", type=float, default=50, help="Risk score threshold for flagging (default: 50)")
    parser.add_argument("--top", type=int, default=None, help="Show only top N highest-risk employees")
    parser.add_argument("--json", action="store_true", help="Output results as JSON")
    args = parser.parse_args()

    rows = read_csv(args.file)
    if not rows:
        print("Error: No data found in CSV file.", file=sys.stderr)
        sys.exit(1)

    results = [compute_risk_score(row) for row in rows]
    results.sort(key=lambda x: x["risk_score"], reverse=True)

    if args.top:
        results = results[:args.top]

    summary = compute_summary(results)

    if args.json:
        output = {
            "summary": summary,
            "employees": results,
        }
        print(json.dumps(output, indent=2))
    else:
        print(format_human(results, summary, args.threshold))


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Headcount Planner - Workforce planning calculations and scenario modeling.

Reads current workforce data and computes future headcount needs based on
growth targets, attrition assumptions, and hiring capacity. Supports
multi-quarter forecasting and department-level breakdowns.

Usage:
    python headcount_planner.py --file workforce.csv --growth 0.15 --attrition 0.12
    python headcount_planner.py --file workforce.csv --growth 0.15 --attrition 0.12 --quarters 4 --json
    python headcount_planner.py --file workforce.csv --growth 0.20 --attrition 0.10 --hiring-capacity 15

Input CSV columns:
    department          - Department name
    current_headcount   - Current headcount in department
    open_roles          - Number of open/approved roles
    attrition_rate      - Department-specific attrition rate (optional, overrides --attrition)
    avg_cost_per_hire   - Average cost per hire for department (optional)
    avg_salary          - Average salary for department (optional)
    growth_rate         - Department-specific growth rate (optional, overrides --growth)

Output: Quarter-by-quarter headcount plan with hiring needs, costs, and gap analysis.
"""

import argparse
import csv
import json
import math
import os
import sys


def read_csv(path: str) -> list:
    """Read CSV file and return list of dicts."""
    if not os.path.isfile(path):
        print(f"Error: File not found: {path}", file=sys.stderr)
        sys.exit(1)
    with open(path, "r", encoding="utf-8") as f:
        reader = csv.DictReader(f)
        rows = list(reader)
    required = {"department", "current_headcount"}
    if rows:
        missing = required - set(rows[0].keys())
        if missing:
            print(f"Error: Missing required columns: {', '.join(missing)}", file=sys.stderr)
            sys.exit(1)
    return rows


def safe_float(val: str, default: float = 0.0) -> float:
    """Safely parse float."""
    try:
        return float(val)
    except (ValueError, TypeError):
        return default


def safe_int(val: str, default: int = 0) -> int:
    """Safely parse int."""
    try:
        return int(float(val))
    except (ValueError, TypeError):
        return default


def forecast_department(dept: dict, growth_rate: float, attrition_rate: float,
                        quarters: int, hiring_capacity: int = None) -> dict:
    """Forecast headcount for a single department over N quarters."""
    name = dept["department"]
    current_hc = safe_int(dept.get("current_headcount", 0))
    open_roles = safe_int(dept.get("open_roles", 0))
    dept_attrition = safe_float(dept.get("attrition_rate"), attrition_rate)
    dept_growth = safe_float(dept.get("growth_rate"), growth_rate)
    avg_cost = safe_float(dept.get("avg_cost_per_hire", 4500))
    avg_salary = safe_float(dept.get("avg_salary", 100000))

    # Quarterly rates
    quarterly_attrition = dept_attrition / 4
    quarterly_growth = dept_growth / 4

    # Target headcount at end of planning horizon
    target_hc = math.ceil(current_hc * (1 + dept_growth))

    quarterly_plan = []
    running_hc = current_hc
    total_hires_needed = 0
    total_cost = 0
    total_salary_cost = 0

    for q in range(1, quarters + 1):
        # Expected attrition this quarter
        expected_attrition = math.ceil(running_hc * quarterly_attrition)

        # Growth hires this quarter
        growth_target = math.ceil(current_hc * quarterly_growth)

        # Total hires needed = backfill + growth + remaining open roles
        backfill = expected_attrition
        growth_hires = growth_target
        open_fill = open_roles if q == 1 else 0  # Fill open roles in Q1

        total_q_hires = backfill + growth_hires + open_fill

        # Apply hiring capacity constraint
        if hiring_capacity is not None:
            total_q_hires = min(total_q_hires, hiring_capacity)

        # Net change
        net_change = total_q_hires - expected_attrition

        # End of quarter headcount
        end_hc = running_hc + net_change

        # Costs
        hiring_cost = total_q_hires * avg_cost
        incremental_salary = total_q_hires * avg_salary * 0.25  # Partial quarter

        quarterly_plan.append({
            "quarter": f"Q{q}",
            "start_headcount": running_hc,
            "expected_attrition": expected_attrition,
            "backfill_hires": backfill,
            "growth_hires": growth_hires,
            "open_role_fills": open_fill,
            "total_hires": total_q_hires,
            "net_change": net_change,
            "end_headcount": end_hc,
            "hiring_cost": round(hiring_cost),
            "incremental_salary_cost": round(incremental_salary),
        })

        total_hires_needed += total_q_hires
        total_cost += hiring_cost
        total_salary_cost += incremental_salary
        running_hc = end_hc

    gap = target_hc - running_hc

    return {
        "department": name,
        "current_headcount": current_hc,
        "open_roles": open_roles,
        "target_headcount": target_hc,
        "final_headcount": running_hc,
        "gap_to_target": gap,
        "growth_rate": dept_growth,
        "attrition_rate": dept_attrition,
        "total_hires_needed": total_hires_needed,
        "total_hiring_cost": round(total_cost),
        "total_incremental_salary": round(total_salary_cost),
        "quarterly_plan": quarterly_plan,
    }


def compute_org_summary(forecasts: list) -> dict:
    """Compute organization-level summary."""
    total_current = sum(f["current_headcount"] for f in forecasts)
    total_target = sum(f["target_headcount"] for f in forecasts)
    total_final = sum(f["final_headcount"] for f in forecasts)
    total_hires = sum(f["total_hires_needed"] for f in forecasts)
    total_hiring_cost = sum(f["total_hiring_cost"] for f in forecasts)
    total_salary_cost = sum(f["total_incremental_salary"] for f in forecasts)
    total_open = sum(f["open_roles"] for f in forecasts)

    # Aggregate quarterly
    quarters_count = len(forecasts[0]["quarterly_plan"]) if forecasts else 0
    quarterly_totals = []
    for q in range(quarters_count):
        q_data = {
            "quarter": f"Q{q+1}",
            "total_hires": sum(f["quarterly_plan"][q]["total_hires"] for f in forecasts),
            "total_attrition": sum(f["quarterly_plan"][q]["expected_attrition"] for f in forecasts),
            "net_change": sum(f["quarterly_plan"][q]["net_change"] for f in forecasts),
            "hiring_cost": sum(f["quarterly_plan"][q]["hiring_cost"] for f in forecasts),
        }
        quarterly_totals.append(q_data)

    return {
        "current_total_headcount": total_current,
        "target_total_headcount": total_target,
        "projected_final_headcount": total_final,
        "total_open_roles": total_open,
        "total_hires_needed": total_hires,
        "total_hiring_cost": total_hiring_cost,
        "total_incremental_salary_cost": total_salary_cost,
        "total_investment": total_hiring_cost + total_salary_cost,
        "net_growth": total_final - total_current,
        "net_growth_pct": round((total_final - total_current) / total_current * 100, 1) if total_current > 0 else 0,
        "quarterly_totals": quarterly_totals,
    }


def format_human(forecasts: list, summary: dict, quarters: int) -> str:
    """Format results for human-readable output."""
    lines = []
    lines.append("=" * 75)
    lines.append("WORKFORCE HEADCOUNT PLAN")
    lines.append("=" * 75)
    lines.append("")
    lines.append(f"  Planning Horizon:          {quarters} quarters")
    lines.append(f"  Current Headcount:         {summary['current_total_headcount']}")
    lines.append(f"  Target Headcount:          {summary['target_total_headcount']}")
    lines.append(f"  Projected Final:           {summary['projected_final_headcount']}")
    lines.append(f"  Net Growth:                {summary['net_growth']} ({summary['net_growth_pct']}%)")
    lines.append(f"  Open Roles to Fill:        {summary['total_open_roles']}")
    lines.append(f"  Total Hires Needed:        {summary['total_hires_needed']}")
    lines.append(f"  Total Hiring Cost:         ${summary['total_hiring_cost']:,.0f}")
    lines.append(f"  Incremental Salary Cost:   ${summary['total_incremental_salary_cost']:,.0f}")
    lines.append(f"  Total Investment:          ${summary['total_investment']:,.0f}")

    # Quarterly overview
    lines.append("")
    lines.append("-" * 75)
    lines.append("QUARTERLY OVERVIEW (ALL DEPARTMENTS)")
    lines.append("-" * 75)
    lines.append(f"  {'Quarter':<10} {'Hires':>8} {'Attrition':>10} {'Net':>8} {'Hiring Cost':>14}")
    lines.append(f"  {'-'*10} {'-'*8} {'-'*10} {'-'*8} {'-'*14}")
    for qt in summary["quarterly_totals"]:
        lines.append(f"  {qt['quarter']:<10} {qt['total_hires']:>8} {qt['total_attrition']:>10} {qt['net_change']:>+8} ${qt['hiring_cost']:>12,.0f}")

    # Department detail
    lines.append("")
    lines.append("-" * 75)
    lines.append("DEPARTMENT BREAKDOWN")
    lines.append("-" * 75)
    lines.append(f"  {'Department':<20} {'Current':>8} {'Target':>8} {'Final':>8} {'Hires':>8} {'Gap':>6} {'Cost':>12}")
    lines.append(f"  {'-'*20} {'-'*8} {'-'*8} {'-'*8} {'-'*8} {'-'*6} {'-'*12}")
    for f in forecasts:
        lines.append(
            f"  {f['department']:<20} {f['current_headcount']:>8} {f['target_headcount']:>8} "
            f"{f['final_headcount']:>8} {f['total_hires_needed']:>8} {f['gap_to_target']:>+6} "
            f"${f['total_hiring_cost']:>10,.0f}"
        )

    # Detailed quarterly plans per department
    for f in forecasts:
        lines.append("")
        lines.append(f"  --- {f['department']} (Attrition: {f['attrition_rate']*100:.0f}%, Growth: {f['growth_rate']*100:.0f}%) ---")
        lines.append(f"  {'Qtr':<6} {'Start':>7} {'Attrit':>7} {'Back':>6} {'Grow':>6} {'Open':>6} {'Total':>6} {'End':>7}")
        for qp in f["quarterly_plan"]:
            lines.append(
                f"  {qp['quarter']:<6} {qp['start_headcount']:>7} {qp['expected_attrition']:>7} "
                f"{qp['backfill_hires']:>6} {qp['growth_hires']:>6} {qp['open_role_fills']:>6} "
                f"{qp['total_hires']:>6} {qp['end_headcount']:>7}"
            )

    lines.append("")
    return "\n".join(lines)


def main():
    parser = argparse.ArgumentParser(
        description="Workforce headcount planning and scenario modeling."
    )
    parser.add_argument("--file", required=True, help="Path to workforce data CSV")
    parser.add_argument("--growth", type=float, required=True, help="Annual growth rate (e.g., 0.15 for 15%)")
    parser.add_argument("--attrition", type=float, required=True, help="Annual attrition rate (e.g., 0.12 for 12%)")
    parser.add_argument("--quarters", type=int, default=4, help="Number of quarters to forecast (default: 4)")
    parser.add_argument("--hiring-capacity", type=int, default=None, help="Max hires per quarter per department")
    parser.add_argument("--json", action="store_true", help="Output results as JSON")
    args = parser.parse_args()

    rows = read_csv(args.file)
    if not rows:
        print("Error: No data found in CSV file.", file=sys.stderr)
        sys.exit(1)

    forecasts = []
    for row in rows:
        forecast = forecast_department(row, args.growth, args.attrition, args.quarters, args.hiring_capacity)
        forecasts.append(forecast)

    summary = compute_org_summary(forecasts)

    if args.json:
        output = {
            "summary": summary,
            "departments": forecasts,
        }
        print(json.dumps(output, indent=2))
    else:
        print(format_human(forecasts, summary, args.quarters))


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Survey Analyzer - Analyze employee engagement survey results.

Reads survey response CSV data and computes category scores, response rates,
driver analysis (impact on overall engagement), period-over-period comparison,
and segment breakdowns with priority matrix classification.

Usage:
    python survey_analyzer.py --file survey_results.csv
    python survey_analyzer.py --file survey_results.csv --prior prior_survey.csv --json
    python survey_analyzer.py --file survey_results.csv --segment department

Input CSV columns:
    respondent_id   - Unique anonymous respondent ID
    department      - Department name (optional, for segmentation)
    level           - Job level (optional, for segmentation)
    tenure_band     - Tenure grouping (optional, for segmentation)
    location        - Office location (optional, for segmentation)
    category        - Survey question category (e.g., Manager, Growth, Culture, Compensation, Workload)
    question        - Survey question text
    score           - Likert score (1-5)

Output: Category scores, driver analysis, eNPS, segment breakdowns, and recommendations.
"""

import argparse
import csv
import json
import math
import os
import sys
from collections import defaultdict


CATEGORY_BENCHMARKS = {
    "manager": 3.8,
    "growth": 3.5,
    "culture": 3.7,
    "compensation": 3.3,
    "workload": 3.4,
    "belonging": 3.6,
    "communication": 3.5,
    "recognition": 3.4,
    "autonomy": 3.6,
    "mission": 3.8,
}

MIN_SEGMENT_SIZE = 5  # Anonymity threshold


def read_csv(path: str) -> list:
    """Read CSV file and return list of dicts."""
    if not os.path.isfile(path):
        print(f"Error: File not found: {path}", file=sys.stderr)
        sys.exit(1)
    with open(path, "r", encoding="utf-8") as f:
        reader = csv.DictReader(f)
        rows = list(reader)
    required = {"respondent_id", "category", "score"}
    if rows:
        missing = required - set(rows[0].keys())
        if missing:
            print(f"Error: Missing required columns: {', '.join(missing)}", file=sys.stderr)
            sys.exit(1)
    return rows


def parse_score(val: str) -> float:
    """Parse score value."""
    try:
        s = float(val)
        if 1 <= s <= 5:
            return s
    except (ValueError, TypeError):
        pass
    return None


def compute_response_rate(rows: list, total_employees: int = None) -> dict:
    """Compute response rate metrics."""
    respondents = set()
    for row in rows:
        respondents.add(row["respondent_id"])
    count = len(respondents)
    rate = round(count / total_employees * 100, 1) if total_employees else None
    return {
        "respondents": count,
        "total_employees": total_employees,
        "response_rate_pct": rate,
        "meets_threshold": rate >= 80 if rate else None,
    }


def compute_category_scores(rows: list) -> list:
    """Compute average score per category."""
    cat_scores = defaultdict(list)
    for row in rows:
        score = parse_score(row["score"])
        if score is not None:
            cat = row["category"].strip().lower()
            cat_scores[cat].append(score)

    results = []
    for cat, scores in sorted(cat_scores.items()):
        avg = sum(scores) / len(scores)
        benchmark = CATEGORY_BENCHMARKS.get(cat, 3.5)
        favorable = sum(1 for s in scores if s >= 4) / len(scores) * 100
        results.append({
            "category": cat.title(),
            "avg_score": round(avg, 2),
            "favorable_pct": round(favorable, 1),
            "response_count": len(scores),
            "benchmark": benchmark,
            "vs_benchmark": round(avg - benchmark, 2),
        })

    results.sort(key=lambda x: x["avg_score"])
    return results


def compute_overall_engagement(rows: list) -> dict:
    """Compute overall engagement score."""
    scores = []
    for row in rows:
        score = parse_score(row["score"])
        if score is not None:
            scores.append(score)

    if not scores:
        return {"avg_score": 0, "favorable_pct": 0, "response_count": 0}

    avg = sum(scores) / len(scores)
    favorable = sum(1 for s in scores if s >= 4) / len(scores) * 100
    # eNPS approximation: promoters (5) - detractors (1-3)
    promoters = sum(1 for s in scores if s == 5) / len(scores) * 100
    detractors = sum(1 for s in scores if s <= 3) / len(scores) * 100
    enps = round(promoters - detractors)

    return {
        "avg_score": round(avg, 2),
        "favorable_pct": round(favorable, 1),
        "enps": enps,
        "response_count": len(scores),
    }


def compute_driver_analysis(rows: list) -> list:
    """
    Simple driver analysis: compute correlation between each category
    and overall engagement (respondent-level average).
    Uses Pearson correlation approximation with standard library.
    """
    # Build respondent-level data
    respondent_cats = defaultdict(lambda: defaultdict(list))
    respondent_overall = defaultdict(list)

    for row in rows:
        score = parse_score(row["score"])
        if score is not None:
            rid = row["respondent_id"]
            cat = row["category"].strip().lower()
            respondent_cats[rid][cat].append(score)
            respondent_overall[rid].append(score)

    # Average per respondent per category and overall
    respondent_cat_avg = {}
    respondent_overall_avg = {}
    for rid in respondent_overall:
        respondent_overall_avg[rid] = sum(respondent_overall[rid]) / len(respondent_overall[rid])
        respondent_cat_avg[rid] = {}
        for cat, scores in respondent_cats[rid].items():
            respondent_cat_avg[rid][cat] = sum(scores) / len(scores)

    # Compute correlation per category
    all_cats = set()
    for rid in respondent_cat_avg:
        all_cats.update(respondent_cat_avg[rid].keys())

    drivers = []
    for cat in all_cats:
        x_vals = []
        y_vals = []
        for rid in respondent_cat_avg:
            if cat in respondent_cat_avg[rid]:
                x_vals.append(respondent_cat_avg[rid][cat])
                y_vals.append(respondent_overall_avg[rid])

        if len(x_vals) < 5:
            continue

        # Pearson correlation
        n = len(x_vals)
        mean_x = sum(x_vals) / n
        mean_y = sum(y_vals) / n
        cov = sum((x - mean_x) * (y - mean_y) for x, y in zip(x_vals, y_vals)) / n
        std_x = math.sqrt(sum((x - mean_x) ** 2 for x in x_vals) / n)
        std_y = math.sqrt(sum((y - mean_y) ** 2 for y in y_vals) / n)
        if std_x > 0 and std_y > 0:
            r = cov / (std_x * std_y)
        else:
            r = 0

        avg_score = sum(x_vals) / len(x_vals)
        drivers.append({
            "category": cat.title(),
            "impact": round(r, 3),
            "avg_score": round(avg_score, 2),
        })

    drivers.sort(key=lambda x: x["impact"], reverse=True)
    return drivers


def classify_priorities(drivers: list) -> list:
    """
    Classify categories into priority matrix quadrants:
    High Impact + Low Score = Priority Action
    High Impact + High Score = Maintain
    Low Impact + Low Score = Monitor
    Low Impact + High Score = Celebrate
    """
    if not drivers:
        return []

    median_impact = sorted([d["impact"] for d in drivers])[len(drivers) // 2]
    median_score = sorted([d["avg_score"] for d in drivers])[len(drivers) // 2]

    for d in drivers:
        high_impact = d["impact"] >= median_impact
        high_score = d["avg_score"] >= median_score
        if high_impact and not high_score:
            d["quadrant"] = "PRIORITY_ACTION"
        elif high_impact and high_score:
            d["quadrant"] = "MAINTAIN"
        elif not high_impact and not high_score:
            d["quadrant"] = "MONITOR"
        else:
            d["quadrant"] = "CELEBRATE"

    return drivers


def compute_segment_breakdown(rows: list, segment_field: str) -> list:
    """Compute scores by segment (department, level, etc.)."""
    seg_scores = defaultdict(list)
    for row in rows:
        score = parse_score(row["score"])
        seg_val = row.get(segment_field, "").strip()
        if score is not None and seg_val:
            seg_scores[seg_val].append(score)

    results = []
    for seg, scores in sorted(seg_scores.items()):
        if len(set(row["respondent_id"] for row in rows if row.get(segment_field, "").strip() == seg)) < MIN_SEGMENT_SIZE:
            results.append({
                "segment": seg,
                "suppressed": True,
                "reason": f"Fewer than {MIN_SEGMENT_SIZE} respondents (anonymity protection)",
            })
            continue

        avg = sum(scores) / len(scores)
        favorable = sum(1 for s in scores if s >= 4) / len(scores) * 100
        results.append({
            "segment": seg,
            "avg_score": round(avg, 2),
            "favorable_pct": round(favorable, 1),
            "response_count": len(scores),
            "suppressed": False,
        })

    results.sort(key=lambda x: x.get("avg_score", 0))
    return results


def compare_periods(current: list, prior: list) -> list:
    """Compare current period scores to prior period."""
    prior_cats = {}
    for row in prior:
        score = parse_score(row["score"])
        if score is not None:
            cat = row["category"].strip().lower()
            if cat not in prior_cats:
                prior_cats[cat] = []
            prior_cats[cat].append(score)

    prior_avgs = {cat: sum(s) / len(s) for cat, s in prior_cats.items()}

    current_cats = compute_category_scores(current)
    for cat_data in current_cats:
        cat_key = cat_data["category"].lower()
        if cat_key in prior_avgs:
            cat_data["prior_score"] = round(prior_avgs[cat_key], 2)
            cat_data["change"] = round(cat_data["avg_score"] - prior_avgs[cat_key], 2)
        else:
            cat_data["prior_score"] = None
            cat_data["change"] = None

    return current_cats


def build_recommendations(category_scores: list, drivers: list) -> list:
    """Generate recommendations from analysis."""
    recs = []

    # Find priority action items
    priority_items = [d for d in drivers if d.get("quadrant") == "PRIORITY_ACTION"]
    for item in priority_items[:3]:
        recs.append(
            f"[PRIORITY] {item['category']} has high impact on engagement (r={item['impact']}) "
            f"but scores below median ({item['avg_score']}/5.0). Investigate root causes and develop a targeted action plan."
        )

    # Low-scoring categories
    for cat in category_scores[:2]:
        if cat["vs_benchmark"] < -0.3:
            recs.append(
                f"{cat['category']} scores {abs(cat['vs_benchmark']):.2f} below benchmark "
                f"({cat['avg_score']} vs {cat['benchmark']}). Review with department leaders and identify specific pain points."
            )

    if not recs:
        recs.append("All categories are at or above benchmark. Focus on maintaining momentum and addressing any segment-specific gaps.")

    return recs


def format_human(overall: dict, categories: list, drivers: list, segments: list,
                 recommendations: list, response_rate: dict) -> str:
    """Format results for human-readable output."""
    lines = []
    lines.append("=" * 65)
    lines.append("ENGAGEMENT SURVEY ANALYSIS REPORT")
    lines.append("=" * 65)
    lines.append("")
    lines.append(f"  Overall Engagement Score: {overall['avg_score']} / 5.0")
    lines.append(f"  Favorable Response Rate:  {overall['favorable_pct']}%")
    lines.append(f"  eNPS:                     {overall['enps']}")
    lines.append(f"  Total Responses:          {overall['response_count']}")
    if response_rate.get("response_rate_pct"):
        lines.append(f"  Survey Response Rate:     {response_rate['response_rate_pct']}%")
    lines.append("")

    lines.append("-" * 65)
    lines.append("CATEGORY SCORES")
    lines.append("-" * 65)
    lines.append(f"  {'Category':<20} {'Score':>6} {'Fav%':>6} {'Bench':>6} {'Delta':>7}")
    lines.append(f"  {'-'*20} {'-'*6} {'-'*6} {'-'*6} {'-'*7}")
    for cat in categories:
        delta = f"{cat['vs_benchmark']:+.2f}" if cat['vs_benchmark'] else "--"
        lines.append(f"  {cat['category']:<20} {cat['avg_score']:>6.2f} {cat['favorable_pct']:>5.1f}% {cat['benchmark']:>6.2f} {delta:>7}")

    if drivers:
        lines.append("")
        lines.append("-" * 65)
        lines.append("DRIVER ANALYSIS (Impact on Overall Engagement)")
        lines.append("-" * 65)
        lines.append(f"  {'Category':<20} {'Impact':>8} {'Score':>6} {'Quadrant':<20}")
        lines.append(f"  {'-'*20} {'-'*8} {'-'*6} {'-'*20}")
        for d in drivers:
            quad = d.get("quadrant", "--").replace("_", " ").title()
            lines.append(f"  {d['category']:<20} {d['impact']:>8.3f} {d['avg_score']:>6.2f} {quad:<20}")

    if segments:
        lines.append("")
        lines.append("-" * 65)
        lines.append("SEGMENT BREAKDOWN")
        lines.append("-" * 65)
        for seg in segments:
            if seg.get("suppressed"):
                lines.append(f"  {seg['segment']:<25} [SUPPRESSED - {seg['reason']}]")
            else:
                lines.append(f"  {seg['segment']:<25} Score: {seg['avg_score']:.2f}  Favorable: {seg['favorable_pct']:.1f}%  (n={seg['response_count']})")

    lines.append("")
    lines.append("-" * 65)
    lines.append("RECOMMENDATIONS")
    lines.append("-" * 65)
    for i, rec in enumerate(recommendations, 1):
        lines.append(f"  {i}. {rec}")

    lines.append("")
    return "\n".join(lines)


def main():
    parser = argparse.ArgumentParser(
        description="Analyze employee engagement survey results."
    )
    parser.add_argument("--file", required=True, help="Path to survey results CSV")
    parser.add_argument("--prior", default=None, help="Path to prior period survey CSV for comparison")
    parser.add_argument("--segment", default="department", help="Segment field for breakdown (default: department)")
    parser.add_argument("--total-employees", type=int, default=None, help="Total employee count for response rate calculation")
    parser.add_argument("--json", action="store_true", help="Output results as JSON")
    args = parser.parse_args()

    rows = read_csv(args.file)
    if not rows:
        print("Error: No data found in CSV file.", file=sys.stderr)
        sys.exit(1)

    prior_rows = read_csv(args.prior) if args.prior else None

    overall = compute_overall_engagement(rows)
    response_rate = compute_response_rate(rows, args.total_employees)

    if prior_rows:
        categories = compare_periods(rows, prior_rows)
    else:
        categories = compute_category_scores(rows)

    drivers = compute_driver_analysis(rows)
    drivers = classify_priorities(drivers)
    segments = compute_segment_breakdown(rows, args.segment)
    recommendations = build_recommendations(categories, drivers)

    if args.json:
        output = {
            "overall_engagement": overall,
            "response_rate": response_rate,
            "category_scores": categories,
            "driver_analysis": drivers,
            "segment_breakdown": segments,
            "recommendations": recommendations,
        }
        print(json.dumps(output, indent=2))
    else:
        print(format_human(overall, categories, drivers, segments, recommendations, response_rate))


if __name__ == "__main__":
    main()