quantwise 1.2.0 → 1.2.2

package/.claude/skills/options-strategy-advisor/README.md

@@ -0,0 +1,469 @@
+# Options Strategy Advisor
+
+Educational options trading tool providing theoretical pricing, strategy analysis, and risk management guidance using Black-Scholes model.
+
+## Overview
+
+Options Strategy Advisor helps traders understand and analyze options strategies without requiring expensive real-time options data. It uses theoretical pricing models (Black-Scholes) combined with free stock market data (FMP API) to simulate strategies and calculate Greeks.
+
+**Key Features:**
+- ✅ Black-Scholes pricing engine
+- ✅ All Greeks calculation (Delta, Gamma, Theta, Vega, Rho)
+- ✅ 17+ options strategies supported
+- ✅ P/L simulation and visualization
+- ✅ Earnings strategy integration
+- ✅ Historical volatility calculation
+- ✅ Risk management guidance
+
+## Why This Approach?
+
+**No expensive data subscriptions needed:**
+- Real-time options data: $99-$500/month (Polygon.io, Intrinio)
+- FMP API Free tier: $0/month (250 requests/day)
+
+**Educational focus:**
+- Learn how strategies work
+- Understand Greeks and risk metrics
+- Compare strategies side-by-side
+
+**Practical application:**
+- Theoretical prices ≈ market mid-prices
+- User can input actual IV from broker
+- Good for strategy planning and education
+
+## Supported Strategies
+
+### Income Strategies
+1. **Covered Call** - Generate income from stock holdings
+2. **Cash-Secured Put** - Get paid to buy stock
+3. **Poor Man's Covered Call** - Capital-efficient covered call
+
+### Protection Strategies
+4. **Protective Put** - Insurance for stock positions
+5. **Collar** - Limited risk/reward protection
+
+### Directional Strategies
+6. **Bull Call Spread** - Limited risk bullish play
+7. **Bull Put Spread** - Credit spread for bullish view
+8. **Bear Call Spread** - Credit spread for bearish view
+9. **Bear Put Spread** - Limited risk bearish play
+
+### Volatility Strategies
+10. **Long Straddle** - Profit from big moves
+11. **Long Strangle** - Cheaper straddle, bigger move needed
+12. **Short Straddle** - Profit from no movement (high risk)
+13. **Short Strangle** - Wider range straddle
+
+### Range-Bound Strategies
+14. **Iron Condor** - Profit from range-bound trading
+15. **Iron Butterfly** - Tight range profit
+
+### Advanced Strategies
+16. **Calendar Spread** - Time decay play
+17. **Diagonal Spread** - Directional + time decay
+
+## Installation
+
+### Prerequisites
+- Python 3.8+
+- FMP API key (free tier sufficient)
+
+### Install Dependencies
+```bash
+pip install numpy scipy requests pandas
+```
+
+### Get FMP API Key
+1. Visit https://financialmodelingprep.com/developer/docs
+2. Sign up for free account
+3. Copy API key
+4. Set environment variable:
+```bash
+export FMP_API_KEY="your_key_here"
+```
+
+## Quick Start
+
+### Test Black-Scholes Pricer
+
+```bash
+python scripts/black_scholes.py
+```
+
+**Example Output:**
+```
+BLACK-SCHOLES OPTIONS PRICER - EXAMPLE
+======================================================================
+
+Input Parameters:
+  Stock Price: $180.00
+  Strike Price: $185.00
+  Days to Expiration: 30
+  Volatility: 25.0%
+  Risk-Free Rate: 5.30%
+  Dividend Yield: 1.0%
+
+======================================================================
+CALL OPTION
+======================================================================
+Price: $2.45
+Intrinsic Value: $0.00
+Time Value: $2.45
+
+Greeks:
+  Delta: 0.3654 ($36.54 per $1 move)
+  Gamma: 0.0234 (delta changes by 0.0234)
+  Theta: -$0.18/day (loses $0.18 per day)
+  Vega: $0.25 per 1% IV (gains $0.25 if IV +1%)
+  Rho: $0.12 per 1% rate (gains $0.12 if rate +1%)
+```
+
+### Use in Your Code
+
+```python
+from scripts.black_scholes import OptionPricer
+
+# Initialize pricer
+pricer = OptionPricer(
+    S=180,          # Stock price
+    K=185,          # Strike price
+    T=30/365,       # Time to expiration (years)
+    r=0.053,        # Risk-free rate (5.3%)
+    sigma=0.25,     # Volatility (25%)
+    q=0.01          # Dividend yield (1%)
+)
+
+# Get call option price
+call_price = pricer.call_price()
+print(f"Call Price: ${call_price:.2f}")
+
+# Get all Greeks for call
+call_greeks = pricer.get_all_greeks('call')
+print(f"Delta: {call_greeks['delta']:.4f}")
+print(f"Gamma: {call_greeks['gamma']:.4f}")
+print(f"Theta: ${call_greeks['theta']:.2f}/day")
+print(f"Vega: ${call_greeks['vega']:.2f} per 1%")
+```
+
+### Calculate Historical Volatility
+
+```python
+from scripts.black_scholes import (
+    calculate_historical_volatility,
+    fetch_historical_prices_for_hv
+)
+
+# Fetch prices from FMP
+api_key = "your_key"
+prices = fetch_historical_prices_for_hv("AAPL", api_key, days=90)
+
+# Calculate 30-day HV
+hv = calculate_historical_volatility(prices, window=30)
+print(f"30-Day HV: {hv*100:.2f}%")
+```
+
+## Understanding the Metrics
+
+### Option Price Components
+
+**Intrinsic Value:**
+- Call: max(0, Stock Price - Strike Price)
+- Put: max(0, Strike Price - Stock Price)
+
+**Time Value:**
+- Option Price - Intrinsic Value
+- Decays to $0 at expiration
+
+### The Greeks
+
+**Delta (Δ)** - Directional Exposure
+```
+Range: 0 to 1 (calls), -1 to 0 (puts)
+Meaning: Change in option price per $1 stock move
+
+Example: Δ = 0.50
+→ If stock +$1, option +$0.50
+→ If stock -$1, option -$0.50
+```
+
+**Gamma (Γ)** - Delta Acceleration
+```
+Meaning: Change in delta per $1 stock move
+Peak: ATM options
+Low: Deep ITM or OTM
+
+Example: Γ = 0.05, Δ currently = 0.50
+→ If stock +$1, delta becomes 0.55
+```
+
+**Theta (Θ)** - Time Decay
+```
+Meaning: Change in option price per day
+Sign: Usually negative (options lose value over time)
+Peak: Last 30 days before expiration
+
+Example: Θ = -$0.15/day
+→ Tomorrow, option loses $0.15 if nothing else changes
+```
+
+**Vega (ν)** - Volatility Sensitivity
+```
+Meaning: Change in option price per 1% IV change
+Sign: Always positive (options gain value when vol increases)
+
+Example: ν = $0.25 per 1%
+→ If IV increases from 25% to 26%, option +$0.25
+```
+
+**Rho (ρ)** - Interest Rate Sensitivity
+```
+Meaning: Change in option price per 1% rate change
+Sign: Positive for calls, negative for puts
+Impact: Usually small unless long-dated options
+
+Example: ρ = $0.10 per 1%
+→ If interest rate increases 1%, option +$0.10
+```
+
+### Volatility: HV vs IV
+
+**Historical Volatility (HV):**
+- Calculated from past price movements
+- Objective, based on actual data
+- Available free (from price data)
+
+**Implied Volatility (IV):**
+- Derived from option market prices
+- Subjective, based on supply/demand
+- Requires real-time options data (or user input)
+
+**Comparison:**
+```
+IV > HV: Options expensive → Consider selling premium
+IV < HV: Options cheap → Consider buying options
+IV = HV: Fairly priced → Any strategy works
+```
+
+## Common Workflows
+
+### 1. Analyze a Strategy
+
+```python
+from scripts.black_scholes import OptionPricer
+
+# Stock: AAPL @ $180
+# Strategy: Bull Call Spread $180/$185 (30 DTE)
+
+# Price long call ($180 strike)
+long_call = OptionPricer(S=180, K=180, T=30/365, r=0.053, sigma=0.25)
+long_price = long_call.call_price()
+long_delta = long_call.call_delta()
+
+# Price short call ($185 strike)
+short_call = OptionPricer(S=180, K=185, T=30/365, r=0.053, sigma=0.25)
+short_price = short_call.call_price()
+short_delta = short_call.call_delta()
+
+# Strategy metrics
+net_debit = long_price - short_price
+max_profit = (185 - 180) - net_debit
+max_loss = -net_debit
+position_delta = long_delta - short_delta
+
+print(f"Bull Call Spread $180/$185")
+print(f"Net Debit: ${net_debit:.2f}")
+print(f"Max Profit: ${max_profit:.2f} (at $185+)")
+print(f"Max Loss: ${max_loss:.2f} (at $180-)")
+print(f"Position Delta: {position_delta:.4f}")
+```
+
+### 2. Compare IV to HV
+
+```python
+# Get HV
+prices = fetch_historical_prices_for_hv("AAPL", api_key, days=90)
+hv = calculate_historical_volatility(prices, window=30)
+
+# User provides IV (from broker platform)
+iv = 0.28  # 28% from ThinkorSwim
+
+print(f"Historical Volatility: {hv*100:.2f}%")
+print(f"Implied Volatility: {iv*100:.1f}%")
+
+if iv > hv * 1.1:
+    print("→ Options expensive (IV > HV) - Consider selling premium")
+elif iv < hv * 0.9:
+    print("→ Options cheap (IV < HV) - Consider buying options")
+else:
+    print("→ Fairly priced")
+```
+
+### 3. Earnings Strategy
+
+Check if earnings coming up (use Earnings Calendar skill):
+```python
+# If earnings in 7 days:
+# - IV typically elevated (30-50% higher)
+# - Consider straddle/strangle (profit from big move)
+# - Or sell iron condor (profit from IV crush)
+
+# Example: Long Straddle
+straddle_cost = call_price + put_price
+breakeven_up = stock_price + straddle_cost
+breakeven_down = stock_price - straddle_cost
+
+print(f"Straddle Cost: ${straddle_cost:.2f}")
+print(f"Breakevens: ${breakeven_down:.2f} / ${breakeven_up:.2f}")
+print(f"Need {abs(breakeven_up - stock_price)/stock_price*100:.1f}% move to profit")
+```
+
+## Limitations & Best Practices
+
+### Theoretical vs Market Prices
+
+**Black-Scholes Assumptions:**
+- European options (can't exercise early)
+- Constant volatility (changes in reality)
+- No transaction costs
+- Continuous trading
+
+**Real World Differences:**
+- American options (most stocks) can exercise early
+- Bid-ask spread: Actual cost higher than theoretical mid
+- Commissions and slippage
+- Liquidity: Wide markets on illiquid options
+
+### Best Practices
+
+**1. Use for Education & Planning:**
+- Learn how strategies work
+- Compare different approaches
+- Understand risk/reward before trading
+
+**2. Verify Before Trading:**
+- Get real quotes from your broker
+- Check bid-ask spread
+- Confirm option liquidity (open interest, volume)
+
+**3. Input Actual IV:**
+- Theoretical price assumes constant volatility
+- Use current market IV for accuracy
+- Check IV percentile (high/low relative to history)
+
+**4. Account for Dividends:**
+- Ex-dividend dates affect option prices
+- Calls lose value, puts gain value on ex-div date
+- Script supports dividend yield input
+
+**5. Monitor Greeks:**
+- Delta: Overall directional exposure
+- Theta: Daily time decay (seller advantage)
+- Vega: Volatility risk (watch during earnings)
+- Gamma: Risk of delta changing (avoid near expiration)
+
+## Integration with Other Skills
+
+**Earnings Calendar:**
+- Fetch earnings dates
+- Identify IV crush opportunities
+- Time earnings strategies
+
+**Technical Analyst:**
+- Use support/resistance for strike selection
+- Trend analysis for directional strategies
+- Breakout potential for straddle timing
+
+**US Stock Analysis:**
+- Fundamental analysis for LEAPS
+- Dividend yield for covered call/put
+- Earnings quality for earnings plays
+
+**Bubble Detector:**
+- High risk → protective puts
+- Low risk → bullish strategies
+- Critical risk → avoid long premium
+
+**Portfolio Manager:**
+- Track options with stock positions
+- Aggregate Greeks across portfolio
+- Options as hedging tool
+
+## API Usage & Costs
+
+**Free Tier Sufficient:**
+- Stock prices: 1 request per symbol
+- Historical prices (HV): 1 request per symbol
+- Dividend data: 1 request per symbol
+
+**Example Analysis Cost:**
+```
+Covered Call on AAPL:
+- Current price: 1 request
+- HV calculation: 1 request (90 days data)
+- Dividend yield: 1 request
+Total: 3 requests
+
+Daily budget: 250 requests / day
+→ Can analyze ~80 strategies per day
+```
+
+## Troubleshooting
+
+### Negative Option Price
+**Cause:** Invalid inputs (strike vs stock price)
+**Solution:** Check that inputs make sense
+
+### Greeks Seem Wrong
+**Cause:** Using wrong units (annual vs daily)
+**Solution:** Verify T is in years, theta is per day
+
+### HV Very Different from IV
+**Normal:** IV reflects future expectations, HV is past
+**Action:** Use IV from broker for more accuracy
+
+### Option Price Too High/Low
+**Cause:** Volatility input incorrect
+**Solution:** Verify sigma is annual (e.g., 0.25 for 25%)
+
+## Resources
+
+### Documentation
+- `SKILL.md` - Complete workflow and strategies
+- `references/strategies_guide.md` - All strategies explained (TBD)
+- `references/greeks_explained.md` - Greeks deep dive (TBD)
+
+### External Resources
+- Options Playbook: https://www.optionsplaybook.com/
+- CBOE Education: https://www.cboe.com/education/
+- Black-Scholes Calculator: https://www.option-price.com/
+
+### Get Real IV
+- ThinkorSwim (TD Ameritrade): Free
+- TastyTrade: Free
+- Barchart: https://www.barchart.com/options
+- CBOE: http://www.cboe.com/delayedquote/
+
+## Future Enhancements
+
+**Planned:**
+- Strategy simulation script (complete P/L analysis)
+- P/L diagram generator (ASCII art)
+- Earnings strategy advisor (integrated with Earnings Calendar)
+- Complete strategy reference guides
+
+**Contributions Welcome:**
+- Additional strategies
+- Improved volatility models
+- Better visualization tools
+
+## License
+
+Educational use. Trade at your own risk. Options involve significant risk and are not suitable for all investors.
+
+---
+
+**Version:** 1.0
+**Last Updated:** 2025-11-08
+**Dependencies:** Python 3.8+, numpy, scipy, requests
+**API:** FMP API (Free tier sufficient)
+**Model:** Black-Scholes (European options pricing)