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)

  1. Trend gate (§5.1): require ema21 > ema55 (otherwise no long). See spec §5.1 (EMA stack).
  2. OTE / entry = the pullback zone: the price where a support node coincides with the EMA55 (otherwise EMA144). entry = confluence(support_node, ema55).
  3. Stop = just below the floor node: stop = floor.strike − buffer (buffer = 1 node-width or a fraction of ATR). risk = entry − stop.
  4. VEX ladder = the ascending targets[] = T1/T2/T3.
  5. RR = (T1 − entry) / risk.
  6. Invalidation (notification field) = ema21 crosses below ema55 or 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)

  1. ChainProvider + MockProvider (synthetic chains).
  2. NodeEngine.detect(snapshot) -> Nodes (+ pure tests).
  3. SetupDeriver.long(snapshot, nodes) -> Setup | None (OTE/stop/ladder/RR + §5.1 trend gate).
  4. Gate rr ≥ 3 → score_setup (§5) → TalonRenderer (reuse weekly_report.py).
  5. 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↓.