Feature/interactive examples

[elninad]

Summary

• Adds a new interactive-examples/ directory with 47 CLI scripts demonstrating real-world, read-only use cases of the Upstox API
• Covers Instrument Search, Analytics Token, Options Analytics, Market Data (WebSocket), and more
• All scripts follow a consistent pattern: python <script>.py --token <TOKEN> with argparse, shared utils.py helpers, and terminal-formatted output
• Includes an automated test_runner.py that validates all 47 scripts against a live token
• No new SDK dependencies — scripts only require upstox-python-sdk and plotext

What's included

Category	Scripts	Highlights
Instrument Search	3	Equity, futures, options search with filters
Futures & Basis	5	Calendar spreads, cash-futures basis, roll cost, MCX crude
Options Strategies	7	Straddle, strangle, iron condor, butterfly, put-call parity
Options Analytics	11	Chain builder, max pain, OI skew, GEX, PCR, IV percentile, implied move, expiry decay
Arbitrage	3	NSE-BSE arb, ETF vs index, currency futures spread
Historical Analysis	7	Candles, moving averages, HV, 52-week range, VWAP, beta, stock correlation
Portfolio Screening	3	Sector comparison, volume ranking, OI buildup
Market Data	8	Status, holidays, timings, intraday chart, live depth (WebSocket)

Key scripts

• options_analytics/pcr_trend.py — Put-Call Ratio with per-strike breakdown + bullish/bearish signal
• options_analytics/iv_percentile.py — IV Percentile & IV Rank vs 1-year HV distribution
• options_analytics/implied_move.py — Expected move derived from ATM straddle pricing
• options_analytics/expiry_decay.py — Theta decay tracker for near-expiry premiums
• historical_analysis/vwap.py — VWAP from 1-min intraday candles with above/below signal
• historical_analysis/beta_calculator.py — Stock beta and correlation vs NIFTY 50
• historical_analysis/stock_correlation.py — Pairwise Pearson correlation matrix for 2+ stocks
• market_data/live_depth.py — Real-time 5-level market depth via WebSocket (2×2 grid)