Margin Simulation

#!/usr/bin/env python3
"""
Margin Simulation Engine
========================
Models agency profitability at the client/scope/campaign level. Combines a
deterministic P&L calculator with Monte Carlo simulation for uncertainty
quantification, leakage detection, and sensitivity analysis.

Architecture:
  - Deterministic layer: Standard P&L (revenue - costs = margin)
  - Stochastic layer: Monte Carlo (N=5000 draws) models uncertainty in
    scope creep, rework, client delays, and vendor overruns
  - Leakage detector: Flags margin erosion sources with estimated impact
  - Sensitivity analyzer: Tests which cost driver has the largest marginal
    impact on margin — answers "where should I negotiate?"

The 70/30 AI model is embedded: FTE costs reflect human hours only (after AI
automation), and AI infrastructure cost is modeled as a fixed overhead.

Usage:
    from scripts.margin_engine import MarginSimulator
    sim = MarginSimulator(config)
    result = sim.run()

    # CLI:
    python margin_engine.py --input config.json --output margin.json
"""

import json
import sys
import argparse
import math
from dataclasses import dataclass, field, asdict
from typing import Optional

# Try numpy for Monte Carlo; fall back to pure Python if unavailable
try:
    import numpy as np
    HAS_NUMPY = True
except ImportError:
    HAS_NUMPY = False
    import random


# ── Constants ───────────────────────────────────────────────────────────────

DEFAULT_MONTE_CARLO_RUNS = 5000
AGENCY_OVERHEAD_PCT = 0.12        # 12% agency overhead on delivery cost
AI_INFRASTRUCTURE_MONTHLY = 500   # Base AI tooling cost (Claude, MCP, infra)
DEFAULT_MARGIN_TARGET = 0.30      # 30% target gross margin
DEFAULT_REWORK_RATE = 0.10        # 10% rework buffer
DEFAULT_SCOPE_CREEP_RATE = 0.15   # 15% scope creep probability per month
DEFAULT_CLIENT_DELAY_RATE = 0.20  # 20% probability of client-caused delays


# ── Leakage Patterns ────────────────────────────────────────────────────────

LEAKAGE_PATTERNS = {
    "no_revision_cap": {
        "name": "Uncapped revisions",
        "impact_pct": 0.15,  # 15% cost increase
        "description": "No revision cap → average 2-3 extra rounds per deliverable",
        "fix": "Add 'up to 2 rounds' clause; bill overages at hourly rate",
    },
    "no_pm_hours": {
        "name": "Unpriced PM overhead",
        "impact_pct": 0.12,
        "description": "Project management not explicitly costed → absorbed by team",
        "fix": "Add explicit PM allocation at 10-15% of delivery hours",
    },
    "scope_creep": {
        "name": "Scope creep (no CO mechanism)",
        "impact_pct": 0.20,
        "description": "No change order process → additional work absorbed at no charge",
        "fix": "Implement change order threshold and approval workflow",
    },
    "client_delays": {
        "name": "Client approval delays",
        "impact_pct": 0.10,
        "description": "No client SLA → team idles waiting for feedback, hours still burn",
        "fix": "Add 3-business-day approval SLA with deemed-approved clause",
    },
    "vendor_overruns": {
        "name": "Vendor cost overruns",
        "impact_pct": 0.08,
        "description": "Third-party costs exceed estimates (media, production, tech)",
        "fix": "Add vendor cost caps with client pass-through for overages",
    },
    "seniority_mismatch": {
        "name": "Seniority inflation",
        "impact_pct": 0.15,
        "description": "Senior resources pulled into junior tasks due to capacity gaps",
        "fix": "Right-size team; use AI agents for junior-level execution",
    },
    "as_needed_support": {
        "name": "Ad hoc 'as needed' work",
        "impact_pct": 0.20,
        "description": "'As needed' clause consumed without tracking → invisible hours",
        "fix": "Cap ad hoc hours at N/month; track and report monthly",
    },
    "tool_costs_unpriced": {
        "name": "Tool/platform costs absorbed",
        "impact_pct": 0.05,
        "description": "SaaS licenses, API costs, platform fees not passed to client",
        "fix": "Add technology line item or pass-through clause",
    },
}


# ── Data Classes ────────────────────────────────────────────────────────────

@dataclass
class CostLine:
    """A single cost component."""
    category: str       # fte, vendor, overhead, tools, rework, buffer
    name: str
    monthly_amount: float
    notes: str = ""
    is_variable: bool = False  # Variable costs scale with scope changes
    uncertainty_pct: float = 0.0  # ±% for Monte Carlo draws


@dataclass
class LeakageItem:
    """A detected margin leakage source."""
    pattern: str
    name: str
    monthly_impact: float
    impact_pct: float
    description: str
    fix: str
    severity: str = "Medium"  # Low, Medium, High


@dataclass
class ScenarioResult:
    """Result of a single P&L scenario."""
    name: str
    monthly_revenue: float
    total_cost: float
    gross_margin: float
    margin_pct: float
    oi_ebitda: float
    verdict: str


@dataclass
class MonteCarloResult:
    """Summary of Monte Carlo simulation."""
    runs: int
    mean_margin_pct: float
    median_margin_pct: float
    p10_margin_pct: float   # 10th percentile (pessimistic)
    p90_margin_pct: float   # 90th percentile (optimistic)
    std_margin_pct: float
    prob_below_target: float  # P(margin < target)
    prob_negative: float      # P(margin < 0)


@dataclass
class SensitivityItem:
    """Sensitivity of margin to a cost driver."""
    driver: str
    base_value: float
    delta_pct: float        # % change applied
    margin_impact_pct: float  # Resulting margin change in percentage points
    direction: str           # "up" or "down"


@dataclass
class MarginResult:
    """Full margin simulation output."""
    client_name: str = ""
    engagement_type: str = ""  # retainer, project, campaign

    # Revenue
    monthly_revenue: float = 0
    contract_months: int = 12
    total_contract_value: float = 0

    # Deterministic P&L
    fte_cost: float = 0
    vendor_cost: float = 0
    tool_cost: float = 0
    overhead_cost: float = 0
    ai_infrastructure_cost: float = 0
    rework_buffer: float = 0
    risk_buffer: float = 0
    total_delivery_cost: float = 0
    gross_margin: float = 0
    margin_pct: float = 0
    oi_ebitda: float = 0
    margin_target: float = 0.30

    # Cost breakdown
    cost_lines: list = field(default_factory=list)

    # Leakage
    leakage_items: list = field(default_factory=list)
    total_leakage: float = 0
    adjusted_margin_pct: float = 0

    # Monte Carlo
    monte_carlo: dict = field(default_factory=dict)

    # Sensitivity
    sensitivity: list = field(default_factory=list)

    # Scenarios
    scenarios: list = field(default_factory=list)

    # Verdict
    verdict: str = ""
    verdict_rationale: str = ""
    recommendations: list = field(default_factory=list)

    def to_dict(self):
        d = asdict(self)
        # Round all floats
        def round_floats(obj, decimals=2):
            if isinstance(obj, float):
                return round(obj, decimals)
            elif isinstance(obj, dict):
                return {k: round_floats(v, decimals) for k, v in obj.items()}
            elif isinstance(obj, list):
                return [round_floats(i, decimals) for i in obj]
            return obj
        return round_floats(d)

    def to_json(self, indent=2):
        return json.dumps(self.to_dict(), indent=indent, ensure_ascii=False)


# ── Simulator ───────────────────────────────────────────────────────────────

class MarginSimulator:
    """
    Main margin simulation engine.

    Config dict expected keys:
        client_name: str
        engagement_type: str (retainer|project|campaign)
        monthly_revenue: float
        contract_months: int (default 12)
        margin_target: float (default 0.30)

        # Cost inputs (all monthly)
        fte_costs: list[dict] — [{name, monthly_amount, seniority, fte, uncertainty_pct}]
        vendor_costs: list[dict] — [{name, monthly_amount, uncertainty_pct}]
        tool_costs: list[dict] — [{name, monthly_amount}]
        overhead_pct: float (default 0.12)
        ai_infrastructure: float (default 500)
        rework_rate: float (default 0.10)
        risk_buffer_pct: float (default 0.05)

        # Leakage flags (optional booleans)
        has_revision_cap: bool
        has_pm_hours: bool
        has_change_order: bool
        has_client_sla: bool
        has_vendor_caps: bool
        has_seniority_match: bool
        has_adhoc_cap: bool
        has_tool_passthrough: bool

        # Monte Carlo settings
        monte_carlo_runs: int (default 5000)
        scope_creep_rate: float (default 0.15)
        client_delay_rate: float (default 0.20)
    """

    def __init__(self, config: dict):
        self.config = config
        self.result = MarginResult(
            client_name=config.get("client_name", "Unknown"),
            engagement_type=config.get("engagement_type", "retainer"),
            monthly_revenue=config.get("monthly_revenue", 0),
            contract_months=config.get("contract_months", 12),
            margin_target=config.get("margin_target", DEFAULT_MARGIN_TARGET),
        )

    def run(self) -> MarginResult:
        """Execute full margin simulation pipeline."""
        self._build_cost_structure()
        self._calculate_deterministic_pnl()
        self._detect_leakage()
        self._run_monte_carlo()
        self._run_sensitivity()
        self._build_scenarios()
        self._determine_verdict()
        return self.result

    def _build_cost_structure(self):
        """Assemble all cost lines from config."""
        lines = []

        # FTE costs
        for fte in self.config.get("fte_costs", []):
            lines.append(CostLine(
                category="fte",
                name=fte.get("name", "FTE"),
                monthly_amount=fte.get("monthly_amount", 0),
                notes=f"{fte.get('fte', '?')} FTE @ {fte.get('seniority', 'mid')}",
                is_variable=True,
                uncertainty_pct=fte.get("uncertainty_pct", 10),
            ))

        # Vendor costs
        for v in self.config.get("vendor_costs", []):
            lines.append(CostLine(
                category="vendor",
                name=v.get("name", "Vendor"),
                monthly_amount=v.get("monthly_amount", 0),
                is_variable=True,
                uncertainty_pct=v.get("uncertainty_pct", 15),
            ))

        # Tool costs
        for t in self.config.get("tool_costs", []):
            lines.append(CostLine(
                category="tools",
                name=t.get("name", "Tool"),
                monthly_amount=t.get("monthly_amount", 0),
                is_variable=False,
                uncertainty_pct=5,
            ))

        # AI infrastructure
        ai_cost = self.config.get("ai_infrastructure", AI_INFRASTRUCTURE_MONTHLY)
        lines.append(CostLine(
            category="ai",
            name="AI infrastructure (Claude, MCP, agents)",
            monthly_amount=ai_cost,
            is_variable=False,
            uncertainty_pct=10,
        ))

        self.result.cost_lines = lines

    def _calculate_deterministic_pnl(self):
        """Calculate the base-case P&L."""
        rev = self.result.monthly_revenue

        fte_cost = sum(c.monthly_amount for c in self.result.cost_lines if c.category == "fte")
        vendor_cost = sum(c.monthly_amount for c in self.result.cost_lines if c.category == "vendor")
        tool_cost = sum(c.monthly_amount for c in self.result.cost_lines if c.category == "tools")
        ai_cost = sum(c.monthly_amount for c in self.result.cost_lines if c.category == "ai")

        # Overhead
        delivery_base = fte_cost + vendor_cost
        overhead_pct = self.config.get("overhead_pct", AGENCY_OVERHEAD_PCT)
        overhead = delivery_base * overhead_pct

        # Rework buffer
        rework_rate = self.config.get("rework_rate", DEFAULT_REWORK_RATE)
        rework = fte_cost * rework_rate

        # Risk buffer
        risk_pct = self.config.get("risk_buffer_pct", 0.05)
        risk_buffer = delivery_base * risk_pct

        total_cost = fte_cost + vendor_cost + tool_cost + ai_cost + overhead + rework + risk_buffer

        self.result.fte_cost = fte_cost
        self.result.vendor_cost = vendor_cost
        self.result.tool_cost = tool_cost
        self.result.ai_infrastructure_cost = ai_cost
        self.result.overhead_cost = overhead
        self.result.rework_buffer = rework
        self.result.risk_buffer = risk_buffer
        self.result.total_delivery_cost = total_cost
        self.result.gross_margin = rev - total_cost
        self.result.margin_pct = ((rev - total_cost) / rev * 100) if rev > 0 else 0
        self.result.oi_ebitda = (rev - total_cost) * self.result.contract_months
        self.result.total_contract_value = rev * self.result.contract_months

    def _detect_leakage(self):
        """Identify margin leakage sources from config flags."""
        flag_map = {
            "has_revision_cap": ("no_revision_cap", False),
            "has_pm_hours": ("no_pm_hours", False),
            "has_change_order": ("scope_creep", False),
            "has_client_sla": ("client_delays", False),
            "has_vendor_caps": ("vendor_overruns", False),
            "has_seniority_match": ("seniority_mismatch", False),
            "has_adhoc_cap": ("as_needed_support", False),
            "has_tool_passthrough": ("tool_costs_unpriced", False),
        }

        delivery_cost = self.result.total_delivery_cost
        total_leakage = 0

        for config_key, (pattern_key, safe_default) in flag_map.items():
            has_protection = self.config.get(config_key, safe_default)
            if not has_protection:
                pattern = LEAKAGE_PATTERNS[pattern_key]
                impact = delivery_cost * pattern["impact_pct"]
                severity = "High" if pattern["impact_pct"] >= 0.15 else "Medium" if pattern["impact_pct"] >= 0.08 else "Low"

                self.result.leakage_items.append(LeakageItem(
                    pattern=pattern_key,
                    name=pattern["name"],
                    monthly_impact=impact,
                    impact_pct=pattern["impact_pct"] * 100,
                    description=pattern["description"],
                    fix=pattern["fix"],
                    severity=severity,
                ))
                total_leakage += impact

        self.result.total_leakage = total_leakage
        adjusted_cost = self.result.total_delivery_cost + total_leakage
        rev = self.result.monthly_revenue
        self.result.adjusted_margin_pct = ((rev - adjusted_cost) / rev * 100) if rev > 0 else 0

    def _run_monte_carlo(self):
        """Run Monte Carlo simulation to quantify margin uncertainty."""
        n = self.config.get("monte_carlo_runs", DEFAULT_MONTE_CARLO_RUNS)
        rev = self.result.monthly_revenue
        if rev <= 0:
            self.result.monte_carlo = {}
            return

        scope_creep_rate = self.config.get("scope_creep_rate", DEFAULT_SCOPE_CREEP_RATE)
        client_delay_rate = self.config.get("client_delay_rate", DEFAULT_CLIENT_DELAY_RATE)

        margins = []

        if HAS_NUMPY:
            rng = np.random.default_rng(42)
            for _ in range(n):
                total = 0
                for c in self.result.cost_lines:
                    unc = c.uncertainty_pct / 100
                    drawn = c.monthly_amount * (1 + rng.normal(0, unc))
                    total += max(drawn, 0)

                # Overhead on drawn costs
                overhead_pct = self.config.get("overhead_pct", AGENCY_OVERHEAD_PCT)
                total *= (1 + overhead_pct)

                # Scope creep event
                if rng.random() < scope_creep_rate:
                    creep_factor = rng.uniform(0.05, 0.25)
                    total *= (1 + creep_factor)

                # Client delay event
                if rng.random() < client_delay_rate:
                    delay_cost = total * rng.uniform(0.03, 0.12)
                    total += delay_cost

                # Rework
                rework_rate = self.config.get("rework_rate", DEFAULT_REWORK_RATE)
                total *= (1 + rng.normal(rework_rate, rework_rate * 0.3))

                margin = (rev - total) / rev * 100
                margins.append(margin)

            margins = np.array(margins)
            self.result.monte_carlo = asdict(MonteCarloResult(
                runs=n,
                mean_margin_pct=float(np.mean(margins)),
                median_margin_pct=float(np.median(margins)),
                p10_margin_pct=float(np.percentile(margins, 10)),
                p90_margin_pct=float(np.percentile(margins, 90)),
                std_margin_pct=float(np.std(margins)),
                prob_below_target=float(np.mean(margins < self.result.margin_target * 100)),
                prob_negative=float(np.mean(margins < 0)),
            ))
        else:
            # Pure Python fallback
            random.seed(42)
            for _ in range(n):
                total = 0
                for c in self.result.cost_lines:
                    unc = c.uncertainty_pct / 100
                    drawn = c.monthly_amount * (1 + random.gauss(0, unc))
                    total += max(drawn, 0)

                overhead_pct = self.config.get("overhead_pct", AGENCY_OVERHEAD_PCT)
                total *= (1 + overhead_pct)

                if random.random() < scope_creep_rate:
                    total *= (1 + random.uniform(0.05, 0.25))

                if random.random() < client_delay_rate:
                    total += total * random.uniform(0.03, 0.12)

                rework_rate = self.config.get("rework_rate", DEFAULT_REWORK_RATE)
                total *= (1 + random.gauss(rework_rate, rework_rate * 0.3))

                margins.append((rev - total) / rev * 100)

            margins.sort()
            mean_m = sum(margins) / n
            median_m = margins[n // 2]
            p10 = margins[int(n * 0.10)]
            p90 = margins[int(n * 0.90)]
            variance = sum((m - mean_m) ** 2 for m in margins) / n
            std_m = math.sqrt(variance)
            prob_below = sum(1 for m in margins if m < self.result.margin_target * 100) / n
            prob_neg = sum(1 for m in margins if m < 0) / n

            self.result.monte_carlo = asdict(MonteCarloResult(
                runs=n, mean_margin_pct=mean_m, median_margin_pct=median_m,
                p10_margin_pct=p10, p90_margin_pct=p90, std_margin_pct=std_m,
                prob_below_target=prob_below, prob_negative=prob_neg,
            ))

    def _run_sensitivity(self):
        """Test which cost driver moves margin the most (±20% shock)."""
        rev = self.result.monthly_revenue
        base_cost = self.result.total_delivery_cost
        base_margin = self.result.margin_pct
        delta = 0.20  # 20% shock

        if rev <= 0:
            return

        drivers = {}
        for c in self.result.cost_lines:
            cat = c.category
            if cat not in drivers:
                drivers[cat] = 0
            drivers[cat] += c.monthly_amount

        for driver, amount in drivers.items():
            if amount <= 0:
                continue
            shocked_cost = base_cost + (amount * delta)
            shocked_margin = (rev - shocked_cost) / rev * 100
            impact = shocked_margin - base_margin

            self.result.sensitivity.append(asdict(SensitivityItem(
                driver=driver,
                base_value=amount,
                delta_pct=delta * 100,
                margin_impact_pct=impact,
                direction="up",
            )))

        # Sort by absolute impact (most sensitive first)
        self.result.sensitivity.sort(key=lambda x: abs(x["margin_impact_pct"]), reverse=True)

    def _build_scenarios(self):
        """Generate base, optimistic, and pessimistic scenarios."""
        rev = self.result.monthly_revenue
        base = self.result.total_delivery_cost

        scenarios = [
            ("Base case", base, 0),
            ("Optimistic (AI uplift, no creep)", base * 0.85, -15),
            ("Pessimistic (scope creep + rework)", base * 1.30, 30),
            ("With leakage (no protections)", base + self.result.total_leakage, 0),
        ]

        for name, cost, note in scenarios:
            margin = rev - cost
            margin_pct = (margin / rev * 100) if rev > 0 else 0
            verdict = (
                "Viable" if margin_pct >= 30 else
                "Tight" if margin_pct >= 15 else
                "Underfunded" if margin_pct >= 0 else
                "Non-viable"
            )
            self.result.scenarios.append(asdict(ScenarioResult(
                name=name,
                monthly_revenue=rev,
                total_cost=cost,
                gross_margin=margin,
                margin_pct=margin_pct,
                oi_ebitda=margin * self.result.contract_months,
                verdict=verdict,
            )))

    def _determine_verdict(self):
        """Issue overall commercial verdict."""
        margin = self.result.margin_pct
        mc = self.result.monte_carlo
        leakage_count = len(self.result.leakage_items)
        high_leakage = sum(1 for l in self.result.leakage_items if l.severity == "High")

        recs = []

        # Margin-based verdict
        if margin >= 40:
            self.result.verdict = "Highly viable"
            self.result.verdict_rationale = (
                f"Base margin at {margin:.1f}% — well above {self.result.margin_target*100:.0f}% target. "
                f"Strong commercial position."
            )
        elif margin >= self.result.margin_target * 100:
            self.result.verdict = "Viable"
            self.result.verdict_rationale = (
                f"Base margin at {margin:.1f}% — meets {self.result.margin_target*100:.0f}% target."
            )
        elif margin >= 15:
            self.result.verdict = "Tight"
            self.result.verdict_rationale = (
                f"Base margin at {margin:.1f}% — below target. "
                f"Vulnerable to scope creep and rework."
            )
            recs.append("Increase fee by 10-20% or reduce deliverable count.")
        elif margin >= 0:
            self.result.verdict = "Underfunded"
            self.result.verdict_rationale = (
                f"Base margin at {margin:.1f}% — near breakeven. "
                f"Any scope creep or rework makes this unprofitable."
            )
            recs.append("Renegotiate fee or significantly reduce scope.")
            recs.append("Shift more tasks to AI-first execution to cut FTE cost.")
        else:
            self.result.verdict = "Non-viable"
            self.result.verdict_rationale = (
                f"Negative margin at {margin:.1f}%. "
                f"Delivery cost (${self.result.total_delivery_cost:,.0f}/mo) exceeds "
                f"revenue (${self.result.monthly_revenue:,.0f}/mo)."
            )
            recs.append("Reject unless fee is increased or scope fundamentally reduced.")

        # Monte Carlo enrichment
        if mc:
            prob_below = mc.get("prob_below_target", 0) * 100
            prob_neg = mc.get("prob_negative", 0) * 100
            if prob_below > 50:
                recs.append(
                    f"Monte Carlo: {prob_below:.0f}% probability of falling below target margin. "
                    f"P10 margin: {mc.get('p10_margin_pct', 0):.1f}%."
                )
            if prob_neg > 10:
                recs.append(
                    f"Monte Carlo: {prob_neg:.0f}% probability of negative margin — significant financial risk."
                )

        # Leakage warnings
        if high_leakage > 0:
            recs.append(
                f"{high_leakage} high-severity leakage source(s) detected. "
                f"Total monthly leakage: ${self.result.total_leakage:,.0f}. "
                f"Adjusted margin would be {self.result.adjusted_margin_pct:.1f}%."
            )

        # Sensitivity insight
        if self.result.sensitivity:
            top = self.result.sensitivity[0]
            recs.append(
                f"Most sensitive cost driver: '{top['driver']}' — "
                f"a 20% increase would reduce margin by {abs(top['margin_impact_pct']):.1f}pp."
            )

        self.result.recommendations = recs


# ── CLI Entry Point ─────────────────────────────────────────────────────────

def main():
    parser = argparse.ArgumentParser(description="Margin Simulation Engine")
    parser.add_argument("--input", "-i", required=True, help="JSON config file")
    parser.add_argument("--output", "-o", default=None, help="Output JSON path")
    args = parser.parse_args()

    with open(args.input, "r", encoding="utf-8") as f:
        config = json.load(f)

    sim = MarginSimulator(config)
    result = sim.run()
    output = result.to_json()

    if args.output:
        with open(args.output, "w", encoding="utf-8") as f:
            f.write(output)
        print(f"✅ Margin simulation complete → {args.output}")
        print(f"   Verdict: {result.verdict}")
        print(f"   Revenue: ${result.monthly_revenue:,.0f}/mo | Cost: ${result.total_delivery_cost:,.0f}/mo")
        print(f"   Margin: {result.margin_pct:.1f}% | OI/EBITDA: ${result.oi_ebitda:,.0f}")
        if result.monte_carlo:
            mc = result.monte_carlo
            print(f"   Monte Carlo: P10={mc['p10_margin_pct']:.1f}% | Mean={mc['mean_margin_pct']:.1f}% | P90={mc['p90_margin_pct']:.1f}%")
        print(f"   Leakage: ${result.total_leakage:,.0f}/mo ({len(result.leakage_items)} sources)")
    else:
        print(output)


if __name__ == "__main__":
    main()