TradingAgents/DECISIONS.md

Architecture Decisions Log

Decision 001: Hybrid LLM Setup (Ollama + OpenRouter)

Date: 2026-03-17 Status: Implemented ✅

Context: Need cost-effective LLM setup for scanner pipeline with different complexity tiers.

Decision: Use hybrid approach:

• quick_think + mid_think: qwen3.5:27b via Ollama at http://192.168.50.76:11434 (local, free)
• deep_think: deepseek/deepseek-r1-0528 via OpenRouter (cloud, paid)

Config location: tradingagents/default_config.py — per-tier _llm_provider and _backend_url keys.

Consequence: Removed top-level llm_provider and backend_url from config. Each tier must have its own {tier}_llm_provider set explicitly.

---

Decision 002: Data Vendor Fallback Strategy

Date: 2026-03-17 Status: Implemented ✅

Context: Alpha Vantage free/demo key doesn't support ETF symbols and has strict rate limits. Need reliable data for scanner.

Decision:

• route_to_vendor() catches AlphaVantageError (base class) to trigger fallback, not just RateLimitError.
• AV scanner functions raise AlphaVantageError when ALL queries fail (not silently embedding errors in output strings).
• yfinance is the fallback vendor and uses SPDR ETF proxies for sector performance instead of broken Sector.overview.

Files changed:

• tradingagents/dataflows/interface.py — broadened catch
• tradingagents/dataflows/alpha_vantage_scanner.py — raise on total failure
• tradingagents/dataflows/yfinance_scanner.py — ETF proxy approach

---

Decision 003: yfinance Sector Performance via ETF Proxies

Date: 2026-03-17 Status: Implemented ✅

Context: yfinance.Sector("technology").overview returns only metadata (companies_count, market_cap, etc.) — no performance data (oneDay, oneWeek, etc.).

Decision: Use SPDR sector ETFs as proxies:

sector_etfs = {
    "Technology": "XLK", "Healthcare": "XLV", "Financials": "XLF",
    "Energy": "XLE", "Consumer Discretionary": "XLY", ...
}

Download 6 months of history via yf.download() and compute 1-day, 1-week, 1-month, YTD percentage changes from closing prices.

File: tradingagents/dataflows/yfinance_scanner.py

---

Decision 004: Inline Tool Execution Loop for Scanner Agents

Date: 2026-03-17 Status: Implemented ✅

Context: The existing trading graph uses separate ToolNode graph nodes for tool execution (agent → tool_node → agent routing loop). Scanner agents are simpler single-pass nodes — no ToolNode in the graph. When the LLM returned tool_calls, nobody executed them, resulting in empty reports.

Decision: Created tradingagents/agents/utils/tool_runner.py with run_tool_loop() that runs an inline tool execution loop within each scanner agent node:

1. Invoke chain
2. If tool_calls present → execute tools → append ToolMessages → re-invoke
3. Repeat up to MAX_TOOL_ROUNDS=5 until LLM produces text response

Alternative considered: Adding ToolNode + conditional routing to scanner_setup.py (like trading graph). Rejected — too complex for the fan-out/fan-in pattern and would require 4 separate tool nodes with routing logic.

Files:

• tradingagents/agents/utils/tool_runner.py (new)
• All scanner agents updated to use run_tool_loop()

---

Decision 005: LangGraph State Reducers for Parallel Fan-Out

Date: 2026-03-17 Status: Implemented ✅

Context: Phase 1 runs 3 scanners in parallel. All write to shared state fields (sender, etc.). LangGraph requires reducers for concurrent writes — otherwise raises INVALID_CONCURRENT_GRAPH_UPDATE.

Decision: Added _last_value reducer to all ScannerState fields via Annotated[str, _last_value].

File: tradingagents/agents/utils/scanner_states.py

---

Decision 006: CLI --date Flag for Scanner

Date: 2026-03-17 Status: Implemented ✅

Context: python -m cli.main scan was interactive-only (prompts for date). Needed non-interactive invocation for testing/automation.

Decision: Added --date / -d option to scan command. Falls back to interactive prompt if not provided.

File: cli/main.py

---

Decision 008: Git Remote Strategy — origin = fork

Date: 2026-03-17 Status: Documented ✅

Setup: There is only one configured remote:

origin → http://127.0.0.1:46699/git/aguzererler/TradingAgents  (the user's fork)

No upstream remote for the parent repo.

Rule: Always push feature branches to origin. Never push directly to main. PRs are created from claude/* branches on the fork via the Gitea web UI (no gh CLI available).

---

Decision 009: Medium-Term Upgrade — Macro Regime via yfinance Only

Date: 2026-03-17 Status: Implemented ✅

Context: Macro regime classification needs VIX, credit spreads, yield curve, market breadth, sector rotation — all free signals.

Decision: Use yfinance exclusively for all macro regime signals (no Alpha Vantage endpoint for this data). 6 signals from ^VIX, ^GSPC, HYG, LQD, TLT, SHY, and sector ETFs. No vendor routing needed.

Scoring: Each signal ±1. Total ≥3 = risk-on, ≤-3 = risk-off, else transition. Confidence based on absolute score: |score| ≥4 → high, ≥2 → medium, else low.

File: tradingagents/dataflows/macro_regime.py

---

Decision 009: TTM Tool Prefers Alpha Vantage (More History)

Date: 2026-03-17 Status: Implemented ✅

Context: yfinance returns only 4-5 quarterly periods. Alpha Vantage INCOME_STATEMENT endpoint returns up to 20 quarters. For 8-quarter trend analysis, AV is significantly better.

Decision: get_ttm_analysis tool uses route_to_vendor with AV as primary, yfinance as fallback. TTM module handles <8 quarters gracefully (computes with what's available, reports quarters_available).

File: tradingagents/dataflows/ttm_analysis.py

---

Decision 010: Peer Comparison via Hardcoded Sector Tickers

Date: 2026-03-17 Status: Implemented ✅

Context: No Alpha Vantage endpoint for peer comparison. yfinance top_companies was unreliable (Mistake 3). Need deterministic peer lists.

Decision: Hardcode _SECTOR_TICKERS mapping (20 tickers per sector) and _SECTOR_ETFS in peer_comparison.py. Peer data via yf.download() — reliable and fast. Sector ETF used as benchmark for alpha calculation.

Trade-off: Peers don't auto-update if sector composition changes. Acceptable for current use case.

File: tradingagents/dataflows/peer_comparison.py

---

Decision 007: .env Loading Strategy

Date: 2026-03-17 Status: Implemented ✅

Context: load_dotenv() loads from CWD. When running from a git worktree, the worktree .env may have placeholder values while the main repo .env has real keys.

Decision: cli/main.py calls load_dotenv() (CWD) then load_dotenv(Path(__file__).parent.parent / ".env") as fallback. The worktree .env was also updated with real API keys.

Note for future: If .env issues recur, check which .env file is being picked up. The worktree and main repo each have their own .env.