115 lines
4.7 KiB
Markdown
115 lines
4.7 KiB
Markdown
# 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:
|
|
```python
|
|
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 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`.
|