Chro Advisor

#!/usr/bin/env python3
"""
Compensation Benchmarker
========================
Salary benchmarking and total comp modeling for startup teams.
Analyzes pay equity, compa-ratios, and total comp vs. market.

Usage:
    python comp_benchmarker.py                       # Run with built-in sample data
    python comp_benchmarker.py --config roster.json  # Load from JSON
    python comp_benchmarker.py --help

Output: Band compliance report, compa-ratio distribution, pay equity flags,
        equity value analysis, and total comp vs. market.
"""

import argparse
import json
import csv
import io
import sys
from dataclasses import dataclass, field, asdict
from typing import Optional
from datetime import date
import math


# ---------------------------------------------------------------------------
# Data structures
# ---------------------------------------------------------------------------

@dataclass
class BandDefinition:
    """Salary band for a role level."""
    level: str          # L1, L2, L3, L4, M1, M2, M3, VP
    function: str       # Engineering, Sales, Product, G&A, Marketing, CS
    band_min: int       # Annual USD
    band_mid: int       # P50 anchor
    band_max: int       # Band ceiling
    market_p25: int     # Market 25th percentile
    market_p50: int     # Market median (should align with band_mid for P50 strategy)
    market_p75: int     # Market 75th percentile
    location_zone: str  # Tier1 (SF/NYC), Tier2 (Austin/Denver), Tier3 (Remote/other), EU


@dataclass
class Employee:
    """One employee record."""
    id: str
    name: str
    role: str
    level: str
    function: str
    location_zone: str
    base_salary: int
    bonus_target_pct: float   # % of base
    equity_shares: int        # Total unvested options/RSUs
    equity_strike: float      # Strike price (0 for RSUs)
    equity_current_409a: float  # Current 409A share price
    equity_vest_years_remaining: float  # How many years of vesting remain
    benefits_annual: int      # Employer-paid benefits cost
    gender: str               # M/F/NB/Undisclosed (for equity audit)
    ethnicity: str            # For equity audit — can be "Undisclosed"
    tenure_years: float
    performance_rating: int   # 1–5
    last_raise_months_ago: int
    last_equity_refresh_months_ago: Optional[int] = None


@dataclass
class CompRoster:
    company: str
    as_of_date: str             # ISO date
    funding_stage: str          # Seed, Series A, Series B, etc.
    comp_philosophy_target: str # P50, P65, P75 — your target percentile
    preferred_stock_price: float  # Last round price (for offer modeling)
    employees: list[Employee] = field(default_factory=list)
    bands: list[BandDefinition] = field(default_factory=list)


# ---------------------------------------------------------------------------
# Band lookup
# ---------------------------------------------------------------------------

def find_band(roster: CompRoster, level: str, function: str, zone: str) -> Optional[BandDefinition]:
    """Find best-matching band. Falls back to any matching level+function if zone not found."""
    matches = [b for b in roster.bands if b.level == level and b.function == function and b.location_zone == zone]
    if matches:
        return matches[0]
    # Fallback: same level+function, any zone
    matches = [b for b in roster.bands if b.level == level and b.function == function]
    if matches:
        return matches[0]
    # Fallback: same level, any function
    matches = [b for b in roster.bands if b.level == level]
    if matches:
        return matches[0]
    return None


# ---------------------------------------------------------------------------
# Compensation analysis
# ---------------------------------------------------------------------------

def compa_ratio(salary: int, band_mid: int) -> float:
    return salary / band_mid if band_mid > 0 else 0.0


def band_position(salary: int, band_min: int, band_max: int) -> float:
    """Position in band: 0.0 = at min, 1.0 = at max."""
    if band_max == band_min:
        return 0.5
    return (salary - band_min) / (band_max - band_min)


def annualized_equity_value(emp: Employee) -> int:
    """Current 409A value of unvested equity, annualized."""
    if emp.equity_vest_years_remaining <= 0:
        return 0
    if emp.equity_current_409a > emp.equity_strike:
        intrinsic = (emp.equity_current_409a - emp.equity_strike) * emp.equity_shares
    else:
        # Options underwater — still show at current FMV for RSUs or future value for options
        intrinsic = emp.equity_current_409a * emp.equity_shares if emp.equity_strike == 0 else 0
    return int(intrinsic / emp.equity_vest_years_remaining)


def total_comp(emp: Employee) -> int:
    bonus = int(emp.base_salary * emp.bonus_target_pct)
    equity = annualized_equity_value(emp)
    return emp.base_salary + bonus + equity + emp.benefits_annual


def analyze_employee(emp: Employee, roster: CompRoster) -> dict:
    band = find_band(roster, emp.level, emp.function, emp.location_zone)
    result = {
        "id": emp.id,
        "name": emp.name,
        "role": emp.role,
        "level": emp.level,
        "function": emp.function,
        "zone": emp.location_zone,
        "base": emp.base_salary,
        "bonus_target": int(emp.base_salary * emp.bonus_target_pct),
        "equity_annual": annualized_equity_value(emp),
        "benefits": emp.benefits_annual,
        "total_comp": total_comp(emp),
        "performance": emp.performance_rating,
        "tenure_years": emp.tenure_years,
        "last_raise_months": emp.last_raise_months_ago,
        "band": band,
        "compa_ratio": None,
        "band_position": None,
        "vs_market_p50": None,
        "flags": [],
    }

    if band:
        cr = compa_ratio(emp.base_salary, band.band_mid)
        bp = band_position(emp.base_salary, band.band_min, band.band_max)
        result["compa_ratio"] = round(cr, 3)
        result["band_position"] = round(bp, 3)
        result["vs_market_p50"] = round((emp.base_salary - band.market_p50) / band.market_p50 * 100, 1)

        # Flags
        if emp.base_salary < band.band_min:
            result["flags"].append(("CRITICAL", "Base below band minimum — immediate attrition risk"))
        elif cr < 0.88:
            result["flags"].append(("HIGH", f"Compa-ratio {cr:.2f} — significantly below midpoint"))
        elif cr < 0.93:
            result["flags"].append(("MEDIUM", f"Compa-ratio {cr:.2f} — below target zone (0.95–1.05)"))

        if emp.base_salary > band.band_max:
            result["flags"].append(("HIGH", "Base above band maximum — review for promotion or band update"))

        if emp.performance_rating >= 4 and cr < 0.95:
            result["flags"].append(("HIGH", f"High performer (rating {emp.performance_rating}) underpaid — flight risk"))

        if emp.last_raise_months_ago > 18:
            result["flags"].append(("MEDIUM", f"No raise in {emp.last_raise_months_ago} months — review due"))

        if emp.equity_vest_years_remaining < 1.0 and (emp.last_equity_refresh_months_ago is None or emp.last_equity_refresh_months_ago > 24):
            result["flags"].append(("HIGH", "Equity nearly fully vested with no refresh — retention hook gone"))

    else:
        result["flags"].append(("INFO", "No band found for this level/function/zone"))

    return result


# ---------------------------------------------------------------------------
# Aggregate analysis
# ---------------------------------------------------------------------------

def pay_equity_audit(analyses: list[dict], employees: list[Employee]) -> dict:
    """Simple pay equity analysis by gender and ethnicity."""
    emp_by_id = {e.id: e for e in employees}

    def group_stats(group_key_fn):
        groups: dict[str, list[float]] = {}
        for a in analyses:
            if a["compa_ratio"] is None:
                continue
            emp = emp_by_id.get(a["id"])
            if not emp:
                continue
            key = group_key_fn(emp)
            if key not in groups:
                groups[key] = []
            groups[key].append(a["compa_ratio"])
        return {k: {"n": len(v), "avg_cr": round(sum(v)/len(v), 3), "min_cr": round(min(v), 3), "max_cr": round(max(v), 3)}
                for k, v in groups.items() if v}

    gender_stats = group_stats(lambda e: e.gender)
    ethnicity_stats = group_stats(lambda e: e.ethnicity)

    # Compute gap vs. the largest group
    def compute_gap(stats: dict) -> dict[str, float]:
        if not stats:
            return {}
        largest = max(stats.items(), key=lambda x: x[1]["n"])
        ref_cr = largest[1]["avg_cr"]
        return {k: round((v["avg_cr"] - ref_cr) / ref_cr * 100, 1) for k, v in stats.items()}

    gender_gaps = compute_gap(gender_stats)
    ethnicity_gaps = compute_gap(ethnicity_stats)

    return {
        "gender": gender_stats,
        "gender_gaps_pct": gender_gaps,
        "ethnicity": ethnicity_stats,
        "ethnicity_gaps_pct": ethnicity_gaps,
    }


def compa_ratio_distribution(analyses: list[dict]) -> dict:
    crs = [a["compa_ratio"] for a in analyses if a["compa_ratio"] is not None]
    if not crs:
        return {}
    buckets = {
        "< 0.85 (below band)": 0,
        "0.85–0.94 (developing)": 0,
        "0.95–1.05 (target zone)": 0,
        "1.06–1.15 (senior in role)": 0,
        "> 1.15 (above band)": 0,
    }
    for cr in crs:
        if cr < 0.85:
            buckets["< 0.85 (below band)"] += 1
        elif cr < 0.95:
            buckets["0.85–0.94 (developing)"] += 1
        elif cr <= 1.05:
            buckets["0.95–1.05 (target zone)"] += 1
        elif cr <= 1.15:
            buckets["1.06–1.15 (senior in role)"] += 1
        else:
            buckets["> 1.15 (above band)"] += 1
    avg = sum(crs) / len(crs)
    return {"distribution": buckets, "avg_compa_ratio": round(avg, 3), "n": len(crs)}


# ---------------------------------------------------------------------------
# Report output
# ---------------------------------------------------------------------------

def fmt(n) -> str:
    return f"${int(n):,.0f}"


def bar(value: float, width: int = 20) -> str:
    filled = min(width, max(0, int(value * width)))
    return "█" * filled + "░" * (width - filled)


def print_report(roster: CompRoster):
    WIDTH = 76
    SEP = "=" * WIDTH
    sep = "-" * WIDTH

    analyses = [analyze_employee(e, roster) for e in roster.employees]
    cr_dist = compa_ratio_distribution(analyses)
    equity_audit = pay_equity_audit(analyses, roster.employees)

    print(SEP)
    print(f"  COMPENSATION BENCHMARKING REPORT — {roster.company}")
    print(f"  As of: {roster.as_of_date}  |  Stage: {roster.funding_stage}  |  Target: {roster.comp_philosophy_target}")
    print(SEP)

    # Summary stats
    total_emps = len(roster.employees)
    flagged = sum(1 for a in analyses if any(s in ["CRITICAL", "HIGH"] for s, _ in a["flags"]))
    total_payroll = sum(e.base_salary for e in roster.employees)
    avg_total_comp = sum(a["total_comp"] for a in analyses) // total_emps if total_emps else 0

    print(f"\n[ SUMMARY ]")
    print(sep)
    print(f"  Employees analyzed:      {total_emps}")
    print(f"  Flagged (critical/high): {flagged}")
    print(f"  Total base payroll:      {fmt(total_payroll)}/year")
    print(f"  Avg total comp:          {fmt(avg_total_comp)}/year")
    if cr_dist:
        print(f"  Avg compa-ratio:         {cr_dist['avg_compa_ratio']:.3f}")

    # Compa-ratio distribution
    if cr_dist:
        print(f"\n[ COMPA-RATIO DISTRIBUTION ]")
        print(sep)
        total_n = cr_dist["n"]
        for label, count in cr_dist["distribution"].items():
            pct = count / total_n if total_n else 0
            bar_str = bar(pct, 25)
            print(f"  {label:<30} {bar_str}  {count:3d} ({pct*100:4.0f}%)")

    # Pay equity audit
    print(f"\n[ PAY EQUITY AUDIT ]")
    print(sep)

    print(f"  By Gender:")
    for group, stats in equity_audit["gender"].items():
        gap = equity_audit["gender_gaps_pct"].get(group, 0.0)
        gap_str = f"  gap: {gap:+.1f}%" if gap != 0 else "  (reference group)"
        flag = " ⚠" if abs(gap) > 5 else ""
        print(f"    {group:<15} n={stats['n']}  avg_CR={stats['avg_cr']:.3f}{gap_str}{flag}")

    print(f"\n  By Ethnicity:")
    for group, stats in equity_audit["ethnicity"].items():
        gap = equity_audit["ethnicity_gaps_pct"].get(group, 0.0)
        gap_str = f"  gap: {gap:+.1f}%" if gap != 0 else "  (reference group)"
        flag = " ⚠" if abs(gap) > 5 else ""
        print(f"    {group:<20} n={stats['n']}  avg_CR={stats['avg_cr']:.3f}{gap_str}{flag}")

    print(f"\n  ⚠ = gap > 5%. Investigate with regression controlling for level, tenure, and performance.")

    # Employee detail with flags
    print(f"\n[ EMPLOYEE DETAIL ]")
    print(sep)

    # Group by function
    functions = sorted(set(e.function for e in roster.employees))
    for fn in functions:
        fn_analyses = [a for a in analyses if a["function"] == fn]
        if not fn_analyses:
            continue
        print(f"\n  ── {fn} ──")
        print(f"  {'Name':<22} {'Role':<28} {'Lvl':<5} {'Base':>10} {'TotalComp':>11} {'CR':>6} {'Perf':>5}  Flags")
        print(f"  {'-'*22} {'-'*28} {'-'*5} {'-'*10} {'-'*11} {'-'*6} {'-'*5}  {'-'*20}")

        for a in sorted(fn_analyses, key=lambda x: -x["base"]):
            cr_str = f"{a['compa_ratio']:.2f}" if a["compa_ratio"] else "N/A"
            flag_summary = ", ".join(s for s, _ in a["flags"] if s in ("CRITICAL", "HIGH", "MEDIUM"))
            flag_str = flag_summary if flag_summary else "OK"
            print(f"  {a['name']:<22} {a['role']:<28} {a['level']:<5} "
                  f"{fmt(a['base']):>10} {fmt(a['total_comp']):>11} {cr_str:>6} {a['performance']:>5}  {flag_str}")

            # Print flag detail for critical/high
            for severity, msg in a["flags"]:
                if severity in ("CRITICAL", "HIGH"):
                    print(f"  {'':>22}   ↳ [{severity}] {msg}")

    # Action items
    critical = [(a["name"], msg) for a in analyses for sev, msg in a["flags"] if sev == "CRITICAL"]
    high = [(a["name"], msg) for a in analyses for sev, msg in a["flags"] if sev == "HIGH"]
    medium = [(a["name"], msg) for a in analyses for sev, msg in a["flags"] if sev == "MEDIUM"]

    print(f"\n[ ACTION ITEMS ]")
    print(sep)

    if critical:
        print(f"\n  CRITICAL — Address this review cycle:")
        for name, msg in critical:
            print(f"    • {name}: {msg}")

    if high:
        print(f"\n  HIGH — Address within 30 days:")
        for name, msg in high[:10]:
            print(f"    • {name}: {msg}")
        if len(high) > 10:
            print(f"    ... and {len(high)-10} more")

    if medium:
        print(f"\n  MEDIUM — Address in next comp cycle:")
        for name, msg in medium[:8]:
            print(f"    • {name}: {msg}")
        if len(medium) > 8:
            print(f"    ... and {len(medium)-8} more")

    if not critical and not high and not medium:
        print(f"\n  No critical or high-severity issues. Compensation appears well-managed.")

    # Remediation cost estimate
    below_min = [a for a in analyses if a["band"] and a["base"] < a["band"].band_min]
    below_mid = [a for a in analyses if a["compa_ratio"] and a["compa_ratio"] < 0.90]

    if below_min or below_mid:
        print(f"\n[ REMEDIATION COST ESTIMATE ]")
        print(sep)

        if below_min:
            cost_to_min = sum(a["band"].band_min - a["base"] for a in below_min)
            print(f"  Cost to bring below-minimum to band min:  {fmt(cost_to_min)}/year  ({len(below_min)} employees)")

        if below_mid:
            cost_to_90 = sum(int(a["band"].band_mid * 0.90) - a["base"] for a in below_mid if a["base"] < int(a["band"].band_mid * 0.90))
            cost_to_90 = max(0, cost_to_90)
            print(f"  Cost to bring CR < 0.90 to CR = 0.90:    {fmt(cost_to_90)}/year  ({len(below_mid)} employees)")

        total_payroll_impact = sum(e.base_salary for e in roster.employees)
        total_remediation = (below_min and cost_to_min or 0)
        print(f"\n  Total payroll before remediation:  {fmt(total_payroll_impact)}/year")
        print(f"  Remediation as % of payroll:       {total_remediation/total_payroll_impact*100:.1f}%")

    print(f"\n{SEP}\n")


def export_csv(roster: CompRoster) -> str:
    analyses = [analyze_employee(e, roster) for e in roster.employees]
    output = io.StringIO()
    writer = csv.writer(output)
    writer.writerow(["ID", "Name", "Role", "Level", "Function", "Zone",
                     "Base", "Bonus Target", "Equity Annual", "Benefits", "Total Comp",
                     "Compa Ratio", "Band Position", "vs Market P50 %",
                     "Performance", "Tenure Years", "Last Raise (mo)",
                     "Gender", "Ethnicity", "Critical Flags", "High Flags"])
    for a, e in zip(analyses, roster.employees):
        critical_flags = "; ".join(msg for sev, msg in a["flags"] if sev == "CRITICAL")
        high_flags = "; ".join(msg for sev, msg in a["flags"] if sev == "HIGH")
        writer.writerow([a["id"], a["name"], a["role"], a["level"], a["function"], a["zone"],
                         a["base"], a["bonus_target"], a["equity_annual"], a["benefits"], a["total_comp"],
                         a["compa_ratio"], a["band_position"], a["vs_market_p50"],
                         a["performance"], a["tenure_years"], a["last_raise_months"],
                         e.gender, e.ethnicity, critical_flags, high_flags])
    return output.getvalue()


# ---------------------------------------------------------------------------
# Sample data
# ---------------------------------------------------------------------------

def build_sample_roster() -> CompRoster:
    roster = CompRoster(
        company="AcmeTech (Series A)",
        as_of_date=date.today().isoformat(),
        funding_stage="Series A",
        comp_philosophy_target="P50",
        preferred_stock_price=8.50,
    )

    # Bands (Engineering, P50 target, Tier1 = SF/NYC)
    roster.bands = [
        BandDefinition("L2", "Engineering", 115_000, 132_000, 155_000, 110_000, 132_000, 155_000, "Tier1"),
        BandDefinition("L3", "Engineering", 148_000, 170_000, 198_000, 145_000, 170_000, 198_000, "Tier1"),
        BandDefinition("L4", "Engineering", 185_000, 215_000, 248_000, 182_000, 215_000, 250_000, "Tier1"),
        BandDefinition("M1", "Engineering", 170_000, 195_000, 225_000, 168_000, 195_000, 225_000, "Tier1"),
        BandDefinition("L2", "Engineering", 95_000, 108_000, 125_000, 92_000, 108_000, 126_000, "Tier2"),
        BandDefinition("L3", "Engineering", 122_000, 140_000, 162_000, 120_000, 140_000, 162_000, "Tier2"),
        BandDefinition("L2", "Sales",       80_000,  92_000, 108_000,  78_000,  92_000, 108_000, "Tier1"),
        BandDefinition("L3", "Sales",       95_000, 110_000, 128_000,  93_000, 110_000, 128_000, "Tier1"),
        BandDefinition("M1", "Sales",      130_000, 150_000, 172_000, 128_000, 150_000, 172_000, "Tier1"),
        BandDefinition("L2", "Product",    125_000, 145_000, 168_000, 123_000, 145_000, 168_000, "Tier1"),
        BandDefinition("L3", "Product",    155_000, 178_000, 205_000, 153_000, 178_000, 205_000, "Tier1"),
        BandDefinition("L2", "G&A",         85_000,  98_000, 115_000,  83_000,  98_000, 115_000, "Tier1"),
        BandDefinition("L3", "G&A",        110_000, 128_000, 148_000, 108_000, 128_000, 148_000, "Tier1"),
    ]

    roster.employees = [
        # Engineering — mix of scenarios
        Employee("E001", "Aarav Shah", "Senior SWE (Backend)", "L3", "Engineering", "Tier1",
                 base_salary=168_000, bonus_target_pct=0.0, equity_shares=40_000,
                 equity_strike=1.50, equity_current_409a=6.80, equity_vest_years_remaining=2.5,
                 benefits_annual=18_000, gender="M", ethnicity="Asian",
                 tenure_years=2.5, performance_rating=4, last_raise_months_ago=14,
                 last_equity_refresh_months_ago=None),

        Employee("E002", "Yuki Tanaka", "Senior SWE (Frontend)", "L3", "Engineering", "Tier1",
                 base_salary=152_000, bonus_target_pct=0.0, equity_shares=30_000,
                 equity_strike=2.20, equity_current_409a=6.80, equity_vest_years_remaining=0.5,
                 benefits_annual=18_000, gender="F", ethnicity="Asian",
                 tenure_years=3.8, performance_rating=5, last_raise_months_ago=11,
                 last_equity_refresh_months_ago=30),
        # Note: Yuki is high performer, near-vested, no recent refresh — flag expected

        Employee("E003", "Marcus Johnson", "SWE II (Backend)", "L2", "Engineering", "Tier1",
                 base_salary=110_000, bonus_target_pct=0.0, equity_shares=15_000,
                 equity_strike=2.50, equity_current_409a=6.80, equity_vest_years_remaining=3.0,
                 benefits_annual=15_000, gender="M", ethnicity="Black",
                 tenure_years=1.2, performance_rating=3, last_raise_months_ago=12,
                 last_equity_refresh_months_ago=None),
        # Note: Below band midpoint, recently hired — developing flag

        Employee("E004", "Priya Nair", "Staff SWE", "L4", "Engineering", "Tier1",
                 base_salary=222_000, bonus_target_pct=0.0, equity_shares=60_000,
                 equity_strike=0.80, equity_current_409a=6.80, equity_vest_years_remaining=2.0,
                 benefits_annual=18_000, gender="F", ethnicity="Asian",
                 tenure_years=4.2, performance_rating=5, last_raise_months_ago=8,
                 last_equity_refresh_months_ago=8),

        Employee("E005", "Tom Rivera", "SWE II (Platform)", "L2", "Engineering", "Tier2",
                 base_salary=88_000, bonus_target_pct=0.0, equity_shares=12_000,
                 equity_strike=3.00, equity_current_409a=6.80, equity_vest_years_remaining=2.5,
                 benefits_annual=14_000, gender="M", ethnicity="Hispanic",
                 tenure_years=1.8, performance_rating=4, last_raise_months_ago=22,
                 last_equity_refresh_months_ago=None),
        # Note: No raise in 22 months, high performer — flag expected

        Employee("E006", "Sarah Kim", "Eng Manager", "M1", "Engineering", "Tier1",
                 base_salary=192_000, bonus_target_pct=0.10, equity_shares=35_000,
                 equity_strike=1.20, equity_current_409a=6.80, equity_vest_years_remaining=1.8,
                 benefits_annual=18_000, gender="F", ethnicity="Asian",
                 tenure_years=2.8, performance_rating=4, last_raise_months_ago=9,
                 last_equity_refresh_months_ago=9),

        # Sales
        Employee("S001", "David Chen", "Account Executive (MM)", "L3", "Sales", "Tier1",
                 base_salary=105_000, bonus_target_pct=0.50, equity_shares=8_000,
                 equity_strike=3.50, equity_current_409a=6.80, equity_vest_years_remaining=2.0,
                 benefits_annual=15_000, gender="M", ethnicity="Asian",
                 tenure_years=1.5, performance_rating=3, last_raise_months_ago=15,
                 last_equity_refresh_months_ago=None),

        Employee("S002", "Amara Osei", "AE (Mid-Market)", "L3", "Sales", "Tier1",
                 base_salary=98_000, bonus_target_pct=0.50, equity_shares=6_000,
                 equity_strike=3.50, equity_current_409a=6.80, equity_vest_years_remaining=2.5,
                 benefits_annual=15_000, gender="F", ethnicity="Black",
                 tenure_years=1.0, performance_rating=4, last_raise_months_ago=12,
                 last_equity_refresh_months_ago=None),
        # Note: High performer, significantly below midpoint — flag expected

        Employee("S003", "Jordan Blake", "Sales Manager", "M1", "Sales", "Tier1",
                 base_salary=155_000, bonus_target_pct=0.20, equity_shares=20_000,
                 equity_strike=2.00, equity_current_409a=6.80, equity_vest_years_remaining=1.5,
                 benefits_annual=16_000, gender="NB", ethnicity="White",
                 tenure_years=2.2, performance_rating=3, last_raise_months_ago=10,
                 last_equity_refresh_months_ago=10),

        # Product
        Employee("P001", "Nina Patel", "Senior PM", "L3", "Product", "Tier1",
                 base_salary=176_000, bonus_target_pct=0.10, equity_shares=22_000,
                 equity_strike=1.80, equity_current_409a=6.80, equity_vest_years_remaining=2.0,
                 benefits_annual=17_000, gender="F", ethnicity="Asian",
                 tenure_years=2.0, performance_rating=4, last_raise_months_ago=12,
                 last_equity_refresh_months_ago=12),

        # G&A
        Employee("G001", "Chris Mueller", "Finance Manager", "L3", "G&A", "Tier1",
                 base_salary=125_000, bonus_target_pct=0.10, equity_shares=10_000,
                 equity_strike=2.80, equity_current_409a=6.80, equity_vest_years_remaining=3.0,
                 benefits_annual=16_000, gender="M", ethnicity="White",
                 tenure_years=1.5, performance_rating=3, last_raise_months_ago=15,
                 last_equity_refresh_months_ago=None),

        Employee("G002", "Fatima Al-Hassan", "HR Operations", "L2", "G&A", "Tier1",
                 base_salary=82_000, bonus_target_pct=0.08, equity_shares=5_000,
                 equity_strike=4.00, equity_current_409a=6.80, equity_vest_years_remaining=3.5,
                 benefits_annual=14_000, gender="F", ethnicity="Middle Eastern",
                 tenure_years=0.8, performance_rating=3, last_raise_months_ago=8,
                 last_equity_refresh_months_ago=None),
        # Note: Below band minimum — critical flag expected
    ]

    return roster


# ---------------------------------------------------------------------------
# CLI
# ---------------------------------------------------------------------------

def load_roster_from_json(path: str) -> CompRoster:
    with open(path) as f:
        data = json.load(f)
    employees = [Employee(**e) for e in data.pop("employees", [])]
    bands = [BandDefinition(**b) for b in data.pop("bands", [])]
    roster = CompRoster(**data)
    roster.employees = employees
    roster.bands = bands
    return roster


def main():
    parser = argparse.ArgumentParser(
        description="Compensation Benchmarker — salary analysis and pay equity audit",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Examples:
  python comp_benchmarker.py                          # Run sample roster
  python comp_benchmarker.py --config roster.json     # Load from JSON
  python comp_benchmarker.py --export-csv             # Output CSV
  python comp_benchmarker.py --export-json            # Output JSON template
        """
    )
    parser.add_argument("--config", help="Path to JSON roster file")
    parser.add_argument("--export-csv", action="store_true", help="Export analysis as CSV")
    parser.add_argument("--export-json", action="store_true", help="Export sample roster as JSON template")
    args = parser.parse_args()

    if args.config:
        roster = load_roster_from_json(args.config)
    else:
        roster = build_sample_roster()

    if args.export_json:
        data = asdict(roster)
        print(json.dumps(data, indent=2))
        return

    if args.export_csv:
        print(export_csv(roster))
        return

    print_report(roster)


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Hiring Plan Modeler
===================
Builds hiring plans from business goals with cost projections.
Outputs quarterly headcount plan, cost model, and risk assessment.

Usage:
    python hiring_plan_modeler.py                    # Run with built-in sample data
    python hiring_plan_modeler.py --config plan.json # Load from JSON config
    python hiring_plan_modeler.py --help
"""

import argparse
import json
import sys
from dataclasses import dataclass, field, asdict
from datetime import datetime, date
from typing import Optional
import csv
import io


# ---------------------------------------------------------------------------
# Data structures
# ---------------------------------------------------------------------------

@dataclass
class HireTarget:
    """One planned hire."""
    role: str
    level: str              # L1, L2, L3, L4, M1, M2, M3, VP, C-Suite
    function: str           # Engineering, Sales, Product, G&A, Marketing, CS
    quarter: str            # Q1-2025, Q2-2025, etc.
    base_salary: int        # Annual, USD
    bonus_pct: float        # % of base (e.g., 0.10 for 10%)
    equity_annual_usd: int  # Annualized equity value at current 409A
    benefits_annual: int    # Employer-paid benefits
    recruiter_fee_pct: float= 0.20  # Agency fee if used (0 for internal recruiter)
    ramp_months: int        = 3     # Months to full productivity
    priority: str           = "High"  # High / Medium / Low
    business_case: str      = ""
    open_to_internal: bool  = False


@dataclass
class HiringPlan:
    company: str
    plan_period: str        # e.g., "2025 Annual"
    current_headcount: int
    target_revenue: int     # Annual target revenue ($)
    current_revenue: int    # Current ARR ($)
    hires: list[HireTarget] = field(default_factory=list)

    # Cost overheads beyond comp
    overhead_rate: float = 0.25     # Workspace, software, onboarding overhead as % of base
    internal_recruiter_cost: int = 0  # If you have an internal recruiter, annual cost


# ---------------------------------------------------------------------------
# Computation
# ---------------------------------------------------------------------------

def quarter_to_sortkey(q: str) -> tuple[int, int]:
    """Parse 'Q2-2025' → (2025, 2)"""
    parts = q.upper().split("-")
    if len(parts) == 2:
        q_num = int(parts[0].replace("Q", ""))
        year = int(parts[1])
        return (year, q_num)
    return (9999, 9)


def get_quarters(hires: list[HireTarget]) -> list[str]:
    """Return sorted unique quarters from hire list."""
    quarters = sorted(set(h.quarter for h in hires), key=quarter_to_sortkey)
    return quarters


def compute_hire_costs(hire: HireTarget) -> dict:
    """Compute total first-year cost for one hire."""
    total_comp = hire.base_salary + int(hire.base_salary * hire.bonus_pct) + hire.equity_annual_usd + hire.benefits_annual
    recruiter_fee = int(hire.base_salary * hire.recruiter_fee_pct)
    overhead = int(hire.base_salary * 0.25)  # workspace, tools, onboarding
    ramp_productivity_cost = int(hire.base_salary * (hire.ramp_months / 12))  # cost during ramp

    return {
        "base_salary": hire.base_salary,
        "target_bonus": int(hire.base_salary * hire.bonus_pct),
        "equity_annual": hire.equity_annual_usd,
        "benefits": hire.benefits_annual,
        "total_comp": total_comp,
        "recruiter_fee": recruiter_fee,
        "overhead": overhead,
        "ramp_cost": ramp_productivity_cost,
        "first_year_total": total_comp + recruiter_fee + overhead,
        "fully_loaded_first_year": total_comp + recruiter_fee + overhead + ramp_productivity_cost,
    }


def summarize_by_quarter(plan: HiringPlan) -> dict[str, dict]:
    """Aggregate headcount and costs per quarter."""
    quarters = get_quarters(plan.hires)
    summary = {}
    running_headcount = plan.current_headcount

    for q in quarters:
        q_hires = [h for h in plan.hires if h.quarter == q]
        q_costs = [compute_hire_costs(h) for h in q_hires]

        total_comp = sum(c["total_comp"] for c in q_costs)
        total_first_year = sum(c["first_year_total"] for c in q_costs)
        recruiter_fees = sum(c["recruiter_fee"] for c in q_costs)

        running_headcount += len(q_hires)

        summary[q] = {
            "new_hires": len(q_hires),
            "headcount_eop": running_headcount,
            "total_annual_comp_added": total_comp,
            "total_first_year_cost": total_first_year,
            "recruiter_fees": recruiter_fees,
            "hires": q_hires,
            "costs": q_costs,
        }

    return summary


def summarize_by_function(plan: HiringPlan) -> dict[str, dict]:
    """Aggregate headcount and costs per function."""
    functions: dict[str, dict] = {}
    for hire in plan.hires:
        fn = hire.function
        if fn not in functions:
            functions[fn] = {"count": 0, "total_comp": 0, "total_first_year": 0, "roles": []}
        costs = compute_hire_costs(hire)
        functions[fn]["count"] += 1
        functions[fn]["total_comp"] += costs["total_comp"]
        functions[fn]["total_first_year"] += costs["first_year_total"]
        functions[fn]["roles"].append(hire.role)
    return functions


def compute_totals(plan: HiringPlan) -> dict:
    all_costs = [compute_hire_costs(h) for h in plan.hires]
    total_hires = len(plan.hires)
    total_comp = sum(c["total_comp"] for c in all_costs)
    total_first_year = sum(c["first_year_total"] for c in all_costs)
    total_fully_loaded = sum(c["fully_loaded_first_year"] for c in all_costs)
    total_recruiter = sum(c["recruiter_fee"] for c in all_costs)

    final_headcount = plan.current_headcount + total_hires
    revenue_per_employee = plan.target_revenue / final_headcount if final_headcount > 0 else 0
    revenue_per_employee_current = plan.current_revenue / plan.current_headcount if plan.current_headcount > 0 else 0

    return {
        "total_hires": total_hires,
        "final_headcount": final_headcount,
        "headcount_growth_pct": ((final_headcount - plan.current_headcount) / plan.current_headcount * 100) if plan.current_headcount > 0 else 0,
        "total_annual_comp_added": total_comp,
        "total_first_year_cost": total_first_year,
        "total_fully_loaded_first_year": total_fully_loaded,
        "total_recruiter_fees": total_recruiter,
        "revenue_per_employee_target": revenue_per_employee,
        "revenue_per_employee_current": revenue_per_employee_current,
        "avg_comp_per_hire": total_comp // total_hires if total_hires > 0 else 0,
    }


# ---------------------------------------------------------------------------
# Risk assessment
# ---------------------------------------------------------------------------

def assess_risks(plan: HiringPlan, totals: dict) -> list[dict]:
    risks = []

    # Headcount growth too fast
    growth_pct = totals["headcount_growth_pct"]
    if growth_pct > 80:
        risks.append({
            "severity": "HIGH",
            "category": "Execution",
            "finding": f"Headcount growing {growth_pct:.0f}% this period. "
                       "Culture and processes rarely scale this fast without breakage.",
            "recommendation": "Stagger Q3/Q4 hires. Validate Q1/Q2 cohort is onboarded before next wave."
        })
    elif growth_pct > 50:
        risks.append({
            "severity": "MEDIUM",
            "category": "Execution",
            "finding": f"Headcount growing {growth_pct:.0f}% — significant scaling challenge.",
            "recommendation": "Ensure onboarding infrastructure scales. Assign buddy/mentor to each hire."
        })

    # High concentration in one quarter
    quarters = get_quarters(plan.hires)
    q_counts = {q: sum(1 for h in plan.hires if h.quarter == q) for q in quarters}
    max_q = max(q_counts.values()) if q_counts else 0
    if max_q > len(plan.hires) * 0.5 and max_q > 4:
        heavy_q = [q for q, c in q_counts.items() if c == max_q][0]
        risks.append({
            "severity": "MEDIUM",
            "category": "Hiring Execution",
            "finding": f"More than 50% of hires planned in {heavy_q} ({max_q} hires). "
                       "Recruiting capacity and onboarding bandwidth may be insufficient.",
            "recommendation": "Spread hires across quarters. Hiring pipeline needs to start 60–90 days before target start date."
        })

    # Revenue per employee declining
    if totals["revenue_per_employee_target"] < totals["revenue_per_employee_current"] * 0.7:
        risks.append({
            "severity": "HIGH",
            "category": "Financial",
            "finding": f"Revenue per employee declining from ${totals['revenue_per_employee_current']:,.0f} to "
                       f"${totals['revenue_per_employee_target']:,.0f} — a {((totals['revenue_per_employee_target']/totals['revenue_per_employee_current'])-1)*100:.0f}% drop.",
            "recommendation": "Validate that revenue model supports this headcount. Is target revenue achievable with this team?"
        })

    # Low priority hires consuming budget
    low_priority_hires = [h for h in plan.hires if h.priority == "Low"]
    if low_priority_hires:
        lp_cost = sum(compute_hire_costs(h)["first_year_total"] for h in low_priority_hires)
        risks.append({
            "severity": "MEDIUM",
            "category": "Prioritization",
            "finding": f"{len(low_priority_hires)} 'Low' priority hires consuming ${lp_cost:,.0f} in first-year costs.",
            "recommendation": "Consider deferring Low priority hires to preserve runway. Cut these first if budget tightens."
        })

    # Hires without business cases
    no_case = [h for h in plan.hires if not h.business_case]
    if no_case:
        risks.append({
            "severity": "MEDIUM",
            "category": "Governance",
            "finding": f"{len(no_case)} hires have no documented business case: {', '.join(h.role for h in no_case[:5])}{'...' if len(no_case) > 5 else ''}",
            "recommendation": "Every hire over $80K should have a written business case. What revenue or risk does this role address?"
        })

    # High recruiter fee exposure
    if totals["total_recruiter_fees"] > 100_000:
        risks.append({
            "severity": "LOW",
            "category": "Cost",
            "finding": f"${totals['total_recruiter_fees']:,.0f} in recruiter fees. "
                       "Consider whether internal recruiter investment would be cheaper at this hiring volume.",
            "recommendation": f"Internal recruiter at $120–150K fully loaded pays off at 3–4 hires/year vs. agency fees."
        })

    # No risks — that's itself a flag
    if not risks:
        risks.append({
            "severity": "INFO",
            "category": "General",
            "finding": "No major risks flagged. Plan appears well-structured.",
            "recommendation": "Validate assumptions: time-to-fill estimates, revenue model, and Q1 hiring pipeline status."
        })

    return risks


# ---------------------------------------------------------------------------
# Formatting / Output
# ---------------------------------------------------------------------------

def fmt(n: int) -> str:
    return f"${n:,.0f}"


def pct(n: float) -> str:
    return f"{n:.1f}%"


def print_report(plan: HiringPlan):
    WIDTH = 72
    SEP = "=" * WIDTH
    sep = "-" * WIDTH

    print(SEP)
    print(f"  HIRING PLAN: {plan.company}")
    print(f"  Period: {plan.plan_period}  |  Generated: {date.today().isoformat()}")
    print(SEP)

    totals = compute_totals(plan)
    q_summary = summarize_by_quarter(plan)
    fn_summary = summarize_by_function(plan)
    risks = assess_risks(plan, totals)

    # Executive summary
    print("\n[ EXECUTIVE SUMMARY ]")
    print(sep)
    print(f"  Current headcount:       {plan.current_headcount:>5}")
    print(f"  Planned hires:           {totals['total_hires']:>5}")
    print(f"  Final headcount:         {totals['final_headcount']:>5}  (+{totals['headcount_growth_pct']:.0f}%)")
    print(f"  Current ARR:             {fmt(plan.current_revenue):>12}")
    print(f"  Target revenue:          {fmt(plan.target_revenue):>12}")
    print(f"  Revenue/employee now:    {fmt(int(totals['revenue_per_employee_current'])):>12}")
    print(f"  Revenue/employee target: {fmt(int(totals['revenue_per_employee_target'])):>12}")
    print()
    print(f"  Total annual comp added: {fmt(totals['total_annual_comp_added']):>12}")
    print(f"  Total first-year cost:   {fmt(totals['total_first_year_cost']):>12}")
    print(f"  Fully loaded (w/ ramp):  {fmt(totals['total_fully_loaded_first_year']):>12}")
    print(f"  Recruiter fees:          {fmt(totals['total_recruiter_fees']):>12}")
    print(f"  Avg comp per hire:       {fmt(totals['avg_comp_per_hire']):>12}")

    # Quarterly breakdown
    print(f"\n[ QUARTERLY HEADCOUNT PLAN ]")
    print(sep)
    print(f"  {'Quarter':<10} {'New Hires':>10} {'HC (EOP)':>10} {'Comp Added':>14} {'1yr Cost':>14} {'Recruiter $':>12}")
    print(f"  {'-'*10} {'-'*10} {'-'*10} {'-'*14} {'-'*14} {'-'*12}")
    for q, data in q_summary.items():
        print(f"  {q:<10} {data['new_hires']:>10} {data['headcount_eop']:>10} "
              f"{fmt(data['total_annual_comp_added']):>14} "
              f"{fmt(data['total_first_year_cost']):>14} "
              f"{fmt(data['recruiter_fees']):>12}")

    # By function
    print(f"\n[ HEADCOUNT BY FUNCTION ]")
    print(sep)
    print(f"  {'Function':<18} {'Hires':>7} {'Annual Comp':>14} {'1yr Cost':>14}")
    print(f"  {'-'*18} {'-'*7} {'-'*14} {'-'*14}")
    for fn, data in sorted(fn_summary.items(), key=lambda x: -x[1]["count"]):
        print(f"  {fn:<18} {data['count']:>7} {fmt(data['total_comp']):>14} {fmt(data['total_first_year']):>14}")

    # Hire detail
    print(f"\n[ HIRE DETAIL ]")
    print(sep)
    print(f"  {'Role':<30} {'Fn':<14} {'Lvl':<6} {'Q':<8} {'Base':>10} {'Total Comp':>12} {'Priority':<8}")
    print(f"  {'-'*30} {'-'*14} {'-'*6} {'-'*8} {'-'*10} {'-'*12} {'-'*8}")
    for h in sorted(plan.hires, key=lambda x: quarter_to_sortkey(x.quarter)):
        costs = compute_hire_costs(h)
        print(f"  {h.role:<30} {h.function:<14} {h.level:<6} {h.quarter:<8} "
              f"{fmt(h.base_salary):>10} {fmt(costs['total_comp']):>12} {h.priority:<8}")
        if h.business_case:
            bc = h.business_case[:60] + "..." if len(h.business_case) > 60 else h.business_case
            print(f"  {'':>30}   ↳ {bc}")

    # Risk assessment
    print(f"\n[ RISK ASSESSMENT ]")
    print(sep)
    sev_order = {"HIGH": 0, "MEDIUM": 1, "LOW": 2, "INFO": 3}
    for risk in sorted(risks, key=lambda r: sev_order.get(r["severity"], 99)):
        sev = risk["severity"]
        marker = {"HIGH": "⚠ HIGH", "MEDIUM": "◆ MED ", "LOW": "◇ LOW ", "INFO": "ℹ INFO"}[sev]
        print(f"\n  [{marker}] {risk['category']}")
        # Wrap finding
        finding = risk["finding"]
        words = finding.split()
        line = "  Finding: "
        for w in words:
            if len(line) + len(w) + 1 > WIDTH - 2:
                print(line)
                line = "           " + w + " "
            else:
                line += w + " "
        if line.strip():
            print(line)
        reco = risk["recommendation"]
        words = reco.split()
        line = "  Action:  "
        for w in words:
            if len(line) + len(w) + 1 > WIDTH - 2:
                print(line)
                line = "           " + w + " "
            else:
                line += w + " "
        if line.strip():
            print(line)

    print(f"\n{SEP}\n")


def export_csv(plan: HiringPlan) -> str:
    """Return CSV of hire detail."""
    output = io.StringIO()
    writer = csv.writer(output)
    writer.writerow(["Role", "Function", "Level", "Quarter", "Priority",
                     "Base Salary", "Bonus Target", "Equity Annual", "Benefits",
                     "Total Comp", "Recruiter Fee", "Overhead", "First Year Total",
                     "Ramp Months", "Open to Internal", "Business Case"])
    for h in plan.hires:
        c = compute_hire_costs(h)
        writer.writerow([h.role, h.function, h.level, h.quarter, h.priority,
                         h.base_salary, c["target_bonus"], h.equity_annual_usd, h.benefits_annual,
                         c["total_comp"], c["recruiter_fee"], c["overhead"], c["first_year_total"],
                         h.ramp_months, h.open_to_internal, h.business_case])
    return output.getvalue()


# ---------------------------------------------------------------------------
# Sample data
# ---------------------------------------------------------------------------

def build_sample_plan() -> HiringPlan:
    """Sample Series A → B hiring plan."""
    plan = HiringPlan(
        company="AcmeTech (Series A)",
        plan_period="2025 Annual",
        current_headcount=32,
        current_revenue=3_500_000,
        target_revenue=8_000_000,
        overhead_rate=0.25,
        internal_recruiter_cost=140_000,
    )

    plan.hires = [
        # Q1 — Foundation hires
        HireTarget(
            role="Staff Software Engineer (Backend)",
            level="L4", function="Engineering", quarter="Q1-2025",
            base_salary=185_000, bonus_pct=0.0, equity_annual_usd=25_000,
            benefits_annual=18_000, recruiter_fee_pct=0.0, ramp_months=2,
            priority="High", open_to_internal=True,
            business_case="Core API team is bottleneck for 3 roadmap items. Staff-level needed to lead architecture."
        ),
        HireTarget(
            role="Account Executive (Mid-Market)",
            level="L3", function="Sales", quarter="Q1-2025",
            base_salary=95_000, bonus_pct=0.50, equity_annual_usd=10_000,
            benefits_annual=15_000, recruiter_fee_pct=0.18, ramp_months=4,
            priority="High",
            business_case="Pipeline coverage at 1.8x quota. Need 2.5x by Q2. AE adds $600K ARR/year at ramp."
        ),
        HireTarget(
            role="Product Designer (Senior)",
            level="L3", function="Product", quarter="Q1-2025",
            base_salary=145_000, bonus_pct=0.0, equity_annual_usd=18_000,
            benefits_annual=18_000, recruiter_fee_pct=0.0, ramp_months=2,
            priority="High",
            business_case="Single designer for 4 squads. UX debt slowing enterprise deals requiring onboarding improvements."
        ),

        # Q2 — Growth hires
        HireTarget(
            role="Engineering Manager (Frontend)",
            level="M1", function="Engineering", quarter="Q2-2025",
            base_salary=175_000, bonus_pct=0.10, equity_annual_usd=22_000,
            benefits_annual=18_000, recruiter_fee_pct=0.20, ramp_months=3,
            priority="High",
            business_case="Frontend team at 7 ICs with no dedicated EM. Performance review debt is high; manager needed."
        ),
        HireTarget(
            role="Account Executive (Mid-Market)",
            level="L2", function="Sales", quarter="Q2-2025",
            base_salary=85_000, bonus_pct=0.50, equity_annual_usd=8_000,
            benefits_annual=15_000, recruiter_fee_pct=0.18, ramp_months=4,
            priority="High",
            business_case="Second AE to reach 2.5x pipeline coverage target."
        ),
        HireTarget(
            role="Customer Success Manager",
            level="L2", function="Customer Success", quarter="Q2-2025",
            base_salary=90_000, bonus_pct=0.15, equity_annual_usd=8_000,
            benefits_annual=15_000, recruiter_fee_pct=0.0, ramp_months=2,
            priority="Medium",
            business_case="CSM:account ratio at 1:60, industry standard 1:30. NRR has dipped 4pts in 2 quarters."
        ),
        HireTarget(
            role="Data Engineer",
            level="L2", function="Engineering", quarter="Q2-2025",
            base_salary=155_000, bonus_pct=0.0, equity_annual_usd=18_000,
            benefits_annual=18_000, recruiter_fee_pct=0.0, ramp_months=3,
            priority="Medium",
            business_case="Analytics infrastructure blocking product analytics, customer dashboards, and board metrics."
        ),

        # Q3 — Scale hires
        HireTarget(
            role="Senior Software Engineer (Backend)",
            level="L3", function="Engineering", quarter="Q3-2025",
            base_salary=165_000, bonus_pct=0.0, equity_annual_usd=20_000,
            benefits_annual=18_000, recruiter_fee_pct=0.0, ramp_months=2,
            priority="High",
            business_case="Backend team needs capacity to deliver Q3 roadmap without delaying Q4 items."
        ),
        HireTarget(
            role="Head of Marketing",
            level="M3", function="Marketing", quarter="Q3-2025",
            base_salary=180_000, bonus_pct=0.15, equity_annual_usd=30_000,
            benefits_annual=18_000, recruiter_fee_pct=0.20, ramp_months=3,
            priority="High",
            business_case="No marketing function. 100% of pipeline is outbound. Need inbound by Q1-2026 for Series B."
        ),
        HireTarget(
            role="People Operations Manager",
            level="M1", function="G&A", quarter="Q3-2025",
            base_salary=120_000, bonus_pct=0.10, equity_annual_usd=12_000,
            benefits_annual=16_000, recruiter_fee_pct=0.0, ramp_months=2,
            priority="Medium",
            business_case="Founders spending 8hrs/week on HR ops at 40 employees. Unscalable. First dedicated HR hire."
        ),

        # Q4 — Stretch hires (conditional on revenue milestone)
        HireTarget(
            role="Senior Software Engineer (Frontend)",
            level="L3", function="Engineering", quarter="Q4-2025",
            base_salary=160_000, bonus_pct=0.0, equity_annual_usd=18_000,
            benefits_annual=18_000, recruiter_fee_pct=0.0, ramp_months=2,
            priority="Medium",
            business_case="Conditional on Q3 ARR exceeding $5.5M. Frontend team capacity planning for 2026 roadmap."
        ),
        HireTarget(
            role="Account Executive (Enterprise)",
            level="L4", function="Sales", quarter="Q4-2025",
            base_salary=120_000, bonus_pct=0.60, equity_annual_usd=15_000,
            benefits_annual=15_000, recruiter_fee_pct=0.20, ramp_months=6,
            priority="Low",
            business_case="Enterprise motion exploratory. Requires ICP validation in Q2-Q3 before committing."
        ),
        HireTarget(
            role="DevOps / Platform Engineer",
            level="L3", function="Engineering", quarter="Q4-2025",
            base_salary=150_000, bonus_pct=0.0, equity_annual_usd=18_000,
            benefits_annual=18_000, recruiter_fee_pct=0.0, ramp_months=3,
            priority="Low",
            business_case="Platform reliability becoming bottleneck. Conditional on uptime SLA breaches continuing in Q3."
        ),
    ]

    return plan


# ---------------------------------------------------------------------------
# CLI
# ---------------------------------------------------------------------------

def load_plan_from_json(path: str) -> HiringPlan:
    with open(path) as f:
        data = json.load(f)
    hires = [HireTarget(**h) for h in data.pop("hires", [])]
    plan = HiringPlan(**data)
    plan.hires = hires
    return plan


def main():
    parser = argparse.ArgumentParser(
        description="Hiring Plan Modeler — build headcount plans with cost projections",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Examples:
  python hiring_plan_modeler.py                       # Run sample plan
  python hiring_plan_modeler.py --config plan.json    # Load from JSON
  python hiring_plan_modeler.py --export-csv          # Output CSV of hires
  python hiring_plan_modeler.py --export-json         # Output plan as JSON template
        """
    )
    parser.add_argument("--config", help="Path to JSON plan file")
    parser.add_argument("--export-csv", action="store_true", help="Export hire detail as CSV")
    parser.add_argument("--export-json", action="store_true", help="Export sample plan as JSON template")
    args = parser.parse_args()

    if args.config:
        plan = load_plan_from_json(args.config)
    else:
        plan = build_sample_plan()

    if args.export_json:
        data = asdict(plan)
        print(json.dumps(data, indent=2))
        return

    if args.export_csv:
        print(export_csv(plan))
        return

    print_report(plan)


if __name__ == "__main__":
    main()