crucible / engine /insider.py
s-ttp's picture
Open items: break-even solved on the adopted margin (floor never cuts); recalibrated thesis gate; benign co-citation; no triggers on price multiples; nominated peers only; benchmark applicability; merged guidance rows; engine-EPS basis; market composite noun; insider transaction counts; filer names; quarter limitation; story revenue/share precision
d092871 verified
Raw History Blame Contribute Delete
10.3 kB
"""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")