Options positioning data (put/call, IV skew, OI) as a point-in-time data category

[dearvn]

Problem

TradingAgents simulates a trading firm, but no analyst currently sees
derivatives positioning. Real desks routinely read put/call ratios, IV skew,
unusual volume vs. open interest, and dealer gamma around catalysts like earnings.
TOOLS_CATEGORIES has no options category today (core_stock_apis,
technical_indicators, fundamental_data, news_data, macro_data, prediction_markets).

Why this isn't a one-liner: look-ahead

The obvious free source, yfinance Ticker.option_chain(), only returns the
current snapshot. Calling it for a past trade_date would leak future data
into backtests, the same class of issue fixed for FRED in 8b7ece8. So the
category needs a point-in-time contract from day one.

Proposal

1. New category options_data with get_options_positioning(ticker, curr_date),
   returning a compact text summary so the prompt stays small.
2. Keyless baseline vendor: yfinance, live-only. For historical dates it
   returns the explicit "unavailable" sentinel (via NoMarketDataError) and
   never current data.
3. Optional and off the critical path: in the prototype the tool is bound to the
   existing market analyst (smallest diff, no new graph node or CLI option).
   Happy to split it into a separate optional analyst instead (see question 1).
4. Vendors that have true point-in-time options history can plug in through
   data_vendors like any other category.

Prototype

Branch: https://github.com/dearvn/TradingAgents/tree/feat/options-data-category
(one commit on top of v0.4.2; 13 new tests; full suite 689 passed; ruff clean)

Questions

1. Would you prefer a new optional analyst, or extending the market analyst?
2. Is a live-only baseline that returns the sentinel for historical dates acceptable?

Disclosure

I build SocSwift, an options-flow data service. This proposal is vendor-neutral
and I'll implement the keyless yfinance baseline first. A SocSwift vendor, if
welcome at all, would be a separate opt-in PR behind an API key.

[dearvn]

Prototype is up: https://github.com/dearvn/TradingAgents/tree/feat/options-data-category
(single commit e720ad8 on top of v0.4.2)

• Smallest diff for now: the tool is bound to the existing market analyst
  rather than a new CLI analyst (+28 lines in existing files). Easy to split
  out if you prefer (question 1).
• A past curr_date gets a withheld notice with no network call; a test fails
  if the chain is fetched for a historical date.
• options_data is in OPTIONAL_CATEGORIES, so a Yahoo failure degrades to
  DATA_UNAVAILABLE instead of aborting the run.
• Same-day expirations are skipped (distorted IV and volume/OI), and IV is read
  only from strikes with a two-sided quote.

Sample output for SPY (live, 2026-09-11):

- Put/call volume ratio: 1.18 (puts 117,473 / calls 99,210)
- Put/call open-interest ratio: 1.72 (puts 146,422 / calls 85,030)

| Expiration | DTE | ATM IV | Skew (vol pts) | P/C volume | P/C OI |
|---|---|---|---|---|---|
| 2026-09-14 | 3 | 12.3% | +12.9 | 1.19 | 1.16 |
| 2026-09-15 | 4 | 12.8% | +11.4 | 1.48 | 3.66 |

Open-interest walls — Calls: 770, 775, 785 · Puts: 700, 760, 755

One more question: skew uses ±10% moneyness. Would you prefer a 25Δ definition?