# Premium Analyzer Configuration Guide

## Quick Start: Paste These Into Your .env

### CONSERVATIVE (Best for Careful Option Buying)
```env
# Global Control
PREMIUM_ALERT_ENABLED=true
PREMIUM_ALERT_DEBUG=false

# Z-Score Thresholds (stricter = fewer alerts)
# 2.5 sigma = ~1.2% of observations (very rare, very cheap)
PREMIUM_Z_THRESHOLD=2.5
PREMIUM_CE_Z_THRESHOLD=2.5
PREMIUM_PE_Z_THRESHOLD=2.5

# Percentile Thresholds (bottom X% of distribution)
# 10 = bottom 10% is "cheap", reject anything above 10%
PREMIUM_PERCENTILE_LOW=10.0
PREMIUM_PERCENTILE_HIGH=5.0

# OI Must Be Building (not declining)
# Z-score of OI rate of change must be > 0.5
PREMIUM_MIN_OI_Z_SCORE=0.5

# Volume Must Be Above Normal
# 0.60 = 60th percentile (better than 60% of historical volumes)
PREMIUM_MIN_VOLUME_PCT=0.60

# Data Quality
PREMIUM_MIN_SAMPLE_COUNT=50

# Time-Based Filters
PREMIUM_EXCLUDE_MARKET_OPEN=true
PREMIUM_MARKET_OPEN_EXCLUSION_MINUTES=30
PREMIUM_EXCLUDE_CLOSE=true
PREMIUM_MARKET_CLOSE_EXCLUSION_MINUTES=15

# Expiry Safety
PREMIUM_MIN_DAYS_TO_EXPIRY=2
```

### MODERATE (Balanced - More Opportunities, Still Quality)
```env
PREMIUM_ALERT_ENABLED=true
PREMIUM_ALERT_DEBUG=true

PREMIUM_Z_THRESHOLD=2.0
PREMIUM_CE_Z_THRESHOLD=2.0
PREMIUM_PE_Z_THRESHOLD=2.0

PREMIUM_PERCENTILE_LOW=15.0
PREMIUM_PERCENTILE_HIGH=10.0

PREMIUM_MIN_OI_Z_SCORE=0.3
PREMIUM_MIN_VOLUME_PCT=0.55

PREMIUM_MIN_SAMPLE_COUNT=40

PREMIUM_EXCLUDE_MARKET_OPEN=true
PREMIUM_MARKET_OPEN_EXCLUSION_MINUTES=20
PREMIUM_EXCLUDE_CLOSE=true
PREMIUM_MARKET_CLOSE_EXCLUSION_MINUTES=10

PREMIUM_MIN_DAYS_TO_EXPIRY=2
```

### AGGRESSIVE (Max Opportunities, Some False Positives)
```env
PREMIUM_ALERT_ENABLED=true
PREMIUM_ALERT_DEBUG=true

PREMIUM_Z_THRESHOLD=1.5
PREMIUM_CE_Z_THRESHOLD=1.5
PREMIUM_PE_Z_THRESHOLD=1.5

PREMIUM_PERCENTILE_LOW=20.0
PREMIUM_PERCENTILE_HIGH=15.0

PREMIUM_MIN_OI_Z_SCORE=0.1
PREMIUM_MIN_VOLUME_PCT=0.50

PREMIUM_MIN_SAMPLE_COUNT=30

PREMIUM_EXCLUDE_MARKET_OPEN=true
PREMIUM_MARKET_OPEN_EXCLUSION_MINUTES=15
PREMIUM_EXCLUDE_CLOSE=false

PREMIUM_MIN_DAYS_TO_EXPIRY=1
```

## Parameter Explanation

### 1. Z-Score Thresholds (`PREMIUM_Z_THRESHOLD`)

**What it does**: Premium is X sigma away from average
- 1.5 sigma = ~6.7% of observations (loose)
- 2.0 sigma = ~2.3% of observations (medium)
- 2.5 sigma = ~1.2% of observations (strict)
- 3.0 sigma = ~0.3% of observations (very strict)

**For Option Buying**: Use 2.5+ to avoid noise
- Lower = More alerts but more false positives
- Higher = Fewer alerts but better quality

**Recommendation**: Start with **2.5**, reduce to 2.0 if you're missing opportunities

---

### 2. Percentile Low (`PREMIUM_PERCENTILE_LOW`)

**What it does**: Premium must be in bottom X% to alert
- 5% = Only bottom 5% trigger (very selective)
- 10% = Bottom 10% (good for options)
- 15% = Bottom 15% (more opportunities)
- 20% = Bottom 20% (loose)

**For Option Buying**: Use 10-15%
- This matches typical "cheap" premium ranges
- Bottom 5% often includes gap moves (bad entry)

**Recommendation**: Start with **10%**, increase to 15% in low-vol markets

---

### 3. OI Z-Score (`PREMIUM_MIN_OI_Z_SCORE`)

**What it does**: OI must be accelerating/building (not declining)
- 0.0 = No requirement (OI can be declining)
- 0.3 = Slight acceleration required
- 0.5 = Moderate acceleration
- 1.0 = Strong acceleration

**For Option Buying**: Use 0.3-0.5
- This ensures institutional buyers are stepping in
- Rising OI on cheap premium = real opportunity
- Declining OI = avoid (no liquidity)

**Recommendation**: Start with **0.5**, reduce to 0.3 in slower markets

**Why This Matters**:
```
Cheap Premium + Rising OI = ✅ BUY (institutional support)
Cheap Premium + Flat OI = ⚠️ MAYBE (wait for momentum)
Cheap Premium + Falling OI = ❌ AVOID (trapped value)
```

---

### 4. Volume Percentile (`PREMIUM_MIN_VOLUME_PCT`)

**What it does**: Volume must be above X percentile to avoid illiquid traps
- 0.50 = Above median (50th percentile)
- 0.60 = Above 60th percentile (good liquidity)
- 0.70 = Above 70th percentile (very liquid)

**For Option Buying**: Use 0.60
- Ensures you can enter/exit without slippage
- Premium cheap due to low volume = bad entry

**Recommendation**: **0.60** for most pairs, 0.50 for very liquid (Nifty/Bank)

---

### 5. Market Open Exclusion (`PREMIUM_EXCLUDE_MARKET_OPEN`)

**What it does**: Skip alerts in first N minutes of market open
- Default: 30 minutes
- Reason: Opening volatility creates false premium extremes

**For Option Buying**: Use **30 minutes**
- 9:15-9:45 AM is chaos (Kite data catch-up, gaps, news)
- Cheap premium at 9:30 often reverses by 9:45
- Wait until 9:45+ when real opportunities emerge

**Recommendation**: Keep **30 minutes**, reduce to 20 if you want more alerts

---

### 6. Market Close Exclusion (`PREMIUM_EXCLUDE_CLOSE`)

**What it does**: Skip alerts in last N minutes before close
- Default: 15 minutes
- Reason: Late premium extremes are often trapped positions

**For Option Buying**: Use **15 minutes**
- 3:15-3:30 PM is volatile (fund/retail closing)
- Cheap premium at 3:20 might gap next day

**Recommendation**: Keep **15 minutes**, can increase to 20 in index options

---

### 7. Days to Expiry (`PREMIUM_MIN_DAYS_TO_EXPIRY`)

**What it does**: Minimum days remaining on option contract
- 1 = Allow 1-DTE (avoid gamma crush trap)
- 2 = Minimum 2 DTE (safer, more predictable)
- 3 = Minimum 3+ DTE (most stable)

**For Option Buying**: Use **2**
- 1-DTE options decay 5-10% per day (gamma trap)
- Even "cheap" 1-DTE can become expensive in hours
- 2+ DTE gives you 24+ hours to be right

**Recommendation**: Use **2**, only drop to 1 if buying intraday scalps

---

### 8. Sample Count (`PREMIUM_MIN_SAMPLE_COUNT`)

**What it does**: Minimum historical data points needed before alerting
- 30 = Use ~5 min lookback (less reliable)
- 50 = Use ~8 min lookback (good balance)
- 100 = Use ~17 min lookback (very reliable)
- 200 = Use ~33 min lookback (most stable)

**For Option Buying**: Use **50-100**
- Need enough data to compute reliable mean/std
- Too little data = false signals
- Too much data = slow to react

**Recommendation**: Start with **50**, increase to 100 if alerts are too frequent

---

## Tuning Strategy

### If You're Getting Too Many Alerts:

1. **First**: Increase `PREMIUM_Z_THRESHOLD` from 2.0 → 2.5
   - Reduces alerts by ~40%

2. **Second**: Lower `PREMIUM_PERCENTILE_LOW` from 15 → 10
   - Only alerts when really cheap

3. **Third**: Increase `PREMIUM_MIN_OI_Z_SCORE` from 0.3 → 0.5
   - Requires OI to be actively building

4. **Fourth**: Increase `PREMIUM_MIN_VOLUME_PCT` from 0.55 → 0.65
   - Requires better liquidity

### If You're Getting Too Few Alerts:

1. **First**: Decrease `PREMIUM_Z_THRESHOLD` from 2.5 → 2.0
   - Increases alerts by ~50%

2. **Second**: Increase `PREMIUM_PERCENTILE_LOW` from 10 → 15
   - Alert on broader "cheap" range

3. **Third**: Decrease `PREMIUM_MIN_OI_Z_SCORE` from 0.5 → 0.2
   - Relax OI building requirement

4. **Fourth**: Reduce `PREMIUM_EXCLUDE_MARKET_OPEN` to 20 minutes
   - Capture intraday setups sooner

---

## Monitoring & Backtesting

### Enable Debug Logging:
```env
PREMIUM_ALERT_DEBUG=true
```

This logs all rejected opportunities with reason. Monitor logs to see:
- How many are rejected for each reason
- Which thresholds are most restrictive

### Check Logs:
```bash
tail -f storage/logs/laravel.log | grep "Premium opportunity"
```

### Example Log Output:
```
Premium opportunity rejected (CE): premium_not_cheap - Percentile: 25 > 10
Premium opportunity rejected (CE): oi_not_building - OI Z-Score: 0.2 < 0.5
Premium alert created (CE): Score=78.45, Confidence=92.3%
```

---

## Side-Specific Tuning

You can override thresholds per side if CE and PE behave differently:

```env
# CE is usually more expensive, so relax slightly
PREMIUM_CE_Z_THRESHOLD=2.2
PREMIUM_CE_PERCENTILE_LOW=12.0

# PE is usually cheaper, so be stricter
PREMIUM_PE_Z_THRESHOLD=2.8
PREMIUM_PE_PERCENTILE_LOW=8.0
```

---

## Recommended Starting Configuration

Copy this and test for 1 week:

```env
PREMIUM_ALERT_ENABLED=true
PREMIUM_ALERT_DEBUG=true
PREMIUM_Z_THRESHOLD=2.5
PREMIUM_PERCENTILE_LOW=10.0
PREMIUM_MIN_OI_Z_SCORE=0.5
PREMIUM_MIN_VOLUME_PCT=0.60
PREMIUM_MIN_SAMPLE_COUNT=50
PREMIUM_EXCLUDE_MARKET_OPEN=true
PREMIUM_MARKET_OPEN_EXCLUSION_MINUTES=30
PREMIUM_EXCLUDE_CLOSE=true
PREMIUM_MARKET_CLOSE_EXCLUSION_MINUTES=15
PREMIUM_MIN_DAYS_TO_EXPIRY=2
```

**Expected Results**:
- 3-8 alerts/day per pair
- ~60-70% of alerts will be profitable
- Avg win: 8-15% return
- Avg loss: -5% to -10%