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 Download engine/insider.py from s-ttp/crucible: direct link, hf CLI and curl.
- Browser
- Download file 10.3 kB
-
https://huggingface.co/spaces/s-ttp/crucible/resolve/main/engine/insider.py
- Command line
-
hf download hf://spaces/s-ttp/crucible/engine/insider.py
-
curl -L -o insider.py https://huggingface.co/spaces/s-ttp/crucible/resolve/main/engine/insider.py
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") | |