--- phase: 01-tradier-data-layer plan: 01 type: execute wave: 1 depends_on: [] files_modified: - tradingagents/dataflows/tradier_common.py - tradingagents/dataflows/tradier.py autonomous: true requirements: - DATA-01 - DATA-02 - DATA-03 - DATA-04 - DATA-05 must_haves: truths: - "get_options_expirations() returns a list of YYYY-MM-DD date strings filtered by DTE range" - "get_options_chain() returns an OptionsChain with OptionsContract dataclasses containing Greeks and IV" - "OptionsChain.to_dataframe() returns a pandas DataFrame with all contract fields" - "OptionsChain.filter_by_dte() returns a filtered OptionsChain within the specified DTE range" - "Tradier API auth uses TRADIER_API_KEY env var and TRADIER_SANDBOX toggles base URL" - "Rate limit detection raises TradierRateLimitError on 429 or exhausted X-Ratelimit-Available" artifacts: - path: "tradingagents/dataflows/tradier_common.py" provides: "Auth, base URL, rate limit error, HTTP helper" exports: ["get_api_key", "get_base_url", "make_tradier_request", "make_tradier_request_with_retry", "TradierRateLimitError"] - path: "tradingagents/dataflows/tradier.py" provides: "Tradier vendor module with options chain retrieval" exports: ["OptionsContract", "OptionsChain", "get_options_expirations", "get_options_chain", "get_options_chain_structured", "clear_options_cache"] key_links: - from: "tradingagents/dataflows/tradier.py" to: "tradingagents/dataflows/tradier_common.py" via: "imports make_tradier_request, TradierRateLimitError" pattern: "from .tradier_common import" --- Create the Tradier vendor module with typed data structures, API integration, and options chain retrieval with Greeks and IV. Purpose: Establish the core data retrieval layer that all downstream options analysis depends on. This is the foundation -- typed dataclasses (OptionsContract, OptionsChain) define the contract for every subsequent phase. Output: Two new files (tradier_common.py, tradier.py) providing complete options chain retrieval with 1st-order Greeks, IV, DTE filtering, session caching, and rate limit handling. @$HOME/.claude/get-shit-done/workflows/execute-plan.md @$HOME/.claude/get-shit-done/templates/summary.md @.planning/PROJECT.md @.planning/ROADMAP.md @.planning/STATE.md @.planning/phases/01-tradier-data-layer/01-CONTEXT.md @.planning/phases/01-tradier-data-layer/01-RESEARCH.md From tradingagents/dataflows/alpha_vantage_common.py: ```python class AlphaVantageRateLimitError(Exception): """Exception raised when Alpha Vantage API rate limit is exceeded.""" pass def get_api_key() -> str: api_key = os.getenv("ALPHA_VANTAGE_API_KEY") if not api_key: raise ValueError("ALPHA_VANTAGE_API_KEY environment variable is not set.") return api_key ``` From tradingagents/dataflows/config.py: ```python def get_config() -> Dict: """Get the current configuration.""" ``` Task 1: Create Tradier common module (auth, HTTP helper, rate limit error) tradingagents/dataflows/tradier_common.py - tradingagents/dataflows/alpha_vantage_common.py - tradingagents/dataflows/config.py Create `tradingagents/dataflows/tradier_common.py` with: 1. **Constants** (per D-02): - `TRADIER_PRODUCTION_URL = "https://api.tradier.com"` - `TRADIER_SANDBOX_URL = "https://sandbox.tradier.com"` 2. **TradierRateLimitError** exception class: - `class TradierRateLimitError(Exception): pass` 3. **get_api_key()** function (per D-01): - Read `os.getenv("TRADIER_API_KEY")` - If not set, raise `ValueError("TRADIER_API_KEY environment variable is not set.")` - Return the key string 4. **get_base_url()** function (per D-02): - Read `os.getenv("TRADIER_SANDBOX", "false")` - If value `.lower()` is in `("true", "1", "yes")`, return `TRADIER_SANDBOX_URL` - Otherwise return `TRADIER_PRODUCTION_URL` 5. **make_tradier_request(path: str, params: dict | None = None) -> dict** function: - Build URL: `f"{get_base_url()}{path}"` - Headers: `{"Authorization": f"Bearer {get_api_key()}", "Accept": "application/json"}` - Execute `requests.get(url, headers=headers, params=params or {})` - Read `available = response.headers.get("X-Ratelimit-Available")`. If `available is not None`, try `int(available)`. On `ValueError` or `TypeError`, raise `TradierRateLimitError` including the **raw** `X-Ratelimit-Available` value and `response.headers.get("X-Ratelimit-Expiry")`. If conversion succeeds and the integer is `<= 0`, raise `TradierRateLimitError` including `X-Ratelimit-Expiry` - Check `response.status_code == 429` -- raise `TradierRateLimitError("Tradier rate limit exceeded (HTTP 429)")` - Call `response.raise_for_status()` - Return `response.json()` 6. **make_tradier_request_with_retry(path: str, params: dict | None = None, max_retries: int = 3) -> dict** function: - Loop `for attempt in range(max_retries):` - Try `make_tradier_request(path, params)` - On `TradierRateLimitError`: if `attempt < max_retries - 1`, `time.sleep(2 ** attempt)` then continue; else re-raise - Return result on success Imports needed: `os`, `time`, `requests` uv run python -c "from tradingagents.dataflows.tradier_common import get_api_key, get_base_url, make_tradier_request, make_tradier_request_with_retry, TradierRateLimitError; print('imports OK')" - tradingagents/dataflows/tradier_common.py exists - File contains `TRADIER_PRODUCTION_URL = "https://api.tradier.com"` - File contains `TRADIER_SANDBOX_URL = "https://sandbox.tradier.com"` - File contains `class TradierRateLimitError(Exception):` - File contains `def get_api_key() -> str:` - File contains `def get_base_url() -> str:` - File contains `def make_tradier_request(path: str, params: dict | None = None) -> dict:` - File contains `def make_tradier_request_with_retry(` - File contains `os.getenv("TRADIER_API_KEY")` - File contains `os.getenv("TRADIER_SANDBOX", "false")` - File contains `X-Ratelimit-Available` - File contains `Bearer {get_api_key()}` - `uv run python -c "from tradingagents.dataflows.tradier_common import TradierRateLimitError"` exits 0 tradier_common.py exports TradierRateLimitError, get_api_key, get_base_url, make_tradier_request, make_tradier_request_with_retry. Auth reads TRADIER_API_KEY env var, sandbox detection reads TRADIER_SANDBOX env var, rate limit detection checks both headers and HTTP 429. Task 2: Create Tradier vendor module with typed dataclasses and chain retrieval tradingagents/dataflows/tradier.py - tradingagents/dataflows/tradier_common.py - tradingagents/dataflows/y_finance.py - tradingagents/dataflows/alpha_vantage.py Create `tradingagents/dataflows/tradier.py` with: 1. **OptionsContract dataclass** (per D-06): ``` @dataclass class OptionsContract: symbol: str # OCC symbol e.g. AAPL220617C00270000 underlying: str # e.g. AAPL option_type: str # "call" or "put" strike: float expiration_date: str # YYYY-MM-DD bid: float ask: float last: float volume: int open_interest: int # Greeks (from ORATS via Tradier) delta: float | None = None gamma: float | None = None theta: float | None = None vega: float | None = None rho: float | None = None phi: float | None = None # IV bid_iv: float | None = None mid_iv: float | None = None ask_iv: float | None = None smv_vol: float | None = None greeks_updated_at: str | None = None ``` 2. **OptionsChain dataclass** (per D-06): ``` @dataclass class OptionsChain: underlying: str fetch_timestamp: str expirations: list[str] contracts: list[OptionsContract] = field(default_factory=list) def to_dataframe(self) -> pd.DataFrame: return pd.DataFrame([vars(c) for c in self.contracts]) def filter_by_dte(self, min_dte: int = 0, max_dte: int = 50) -> "OptionsChain": # Calculate DTE for each contract, keep those in range # Return new OptionsChain with filtered contracts and updated expirations list ``` The `filter_by_dte` method must: calculate `(exp_date - date.today()).days` for each contract's `expiration_date`, keep contracts where `min_dte <= dte <= max_dte`, derive the `expirations` list from the filtered contracts' unique expiration_dates (sorted), return a new OptionsChain instance. 3. **_parse_contract(raw: dict) -> OptionsContract** private function: - Extract `greeks = raw.get("greeks") or {}` - Map all fields from Tradier response dict to OptionsContract - Use `float(raw.get("bid", 0) or 0)` pattern for nullable numeric fields (bid, ask, last) - Use `int(raw.get("volume", 0) or 0)` for volume, open_interest - Greeks and IV fields use `greeks.get("delta")` etc. (None if missing -- per Pitfall 1: sandbox has no Greeks) - `greeks_updated_at = greeks.get("updated_at")` 4. **get_options_expirations(symbol: str, min_dte: int = 0, max_dte: int = 50) -> list[str]** function: - Call `make_tradier_request_with_retry("/v1/markets/options/expirations", {"symbol": symbol.upper(), "includeAllRoots": "false", "strikes": "false"})` - Extract dates: `data.get("expirations", {}).get("date", [])` - Normalize single-item response: `if isinstance(dates, str): dates = [dates]` (Pitfall 5) - Filter by DTE range using `date.today()` and `datetime.strptime(d, "%Y-%m-%d").date()` - Return sorted list of qualifying date strings 5. **_fetch_chain_for_expiration(symbol: str, expiration: str) -> list[OptionsContract]** private function: - Call `make_tradier_request_with_retry("/v1/markets/options/chains", {"symbol": symbol.upper(), "expiration": expiration, "greeks": "true"})` (per D-05: always greeks=true) - Extract: `options = data.get("options", {}).get("option", [])` - Normalize single contract: `if isinstance(options, dict): options = [options]` (Pitfall 2) - Return `[_parse_contract(opt) for opt in options]` 6. **Session cache** (Claude's discretion -- in-memory dict): - Module-level `_options_cache: dict[str, OptionsChain] = {}` - `clear_options_cache()` function to reset cache 7. **get_options_chain(symbol: str, min_dte: int = 0, max_dte: int = 50) -> str** function (per D-03: pre-fetch all expirations): - **Cache stores `OptionsChain` only** (`_options_cache: dict[str, OptionsChain]`). On hit for `cache_key`, return `_options_cache[cache_key].to_dataframe().to_string()` (do not pre-serialize strings in the cache) - Call `get_options_expirations(symbol, min_dte, max_dte)` to get qualifying dates - For each expiration, call `_fetch_chain_for_expiration(symbol, expiration)` and accumulate all OptionsContract instances - Build `OptionsChain(underlying=symbol.upper(), fetch_timestamp=datetime.now().isoformat(), expirations=expirations, contracts=all_contracts)` - Store in `_options_cache[cache_key]` - Return `chain.to_dataframe().to_string()` (string return matches vendor function pattern for LLM tool consumption) 8. **get_options_chain_structured(symbol: str, min_dte: int = 0, max_dte: int = 50) -> OptionsChain** function: - Same as get_options_chain but returns the OptionsChain dataclass directly - This is for programmatic access by downstream computation modules (not LLM tools) - Uses same cache Imports: `from dataclasses import dataclass, field`, `from datetime import datetime, date`, `import pandas as pd`, `from .tradier_common import make_tradier_request_with_retry, TradierRateLimitError` uv run python -c "from tradingagents.dataflows.tradier import OptionsContract, OptionsChain, get_options_expirations, get_options_chain, get_options_chain_structured, clear_options_cache; print('imports OK')" - tradingagents/dataflows/tradier.py exists - File contains `@dataclass` (at least twice, for OptionsContract and OptionsChain) - File contains `class OptionsContract:` with fields: symbol, underlying, option_type, strike, expiration_date, bid, ask, last, volume, open_interest, delta, gamma, theta, vega, rho, phi, bid_iv, mid_iv, ask_iv, smv_vol, greeks_updated_at - File contains `class OptionsChain:` with fields: underlying, fetch_timestamp, expirations, contracts - File contains `def to_dataframe(self) -> pd.DataFrame:` - File contains `def filter_by_dte(self, min_dte: int = 0, max_dte: int = 50)` - File contains `def get_options_expirations(symbol: str, min_dte: int = 0, max_dte: int = 50) -> list[str]:` - File contains `def get_options_chain(symbol: str, min_dte: int = 0, max_dte: int = 50) -> str:` - File contains `def get_options_chain_structured(symbol: str, min_dte: int = 0, max_dte: int = 50) -> OptionsChain:` - File contains `def clear_options_cache():` - File contains `"greeks": "true"` (D-05) - File contains `if isinstance(options, dict):` (Pitfall 2 normalization) - File contains `if isinstance(dates, str):` (Pitfall 5 normalization) - File contains `_options_cache` (session cache) - File contains `from .tradier_common import` - `uv run python -c "from tradingagents.dataflows.tradier import OptionsContract, OptionsChain"` exits 0 tradier.py exports OptionsContract, OptionsChain (with to_dataframe and filter_by_dte), get_options_expirations, get_options_chain (string return), get_options_chain_structured (dataclass return), clear_options_cache. Pre-fetches all expirations in DTE range per D-03, always requests greeks=true per D-05, handles Pitfall 2 and Pitfall 5 response normalization, uses session cache per Claude's discretion. - `uv run python -c "from tradingagents.dataflows.tradier_common import TradierRateLimitError, get_api_key, get_base_url, make_tradier_request, make_tradier_request_with_retry; print('common OK')"` - `uv run python -c "from tradingagents.dataflows.tradier import OptionsContract, OptionsChain, get_options_expirations, get_options_chain, get_options_chain_structured, clear_options_cache; print('tradier OK')"` - Two new files exist: tradier_common.py (auth + HTTP) and tradier.py (dataclasses + retrieval) - All exports importable without errors - OptionsContract has all 21 fields (symbol through greeks_updated_at) - OptionsChain has to_dataframe() and filter_by_dte() methods - Rate limit detection covers both header check and HTTP 429 - Sandbox/production URL switching driven by TRADIER_SANDBOX env var After completion, create `.planning/phases/01-tradier-data-layer/01-01-SUMMARY.md`