"""Structured insider-transaction semantics. A Rule 10b5-1 plan sale is scheduled months in advance, under a plan adopted while the insider was not in possession of material non-public information. It carries no discretionary conviction and is not a governance concern. Previously the classification existed only in the narrative note: both scoring paths read a provider feed that records nothing but acquired/disposed, so a plan sale, a tax-withholding disposition and a gift all landed in the same "insider selling" bucket and drove the factor exactly as hard as a discretionary open-market sale. This module owns the classes, their signalling semantics and their factor weights, so the meaning travels with the transaction instead of being reconstructed downstream. """ from __future__ import annotations # ── transaction classes ─────────────────────────────────────────────────────────────── DISCRETIONARY_OPEN_MARKET_BUY = "DISCRETIONARY_OPEN_MARKET_BUY" DISCRETIONARY_OPEN_MARKET_SELL = "DISCRETIONARY_OPEN_MARKET_SELL" PLAN_SALE_10B5_1 = "10B5_1_PLAN_SALE" OPTION_EXERCISE = "OPTION_EXERCISE" TAX_WITHHOLDING = "TAX_WITHHOLDING" GIFT = "GIFT" AWARD = "AWARD" OTHER = "OTHER" NONE, NEUTRAL, POSITIVE, NEGATIVE = "NONE", "NEUTRAL", "POSITIVE", "NEGATIVE" # discretionary_activity_signal · governance_signal · factor_weight · direction · wording SEMANTICS = { DISCRETIONARY_OPEN_MARKET_BUY: {"discretionary_activity_signal": POSITIVE, "governance_signal": NEUTRAL, "motive_inference_allowed": False, "factor_weight": 1.0, "direction": +1, "directional": True, "phrase": "discretionary open-market purchase"}, DISCRETIONARY_OPEN_MARKET_SELL: {"discretionary_activity_signal": NEGATIVE, "governance_signal": NEUTRAL, "motive_inference_allowed": False, "factor_weight": 1.0, "direction": -1, "directional": True, "phrase": "discretionary open-market sale (context required)"}, PLAN_SALE_10B5_1: {"discretionary_activity_signal": NONE, "governance_signal": NEUTRAL, "motive_inference_allowed": False, "factor_weight": 0.1, "direction": -1, "directional": False, "phrase": "scheduled insider sale under a pre-existing Rule 10b5-1 plan"}, OPTION_EXERCISE: {"discretionary_activity_signal": NONE, "governance_signal": NEUTRAL, "motive_inference_allowed": False, "factor_weight": 0.0, "direction": 0, "directional": False, "phrase": "option exercise (not directional by itself)"}, TAX_WITHHOLDING: {"discretionary_activity_signal": NONE, "governance_signal": NEUTRAL, "motive_inference_allowed": False, "factor_weight": 0.0, "direction": 0, "directional": False, "phrase": "shares withheld to cover tax on vesting (not directional)"}, GIFT: {"discretionary_activity_signal": NONE, "governance_signal": NEUTRAL, "motive_inference_allowed": False, "factor_weight": 0.0, "direction": 0, "directional": False, "phrase": "gift"}, AWARD: {"discretionary_activity_signal": NONE, "governance_signal": NEUTRAL, "motive_inference_allowed": False, "factor_weight": 0.0, "direction": 0, "directional": False, "phrase": "equity award"}, OTHER: {"discretionary_activity_signal": NONE, "governance_signal": NEUTRAL, "motive_inference_allowed": False, "factor_weight": 0.2, "direction": 0, "directional": False, "phrase": "other reported transaction"}, } # Form 4 transaction codes → class. A sale is split by the plan flag, never by size. _CODE = {"P": DISCRETIONARY_OPEN_MARKET_BUY, "S": DISCRETIONARY_OPEN_MARKET_SELL, "M": OPTION_EXERCISE, "F": TAX_WITHHOLDING, "G": GIFT, "A": AWARD} def classify(code, plan=False, acquired_disposed=None): """One transaction → one class. The plan flag outranks the code for a sale.""" c = (code or "").strip().upper()[:1] cls = _CODE.get(c) if cls == DISCRETIONARY_OPEN_MARKET_SELL and plan: return PLAN_SALE_10B5_1 if cls: return cls ad = (acquired_disposed or "").strip().upper()[:1] if ad == "A": return DISCRETIONARY_OPEN_MARKET_BUY if ad == "D": return DISCRETIONARY_OPEN_MARKET_SELL return OTHER def semantics(cls): return dict(SEMANTICS.get(cls, SEMANTICS[OTHER])) def classify_all(transactions): """Attach a class and its semantics to each transaction. Input rows may come from Form 4 (``code``/``plan``) or from a provider feed (``acquisition_or_disposal``).""" out = [] for t in transactions or []: cls = classify(t.get("code"), bool(t.get("plan")), t.get("acquisition_or_disposal")) row = dict(t) row["transaction_class"] = cls row.update({k: v for k, v in semantics(cls).items() if k != "phrase"}) out.append(row) return out def insider_factor(transactions): """A type-weighted insider factor in [-1, +1], plus the diagnostics that explain it. Dollar values are weighted by ``factor_weight`` and only classes marked ``directional`` contribute a sign, so a scheduled plan sale can no longer push the factor as hard as a discretionary one, and tax withholding cannot push it at all. """ rows = classify_all(transactions) buy_w = sell_w = 0.0 by_class = {} for r in rows: v = abs(float(r.get("value") or 0.0)) cls = r["transaction_class"] s = semantics(cls) b = by_class.setdefault(cls, {"n": 0, "value": 0.0, "weighted_value": 0.0, "factor_weight": s["factor_weight"], "discretionary_activity_signal": s["discretionary_activity_signal"], "governance_signal": s["governance_signal"]}) b["n"] += 1 b["value"] += v wv = v * s["factor_weight"] b["weighted_value"] += wv if not s["directional"]: continue if s["direction"] > 0: buy_w += wv elif s["direction"] < 0: sell_w += wv tot = buy_w + sell_w score = ((buy_w - sell_w) / tot) if tot > 0 else None return {"score": score, "weighted_buy_value": buy_w, "weighted_sell_value": sell_w, "by_class": by_class, "n_transactions": len(rows), "basis": "dollar values weighted by transaction class; 10b5-1 plan sales ×0.1, " "option exercises / tax withholding / gifts / awards ×0.0 and non-directional"} def characterization(factor): """The sentence the report is allowed to use, derived from the classes actually present.""" bc = (factor or {}).get("by_class") or {} plan = bc.get(PLAN_SALE_10B5_1) or {} disc_s = bc.get(DISCRETIONARY_OPEN_MARKET_SELL) or {} disc_b = bc.get(DISCRETIONARY_OPEN_MARKET_BUY) or {} parts = [] if plan.get("value"): parts.append(f"${plan['value']/1e6:,.1f}M of scheduled insider sales under pre-existing Rule 10b5-1 plans " f"(no discretionary conviction signal; governance signal neutral)") if disc_s.get("value"): parts.append(f"${disc_s['value']/1e6:,.1f}M of discretionary open-market sales") if disc_b.get("value"): parts.append(f"${disc_b['value']/1e6:,.1f}M of discretionary open-market purchases") # each count is a count of TRANSACTIONS, named as such ("2 shares withheld for tax" read as two shares) for cls, one, many in ((OPTION_EXERCISE, "option exercise", "option exercises"), (TAX_WITHHOLDING, "tax-withholding transaction", "tax-withholding transactions"), (GIFT, "gift", "gifts"), (AWARD, "equity award", "equity awards")): b = bc.get(cls) or {} if b.get("n"): parts.append(f"{b['n']} {one if int(b['n']) == 1 else many} (not directional)") if not parts: return "no reportable insider transactions in the window" return "; ".join(parts) # What an insider transaction may be used to say. The Form 4 records WHAT was traded and under which # regime (open market, 10b5-1 plan, tax withholding); it never records WHY. So the activity signal is # the direction of discretionary trading only, and no transaction class permits inferring conviction, # confidence or any other motive (prose.MOTIVE_INFERENCE enforces this for every persona and the PM). MOTIVE_INFERENCE_ALLOWED = False # discretionary net trading below this share of market capitalisation is immaterial to the valuation MATERIALITY_SHARE_OF_MARKET_CAP = 0.0005 def materiality(canon, market_cap): """{discretionary_net_value, share_of_market_cap, material, threshold, basis} for the insider window.""" c = canon or {} net = float(c.get("purchase_value") or 0.0) - float(c.get("open_market_sale_value") or 0.0) share = (abs(net) / market_cap) if (market_cap and market_cap > 0) else None return {"discretionary_net_value": net, "share_of_market_cap": share, "material": bool(share is not None and share >= MATERIALITY_SHARE_OF_MARKET_CAP), "threshold": MATERIALITY_SHARE_OF_MARKET_CAP, "basis": "discretionary open-market purchases − discretionary open-market sales in the window ÷ market cap " "(scheduled 10b5-1 sales, option exercises, tax withholding, gifts and awards excluded)"} def plan_only(factor): """True when every sale in the window was scheduled under a plan.""" bc = (factor or {}).get("by_class") or {} return bool((bc.get(PLAN_SALE_10B5_1) or {}).get("value")) and not (bc.get(DISCRETIONARY_OPEN_MARKET_SELL) or {}).get("value")