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

docs(01-01): complete Tradier data layer plan 

- Add 01-01-SUMMARY.md with execution results
- Update STATE.md with plan progress (1/2), decisions, metrics
- Update ROADMAP.md with phase 01 plan progress
- Mark DATA-01 through DATA-05 requirements complete

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Filipe Salvio 2026-03-29 20:30:48 -03:00
parent f3970448ef
commit 212c8497f2
4 changed files with 198 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

64
.planning/REQUIREMENTS.md
View File

@ -9,14 +9,14 @@ 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)
- [x] **DATA-01**: System can retrieve full options chain (strikes, expirations, bid/ask, volume, OI) via Tradier API
- [x] **DATA-02**: System can retrieve options expirations and available strikes for any ticker via Tradier API
- [x] **DATA-03**: System displays 1st-order Greeks (Delta, Gamma, Theta, Vega, Rho) from ORATS via Tradier
- [x] **DATA-04**: System displays implied volatility per contract (bid_iv, mid_iv, ask_iv, smv_vol)
- [x] **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
- [ ] **DATA-07**: System can retrieve real-time streaming Greeks and quotes via Tastytrade DXLink WebSocket
- [ ] **DATA-08**: System integrates Tradier and Tastytrade as new vendors in the existing data routing layer
### Volatility Analysis
@ -24,9 +24,9 @@ Requirements for initial release. Each maps to roadmap phases.
- [ ] **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
- [ ] **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 target; **when any leg reaches 21 DTE**, begin **mandatory management**—**close or roll every leg** of the position (exceptions only when explicitly allowed in config); 50% profit target; 2x credit stop-loss (numeric thresholds validated per **CONFIG-01**)
- [ ] **VOL-07**: System calculates Volatility Risk Premium (VRP) by comparing IV to historical/realized volatility (independent of the 21 DTE management timing in **VOL-06**)
### Dealer Positioning & Flow
@ -56,7 +56,7 @@ Requirements for initial release. Each maps to roadmap phases.
- [ ] **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-09**: All options agents follow existing create_*() factory pattern and write to shared AgentState; factories expose hooks for **OBS-01** decision/audit logging and **VAL-01** pre-invocation validation of tool inputs
- [ ] **AGENT-10**: Composite Options Score (0-5) computed from IV rank, GEX regime, flow signals, and vol skew
### Integration
@ -67,6 +67,14 @@ Requirements for initial release. Each maps to roadmap phases.
- [ ] **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
### Reliability & Observability
- [ ] **REL-01**: Graceful handling of external API failures: bounded retries where appropriate, clear user-facing errors (no silent empty success)
- [ ] **REL-02**: Rate limiting, exponential backoff, and quota awareness for all external APIs used by **DATA-01**–**DATA-08** (and shared HTTP clients)
- [ ] **VAL-01**: Validate external payloads (schema/range checks) before downstream processing for **DATA-01**–**DATA-08** and **AGENT-01**–**AGENT-06** tool inputs
- [ ] **OBS-01**: Structured agent decision logging / audit trail for **AGENT-02**, **AGENT-05**, **AGENT-08**, and rationale tied to **STRAT-06**
- [ ] **CONFIG-01**: **VOL-05** / **VOL-06** numeric thresholds (IVR bands, DTE targets, profit/stop multiples) are configuration-driven, validated at startup, and documented
## v2 Requirements
Deferred to future release. Tracked but not in current roadmap.
@ -83,32 +91,36 @@ Deferred to future release. Tracked but not in current roadmap.
- **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
## Out of Scope (v1)
Explicitly excluded. Documented to prevent scope creep.
Permanent exclusions for v1 — not planned for the initial options module release.
| 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 |
## Deferred to v2
Tracked as **v2** requirements (**EDATA-*** / **ADV-***) — not in the current v1 roadmap, but **not** permanently excluded.
| v2 ID | Topic | Note |
|-------|--------|------|
| EDATA-01 / EDATA-02 / EDATA-03 | Historical IV storage, 0DTE, multi-ticker batch | See v2 **Enhanced Data** section |
| ADV-01 / ADV-02 / ADV-03 | Portfolio Greeks aggregation, custom vol models, options backtesting | See v2 **Advanced Analytics** section |
## Traceability
Which phases cover which requirements. Updated during roadmap creation.
| Requirement | Phase | Status |
|-------------|-------|--------|
| DATA-01 | Phase 1 | Pending |
| DATA-02 | Phase 1 | Pending |
| DATA-03 | Phase 1 | Pending |
| DATA-04 | Phase 1 | Pending |
| DATA-05 | Phase 1 | Pending |
| DATA-01 | Phase 1 | Complete |
| DATA-02 | Phase 1 | Complete |
| DATA-03 | Phase 1 | Complete |
| DATA-04 | Phase 1 | Complete |
| DATA-05 | Phase 1 | Complete |
| DATA-06 | Phase 2 | Pending |
| DATA-07 | Phase 10 | Pending |
| DATA-08 | Phase 1 | Pending |
@ -148,9 +160,9 @@ Which phases cover which requirements. Updated during roadmap creation.
| INT-05 | Phase 2 | Pending |
**Coverage:**
- v1 requirements: 42 total
- Mapped to phases: 42
- Unmapped: 0
- v1 checklist items: 42 core + 5 reliability/observability (**REL-01**–**REL-02**, **VAL-01**, **OBS-01**, **CONFIG-01**); phase mapping for the five to be assigned during Phase 8/9 planning
- Mapped to phases: 42 (core)
- Unmapped: REL/VAL/OBS/CONFIG (pending phase assignment)
---
*Requirements defined: 2026-03-29*

44
.planning/ROADMAP.md
View File

@ -2,13 +2,28 @@
## Overview
This roadmap delivers a parallel options analysis team for TradingAgents, building from data foundation through computation modules, agent wrappers, and full pipeline integration. The build order follows a strict dependency chain: raw data first (Tradier), then deterministic math modules (Greeks, GEX, volatility, strategies), then LLM agent wrappers that interpret pre-computed signals, then debate/synthesis and pipeline integration. Tastyworks streaming is a final enhancement after the batch pipeline proves correct.
This roadmap delivers a parallel options analysis team for TradingAgents, building from data foundation through computation modules, agent wrappers, and full pipeline integration. The build order follows a strict dependency chain: raw data first (Tradier), then deterministic math modules (Greeks, GEX, volatility, strategies), then LLM agent wrappers that interpret pre-computed signals, then debate/synthesis and pipeline integration. **Tastytrade** streaming (Phase 10) is a final enhancement after the batch pipeline proves correct.
**Canonical requirement IDs** are defined in [.planning/REQUIREMENTS.md](REQUIREMENTS.md). Each phase’s **Requirements:** line lists those IDs; resolve definitions there.
### Requirement ID quick reference
| ID | Meaning |
|----|---------|
| DATA-01–08 | Options data retrieval, Greeks, routing, streaming |
| VOL-01–07 | IV metrics, Tastytrade rules, VRP |
| GEX-01–04 | Gamma exposure and regime |
| FLOW-01–02 | Unusual activity / flow |
| STRAT-01–06 | Strategy construction and reasoning |
| AGENT-01–10 | Options agents, debate, scoring |
| INT-01–05 | Pipeline, CLI, validation, pure math module |
| REL-01–02, VAL-01, OBS-01, CONFIG-01 | Reliability, validation, audit logging, configurable thresholds (see REQUIREMENTS.md) |
## Phases
**Phase Numbering:**
- Integer phases (1, 2, 3): Planned milestone work
- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
- Integer phases (1, 2, 3, …): Planned milestone work
- Decimal phases (2.1, 2.2): **Reserved for future urgent insertions** (marked INSERTED when used). They document ad-hoc work between integers and **do not imply missing integer phases**.
Decimal phases appear between their surrounding integers in numeric order.
@ -18,10 +33,10 @@ Decimal phases appear between their surrounding integers in numeric order.
- [ ] **Phase 4: GEX & Market Microstructure** - Gamma exposure, dealer positioning, walls, flow detection
- [ ] **Phase 5: Volatility Surface** - SVI parametric fitting across strikes and expirations
- [ ] **Phase 6: Strategy Construction** - Multi-leg strategy building, P/L profiles, PoP estimation
- [ ] **Phase 7: TastyTrade Rules Engine** - IVR-based strategy selection and position management rules
- [ ] **Phase 7: Tastytrade Rules Engine** - IVR-based strategy selection and position management rules
- [ ] **Phase 8: Options Agent Team** - LLM agent factories for all options analyst roles
- [ ] **Phase 9: Debate, Scoring & Pipeline Integration** - Options debate, portfolio manager, composite score, LangGraph integration, CLI
- [ ] **Phase 10: Tastyworks Streaming** - Real-time Greeks and quotes via DXLink WebSocket
- [ ] **Phase 10: Tastytrade Streaming** - Real-time Greeks and quotes via DXLink WebSocket
## Phase Details
@ -37,7 +52,7 @@ Decimal phases appear between their surrounding integers in numeric order.
5. Tradier is registered as a new vendor in the existing data routing layer following the established provider pattern
**Plans:** 2 plans
Plans:
- [ ] 01-01-PLAN.md -- Tradier common module and vendor module with typed dataclasses and chain retrieval
- [x] 01-01-PLAN.md -- Tradier common module and vendor module with typed dataclasses and chain retrieval
- [ ] 01-02-PLAN.md -- Vendor routing integration, @tool functions, and comprehensive unit tests
### Phase 2: Deterministic Math Core
@ -95,8 +110,8 @@ Plans:
5. System calculates max profit, max loss, breakeven points, and Probability of Profit for each strategy using deterministic math
**Plans**: TBD
### Phase 7: TastyTrade Rules Engine
**Goal**: System applies proven TastyTrade methodology rules to guide strategy selection and position management timing
### Phase 7: Tastytrade Rules Engine
**Goal**: System applies proven Tastytrade methodology rules to guide strategy selection and position management timing
**Depends on**: Phase 3, Phase 6
**Requirements**: VOL-05, VOL-06
**Success Criteria** (what must be TRUE):
@ -133,12 +148,12 @@ Plans:
**Plans**: TBD
**UI hint**: yes
### Phase 10: Tastyworks Streaming
**Goal**: System can receive real-time streaming Greeks and quotes via Tastyworks for sub-minute data freshness
### Phase 10: Tastytrade Streaming
**Goal**: System can receive real-time streaming Greeks and quotes via Tastytrade for sub-minute data freshness
**Depends on**: Phase 1, Phase 9
**Requirements**: DATA-07
**Success Criteria** (what must be TRUE):
1. System connects to Tastyworks DXLink WebSocket and receives real-time streaming Greeks and quotes
1. System connects to Tastytrade DXLink WebSocket and receives real-time streaming Greeks and quotes
2. Streaming data integrates into the existing vendor routing layer as an alternative to Tradier's hourly ORATS refresh
3. System gracefully falls back to Tradier REST data when WebSocket connection is unavailable
**Plans**: TBD
@ -147,7 +162,8 @@ Plans:
**Execution Order:**
Phases execute in numeric order: 1 -> 2 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8 -> 9 -> 10
Note: Phases 2, 3, and 4 can execute in parallel after Phase 1. Phase 6 depends on Phases 2+3. Phase 7 depends on Phases 3+6. Phase 8 depends on all computation phases (2-7).
**Parallelization:** After **Phase 1** completes, **Phases 2, 3, and 4** may run in parallel (each depends only on Phase 1). **Phase 5** is **not** in that parallel group: it **must follow Phase 3** (and Phase 1) because volatility-surface work depends on volatility metrics from Phase 3. Do not schedule Phase 5 concurrently with Phase 3. Phase 6 depends on Phases 2+3. Phase 7 depends on Phases 3+6. Phase 8 depends on all computation phases (2–7).
| Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------|
@ -157,7 +173,7 @@ Note: Phases 2, 3, and 4 can execute in parallel after Phase 1. Phase 6 depends
| 4. GEX & Market Microstructure | 0/TBD | Not started | - |
| 5. Volatility Surface | 0/TBD | Not started | - |
| 6. Strategy Construction | 0/TBD | Not started | - |
| 7. TastyTrade Rules Engine | 0/TBD | Not started | - |
| 7. Tastytrade Rules Engine | 0/TBD | Not started | - |
| 8. Options Agent Team | 0/TBD | Not started | - |
| 9. Debate, Scoring & Pipeline Integration | 0/TBD | Not started | - |
| 10. Tastyworks Streaming | 0/TBD | Not started | - |
| 10. Tastytrade Streaming | 0/TBD | Not started | - |

35
.planning/STATE.md
View File

@ -2,15 +2,15 @@
gsd_state_version: 1.0
milestone: v1.0
milestone_name: milestone
status: planning
stopped_at: Phase 1 context gathered
last_updated: "2026-03-29T22:43:31.694Z"
last_activity: 2026-03-29 -- Roadmap created with 10 phases covering 42 requirements
status: executing
stopped_at: Completed 01-01-PLAN.md
last_updated: "2026-03-29T23:30:35.534Z"
last_activity: 2026-03-29
progress:
total_phases: 10
completed_phases: 0
total_plans: 0
completed_plans: 0
total_plans: 2
completed_plans: 1
percent: 0
---
@ -21,14 +21,14 @@ progress:
See: .planning/PROJECT.md (updated 2026-03-29)
**Core value:** Agents produce actionable multi-leg options recommendations with transparent, educational reasoning
**Current focus:** Phase 1: Tradier Data Layer
**Current focus:** Phase 01 — Tradier Data Layer
## Current Position
Phase: 1 of 10 (Tradier Data Layer)
Plan: 0 of TBD in current phase
Status: Ready to plan
Last activity: 2026-03-29 -- Roadmap created with 10 phases covering 42 requirements
Phase: 01 (Tradier Data Layer) — EXECUTING
Plan: 2 of 2
Status: Ready to execute
Last activity: 2026-03-29
Progress: [░░░░░░░░░░] 0%
@ -52,6 +52,7 @@ Progress: [░░░░░░░░░░] 0%
- Trend: -
*Updated after each plan completion*
| Phase 01 P01 | 3min | 2 tasks | 2 files |
## Accumulated Context
@ -63,7 +64,9 @@ Recent decisions affecting current work:
- [Roadmap]: Phases 2, 3, 4 can run in parallel after Phase 1 (all depend only on Tradier data layer)
- [Roadmap]: SVI volatility surface isolated in its own phase (Phase 5) due to highest implementation risk
- [Roadmap]: All deterministic math in Phase 2 as standalone module before any agents consume it (critical pitfall mitigation)
- [Roadmap]: Tastyworks streaming deferred to Phase 10 as enhancement; batch pipeline uses Tradier REST throughout
- [Roadmap]: Tastytrade streaming deferred to Phase 10 as enhancement; batch pipeline uses Tradier REST throughout
- [Phase 01]: Session cache stores OptionsChain objects keyed by symbol:min_dte:max_dte
- [Phase 01]: Dual return pattern: string for LLM tools, dataclass for computation modules
### Pending Todos
@ -72,11 +75,11 @@ None yet.
### Blockers/Concerns
- Historical IV data endpoint for IV Rank (52-week history) needs validation during Phase 1/3 planning
- Python version bump to >=3.11 required for tastytrade SDK (Phase 10)
- **Python >=3.11** is the project baseline (see `pyproject.toml` and `.planning/PROJECT.md`); required for the community **tastytrade** SDK used in Phase 10 — use a single venv (e.g. `uv venv --python 3.13`) for the whole repo; no separate “Phase 10 only” interpreter is required if the environment already meets >=3.11
- Tradier sandbox vs production Greeks fidelity unknown until Phase 1 implementation
## Session Continuity
Last session: 2026-03-29T22:43:31.686Z
Stopped at: Phase 1 context gathered
Resume file: .planning/phases/01-tradier-data-layer/01-CONTEXT.md
Last session: 2026-03-29T23:30:35.523Z
Stopped at: Completed 01-01-PLAN.md
Resume file: None

111
.planning/phases/01-tradier-data-layer/01-01-SUMMARY.md Normal file
View File

@ -0,0 +1,111 @@
---
phase: 01-tradier-data-layer
plan: 01
subsystem: dataflows
tags: [tradier, options, greeks, iv, dataclass, rest-api, rate-limit]
# Dependency graph
requires: []
provides:
- "TradierRateLimitError exception for vendor fallback integration"
- "OptionsContract dataclass with 21 fields (Greeks, IV, market data)"
- "OptionsChain dataclass with to_dataframe() and filter_by_dte()"
- "get_options_expirations() with DTE filtering"
- "get_options_chain() string return for LLM tools"
- "get_options_chain_structured() typed return for programmatic use"
- "Tradier auth (TRADIER_API_KEY) and sandbox toggle (TRADIER_SANDBOX)"
- "Rate limit detection via X-Ratelimit-Available header and HTTP 429"
- "Exponential backoff retry via make_tradier_request_with_retry()"
affects: [01-02, 02-greeks-math, 03-volatility, 04-gex, options-agents]
# Tech tracking
tech-stack:
added: [requests]
patterns: [vendor-common-module, typed-dataclass-contracts, session-cache]
key-files:
created:
- tradingagents/dataflows/tradier_common.py
- tradingagents/dataflows/tradier.py
modified: []
key-decisions:
- "Session cache keyed by symbol:min_dte:max_dte stores OptionsChain objects (not strings)"
- "Cache stores OptionsChain dataclass; string serialization happens at retrieval time"
- "Pitfall 2 and 5 normalization inline rather than in a shared helper"
patterns-established:
- "Tradier vendor common: auth + HTTP + rate limit mirrors alpha_vantage_common.py pattern"
- "OptionsContract/OptionsChain as canonical typed structures for all options data"
- "Dual return pattern: string for LLM tools, dataclass for computation modules"
requirements-completed: [DATA-01, DATA-02, DATA-03, DATA-04, DATA-05]
# Metrics
duration: 3min
completed: 2026-03-29
---
# Phase 01 Plan 01: Tradier Data Layer Summary
**Tradier vendor module with typed OptionsContract/OptionsChain dataclasses, ORATS Greeks, IV fields, DTE filtering, session cache, and rate limit handling**
## Performance
- **Duration:** 3 min
- **Started:** 2026-03-29T23:27:00Z
- **Completed:** 2026-03-29T23:30:00Z
- **Tasks:** 2
- **Files modified:** 2
## Accomplishments
- Created tradier_common.py with auth, sandbox toggle, HTTP helper, and rate limit detection (header + HTTP 429)
- Created tradier.py with OptionsContract (21 fields) and OptionsChain (to_dataframe, filter_by_dte) dataclasses
- Implemented full options chain retrieval with DTE filtering, session caching, and Tradier API pitfall normalization
## Task Commits
Each task was committed atomically:
1. **Task 1: Create Tradier common module** - `246c2b7` (feat)
2. **Task 2: Create Tradier vendor module with typed dataclasses** - `f397044` (feat)
## Files Created/Modified
- `tradingagents/dataflows/tradier_common.py` - Auth, base URL, rate limit error, HTTP helper with retry
- `tradingagents/dataflows/tradier.py` - Typed dataclasses and options chain retrieval with Greeks and IV
## Decisions Made
- Session cache stores OptionsChain objects keyed by `symbol:min_dte:max_dte`; string serialization deferred to retrieval time for flexibility
- Pitfall normalizations (single-item string/dict responses) handled inline in each function rather than a shared utility
- Followed existing alpha_vantage_common.py pattern exactly for consistency
## Deviations from Plan
None - plan executed exactly as written.
## Issues Encountered
None
## User Setup Required
None - no external service configuration required. Users will need `TRADIER_API_KEY` env var set when actually calling the API, but that is documented in the module docstrings and will be wired in Plan 02.
## Known Stubs
None - all functions are fully implemented with real API integration.
## Next Phase Readiness
- OptionsContract and OptionsChain dataclasses ready for consumption by Plan 02 (vendor routing integration)
- TradierRateLimitError ready for vendor fallback in interface.py
- Structured return (get_options_chain_structured) ready for downstream computation modules (Greeks math, GEX, volatility)
## Self-Check: PASSED
- FOUND: tradingagents/dataflows/tradier_common.py
- FOUND: tradingagents/dataflows/tradier.py
- FOUND: commit 246c2b7
- FOUND: commit f397044
---
*Phase: 01-tradier-data-layer*
*Completed: 2026-03-29*