QuantEngineByItz/tools/build_model_governance_kill_switch_v1.py

#!/usr/bin/env python3
"""MODEL_GOVERNANCE_KILL_SWITCH_V1 — spec/formulas/domains/governance.yaml.

Evaluates the 5 v8.9 kill-switch conditions and demotes execution_mode by exactly
one rung on the promotion ladder when any condition fires. No automatic promotion —
promotion requires an operator_override record (v8.9 V89_039).
governance/todo/v8_9_p1_adoption_plan.yaml P1-C.2.
"""
from __future__ import annotations

import argparse
import json
from pathlib import Path

ROOT = Path(__file__).resolve().parents[1]
DEFAULT_METRICS = ROOT / "Temp" / "model_governance_metrics_v1.json"
DEFAULT_DECISION_PACKET = ROOT / "Temp" / "final_decision_packet_active.json"
DEFAULT_OUT = ROOT / "Temp" / "model_governance_kill_switch_v1.json"

PROMOTION_LADDER = ["AUDIT_ONLY", "SHADOW", "PILOT", "LIVE_LIMITED", "LIVE_FULL"]


def _load(path: Path) -> dict:
    if not path.exists():
        return {}
    try:
        data = json.loads(path.read_text(encoding="utf-8"))
        return data if isinstance(data, dict) else {}
    except Exception:
        return {}


def evaluate_kill_switches(metrics: dict) -> list[str]:
    triggered = []

    quarantine = metrics.get("data_quarantine_rate_pct")
    if quarantine is not None and quarantine > 5.0:
        triggered.append("data_quarantine_rate_above_5pct")

    shortfall = metrics.get("implementation_shortfall_ratio")
    if shortfall is not None and shortfall > 2.0:
        triggered.append("implementation_shortfall_above_2x_expected")

    t5_hit_rate = metrics.get("t5_hit_rate_pct")
    t5_sample_count = metrics.get("t5_sample_count") or 0
    if t5_hit_rate is not None and t5_sample_count >= 30 and t5_hit_rate < 50.0:
        triggered.append("t5_hit_rate_below_50pct_for_30_trades")

    calibration_error = metrics.get("calibration_error")
    calibration_limit = metrics.get("calibration_error_limit")
    if calibration_error is not None and calibration_limit is not None and calibration_error > calibration_limit:
        triggered.append("calibration_error_above_limit")

    mdd = metrics.get("account_mdd_pct")
    mdd_budget = metrics.get("account_mdd_budget_pct")
    if mdd is not None and mdd_budget is not None and mdd > mdd_budget:
        triggered.append("unexpected_drawdown_breach")

    return triggered


def demote_one_rung(current_mode: str) -> str:
    if current_mode not in PROMOTION_LADDER:
        return "AUDIT_ONLY"
    idx = PROMOTION_LADDER.index(current_mode)
    return PROMOTION_LADDER[max(idx - 1, 0)]


def main() -> int:
    ap = argparse.ArgumentParser()
    ap.add_argument("--metrics", default=str(DEFAULT_METRICS))
    ap.add_argument("--decision-packet", default=str(DEFAULT_DECISION_PACKET))
    ap.add_argument("--out", default=str(DEFAULT_OUT))
    args = ap.parse_args()

    metrics = _load(Path(args.metrics))
    decision_packet = _load(Path(args.decision_packet))

    current_mode = decision_packet.get("execution_mode") or decision_packet.get("global_execution_gate") or "AUDIT_ONLY"

    if not metrics:
        result = {
            "formula_id": "MODEL_GOVERNANCE_KILL_SWITCH_V1",
            "gate": "DATA_MISSING",
            "execution_mode": current_mode,
            "execution_mode_changed": False,
            "kill_switch_triggered": False,
            "kill_switch_reason_codes": [],
            "source_paths": [str(Path(args.metrics)), str(Path(args.decision_packet))],
        }
        out = Path(args.out)
        out.write_text(json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8")
        print(json.dumps(result, ensure_ascii=False, indent=2))
        return 0

    reason_codes = evaluate_kill_switches(metrics)
    if reason_codes:
        new_mode = demote_one_rung(current_mode)
    else:
        new_mode = current_mode

    result = {
        "formula_id": "MODEL_GOVERNANCE_KILL_SWITCH_V1",
        "gate": "KILL_SWITCH_TRIGGERED" if reason_codes else "PASS",
        "execution_mode": new_mode,
        "execution_mode_changed": new_mode != current_mode,
        "kill_switch_triggered": bool(reason_codes),
        "kill_switch_reason_codes": reason_codes,
        "source_paths": [str(Path(args.metrics)), str(Path(args.decision_packet))],
    }
    out = Path(args.out)
    out.write_text(json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8")
    print(json.dumps(result, ensure_ascii=False, indent=2))
    return 0


if __name__ == "__main__":
    raise SystemExit(main())