# Institutional-Grade Options Flow Analytics

This document describes the institutional-grade enhancements to the options flow pipeline.

## Overview

The pipeline has been refactored to convert static retail-style flow detection into dynamic, dealer-aware, time-sequenced signals suitable for intraday momentum and 1-5 day swing trades.

## New Analytics Modules

### 1. Relative Premium Scoring (`relative_premium_scorer.py`)

**Purpose**: Replace static premium filter (minPremium = $80K) with context-aware relative scoring.

**New Fields**:
- `premium_zscore`: Z-score of premium relative to 20-day rolling window per ticker
- `premium_percentile_intraday`: Percentile rank within same-day flow
- `relative_premium_score`: Composite score (0-100) combining z-score, intraday percentile, and median normalization

**Usage**: Premium of $80K might be significant for AAPL but noise for TSLA. This module computes relative significance.

### 2. Signal Component Scoring (`signal_component_scorer.py`)

**Purpose**: Convert binary badge logic (💎 ⭐ 🟢 🔴) into continuous numeric signal components.

**New Fields**:
- `aggression_score`: Measures trade aggression (ITM premiums, ask-side trades)
- `size_concentration_score`: Measures size concentration (single large trade vs many small ones)
- `repeat_trade_velocity`: Measures repeat trade frequency (urgency building)
- `strike_clustering_score`: Measures strike clustering (laddering patterns)
- `signal_strength`: Composite score = 0.30 * aggression + 0.30 * size_concentration + 0.20 * repeat_velocity + 0.20 * strike_clustering

**Note**: Badges remain display-only. Signal strength is computed from components.

### 3. Tier-0 Noise Rejection (`noise_rejector.py`)

**Purpose**: Reject low-quality signals before enrichment to reduce processing overhead.

**New Fields**:
- `early_noise_reject`: Boolean flag indicating if signal should be rejected as noise

**Rejection Criteria**:
- Single isolated trade (no repeat activity within 30 minutes)
- Far OTM weekly lottos (>15% OTM with <7 days to expiry)
- Delta-adjusted premium below threshold (<$50K)

### 4. Time-Sequenced Flow Analysis (`time_sequenced_analyzer.py`)

**Purpose**: Analyze flow patterns over time to detect urgency, distribution, and continuation.

**New Fields**:
- `flow_acceleration`: Change in premium per minute (Δ premium / minute)
- `time_between_hits`: Average time between consecutive trades (minutes)
- `follow_on_ratio`: Fraction of trades in same direction after initial trade (0-1)
- `strike_laddering_detected`: Boolean indicating sequential strike accumulation

**Interpretation**:
- Escalating premium + decreasing time gaps = urgency
- Flat premium + widening gaps = distribution

### 5. Intent Classification (`intent_classifier.py`)

**Purpose**: Replace naive direction (BULL/BEAR) with nuanced volatility and hedging intent.

**New Fields**:
- `delta_exposure`: Delta exposure (contracts * delta * 100 * spot_price)
- `gamma_exposure`: Gamma exposure (contracts * gamma * 100 * spot_price^2)
- `volatility_intent`: Enum (LONG_VOL, SHORT_VOL, DIRECTIONAL, HEDGE_UNWIND)

**Note**: Direction (BULL/BEAR) becomes secondary metadata.

### 6. Dealer-Aware Flow Context (`dealer_flow_context.py`)

**Purpose**: Track dealer hedging pressure and gamma exposure.

**New Fields**:
- `net_gamma_exposure_per_symbol`: Sum of gamma exposures for symbol (positive = long gamma, negative = short gamma)
- `gamma_flip_proximity`: Proximity to gamma flip point (-1 to 1)
- `dealer_hedge_pressure_score`: Dealer hedge pressure score (0-100)

**Usage**: Validates flow continuation, flow reversals, and gamma squeeze setups.

### 7. Market Regime Detection (`market_regime_detector.py`)

**Purpose**: Identify market regime to gate trade signal generation.

**New Fields**:
- `market_regime`: Enum (TREND, RANGE, HIGH_VOL_EVENT)

**Trade Signal Gating**:
- Trend → continuation bias
- Range → fade or vol-sell bias
- Event → volatility expansion bias

### 8. Flow Decay & Reversal Validation (`flow_decay_validator.py`)

**Purpose**: Validate flow decay/reversal signals with anchors.

**New Fields**:
- `flow_state`: Enum (ACTIONABLE, INFORMATIONAL)

**Validation Criteria**: Flow decay/reversal is actionable ONLY IF:
- Premium contracts (relative_premium_score >= 60)
- Dealer hedge pressure decreases
- Price fails near VWAP / opening range / key level
- Otherwise marked as INFORMATIONAL

### 9. Institutional Confidence Metrics (`institutional_confidence.py`)

**Purpose**: Calculate confidence scores for institutional flow signals.

**New Fields**:
- `confidence_score`: Overall confidence score (0-100)
- `institutional_likelihood`: Likelihood flow is institutional (0-1)
- `dealer_pain_level`: Dealer pain level (0-100)
- `expected_move_vs_implied`: Expected move vs implied move ratio

## Integration

All modules are integrated into the main processing pipeline in `main.py`:

1. Basic flow processing (normalization, badges, rocket score)
2. Price context enrichment
3. Alert matching
4. **Institutional analytics pipeline** (NEW):
   - Tier-0 noise rejection
   - Relative premium scoring
   - Signal component scoring
   - Time-sequenced analysis
   - Intent classification
   - Dealer flow context
   - Market regime detection
   - Flow decay validation
   - Confidence metrics
5. Filtering (premium, relative premium, badges, direction)
6. Output formatting

## Filtering Changes

**Before**:
- Static premium filter: `premium_num > 80000`
- Badge requirements: 🟢/🔴 + 💎 + ⭐

**After**:
- Static premium filter: `premium_num > min_premium` (still applied)
- **Relative premium filter**: `relative_premium_score >= 60.0` (NEW)
- **Noise rejection filter**: `early_noise_reject == False` (NEW)
- Badge requirements: 🟢/🔴 + 💎 + ⭐ (still applied, but badges are now display-only)

## API Response

All new fields are included in the API response. The response maintains backward compatibility - existing fields remain unchanged, new fields are additive.

## Design Philosophy

1. **Flow represents pressure, not prediction**: Signals indicate who is forced to act next (dealers hedging)
2. **Institutions trade urgency and forced hedging**: Focus on dealer pain and gamma exposure
3. **Fewer, higher-quality signals > more alerts**: Noise rejection and relative premium filtering reduce false positives
4. **Every signal must answer**: "Who is forced to act next?"

## Success Criteria

If implemented correctly:
- Signal count decreases (noise filtered out)
- Average signal quality increases (relative premium, signal strength)
- False positives reduce (noise rejection, dealer context validation)
- Trades align with intraday momentum and short-term swing horizons (time-sequenced analysis)