charieswei
/
TradingAgents
mirror of https://github.com/TauricResearch/TradingAgents.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: define v1 requirements

This commit is contained in:
Filipe Salvio 2026-03-29 19:30:32 -03:00
parent 2990b43b57
commit a2743c9c7a
1 changed files with 157 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

157
.planning/REQUIREMENTS.md Normal file
View File

@ -0,0 +1,157 @@
# Requirements: TradingAgents Options Module
**Defined:** 2026-03-29
**Core Value:** Agents produce actionable multi-leg options recommendations with transparent, educational reasoning
## v1 Requirements
Requirements for initial release. Each maps to roadmap phases.
### Data Foundation
- [ ] **DATA-01**: System can retrieve full options chain (strikes, expirations, bid/ask, volume, OI) via Tradier API
- [ ] **DATA-02**: System can retrieve options expirations and available strikes for any ticker via Tradier API
- [ ] **DATA-03**: System displays 1st-order Greeks (Delta, Gamma, Theta, Vega, Rho) from ORATS via Tradier
- [ ] **DATA-04**: System displays implied volatility per contract (bid_iv, mid_iv, ask_iv, smv_vol)
- [ ] **DATA-05**: System can filter options chains by DTE range (e.g., 30-60 DTE for income strategies)
- [ ] **DATA-06**: System calculates 2nd-order Greeks (Charm, Vanna, Volga/Vomma) via blackscholes library
- [ ] **DATA-07**: System can retrieve real-time streaming Greeks and quotes via Tastyworks DXLink WebSocket
- [ ] **DATA-08**: System integrates Tradier and Tastyworks as new vendors in the existing data routing layer
### Volatility Analysis
- [ ] **VOL-01**: System calculates IV Rank using 52-week IV high/low for any ticker
- [ ] **VOL-02**: System calculates IV Percentile using 252-day lookback of IV readings
- [ ] **VOL-03**: System estimates Probability of Profit (PoP) for each recommended strategy
- [ ] **VOL-04**: System constructs volatility surface via SVI parametric fitting across strikes and expirations
- [ ] **VOL-05**: System implements TastyTrade rules engine: IVR-based strategy selection (IVR >= 50% = sell premium, IVR < 30% = buy premium)
- [ ] **VOL-06**: System implements TastyTrade position management rules: 45 DTE entry, 21 DTE management, 50% profit target, 2x credit stop-loss
- [ ] **VOL-07**: System calculates Volatility Risk Premium (VRP) by comparing IV to historical/realized volatility
### Dealer Positioning & Flow
- [ ] **GEX-01**: System computes Net Gamma Exposure (GEX) across all strikes from open interest data
- [ ] **GEX-02**: System identifies Call Wall and Put Wall levels (max positive/negative gamma strikes)
- [ ] **GEX-03**: System identifies Gamma Flip zone (where cumulative GEX changes sign) and Vol Trigger level
- [ ] **GEX-04**: System classifies market regime as positive gamma (mean-reverting) or negative gamma (trending)
- [ ] **FLOW-01**: System detects unusual options activity by comparing volume to historical average and open interest
- [ ] **FLOW-02**: System classifies flow direction (bullish/bearish) based on trade side, strike location, and OI changes
### Strategy & Output
- [ ] **STRAT-01**: System recommends multi-leg options strategies (verticals, iron condors, straddles, strangles, butterflies, jade lizards, diagonals, calendars)
- [ ] **STRAT-02**: System selects strategy type based on IV environment (high IV = credit strategies, low IV = debit strategies) and directional bias
- [ ] **STRAT-03**: System outputs specific contract recommendations with exact strikes, expirations, and leg quantities
- [ ] **STRAT-04**: System outputs alternative strike/expiration ranges when exact contracts are illiquid or close to thresholds
- [ ] **STRAT-05**: System calculates max profit, max loss, and breakeven points for each recommended strategy
- [ ] **STRAT-06**: System provides transparent reasoning chain showing why each strategy was selected (educational)
### Agent Pipeline
- [ ] **AGENT-01**: Volatility analysis agent evaluates IV Rank, IV Percentile, VRP, vol surface, and skew
- [ ] **AGENT-02**: Greeks analysis agent evaluates 1st and 2nd-order Greeks and their implications for position risk
- [ ] **AGENT-03**: Options flow / unusual activity agent identifies smart money signals and flow direction
- [ ] **AGENT-04**: Gamma exposure agent analyzes dealer positioning, gamma walls, regime, and structural levels
- [ ] **AGENT-05**: Strategy selection agent recommends specific multi-leg strategies based on all analysis inputs
- [ ] **AGENT-06**: Position sizing agent calculates risk/reward profiles (max P/L, breakevens, PoP) for recommended strategies
- [ ] **AGENT-07**: Options debate phase runs bull/bear debate on the options thesis with configurable rounds
- [ ] **AGENT-08**: Options portfolio manager synthesizes all analysis and debate into final recommendation with reasoning
- [ ] **AGENT-09**: All options agents follow existing create_*() factory pattern and write to shared AgentState
- [ ] **AGENT-10**: Composite Options Score (0-5) computed from IV rank, GEX regime, flow signals, and vol skew
### Integration
- [ ] **INT-01**: Options analysis team runs as parallel section in the LangGraph StateGraph alongside existing stock analysis
- [ ] **INT-02**: Options agents are configurable and optional (can be enabled/disabled like existing analysts)
- [ ] **INT-03**: CLI updated to support options analysis mode with interactive options-specific prompts
- [ ] **INT-04**: Deterministic validation layer checks strategy structural validity, risk limits, and liquidity before output
- [ ] **INT-05**: All deterministic math (Black-Scholes, GEX, 2nd-order Greeks, P/L) in pure Python module, not LLM tool calls
## v2 Requirements
Deferred to future release. Tracked but not in current roadmap.
### Enhanced Data
- **EDATA-01**: Historical IV surface storage for backtesting and regime comparison
- **EDATA-02**: 0DTE strategy analysis with sub-minute data refresh
- **EDATA-03**: Multi-ticker batch analysis for portfolio-level options scanning
### Advanced Analytics
- **ADV-01**: Portfolio-level Greeks aggregation across multiple positions
- **ADV-02**: Custom volatility models (Heston, local vol) for exotic pricing
- **ADV-03**: Options backtesting engine with historical vol surfaces and fill simulation
## Out of Scope
Explicitly excluded. Documented to prevent scope creep.
| Feature | Reason |
|---------|--------|
| Order execution / broker integration | Analysis-only mandate; regulatory complexity |
| Real-time streaming dashboard | Batch `propagate()` architecture; streaming is for data freshness only |
| 0DTE strategy support | Requires real-time infrastructure not yet in place |
| Historical IV surface database | Requires ORATS subscription or building own historical DB |
| Options backtesting engine | Separate domain requiring historical vol surfaces and fill simulation |
| Custom vol models (Heston, local vol) | Over-engineering; SVI sufficient for equity options |
| Portfolio-level Greeks aggregation | No position state in analysis-only module |
| Mobile/web UI | CLI and Python API only |
## Traceability
Which phases cover which requirements. Updated during roadmap creation.
| Requirement | Phase | Status |
|-------------|-------|--------|
| DATA-01 | TBD | Pending |
| DATA-02 | TBD | Pending |
| DATA-03 | TBD | Pending |
| DATA-04 | TBD | Pending |
| DATA-05 | TBD | Pending |
| DATA-06 | TBD | Pending |
| DATA-07 | TBD | Pending |
| DATA-08 | TBD | Pending |
| VOL-01 | TBD | Pending |
| VOL-02 | TBD | Pending |
| VOL-03 | TBD | Pending |
| VOL-04 | TBD | Pending |
| VOL-05 | TBD | Pending |
| VOL-06 | TBD | Pending |
| VOL-07 | TBD | Pending |
| GEX-01 | TBD | Pending |
| GEX-02 | TBD | Pending |
| GEX-03 | TBD | Pending |
| GEX-04 | TBD | Pending |
| FLOW-01 | TBD | Pending |
| FLOW-02 | TBD | Pending |
| STRAT-01 | TBD | Pending |
| STRAT-02 | TBD | Pending |
| STRAT-03 | TBD | Pending |
| STRAT-04 | TBD | Pending |
| STRAT-05 | TBD | Pending |
| STRAT-06 | TBD | Pending |
| AGENT-01 | TBD | Pending |
| AGENT-02 | TBD | Pending |
| AGENT-03 | TBD | Pending |
| AGENT-04 | TBD | Pending |
| AGENT-05 | TBD | Pending |
| AGENT-06 | TBD | Pending |
| AGENT-07 | TBD | Pending |
| AGENT-08 | TBD | Pending |
| AGENT-09 | TBD | Pending |
| AGENT-10 | TBD | Pending |
| INT-01 | TBD | Pending |
| INT-02 | TBD | Pending |
| INT-03 | TBD | Pending |
| INT-04 | TBD | Pending |
| INT-05 | TBD | Pending |
**Coverage:**
- v1 requirements: 42 total
- Mapped to phases: 0
- Unmapped: 42 ⚠️
---
*Requirements defined: 2026-03-29*
*Last updated: 2026-03-29 after initial definition*