Kanchi Dividend Sop

interface:
  display_name: "Kanchi Dividend Sop"
  short_description: "Help with Kanchi Dividend Sop tasks"

#!/usr/bin/env python3
"""Build Kanchi Step 5 entry signals using live FMP data."""

from __future__ import annotations

import argparse
import csv
import json
import os
import sys
import time
from datetime import date, datetime, timezone
from pathlib import Path
from typing import Any

import requests
from dividend_basis import analyze_dividends, step1_decision
from event_scanner import ScanResult, apply_event_cap
from payout_safety import assess_payout_safety
from thresholds import SCHEMA_VERSION, VERDICTS
from verdict import build_run_context, synthesize_verdict

# FMP /stable (the legacy /api/v3 paths now return 403 "Legacy Endpoint" for
# keys issued after 2025-08-31). Endpoints are query-style (?symbol=...) and
# comma-batched quote/profile requests silently return [], so they are fetched
# one symbol per request below.
FMP_BASE_URL = "https://financialmodelingprep.com/stable"


def parse_ticker_csv(raw: str) -> list[str]:
    tickers: list[str] = []
    for part in raw.split(","):
        value = part.strip().upper()
        if not value:
            continue
        if value not in tickers:
            tickers.append(value)
    return tickers


def load_tickers(input_path: Path | None, tickers_csv: str | None) -> list[str]:
    if tickers_csv:
        return parse_ticker_csv(tickers_csv)

    if not input_path:
        return []

    payload = json.loads(input_path.read_text())
    tickers: list[str] = []

    raw_candidates = payload.get("candidates")
    if isinstance(raw_candidates, list):
        for item in raw_candidates:
            if isinstance(item, dict):
                ticker = str(item.get("ticker", "")).strip().upper()
                if ticker and ticker not in tickers:
                    tickers.append(ticker)
            else:
                ticker = str(item).strip().upper()
                if ticker and ticker not in tickers:
                    tickers.append(ticker)

    raw_tickers = payload.get("tickers")
    if isinstance(raw_tickers, list):
        for item in raw_tickers:
            ticker = str(item).strip().upper()
            if ticker and ticker not in tickers:
                tickers.append(ticker)

    return tickers


def to_float(value: Any) -> float | None:
    if value is None:
        return None
    if isinstance(value, bool):
        return None
    try:
        return float(value)
    except (TypeError, ValueError):
        return None


def normalize_metrics_yields(metrics: list[dict[str, Any]], max_points: int = 5) -> list[float]:
    yields_pct: list[float] = []
    for item in metrics:
        raw = to_float(item.get("dividendYield"))
        if raw is None or raw <= 0:
            continue
        # FMP usually returns decimal (0.035). Guard for percent-style values.
        normalized = raw * 100 if raw <= 1.5 else raw
        yields_pct.append(normalized)
        if len(yields_pct) >= max_points:
            break
    return yields_pct


def average(values: list[float]) -> float | None:
    if not values:
        return None
    return sum(values) / len(values)


class FMPClient:
    def __init__(self, api_key: str, sleep_seconds: float = 0.15, timeout: int = 30):
        self.api_key = api_key
        self.sleep_seconds = sleep_seconds
        self.timeout = timeout
        self.session = requests.Session()
        self.api_calls = 0

    def _get(self, endpoint: str, params: dict[str, Any] | None = None) -> Any | None:
        # The API key is sent via header (not query string) so it never appears
        # in a URL — including any URL embedded in a raised exception message.
        query = dict(params or {})
        url = f"{FMP_BASE_URL}/{endpoint}"
        headers = {"apikey": self.api_key}
        attempts = 0

        while attempts < 2:
            attempts += 1
            try:
                response = self.session.get(
                    url, params=query, headers=headers, timeout=self.timeout
                )
                self.api_calls += 1
            except requests.RequestException as exc:
                print(f"WARNING: Request error for {endpoint}: {exc}", file=sys.stderr)
                return None

            if response.status_code == 200:
                if self.sleep_seconds > 0:
                    time.sleep(self.sleep_seconds)
                return response.json()

            if response.status_code == 429 and attempts < 2:
                time.sleep(2.0)
                continue

            print(
                f"WARNING: FMP request failed ({response.status_code}) for {endpoint}",
                file=sys.stderr,
            )
            return None

        return None

    def get_batch_quotes(self, tickers: list[str]) -> dict[str, dict[str, Any]]:
        """Fetch quotes for all tickers (one /stable quote request per symbol).

        Comma-batched /stable quote requests silently return [], so each symbol
        is requested individually.
        """
        result: dict[str, dict[str, Any]] = {}
        for ticker in tickers:
            data = self._get("quote", {"symbol": ticker})
            if not isinstance(data, list) or not data:
                continue
            row = data[0]
            if not isinstance(row, dict):
                continue
            symbol = str(row.get("symbol", "")).strip().upper()
            if symbol:
                result[symbol] = row
        return result

    def get_batch_profiles(self, tickers: list[str]) -> dict[str, dict[str, Any]]:
        """Fetch profiles for all tickers (one /stable profile request per symbol).

        /stable renamed the trailing dividend field lastDiv -> lastDividend; a
        lastDiv alias is restored so downstream consumers are unchanged.
        """
        result: dict[str, dict[str, Any]] = {}
        for ticker in tickers:
            data = self._get("profile", {"symbol": ticker})
            if not isinstance(data, list) or not data:
                continue
            row = data[0]
            if not isinstance(row, dict):
                continue
            if "lastDiv" not in row and "lastDividend" in row:
                row["lastDiv"] = row["lastDividend"]
            symbol = str(row.get("symbol", "")).strip().upper()
            if symbol:
                result[symbol] = row
        return result

    def get_ratios(self, ticker: str, limit: int = 10) -> list[dict[str, Any]]:
        """Annual financial ratios (the 5y dividend-yield history series).

        On /stable, dividendYield and dividendPerShare moved off key-metrics
        onto the ratios endpoint (dividendYield is a decimal, e.g. 0.0404).
        """
        data = self._get("ratios", {"symbol": ticker, "limit": limit})
        if isinstance(data, list):
            return [row for row in data if isinstance(row, dict)]
        return []

    def get_stock_dividend(self, ticker: str) -> list[dict[str, Any]]:
        """WS-1: full declared-dividend history (regular + special).

        /stable dividends returns a flat list (the legacy
        historical-price-full/stock_dividend {symbol, historical:[]} wrapper is
        gone). Records still carry date / dividend / declarationDate.
        """
        data = self._get("dividends", {"symbol": ticker})
        if isinstance(data, list):
            return [row for row in data if isinstance(row, dict)]
        return []

    def get_financials(self, ticker: str, sector: str | None = None) -> dict[str, Any]:
        """WS-2 (5th-review F1): minimal financials for the payout triad.

        Adjusted EPS is NOT in FMP -> source UNAVAILABLE by design (the
        consumer path then fail-safes to HOLD-REVIEW; sector paths use
        sector metrics). Sector metric dicts are left None when FMP does
        not expose them, which deterministically raises *_unavailable
        blockers (CAUTION) for manual fill rather than a false PASS.
        """
        inc = self._get("income-statement", {"symbol": ticker, "limit": 1})
        cf = self._get("cash-flow-statement", {"symbol": ticker, "limit": 1})
        gaap_eps = None
        if isinstance(inc, list) and inc:
            # /stable renamed epsdiluted -> epsDiluted; keep both as fallbacks.
            gaap_eps = (
                to_float(inc[0].get("epsDiluted"))
                or to_float(inc[0].get("epsdiluted"))
                or to_float(inc[0].get("eps"))
            )
        fcf_ps = None
        if isinstance(cf, list) and cf:
            fcf = to_float(cf[0].get("freeCashFlow"))
            shares = (
                to_float(inc[0].get("weightedAverageShsOutDil"))
                if (isinstance(inc, list) and inc)
                else None
            )
            if fcf is not None and shares:
                fcf_ps = fcf / shares
        return {
            "sector": sector,
            "gaap_eps": gaap_eps,
            "adjusted_eps": None,
            "adjusted_eps_source": "UNAVAILABLE",
            "fcf_per_share": fcf_ps,
        }


def build_entry_row(
    ticker: str,
    alpha_pp: float,
    quote: dict[str, Any] | None,
    profile: dict[str, Any] | None,
    key_metrics: list[dict[str, Any]],
    dividend_history: list[dict[str, Any]] | None = None,
    floor_pct: float | None = None,
    financials: dict[str, Any] | None = None,
    event_scan: ScanResult | None = None,
    as_of: str | None = None,
) -> dict[str, Any]:
    price = to_float((quote or {}).get("price"))

    # WS-1: prefer the regular run-rate from declared-dividend history over
    # profile.lastDiv (which is a trailing/TTM figure that lagged the latest
    # declared raise -> defect D5 -- and silently bundled specials -> D4).
    basis = None
    if dividend_history:
        basis = analyze_dividends(
            dividend_history,
            price,
            issuer_language=(profile or {}).get("issuer_language"),
            floor_pct=floor_pct,
            as_of_date=as_of,
        )

    annual_dividend = to_float((profile or {}).get("lastDiv"))
    if annual_dividend is None and key_metrics:
        annual_dividend = to_float(key_metrics[0].get("dividendPerShare"))
    if basis is not None and basis.latest_declared_annualized is not None:
        annual_dividend = basis.latest_declared_annualized

    yields_5y = normalize_metrics_yields(key_metrics, max_points=5)
    avg_yield_5y_pct_raw = average(yields_5y)
    avg_yield_5y_pct = round(avg_yield_5y_pct_raw, 2) if avg_yield_5y_pct_raw is not None else None

    target_yield_pct = (
        round(avg_yield_5y_pct + alpha_pp, 2) if avg_yield_5y_pct is not None else None
    )
    buy_target_price = None
    if annual_dividend is not None and target_yield_pct is not None and target_yield_pct > 0:
        buy_target_price = round(annual_dividend / (target_yield_pct / 100), 2)

    current_yield_pct = None
    if annual_dividend is not None and price is not None and price > 0:
        current_yield_pct = round((annual_dividend / price) * 100, 2)

    drop_needed_pct = None
    if price is not None and buy_target_price is not None and price > 0:
        drop_needed_pct = round(max(0.0, (price - buy_target_price) / price * 100), 2)

    signal = "ASSUMPTION-REQUIRED"
    if price is not None and buy_target_price is not None:
        signal = "TRIGGERED" if price <= buy_target_price else "WAIT"

    notes: list[str] = []
    if quote is None:
        notes.append("quote_missing")
    if profile is None:
        notes.append("profile_missing")
    if annual_dividend is None:
        notes.append("annual_dividend_missing")
    if avg_yield_5y_pct is None:
        notes.append("avg_5y_yield_missing")
    elif len(yields_5y) < 5:
        notes.append(f"avg_5y_yield_points={len(yields_5y)}")

    row: dict[str, Any] = {
        "ticker": ticker,
        "signal": signal,
        "price": round(price, 2) if price is not None else None,
        "annual_dividend_per_share": round(annual_dividend, 4)
        if annual_dividend is not None
        else None,
        "current_yield_pct": current_yield_pct,
        "avg_5y_yield_pct": avg_yield_5y_pct,
        "alpha_pp": round(alpha_pp, 2),
        "target_yield_pct": target_yield_pct,
        "buy_target_price": buy_target_price,
        "drop_needed_pct": drop_needed_pct,
        "yield_observation_count": len(yields_5y),
        "notes": notes,
    }

    # WS-1: attach the dividend-basis breakdown + Step-1 decision.
    if basis is not None:
        row["dividend_basis"] = {
            "status": basis.status,
            "cadence": basis.cadence,
            "latest_declared_annualized": basis.latest_declared_annualized,
            "regular_annual_dividend": basis.regular_annual_dividend,
            "ttm_dividend_incl_special": basis.ttm_dividend_incl_special,
            "regular_forward_yield_pct": basis.regular_forward_yield_pct,
            "ttm_yield_pct": basis.ttm_yield_pct,
            "special_dividend_flag": basis.special_dividend_flag,
            "variable_policy_flag": basis.variable_policy_flag,
            "cut_flag": basis.cut_flag,
            "freeze_flag": basis.freeze_flag,
            "suspension_flag": basis.suspension_flag,
            "last_increase_date": basis.last_increase_date,
            "dividend_dates_used": basis.dividend_dates_used,
            "floor_borderline": basis.floor_borderline,
            "reasons": basis.reasons,
        }
        if floor_pct is not None:
            verdict, reason = step1_decision(
                basis, floor_pct, source_confirmed=basis.latest_declared_confirmed
            )
            row["step1_verdict"] = verdict
            row["step1_reason"] = reason
        for flag in (
            "special_dividend_flag",
            "variable_policy_flag",
            "cut_flag",
            "freeze_flag",
            "suspension_flag",
        ):
            if getattr(basis, flag):
                notes.append(flag)
        if basis.floor_borderline:
            notes.append("floor_borderline")

    pre_order_blockers: list[str] = []
    if basis is not None:
        # freeze_flag is intentionally NOT a blocker here: its disposition
        # (CONDITIONAL-PASS vs HOLD-REVIEW) is decided by synthesize_verdict
        # from step1_verdict + safety. cut/variable/suspension already force
        # step1 FAIL; listing them keeps the audit trail explicit.
        for flag in ("variable_policy_flag", "cut_flag", "suspension_flag"):
            if getattr(basis, flag):
                pre_order_blockers.append(flag)
        if basis.floor_borderline:
            pre_order_blockers.append("dividend_source_stale")

    # WS-3 FIRST (6th-review High2/High3): a missing scan is SKIPPED, never
    # silently clean; the pessimistic cap must run on every row, and a
    # completed merger must reach WS-2 *before* payout safety is assessed.
    if event_scan is None:
        event_scan = ScanResult(ticker=ticker, result="SKIPPED", scanned_at=as_of)
    triggered = str(signal) == "TRIGGERED"
    cap = apply_event_cap(event_scan, step5_triggered=triggered)
    row["event_scan"] = {
        "result": event_scan.result,
        "pending_mna": event_scan.pending_mna,
        "completed_mna_within_4q": event_scan.completed_mna_within_4q,
        "sources": event_scan.sources,
        "scanned_at": event_scan.scanned_at,
        "reasons": event_scan.reasons,
    }
    if cap["verdict_cap"]:
        row["verdict_cap"] = cap["verdict_cap"]
    row["t1_blocked"] = cap["t1_blocked"]
    # Event-scan T1/order-gate blockers are kept on the row for the order
    # gate, but excluded from the verdict-affecting set (their verdict
    # impact is already represented via verdict_cap + event_t1_blocked).
    event_order_blockers = list(cap["blockers"])
    for r in cap["reasons"]:
        notes.append(r)
    if event_scan.completed_mna_within_4q:
        notes.append("completed_merger_within_4q")

    # WS-2: sector-aware payout-safety triad. completed_merger_within_4q now
    # flows from the event scan (High3) so FITB/Comerica GAAP distortion is
    # caught from the real path, not only when financials carries the flag.
    if financials is not None:
        safety = assess_payout_safety(
            sector=financials.get("sector") or (profile or {}).get("sector"),
            annual_dividend=annual_dividend,
            gaap_eps=financials.get("gaap_eps"),
            adjusted_eps=financials.get("adjusted_eps"),
            adjusted_eps_source=financials.get("adjusted_eps_source", "UNAVAILABLE"),
            fcf_per_share=financials.get("fcf_per_share"),
            completed_merger_within_4q=bool(
                financials.get("completed_merger_within_4q", False)
                or event_scan.completed_mna_within_4q
            ),
            bank_metrics=financials.get("bank_metrics"),
            utility_metrics=financials.get("utility_metrics"),
            insurer_metrics=financials.get("insurer_metrics"),
        )
        row["payout_safety"] = {
            "sector_kind": safety.sector_kind,
            "safety_verdict": safety.safety_verdict,
            "gaap_eps_payout": safety.gaap_eps_payout,
            "adjusted_eps_payout": safety.adjusted_eps_payout,
            "fcf_payout": safety.fcf_payout,
            "adjusted_eps_source": safety.adjusted_eps_source,
            "gaap_adj_divergence": safety.gaap_adj_divergence,
            "one_off_flag": safety.one_off_flag,
            "reasons": safety.reasons,
        }
        pre_order_blockers.extend(safety.blockers)
        if safety.one_off_flag:
            notes.append("gaap_one_off")

    order_blockers = sorted(set(pre_order_blockers) | set(event_order_blockers))
    if order_blockers:
        row["pre_order_blockers"] = order_blockers

    # WS-5: synthesize the actionable verdict tier. Verdict-affecting
    # blockers exclude pure event-scan order blockers (cap handles them).
    safety_v = row.get("payout_safety", {}).get("safety_verdict")
    final = synthesize_verdict(
        step1_verdict=row.get("step1_verdict"),
        safety_verdict=safety_v,
        event_verdict_cap=row.get("verdict_cap"),
        event_t1_blocked=bool(row.get("t1_blocked", False)),
        pre_order_blockers=sorted(set(pre_order_blockers)),
    )
    row["verdict"] = final.verdict
    row["t1_blocked"] = final.t1_blocked
    row["verdict_reasons"] = final.reasons
    row["provenance"] = {
        "price_source": "fmp_quote" if quote else None,
        "dividend_source": "fmp_stock_dividend" if dividend_history else "fmp_profile_lastDiv",
        "dividend_dates_used": (basis.dividend_dates_used if basis else []),
        "payout_source": (financials or {}).get("adjusted_eps_source", "UNAVAILABLE"),
        "event_scan_result": (event_scan.result if event_scan else "NOT_SCANNED"),
        "event_scan_checked_at": (event_scan.scanned_at if event_scan else None),
        # 7th-review: audit the COMPLETE unresolved-blocker set (incl.
        # event-scan order blockers), matching row["pre_order_blockers"];
        # synthesize() intentionally consumes only the verdict-affecting
        # subset, but the audit trail must not under-report the T1 gate.
        "unresolved_blockers": order_blockers,
        "evidence_refs": [],  # populated by Claude per SKILL.md source hierarchy
    }

    return row


def render_markdown(rows: list[dict[str, Any]], as_of: str, alpha_pp: float) -> str:
    counts = {"TRIGGERED": 0, "WAIT": 0, "ASSUMPTION-REQUIRED": 0}
    verdict_counts: dict[str, int] = {}
    for row in rows:
        status = str(row.get("signal", "ASSUMPTION-REQUIRED"))
        counts[status] = counts.get(status, 0) + 1
        v = row.get("verdict")
        if v:
            verdict_counts[v] = verdict_counts.get(v, 0) + 1

    verdict_lines = [f"- {v}: `{verdict_counts[v]}`" for v in VERDICTS if v in verdict_counts]

    lines = [
        "# Kanchi Entry Signals",
        "",
        f"- as_of: `{as_of}`",
        f"- alpha_pp: `{alpha_pp:.2f}`",
        f"- ticker_count: `{len(rows)}`",
        "",
        "## Verdict Summary (WS-5 actionable tier)",
        "",
        *(verdict_lines or ["- (no verdicts; run with --yield-floor)"]),
        "",
        "## Step-5 Timing Summary",
        "",
        f"- TRIGGERED: `{counts.get('TRIGGERED', 0)}`",
        f"- WAIT: `{counts.get('WAIT', 0)}`",
        f"- ASSUMPTION-REQUIRED: `{counts.get('ASSUMPTION-REQUIRED', 0)}`",
        "",
        "## Signals",
        "",
        "> Verdict/T1-Blocked are the actionable columns. `signal` is only "
        "Step-5 timing — never act on it alone (a TRIGGERED row can be "
        "HOLD-REVIEW / T1-blocked).",
        "",
        "| Ticker | Verdict | T1 Blocked | Signal | Price | Reg Yield% | "
        "TTM Yield% | Step1 | Safety | Event Scan | Pre-order Blockers |",
        "|---|---|---|---|---:|---:|---:|---|---|---|---|",
    ]

    for row in rows:
        db = row.get("dividend_basis", {})
        ps = row.get("payout_safety", {})
        ev = row.get("event_scan", {})
        blockers = ";".join(row.get("pre_order_blockers", [])) or "-"
        lines.append(
            "| {ticker} | {verdict} | {t1} | {signal} | {price} | {ry} | "
            "{ty} | {s1} | {safety} | {ev} | {blk} |".format(
                ticker=row.get("ticker", ""),
                verdict=row.get("verdict", "-"),
                t1="YES" if row.get("t1_blocked") else "no",
                signal=row.get("signal", ""),
                price=row.get("price", ""),
                ry=db.get("regular_forward_yield_pct", ""),
                ty=db.get("ttm_yield_pct", ""),
                s1=row.get("step1_verdict", "-"),
                safety=ps.get("safety_verdict", "-"),
                ev=ev.get("result", "NOT_SCANNED"),
                blk=blockers,
            )
        )

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


def write_csv(rows: list[dict[str, Any]], output_path: Path) -> None:
    # Verdict/blocker columns are first-class so a CSV-only operator sees
    # the same actionable gate as the JSON (7th-review High).
    fieldnames = [
        "ticker",
        "verdict",
        "t1_blocked",
        "signal",
        "step1_verdict",
        "payout_safety_verdict",
        "event_scan_result",
        "pre_order_blockers",
        "price",
        "annual_dividend_per_share",
        "regular_forward_yield_pct",
        "ttm_yield_pct",
        "current_yield_pct",
        "avg_5y_yield_pct",
        "alpha_pp",
        "target_yield_pct",
        "buy_target_price",
        "drop_needed_pct",
        "yield_observation_count",
        "notes",
    ]

    with output_path.open("w", newline="") as fh:
        writer = csv.DictWriter(fh, fieldnames=fieldnames, extrasaction="ignore")
        writer.writeheader()
        for row in rows:
            db = row.get("dividend_basis", {})
            ps = row.get("payout_safety", {})
            ev = row.get("event_scan", {})
            output = dict(row)
            output["notes"] = ",".join(output.get("notes", []))
            output["pre_order_blockers"] = ";".join(row.get("pre_order_blockers", []))
            output["regular_forward_yield_pct"] = db.get("regular_forward_yield_pct")
            output["ttm_yield_pct"] = db.get("ttm_yield_pct")
            output["payout_safety_verdict"] = ps.get("safety_verdict")
            output["event_scan_result"] = ev.get("result", "NOT_SCANNED")
            writer.writerow(output)


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(description="Build Kanchi Step 5 entry signals from FMP data.")
    parser.add_argument("--input", default=None, help="Path to JSON file containing tickers.")
    parser.add_argument("--tickers", default=None, help="Comma-separated ticker list.")
    parser.add_argument(
        "--alpha-pp",
        type=float,
        default=0.5,
        help="Yield alpha in percentage points (default: 0.5).",
    )
    parser.add_argument("--output-dir", default="reports", help="Directory for outputs.")
    parser.add_argument(
        "--as-of",
        default=date.today().isoformat(),
        help="As-of date (YYYY-MM-DD).",
    )
    parser.add_argument(
        "--filename-prefix",
        default="kanchi_entry_signals",
        help="Output filename prefix.",
    )
    parser.add_argument(
        "--sleep-seconds",
        type=float,
        default=0.15,
        help="Per-request wait time to reduce API throttling.",
    )
    parser.add_argument(
        "--yield-floor",
        type=float,
        default=None,
        help="Step-1 yield floor %% (e.g. 4.0 income-now, 3.0 balanced). "
        "Enables WS-1 Step-1 verdict + Data Freshness Gate.",
    )
    parser.add_argument(
        "--events-json",
        default=None,
        help="Path to a curated corporate-events JSON (WS-3 Step 4b, populated "
        "via WebSearch per SKILL.md). Absent --events-json -> SKIPPED; "
        "unknown ticker inside the events JSON -> NO_EVENT_FOUND. Both are "
        "pessimistic for TRIGGERED names (cap to HOLD-REVIEW + T1 blocked).",
    )
    parser.add_argument("--profile", default=None, help="income-now | balanced | growth-first")
    parser.add_argument("--safety-bias", default=None, help="tight | medium")
    parser.add_argument("--universe-source", default=None, help="Provenance: universe origin.")
    return parser.parse_args()


def main() -> int:
    args = parse_args()
    tickers = load_tickers(Path(args.input) if args.input else None, args.tickers)
    if not tickers:
        raise SystemExit("No tickers provided. Use --tickers or --input.")

    api_key = os.getenv("FMP_API_KEY")
    if not api_key:
        raise SystemExit("FMP_API_KEY is not set.")

    client = FMPClient(api_key=api_key, sleep_seconds=args.sleep_seconds)

    quotes = client.get_batch_quotes(tickers)
    profiles = client.get_batch_profiles(tickers)

    scanner = None
    if args.events_json:
        from event_scanner import ManualEventScanner

        scanner = ManualEventScanner(args.events_json)

    rows: list[dict[str, Any]] = []
    for ticker in tickers:
        metrics = client.get_ratios(ticker, limit=10)
        dividend_history = client.get_stock_dividend(ticker)
        event_scan = scanner.scan(ticker, args.as_of) if scanner else None
        sector = (profiles.get(ticker) or {}).get("sector")
        financials = client.get_financials(ticker, sector=sector)
        row = build_entry_row(
            ticker=ticker,
            alpha_pp=args.alpha_pp,
            quote=quotes.get(ticker),
            profile=profiles.get(ticker),
            key_metrics=metrics,
            dividend_history=dividend_history,
            floor_pct=args.yield_floor,
            financials=financials,
            event_scan=event_scan,
            as_of=args.as_of,
        )
        rows.append(row)

    output_dir = Path(args.output_dir)
    output_dir.mkdir(parents=True, exist_ok=True)

    prefix = f"{args.filename_prefix}_{args.as_of}"
    json_path = output_dir / f"{prefix}.json"
    csv_path = output_dir / f"{prefix}.csv"
    md_path = output_dir / f"{prefix}.md"

    payload = {
        "schema_version": SCHEMA_VERSION,
        "generated_at": datetime.now(timezone.utc).isoformat(),
        "as_of": args.as_of,
        "alpha_pp": args.alpha_pp,
        "yield_floor_pct": args.yield_floor,
        "run_context": build_run_context(
            profile=args.profile,
            yield_floor_pct=args.yield_floor,
            safety_bias=args.safety_bias,
            universe_source=args.universe_source,
            excluded_asset_types=None,
        ),
        "ticker_count": len(tickers),
        "api_calls": client.api_calls,
        "rows": rows,
    }
    json_path.write_text(json.dumps(payload, indent=2, ensure_ascii=False) + "\n")
    write_csv(rows, csv_path)
    md_path.write_text(render_markdown(rows, as_of=args.as_of, alpha_pp=args.alpha_pp) + "\n")

    print(f"Wrote JSON: {json_path}")
    print(f"Wrote CSV: {csv_path}")
    print(f"Wrote MD: {md_path}")
    print(f"API calls: {client.api_calls}")
    return 0


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

#!/usr/bin/env python3
"""Generate a deterministic Kanchi SOP planning markdown file."""

from __future__ import annotations

import argparse
import json
from datetime import date
from pathlib import Path
from typing import Any


def parse_ticker_csv(raw: str) -> list[str]:
    tickers: list[str] = []
    for part in raw.split(","):
        value = part.strip().upper()
        if not value:
            continue
        if value not in tickers:
            tickers.append(value)
    return tickers


def normalize_candidates(payload: dict[str, Any]) -> list[dict[str, str]]:
    raw = payload.get("candidates")
    if isinstance(raw, list):
        normalized: list[dict[str, str]] = []
        for item in raw:
            if isinstance(item, str):
                ticker = item.strip().upper()
                if ticker:
                    normalized.append({"ticker": ticker, "bucket": "unassigned"})
            elif isinstance(item, dict):
                ticker = str(item.get("ticker", "")).strip().upper()
                bucket = str(item.get("bucket", "unassigned")).strip().lower() or "unassigned"
                if ticker:
                    normalized.append({"ticker": ticker, "bucket": bucket})
        return normalized
    return []


def load_candidates(
    input_path: Path | None, tickers_csv: str | None
) -> tuple[list[dict[str, str]], str]:
    if input_path:
        payload = json.loads(input_path.read_text())
        profile = str(payload.get("profile", "balanced")).strip().lower() or "balanced"
        candidates = normalize_candidates(payload)
        if candidates:
            return candidates, profile
        fallback = payload.get("tickers", [])
        if isinstance(fallback, list):
            candidates = [
                {"ticker": str(item).strip().upper(), "bucket": "unassigned"}
                for item in fallback
                if str(item).strip()
            ]
            return candidates, profile
        return [], profile

    if tickers_csv:
        return (
            [
                {"ticker": ticker, "bucket": "unassigned"}
                for ticker in parse_ticker_csv(tickers_csv)
            ],
            "balanced",
        )

    return [], "balanced"


def render_markdown(candidates: list[dict[str, str]], as_of: str, profile: str) -> str:
    lines = [
        "# Kanchi SOP Plan",
        "",
        f"- as_of: `{as_of}`",
        f"- profile: `{profile}`",
        f"- candidate_count: `{len(candidates)}`",
        "",
        "## Candidate Universe",
        "",
        "| Ticker | Bucket | Step1 | Step2 | Step3 | Step4 | Step5 |",
        "|---|---|---|---|---|---|---|",
    ]

    for item in candidates:
        lines.append(
            "| {ticker} | {bucket} | todo | todo | todo | todo | todo |".format(
                ticker=item["ticker"],
                bucket=item["bucket"],
            )
        )

    lines.extend(
        [
            "",
            "## Pullback Entry Notes",
            "",
            "- Default split order: `40% -> 30% -> 30%`",
            "- Default yield alpha: `+0.5pp` vs 5y average yield.",
            "- Add one-line invalidation per ticker before finalizing orders.",
            "",
        ]
    )
    return "\n".join(lines)


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(description="Build Kanchi SOP plan markdown.")
    parser.add_argument("--input", help="Path to JSON input with candidates/tickers.", default=None)
    parser.add_argument("--tickers", help="Comma-separated ticker list.", default=None)
    parser.add_argument("--output-dir", default="reports", help="Output directory path.")
    parser.add_argument(
        "--as-of", default=date.today().isoformat(), help="As-of date (YYYY-MM-DD)."
    )
    parser.add_argument("--filename", default=None, help="Optional output filename.")
    return parser.parse_args()


def main() -> int:
    args = parse_args()
    input_path = Path(args.input) if args.input else None
    candidates, profile = load_candidates(input_path, args.tickers)
    if not candidates:
        raise SystemExit(
            "No candidates found. Provide --tickers or --input with candidates/tickers."
        )

    output_dir = Path(args.output_dir)
    output_dir.mkdir(parents=True, exist_ok=True)
    filename = args.filename or f"kanchi_sop_plan_{args.as_of}.md"
    output_path = output_dir / filename
    output_path.write_text(render_markdown(candidates, args.as_of, profile) + "\n")
    print(f"Wrote SOP plan: {output_path}")
    return 0


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

"""WS-1: dividend-basis engine (regular / special / variable / freeze / cut).

Pure, dependency-free, offline-testable. Replaces the old
``annual_dividend = profile.lastDiv`` shortcut in build_entry_signals.py,
which fed a trailing/TTM figure that (a) lagged the latest declared raise
(defect D5: CFR FAIL'd at 2.97% though latest declared = 3.06%) and
(b) silently included special/variable dividends (D4: ORI/CALM traps).

Detection ORDER is fixed by improvement-plan v2.1 R-1 — specials MUST be
removed before the variable-policy CoV is computed, otherwise a special
dividend (ORI) inflates the residual stream's variance and the issuer is
misclassified as a CALM-style variable payer.
"""

from __future__ import annotations

import statistics
from dataclasses import dataclass, field
from datetime import date, datetime

from thresholds import (
    DIVIDEND_EQUALITY_EPS,
    FLOOR_FRESHNESS_BAND_PP,
    FREEZE_GRACE_DAYS,
    MIN_REGULAR_PAYS,
    SPECIAL_EXTREME_MULTIPLE,
    SPECIAL_OUTLIER_MULTIPLE,
    SPECIAL_REVERT_MULTIPLE,
    VARIABLE_POLICY_COV,
)

_SPECIAL_KEYWORDS = ("special", "supplemental", "one-time", "one time", "extra")
_MAINTAIN_KEYWORDS = ("maintain", "unchanged", "same annualized", "no change", "flat")

# 4th-review point 10: a generic "% of net income" appears in ordinary bank /
# insurer payout-ratio language and must NOT alone flag a variable policy.
# Only the strong tier (an explicit variable/earnings-linked policy) flips the
# flag; the weak tier just leaves an audit note.
_STRONG_VARIABLE_KEYWORDS = (
    "variable dividend policy",
    "variable dividend",
    "one-third of net income",
    "1/3 of net income",
    "distribution based on earnings",
    "dividend equal to",
)
_WEAK_PAYOUT_KEYWORDS = (
    "target payout ratio",
    "capital return framework",
    "dividend payout ratio",
    "% of net income",
    "percent of net income",
)

_CADENCE_BY_GAP_DAYS = (
    (45, "monthly", 12),
    (135, "quarterly", 4),
    (240, "semiannual", 2),
    (450, "annual", 1),
)


def _parse_date(value: str) -> date | None:
    for fmt in ("%Y-%m-%d", "%Y/%m/%d"):
        try:
            return datetime.strptime(value, fmt).date()
        except (ValueError, TypeError):
            continue
    return None


@dataclass
class DividendBasis:
    status: str  # "OK" | "ASSUMPTION-REQUIRED" | "NO-DIVIDEND"
    reasons: list[str] = field(default_factory=list)
    cadence: str = "irregular"
    pays_per_year: int | None = None
    latest_declared_dividend: float | None = None
    latest_declared_annualized: float | None = None
    regular_annual_dividend: float | None = None
    ttm_dividend_incl_special: float | None = None
    special_dividend_flag: bool = False
    variable_policy_flag: bool = False
    cut_flag: bool = False
    freeze_flag: bool = False
    suspension_flag: bool = False
    latest_declared_confirmed: bool = False
    last_increase_date: str | None = None
    dividend_dates_used: list[str] = field(default_factory=list)
    regular_forward_yield_pct: float | None = None
    ttm_yield_pct: float | None = None
    floor_borderline: bool = False


def _infer_cadence(sorted_dates: list[date]) -> tuple[str, int | None]:
    if len(sorted_dates) < 2:
        return "irregular", None
    gaps = [
        (sorted_dates[i + 1] - sorted_dates[i]).days
        for i in range(len(sorted_dates) - 1)
        if (sorted_dates[i + 1] - sorted_dates[i]).days > 0
    ]
    if not gaps:
        return "irregular", None
    median_gap = statistics.median(gaps)
    for max_gap, name, ppy in _CADENCE_BY_GAP_DAYS:
        if median_gap <= max_gap:
            # High dispersion vs the cadence => irregular schedule.
            if len(gaps) >= 3 and statistics.pstdev(gaps) > median_gap * 0.6:
                return "irregular", ppy
            return name, ppy
    return "irregular", 1


def _is_explicit_special(label: object) -> bool:
    if not isinstance(label, str):
        return False
    low = label.lower()
    return any(k in low for k in _SPECIAL_KEYWORDS)


def _sum_window(pays: list[tuple[date, float]], end: date, start_days: int, end_days: int) -> float:
    """Sum amounts with (end - start_days) <= d < (end - end_days) days old."""
    total = 0.0
    for d, amt in pays:
        age = (end - d).days
        if end_days <= age < start_days:
            total += amt
    return total


def analyze_dividends(
    history: list[dict],
    price: float | None,
    *,
    issuer_language: str | None = None,
    floor_pct: float | None = None,
    as_of_date: str | None = None,
) -> DividendBasis:
    """Analyze a stock_dividend `historical` list into a DividendBasis.

    `history` items: {"date": "YYYY-MM-DD", "dividend": float, "label": str?}.
    """
    rows: list[tuple[date, float, object]] = []
    declared: dict[date, bool] = {}
    for item in history or []:
        d = _parse_date(str(item.get("date", "")))
        amt = item.get("dividend")
        try:
            amt = float(amt)
        except (TypeError, ValueError):
            amt = None
        if d is None or amt is None or amt <= 0:
            continue
        rows.append((d, amt, item.get("label")))
        # A non-empty declarationDate means the board formally declared
        # this dividend -> authoritative confirmation for the Data
        # Freshness Gate (5th-review #4 confirmed-source path).
        decl = item.get("declarationDate")
        declared[d] = bool(decl and str(decl).strip())

    if not rows:
        return DividendBasis(status="NO-DIVIDEND", reasons=["no_dividend_history"])

    rows.sort(key=lambda r: r[0])
    all_dates = [r[0] for r in rows]
    cadence, ppy = _infer_cadence(all_dates)

    # --- Step 2: explicit special labels/language ---
    explicit_special = {i for i, r in enumerate(rows) if _is_explicit_special(r[2])}

    # --- Step 3: amount-outliers vs the TRAILING-local median of prior
    #     regular pays (v2.1 R-1). A global median over a 10y+ history is
    #     dragged down by old small dividends, so ordinary long-term
    #     dividend growth would be misclassified as a special and
    #     latest_declared would collapse to a stale amount (D4 recurrence).
    #     Compare each pay only against its recent prior regular pays.
    outlier_special: set[int] = set()
    _TRAILING = max(ppy or 4, 8)
    for i, r in enumerate(rows):
        if i in explicit_special:
            continue
        prior_regular = [
            rows[j][1]
            for j in range(max(0, i - _TRAILING), i)
            if j not in explicit_special and j not in outlier_special
        ]
        if len(prior_regular) < MIN_REGULAR_PAYS:
            # Too little local history to call an outlier -> treat as
            # regular (conservative; avoids flagging early history).
            continue
        local_med = statistics.median(prior_regular)
        if local_med <= 0:
            continue
        if r[1] > SPECIAL_EXTREME_MULTIPLE * local_med:
            outlier_special.add(i)  # extreme isolated spike (magnitude)
        elif r[1] > SPECIAL_OUTLIER_MULTIPLE * local_med:
            # One-off only if a later pay reverts toward the local median;
            # ordinary steep growth keeps rising and is NOT a special.
            revert = any(
                rows[k][1] <= SPECIAL_REVERT_MULTIPLE * local_med
                for k in range(i + 1, min(len(rows), i + 3))
                if k not in explicit_special
            )
            if revert:
                outlier_special.add(i)

    special_idx = explicit_special | outlier_special
    special_flag = bool(special_idx)

    # --- Step 4: residual = regular stream ---
    regular = [(r[0], r[1]) for i, r in enumerate(rows) if i not in special_idx]
    all_pays = [(r[0], r[1]) for r in rows]

    reasons: list[str] = []
    if special_flag:
        reasons.append(f"special_dividends_excluded={len(special_idx)}")

    if len(regular) < MIN_REGULAR_PAYS:
        return DividendBasis(
            status="ASSUMPTION-REQUIRED",
            reasons=reasons + [f"insufficient_regular_pays={len(regular)}"],
            cadence=cadence,
            pays_per_year=ppy,
            special_dividend_flag=special_flag,
        )

    latest_date, latest_amt = regular[-1]
    latest_annualized = latest_amt * ppy if ppy else None

    asof = all_dates[-1]
    asof_reg = regular[-1][0]
    regular_ttm = _sum_window(regular, asof, 366, 0)
    incl_special_ttm = _sum_window(all_pays, asof, 366, 0)

    # --- Step 5: variable-policy on the *residual* (post-special) stream ---
    window = [a for _, a in regular[-max(ppy or 4, 8) :]]
    variable_flag = False
    if len(window) >= MIN_REGULAR_PAYS:
        mean = statistics.fmean(window)
        if mean > 0:
            cov = statistics.pstdev(window) / mean
            variable_flag = cov > VARIABLE_POLICY_COV
    if issuer_language:
        low = issuer_language.lower()
        if any(k in low for k in _STRONG_VARIABLE_KEYWORDS):
            variable_flag = True
        elif not variable_flag and any(k in low for k in _WEAK_PAYOUT_KEYWORDS):
            reasons.append("weak_payout_language_only_review_policy")

    # --- last increase date (ascending scan over regular amounts) ---
    last_increase: date | None = None
    for i in range(1, len(regular)):
        if regular[i][1] > regular[i - 1][1] + DIVIDEND_EQUALITY_EPS:
            last_increase = regular[i][0]

    # --- freeze / cut via year-over-year per-pay RATE (frequency-independent,
    #     robust to rolling-window pay-count drift; v2.1 R-2) ---
    eps = DIVIDEND_EQUALITY_EPS
    cut_flag = False
    freeze_flag = False
    cur_rate = regular[-1][1]
    prior_idx = len(regular) - 1 - ppy if ppy else -1
    prior_rate = regular[prior_idx][1] if prior_idx >= 0 else None
    lang_maintains = bool(
        issuer_language and any(k in issuer_language.lower() for k in _MAINTAIN_KEYWORDS)
    )
    if prior_rate is not None:
        if cur_rate < prior_rate - eps:
            cut_flag = True
        elif abs(cur_rate - prior_rate) <= eps:
            cadence_days = {"monthly": 30, "quarterly": 91, "semiannual": 182}.get(cadence, 365)
            days_since_increase = (asof_reg - last_increase).days if last_increase else 10_000
            time_confirms = days_since_increase > cadence_days + FREEZE_GRACE_DAYS
            if time_confirms or lang_maintains:
                freeze_flag = True
            else:
                reasons.append("flat_window_pending_next_raise")
    else:
        reasons.append("no_prior_year_rate")
        if lang_maintains:
            freeze_flag = True

    # --- suspension: an expected regular declaration is overdue (4th-review
    #     point 4). Distinct from cut (rate down) and freeze (rate held). ---
    cadence_days = {"monthly": 30, "quarterly": 91, "semiannual": 182, "annual": 365}.get(
        cadence, 365
    )
    suspension_flag = False
    ref_date = _parse_date(str(as_of_date)) if as_of_date else None
    if ref_date is not None:
        days_since_last_pay = (ref_date - asof_reg).days
        if days_since_last_pay > cadence_days + FREEZE_GRACE_DAYS:
            suspension_flag = True
            reasons.append(f"declaration_overdue_{days_since_last_pay}d")

    fwd_yield = (
        round(latest_annualized / price * 100, 2)
        if latest_annualized is not None and price and price > 0
        else None
    )
    ttm_yield = (
        round(incl_special_ttm / price * 100, 2)
        if price and price > 0 and incl_special_ttm
        else None
    )

    floor_borderline = False
    if floor_pct is not None and fwd_yield is not None:
        if abs(fwd_yield - floor_pct) <= FLOOR_FRESHNESS_BAND_PP:
            floor_borderline = True
            reasons.append(f"floor_borderline_within_{FLOOR_FRESHNESS_BAND_PP}pp")

    return DividendBasis(
        status="OK",
        reasons=reasons,
        cadence=cadence,
        pays_per_year=ppy,
        latest_declared_dividend=round(latest_amt, 4),
        latest_declared_annualized=round(latest_annualized, 4) if latest_annualized else None,
        regular_annual_dividend=round(regular_ttm, 4) if regular_ttm else None,
        ttm_dividend_incl_special=round(incl_special_ttm, 4) if incl_special_ttm else None,
        special_dividend_flag=special_flag,
        variable_policy_flag=variable_flag,
        cut_flag=cut_flag,
        freeze_flag=freeze_flag,
        suspension_flag=suspension_flag,
        latest_declared_confirmed=declared.get(regular[-1][0], False),
        last_increase_date=last_increase.isoformat() if last_increase else None,
        dividend_dates_used=[d.isoformat() for d, _ in regular[-8:]],
        regular_forward_yield_pct=fwd_yield,
        ttm_yield_pct=ttm_yield,
        floor_borderline=floor_borderline,
    )


def step1_decision(
    basis: DividendBasis,
    floor_pct: float,
    *,
    source_confirmed: bool = False,
) -> tuple[str, str]:
    """Map a DividendBasis to a Step-1 verdict per the v2 decision matrix.

    Returns (verdict, reason). Verdicts: FAIL / STEP1-RECHECK / HOLD-REVIEW /
    STEP1-PASS (caller refines STEP1-PASS into the full tier via WS-2/WS-5).
    """
    if basis.status == "NO-DIVIDEND":
        return "FAIL", "no_dividend"
    if basis.status == "ASSUMPTION-REQUIRED":
        return "STEP1-RECHECK", ";".join(basis.reasons) or "assumption_required"
    if basis.suspension_flag:
        return "FAIL", "dividend_suspension_suspected"
    if basis.variable_policy_flag:
        return "FAIL", "variable_dividend_policy"
    if basis.cut_flag:
        return "FAIL", "dividend_cut"

    fwd = basis.regular_forward_yield_pct
    if fwd is None:
        return "STEP1-RECHECK", "regular_yield_unavailable"

    if fwd < floor_pct:
        # Data Freshness Gate: near-floor + unconfirmed source -> recheck,
        # never a hard FAIL (defect D5).
        if basis.floor_borderline and not source_confirmed:
            return "STEP1-RECHECK", "floor_borderline_unconfirmed_dividend"
        return "FAIL", f"regular_yield_{fwd}_below_floor_{floor_pct}"

    # At/above floor on regular yield.
    if basis.floor_borderline and not source_confirmed:
        return "STEP1-RECHECK", "floor_borderline_confirm_latest_declared"
    if basis.freeze_flag:
        return "HOLD-REVIEW", "dividend_freeze"
    return "STEP1-PASS", "regular_yield_above_floor"

"""WS-3: forward/recent corporate-action scanner (isolated, deterministic-testable).

Critical-review CR-2: the SOP core is a *deterministic* workflow. WebSearch
is non-deterministic and unavailable in some environments, so the event
layer is ISOLATED behind a small interface:

- The pure logic here (materiality gate, classification, pessimistic cap)
  never calls the network and is fully unit-testable.
- A scanner is INJECTED. `ManualEventScanner` reads a curated JSON events
  file (populated by Claude via WebSearch following SKILL.md Step 4b, with
  the source hierarchy IR > SEC > exchange > wire > portal). CI injects a
  fixture scanner -- real WebSearch is never called in tests.

Closes D3 (MKC-Unilever mega-merger missed: Step 4 was backward-only).

4th-review points folded in:
  #5  result in {FAILED-DEGRADED, SKIPPED, NO_EVENT_FOUND} AND Step-5
      timing TRIGGERED  ->  verdict cap HOLD-REVIEW + T1 BLOCKED
      (not merely a provenance stamp).
  #7  sector-specific materiality + rolling-24m cumulative M&A.
  #11 CLEAN_CONFIRMED (primary source checked) is stronger than
      NO_EVENT_FOUND (search only); the latter is treated pessimistically.
"""

from __future__ import annotations

import json
from dataclasses import dataclass, field
from pathlib import Path
from typing import Protocol

from thresholds import (
    MNA_LEVERAGE_DELTA_EBITDA,
    MNA_SHARE_ISSUANCE_PCT,
    MNA_TX_VALUE_PCT_MCAP,
)

# event_scan_result enum (4th-review #11)
CLEAN_CONFIRMED = "CLEAN_CONFIRMED"
NO_EVENT_FOUND = "NO_EVENT_FOUND"
MAJOR_EVENT = "MAJOR_EVENT"
MINOR_EVENT_CAUTION = "MINOR_EVENT_CAUTION"
FAILED_DEGRADED = "FAILED-DEGRADED"
SKIPPED = "SKIPPED"

# Results that, on a TRIGGERED Step-5 name, must pessimistically cap.
_PESSIMISTIC_RESULTS = {FAILED_DEGRADED, SKIPPED, NO_EVENT_FOUND, MAJOR_EVENT}

# The complete valid enum. Anything else (e.g. a typo "FAILED_DEGRADED"
# instead of "FAILED-DEGRADED") is coerced to FAILED_DEGRADED — default-deny,
# never silently clean (6th-review Med1).
_VALID_RESULTS = {
    CLEAN_CONFIRMED,
    NO_EVENT_FOUND,
    MAJOR_EVENT,
    MINOR_EVENT_CAUTION,
    FAILED_DEGRADED,
    SKIPPED,
}


def _coerce_result(value: object) -> str:
    s = str(value).strip()
    return s if s in _VALID_RESULTS else FAILED_DEGRADED


_ROLLING_24M_TX_PCT_MCAP = 0.15


@dataclass
class ScanResult:
    ticker: str
    result: str
    pending_mna: bool = False
    completed_mna_within_4q: bool = False
    spinoff: bool = False
    dividend_policy_change: bool = False
    rating_action: bool = False
    sources: list[str] = field(default_factory=list)
    scanned_at: str | None = None
    reasons: list[str] = field(default_factory=list)


class EventScanner(Protocol):
    def scan(self, ticker: str, as_of: str) -> ScanResult: ...


def is_major_structural_event(deal: dict) -> tuple[bool, list[str]]:
    """Generic + sector-specific + rolling-cumulative materiality (v2.1 R-4, #7).

    `deal` keys (all optional): tx_value, market_cap, share_issuance_pct,
    leverage_delta_ebitda, control_change, listing_change, hq_change,
    structure (merger_of_equals|reverse_morris_trust|spinoff|large_asset_sale),
    policy_change (dividend|rating|leverage), sector, sector_metrics,
    rolling_24m_tx_value.
    """
    reasons: list[str] = []
    mcap = deal.get("market_cap") or 0
    tx = deal.get("tx_value") or 0

    if mcap and tx and tx / mcap > MNA_TX_VALUE_PCT_MCAP:
        reasons.append(f"tx_value_{round(tx / mcap * 100)}pct_mcap")
    if (deal.get("share_issuance_pct") or 0) > MNA_SHARE_ISSUANCE_PCT * 100:
        reasons.append("share_issuance_gt_10pct")
    if (deal.get("leverage_delta_ebitda") or 0) > MNA_LEVERAGE_DELTA_EBITDA:
        reasons.append("leverage_delta_gt_0.5x_ebitda")
    if deal.get("control_change") or deal.get("listing_change") or deal.get("hq_change"):
        reasons.append("control_or_listing_or_hq_change")
    if deal.get("structure") in (
        "merger_of_equals",
        "reverse_morris_trust",
        "spinoff",
        "large_asset_sale",
    ):
        reasons.append(f"structure_{deal['structure']}")
    if deal.get("policy_change") in ("dividend", "rating", "leverage"):
        reasons.append(f"policy_change_{deal['policy_change']}")

    # Sector-specific materiality (#7).
    sm = deal.get("sector_metrics") or {}
    sector = (deal.get("sector") or "").lower()
    if sector in ("bank", "banks", "financial", "financials", "financial services"):
        if (sm.get("acquired_assets_pct") or 0) > 10 or (sm.get("acquired_deposits_pct") or 0) > 10:
            reasons.append("bank_acquired_assets_or_deposits_gt_10pct")
        if sm.get("integration_charge_material"):
            reasons.append("bank_integration_charge_material")
    elif sector in ("utility", "utilities"):
        if (sm.get("acq_or_capex_pct_rate_base") or 0) > 10:
            reasons.append("utility_acq_capex_gt_10pct_rate_base")
        if sm.get("equity_issuance_required"):
            reasons.append("utility_equity_issuance_required")
        if sm.get("regulatory_approval_pending"):
            reasons.append("utility_regulatory_approval_pending")
    elif sector in ("insurer", "insurers", "insurance"):
        if sm.get("affects_statutory_or_reserves_or_combined_ratio"):
            reasons.append("insurer_capital_reserves_combined_ratio_impact")

    # Rolling 24-month cumulative M&A (#7).
    if mcap and (deal.get("rolling_24m_tx_value") or 0) / mcap > _ROLLING_24M_TX_PCT_MCAP:
        reasons.append("rolling_24m_tx_gt_15pct_mcap")

    return (bool(reasons), reasons)


def apply_event_cap(scan: ScanResult, *, step5_triggered: bool) -> dict:
    """Pessimistic cap (user decision + 4th-review #5).

    Returns {verdict_cap, t1_blocked, blockers, reasons}. verdict_cap is None
    when no cap applies (caller keeps the computed verdict).
    """
    blockers: list[str] = []
    reasons: list[str] = []

    # Default-deny: an unknown/typo result is coerced to FAILED-DEGRADED so
    # the pessimistic path runs instead of falling through to clean (Med1).
    result = _coerce_result(scan.result)

    if result == MAJOR_EVENT:
        blockers.append("major_structural_event")
        reasons.extend(scan.reasons or ["major_structural_event"])
        return {
            "verdict_cap": "HOLD-REVIEW",
            "t1_blocked": True,
            "blockers": blockers,
            "reasons": reasons,
        }

    if result in (FAILED_DEGRADED, SKIPPED):
        blockers.append("event_scan_failed_or_skipped")
        reasons.append(f"event_scan_{result}")
    elif result == NO_EVENT_FOUND:
        blockers.append("event_scan_primary_source_unconfirmed")
        reasons.append("no_event_found_primary_source_unchecked")
    elif result == MINOR_EVENT_CAUTION:
        return {
            "verdict_cap": None,
            "t1_blocked": False,
            "blockers": [],
            "reasons": ["minor_bolt_on_event_caution_note"],
        }
    else:  # exactly CLEAN_CONFIRMED (unknowns were coerced away above)
        return {"verdict_cap": None, "t1_blocked": False, "blockers": [], "reasons": []}

    # Weak/failed scans only HARD-cap when the name is actually entry-ready.
    if step5_triggered:
        return {
            "verdict_cap": "HOLD-REVIEW",
            "t1_blocked": True,
            "blockers": blockers,
            "reasons": reasons + ["pessimistic_cap_triggered_name"],
        }
    return {
        "verdict_cap": None,
        "t1_blocked": True,
        "blockers": blockers,
        "reasons": reasons,
    }


class ManualEventScanner:
    """Reads a curated events JSON: {ticker: {result, ...ScanResult fields}}.

    Populated by Claude per SKILL.md Step 4b (WebSearch + IR/SEC primary
    sources). Unknown tickers -> NO_EVENT_FOUND (pessimistic, not CLEAN).
    """

    def __init__(self, events_path: str | Path):
        self._events: dict = {}
        p = Path(events_path)
        if p.exists():
            data = json.loads(p.read_text())
            if isinstance(data, dict):
                self._events = data.get("events", data)

    def scan(self, ticker: str, as_of: str) -> ScanResult:
        rec = self._events.get(ticker.upper())
        if not isinstance(rec, dict):
            return ScanResult(
                ticker=ticker.upper(),
                result=NO_EVENT_FOUND,
                scanned_at=as_of,
                reasons=["ticker_not_in_events_file"],
            )
        return ScanResult(
            ticker=ticker.upper(),
            result=_coerce_result(rec.get("result", NO_EVENT_FOUND)),
            pending_mna=bool(rec.get("pending_mna", False)),
            completed_mna_within_4q=bool(rec.get("completed_mna_within_4q", False)),
            spinoff=bool(rec.get("spinoff", False)),
            dividend_policy_change=bool(rec.get("dividend_policy_change", False)),
            rating_action=bool(rec.get("rating_action", False)),
            sources=list(rec.get("sources", [])),
            scanned_at=str(rec.get("scanned_at", as_of)),
            reasons=list(rec.get("reasons", [])),
        )


class FixtureEventScanner:
    """Test/double scanner: constructed from an in-memory dict."""

    def __init__(self, events: dict[str, ScanResult]):
        self._events = events

    def scan(self, ticker: str, as_of: str) -> ScanResult:
        return self._events.get(
            ticker.upper(),
            ScanResult(ticker=ticker.upper(), result=NO_EVENT_FOUND, scanned_at=as_of),
        )

"""WS-2: sector-aware payout-safety triad (GAAP / Adjusted / FCF).

Pure, dependency-free, offline-testable. Closes defect D2 (MKC payout
understated because a single GAAP-TTM proxy was inflated by a non-cash
acquisition remeasurement gain) and the over-strict utility -FCF problem.

Key rules (improvement-plan v2.1 R-3 + 4th-review):
- FCF payout is meaningless for banks and structurally negative for
  regulated utilities -> sector dispatch, NOT one uniform triad.
- Adjusted EPS is not in FMP; `adjusted_eps_source` is recorded and
  UNAVAILABLE -> verdict capped HOLD-REVIEW (fail-safe), never silent PASS.
- A merger completed within COMPLETED_MNA_LOOKBACK_QUARTERS presumes GAAP
  EPS is distorted -> force the adjusted path or HOLD-REVIEW
  (FITB/Comerica Q1-2026 GAAP EPS $0.15 is the golden case).
- Emits machine-checkable pre_order_blocker codes for WS-6 (4th-review #6).
"""

from __future__ import annotations

from dataclasses import dataclass, field

from thresholds import (
    ADJ_EPS_PAYOUT_CAUTION,
    ADJ_EPS_PAYOUT_MAX,
    BANK_DEPOSIT_BETA_HIGH,
    FCF_PAYOUT_HIGH_RISK,
    FCF_PAYOUT_MAX,
    GAAP_ADJ_DIVERGENCE,
    INSURER_OP_EPS_PAYOUT_MAX,
    UTILITY_FFO_DEBT_MIN,
)

_CONSUMER_SECTORS = {
    "consumer",
    "consumer defensive",
    "consumer staples",
    "consumer cyclical",
    "industrials",
    "industrial",
    "communication",
    "communication services",
    "technology",
    "healthcare",
    "energy",
    "materials",
    "basic materials",
    "real estate",  # treated as consumer-style triad unless flagged a REIT upstream
}
_BANK_SECTORS = {"bank", "banks", "financial", "financials", "financial services"}
_UTILITY_SECTORS = {"utility", "utilities"}
_INSURER_SECTORS = {"insurance", "insurer", "insurers"}


def _sector_kind(sector: str | None) -> str:
    s = (sector or "").strip().lower()
    if s in _BANK_SECTORS:
        return "bank"
    if s in _UTILITY_SECTORS:
        return "utility"
    if s in _INSURER_SECTORS:
        return "insurer"
    return "consumer"


def _ratio(numerator: float | None, denominator: float | None) -> float | None:
    if numerator is None or denominator is None or denominator == 0:
        return None
    return numerator / denominator


@dataclass
class SafetyAssessment:
    sector_kind: str
    safety_verdict: str  # PASS | CAUTION | FAIL | HOLD-REVIEW
    gaap_eps_payout: float | None = None
    adjusted_eps_payout: float | None = None
    fcf_payout: float | None = None
    adjusted_eps_source: str = "UNAVAILABLE"  # FMP | MANUAL | UNAVAILABLE
    gaap_adj_divergence: float | None = None
    one_off_flag: bool = False
    reasons: list[str] = field(default_factory=list)
    blockers: list[str] = field(default_factory=list)


def assess_payout_safety(
    *,
    sector: str | None,
    annual_dividend: float | None,
    gaap_eps: float | None = None,
    adjusted_eps: float | None = None,
    adjusted_eps_source: str = "UNAVAILABLE",
    fcf_per_share: float | None = None,
    completed_merger_within_4q: bool = False,
    bank_metrics: dict | None = None,
    utility_metrics: dict | None = None,
    insurer_metrics: dict | None = None,
) -> SafetyAssessment:
    kind = _sector_kind(sector)
    reasons: list[str] = []
    blockers: list[str] = []

    gaap_payout = _ratio(annual_dividend, gaap_eps)
    adj_payout = _ratio(annual_dividend, adjusted_eps)
    fcf_payout = _ratio(annual_dividend, fcf_per_share)

    # --- GAAP vs Adjusted divergence -> one-off flag (D2) ---
    one_off = False
    divergence = None
    if gaap_eps is not None and adjusted_eps not in (None, 0):
        divergence = abs(gaap_eps - adjusted_eps) / abs(adjusted_eps)
        if divergence > GAAP_ADJ_DIVERGENCE:
            one_off = True
            reasons.append(f"gaap_adj_divergence_{round(divergence * 100)}pct")
            blockers.append("gaap_adjusted_divergence_gt_25pct")

    # --- completed-merger linkage: GAAP presumed distorted (FITB/Comerica) ---
    if completed_merger_within_4q:
        reasons.append("completed_merger_within_4q_gaap_distorted")
        if adjusted_eps is None:
            blockers.append("adjusted_eps_unavailable")
            return SafetyAssessment(
                sector_kind=kind,
                safety_verdict="HOLD-REVIEW",
                gaap_eps_payout=_round(gaap_payout),
                adjusted_eps_payout=None,
                fcf_payout=_round(fcf_payout),
                adjusted_eps_source=adjusted_eps_source,
                gaap_adj_divergence=_round(divergence, 4),
                one_off_flag=True,
                reasons=reasons + ["use_adjusted_eps_after_merger"],
                blockers=blockers,
            )
        one_off = True

    # Adjusted EPS is the safety ANCHOR only for the consumer path. For
    # banks/utilities/insurers the sector module is the anchor, so a missing
    # adjusted EPS must NOT force HOLD-REVIEW there (5th-review F2). The
    # completed-merger GAAP-distortion path above still HOLDs regardless.
    adj_missing = adjusted_eps is None or adjusted_eps_source == "UNAVAILABLE"

    if kind == "bank":
        verdict = _assess_bank(bank_metrics or {}, gaap_payout, reasons, blockers)
    elif kind == "utility":
        verdict = _assess_utility(utility_metrics or {}, gaap_payout, reasons, blockers)
    elif kind == "insurer":
        verdict = _assess_insurer(insurer_metrics or {}, gaap_payout, adj_payout, reasons, blockers)
    else:
        if adj_missing:
            blockers.append("adjusted_eps_unavailable")
            reasons.append("adjusted_eps_unavailable_failsafe_hold")
        verdict = _assess_consumer(adj_payout, fcf_payout, adjusted_eps, reasons, blockers)
        if "adjusted_eps_unavailable" in blockers and verdict in ("PASS", "CAUTION"):
            verdict = "HOLD-REVIEW"

    return SafetyAssessment(
        sector_kind=kind,
        safety_verdict=verdict,
        gaap_eps_payout=_round(gaap_payout),
        adjusted_eps_payout=_round(adj_payout),
        fcf_payout=_round(fcf_payout),
        adjusted_eps_source=adjusted_eps_source,
        gaap_adj_divergence=_round(divergence, 4),
        one_off_flag=one_off,
        reasons=reasons,
        blockers=sorted(set(blockers)),
    )


def _round(value: float | None, ndigits: int = 4) -> float | None:
    return round(value, ndigits) if value is not None else None


def _assess_consumer(adj_payout, fcf_payout, adjusted_eps, reasons, blockers) -> str:
    # Primary: adjusted-EPS payout + FCF payout.
    if fcf_payout is not None and fcf_payout > FCF_PAYOUT_HIGH_RISK:
        reasons.append("fcf_payout_above_100pct")
        return "FAIL"
    if adj_payout is not None and adj_payout > ADJ_EPS_PAYOUT_MAX:
        reasons.append("adj_eps_payout_above_85pct")
        return "FAIL"
    caution = False
    if adj_payout is not None and adj_payout > ADJ_EPS_PAYOUT_CAUTION:
        reasons.append("adj_eps_payout_caution_band")
        caution = True
    if fcf_payout is not None and fcf_payout > FCF_PAYOUT_MAX:
        reasons.append("fcf_payout_above_80pct")
        caution = True
    if adjusted_eps is None:
        return "HOLD-REVIEW"
    return "CAUTION" if caution else "PASS"


def _assess_bank(m: dict, eps_payout, reasons, blockers) -> str:
    # FCF payout is meaningless for banks; use EPS payout + credit + capital.
    npl_trend = str(m.get("npl_trend", "")).lower()
    nco_trend = str(m.get("nco_trend", "")).lower()
    cet1 = m.get("cet1")
    cre_concentration = m.get("cre_concentration")
    verdict = "PASS"
    if cet1 is None:
        blockers.append("bank_capital_unavailable")
        verdict = "CAUTION"
    if cre_concentration is None:
        blockers.append("bank_cre_concentration_unavailable")
        verdict = "CAUTION"
    if npl_trend == "deteriorating" or nco_trend == "deteriorating":
        reasons.append("bank_npl_nco_deteriorating")
        blockers.append("bank_npl_nco_deteriorating")
        verdict = "CAUTION"
    deposit_beta = m.get("deposit_beta")
    db_str = str(deposit_beta).lower()
    if (isinstance(deposit_beta, (int, float)) and deposit_beta > BANK_DEPOSIT_BETA_HIGH) or (
        db_str in ("high", "rising")
    ):
        reasons.append("bank_deposit_beta_elevated")
        if verdict == "PASS":
            verdict = "CAUTION"
    if eps_payout is not None and eps_payout > ADJ_EPS_PAYOUT_MAX:
        reasons.append("bank_eps_payout_high")
        verdict = "FAIL"
    return verdict


def _assess_utility(m: dict, eps_payout, reasons, blockers) -> str:
    # Regulated utilities run structurally negative FCF (rate-base capex);
    # judge on FFO/debt + allowed ROE + rate-case + equity issuance instead.
    ffo_debt = m.get("ffo_to_debt")
    rate_case = str(m.get("rate_case_status", "")).lower()
    equity_issuance = str(m.get("equity_issuance_risk", "")).lower()
    allowed_roe_trend = str(m.get("allowed_roe_trend", "")).lower()
    verdict = "PASS"
    if ffo_debt is None:
        blockers.append("utility_ffo_debt_unavailable")
        verdict = "CAUTION"
    elif ffo_debt < UTILITY_FFO_DEBT_MIN:
        reasons.append(f"utility_ffo_debt_below_{UTILITY_FFO_DEBT_MIN}")
        blockers.append("utility_ffo_debt_weak")
        verdict = "CAUTION"
    if allowed_roe_trend in ("falling", "adverse"):
        reasons.append("utility_allowed_roe_falling")
        if verdict == "PASS":
            verdict = "CAUTION"
    if rate_case in ("adverse", "pending_adverse"):
        reasons.append("utility_rate_case_adverse")
        blockers.append("utility_rate_case_adverse")
        verdict = "HOLD-REVIEW"
    if equity_issuance in ("high", "dilutive"):
        reasons.append("utility_equity_issuance_risk")
        if verdict == "PASS":
            verdict = "CAUTION"
    if eps_payout is not None and eps_payout > 1.0:
        reasons.append("utility_eps_payout_above_100pct")
        verdict = "FAIL"
    return verdict


def _assess_insurer(m: dict, gaap_payout, op_eps_payout, reasons, blockers) -> str:
    combined_ratio = m.get("combined_ratio")
    reserve_dev = str(m.get("reserve_development", "")).lower()
    statutory = str(m.get("statutory_capital", "")).lower()
    verdict = "PASS"
    # Operating-EPS payout is the insurer income anchor (noisy GAAP).
    op_payout = op_eps_payout if op_eps_payout is not None else gaap_payout
    if op_payout is not None and op_payout > INSURER_OP_EPS_PAYOUT_MAX:
        reasons.append("insurer_operating_eps_payout_high")
        verdict = "FAIL"
    if combined_ratio is None:
        blockers.append("insurer_combined_ratio_unavailable")
        if verdict == "PASS":
            verdict = "CAUTION"
    if reserve_dev == "adverse":
        reasons.append("insurer_reserve_development_adverse")
        blockers.append("insurer_reserve_development_adverse")
        if verdict != "FAIL":  # never de-escalate a FAIL
            verdict = "HOLD-REVIEW"
    if combined_ratio is not None and combined_ratio > 1.0:
        reasons.append("insurer_combined_ratio_above_100")
        if verdict == "PASS":
            verdict = "CAUTION"
    if statutory == "weak":
        reasons.append("insurer_statutory_capital_weak")
        if verdict != "FAIL":
            verdict = "HOLD-REVIEW"
    return verdict