V1 Build Brief — GEX/VEX Quality Map Engine
For the dev. The big block to start NOW: the engine that turns an options chain into a GEX/VEX quality map (dealer positioning per strike) and derives from it a RR ≥ 3 setup in Talon format. Codable today against a mock provider — the Unusual Whales API plugs in afterwards as a provider swap (zero rewrite). Ref.:
talon-weekly-reference.md(target format) · spec §5 / §5.1 (scoring + EMA trend) · live lab/quality-map-lab.
0. What it is (in 1 sentence)
An options chain → nodes (King/floor/ceiling) → setup (OTE / stop / VEX ladder) → RR ≥ 3 gate → §5 score → Talon per-name output. This is what Glitch produces with Talon.
1. Provider interface (the swap point)
The engine is source-agnostic. A provider returns a snapshot; MockProvider
first, UnusualWhalesProvider next (same interface, see spec §2.2).
@dataclass(frozen=True)
class StrikeRow:
strike: float
gex: float # dealer gamma exposure at the strike ($)
vex: float # vega exposure ($)
oi_call: int
oi_put: int
doi_call: int # call ΔOI (vs previous day) → real vs hedge
doi_put: int
dp_here: bool # a dark pool print at this strike's level?
@dataclass(frozen=True)
class ChainSnapshot:
ticker: str
spot: float
asof: str # ISO, the close (never look-ahead)
emas: dict[str, float] # {"ema13","ema21","ema55","ema144","ema233"} daily
strikes: list[StrikeRow]
class ChainProvider(Protocol):
def snapshot(self, ticker: str) -> ChainSnapshot: ...
MockProvider generates realistic synthetic chains (one dominant floor, 2-3 resistances,
noise). Goal: prove the pipeline end-to-end, gauntlet-able, before UW access.
2. Node detection (deterministic, pure)
Per strike: strength = |gex| (v1; recalibrate with a gex + ΔOI blend in the gauntlet).
- King node = argmax(strength) over the whole chain.
- Floor = biggest support node (positive gamma / put wall) at or below spot.
- Ceiling = biggest call wall above spot.
- Support nodes = strikes < spot with strength ≥ p70.
- VEX ladder = strikes > spot with strength ≥ p70, sorted ascending = T1, T2, T3…
Output: Nodes(king, floor, ceiling, supports[], targets[]). Pure, testable without network.
3. Setup derivation (long — mirror for short)
- Trend gate (§5.1): require
ema21 > ema55(otherwise no long). See spec §5.1 (EMA stack). - OTE / entry = the pullback zone: the price where a support node coincides with the EMA55
(otherwise EMA144).
entry = confluence(support_node, ema55). - Stop = just below the floor node:
stop = floor.strike − buffer(buffer = 1 node-width or a fraction of ATR).risk = entry − stop. - VEX ladder = the ascending
targets[]= T1/T2/T3. - RR =
(T1 − entry) / risk. - Invalidation (notification field) =
ema21 crosses below ema55or acceptance below EMA144/233.
4. The RR ≥ 3 gate (Glitch's bar)
GO si rr_to_T1 = (T1 − entry) / (entry − stop) ≥ 3.0
Binary, testable, gauntlet-able. This is the NOTIFICATION gate (stricter than the §6 gate at ≥2, which stays the absolute floor). No RR≥3 → no push.
5. Confluence = "the extra" (the cross term, NOT additive)
When the OTE coincides at the same price with several things → quality compounds:
EMA55/144 + node GEX + S/R horizontal + dark pool (dp_here) aligned
→ the darkpool×node interaction term (w 1.2, §5) fires. The MA gives the where;
Skylit stacked on top = multiplicative confirmation. A 4/4 confluence >> 4 signals added up.
6. Wiring into the §5 score (pandora/skylit/scoring.py)
The setup fills a SetupFeatures (already in place):
discount (proximity to the pullback MA) · trend (EMA stack, §5.1) · rr · node_quality
(King's share of |gex|) · fresh (1st tap) · real_node (real ΔOI>0) · flow_align (signed net
premium) · darkpool_aligned (interaction) · iv_gate · index_support · gamma_squeeze.
→ score_setup(features, GateContext(rr=...)) → GO ≥ 70 + the "why" (contributions).
7. Output = Talon per-name format (already spec'd)
TSLA · LONG · score 88/GO · RISK ON (throttle v_joint)
OTE 248 (EMA55 × King floor) · risk floor 244 · RR 3.5
VEX ladder 262 · 271 · 285 · invalidation: EMA21<EMA55 / accept <240
why : node_quality +.. · darkpool×node +.. · discount +.. · flow_align +..
8. Gauntlet checklist (BEFORE it is a "signal")
Nothing is directional until it has proven its edge (touchstone: GEX = vulnerability):
- [ ] Zero look-ahead: nodes/setup computed on the t0 snapshot only.
- [ ] Label = realized ex-post R (realized_r from real fills), not the plan's RR (§5, anti-leakage).
- [ ] RR≥3 setups beat buy&hold out-of-sample: |t| ≥ 2, with costs (2bps + SGOV),
walk-forward, purged/embargo.
- [ ] Node detection stability (no day-to-day flip-flop).
- [ ] Multiple-testing deflated if several rule variants are tested.
9. Build path (suggested order)
ChainProvider+MockProvider(synthetic chains).NodeEngine.detect(snapshot) -> Nodes(+ pure tests).SetupDeriver.long(snapshot, nodes) -> Setup | None(OTE/stop/ladder/RR + §5.1 trend gate).- Gate
rr ≥ 3→score_setup(§5) →TalonRenderer(reuseweekly_report.py). - Backtest/gauntlet on mock data then (after access) swap
UnusualWhalesProvider(spec §2.2).
Decisions still open (they do not block the build — add config flags):
notify on GO only or WATCH too · flow_align hard prerequisite or score · RISK OFF = block or size↓.