191 lines
11 KiB
Markdown
191 lines
11 KiB
Markdown
<!-- Last verified: 2026-03-19 -->
|
|
|
|
# Components
|
|
|
|
## Directory Tree
|
|
|
|
```
|
|
tradingagents/
|
|
├── __init__.py
|
|
├── default_config.py # All config keys, defaults, env var overrides
|
|
├── report_paths.py # Unified report path helpers (reports/daily/{date}/)
|
|
├── observability.py # RunLogger, _LLMCallbackHandler, structured event logging
|
|
├── agents/
|
|
│ ├── __init__.py
|
|
│ ├── analysts/
|
|
│ │ ├── fundamentals_analyst.py # create_fundamentals_analyst(llm)
|
|
│ │ ├── market_analyst.py # create_market_analyst(llm)
|
|
│ │ ├── news_analyst.py # create_news_analyst(llm)
|
|
│ │ └── social_media_analyst.py # create_social_media_analyst(llm)
|
|
│ ├── managers/
|
|
│ │ ├── research_manager.py # create_research_manager(llm, memory)
|
|
│ │ └── risk_manager.py # create_risk_manager(llm, memory)
|
|
│ ├── researchers/
|
|
│ │ ├── bear_researcher.py # create_bear_researcher(llm, memory)
|
|
│ │ └── bull_researcher.py # create_bull_researcher(llm, memory)
|
|
│ ├── risk_mgmt/
|
|
│ │ ├── aggressive_debator.py # create_aggressive_debator(llm)
|
|
│ │ ├── conservative_debator.py # create_conservative_debator(llm)
|
|
│ │ └── neutral_debator.py # create_neutral_debator(llm)
|
|
│ ├── scanners/
|
|
│ │ ├── __init__.py
|
|
│ │ ├── geopolitical_scanner.py # create_geopolitical_scanner(llm)
|
|
│ │ ├── market_movers_scanner.py # create_market_movers_scanner(llm)
|
|
│ │ ├── sector_scanner.py # create_sector_scanner(llm)
|
|
│ │ ├── industry_deep_dive.py # create_industry_deep_dive(llm)
|
|
│ │ └── macro_synthesis.py # create_macro_synthesis(llm)
|
|
│ ├── trader/
|
|
│ │ └── trader.py # create_trader(llm, memory)
|
|
│ └── utils/
|
|
│ ├── agent_states.py # AgentState, InvestDebateState, RiskDebateState
|
|
│ ├── agent_utils.py # Tool re-exports, create_msg_delete()
|
|
│ ├── core_stock_tools.py # get_stock_data, get_indicators, get_macro_regime
|
|
│ ├── fundamental_data_tools.py # get_fundamentals, get_balance_sheet, etc.
|
|
│ ├── json_utils.py # extract_json()
|
|
│ ├── memory.py # FinancialSituationMemory
|
|
│ ├── news_data_tools.py # get_news, get_global_news, get_insider_transactions
|
|
│ ├── scanner_states.py # ScannerState, _last_value reducer
|
|
│ ├── scanner_tools.py # Scanner @tool definitions (7 tools)
|
|
│ ├── technical_indicators_tools.py
|
|
│ └── tool_runner.py # run_tool_loop(), MAX_TOOL_ROUNDS, MIN_REPORT_LENGTH
|
|
├── dataflows/
|
|
│ ├── __init__.py
|
|
│ ├── config.py # set_config(), get_config(), initialize_config()
|
|
│ ├── interface.py # route_to_vendor, VENDOR_METHODS, FALLBACK_ALLOWED
|
|
│ ├── alpha_vantage.py # Re-export facade
|
|
│ ├── alpha_vantage_common.py # Exception hierarchy, rate limiter
|
|
│ ├── alpha_vantage_fundamentals.py
|
|
│ ├── alpha_vantage_indicator.py
|
|
│ ├── alpha_vantage_news.py
|
|
│ ├── alpha_vantage_scanner.py
|
|
│ ├── alpha_vantage_stock.py
|
|
│ ├── finnhub.py
|
|
│ ├── finnhub_common.py # Exception hierarchy, rate limiter
|
|
│ ├── finnhub_fundamentals.py
|
|
│ ├── finnhub_indicators.py
|
|
│ ├── finnhub_news.py
|
|
│ ├── finnhub_scanner.py
|
|
│ ├── finnhub_stock.py
|
|
│ ├── macro_regime.py
|
|
│ ├── peer_comparison.py
|
|
│ ├── stockstats_utils.py
|
|
│ ├── ttm_analysis.py
|
|
│ ├── utils.py
|
|
│ ├── y_finance.py # Core yfinance data functions
|
|
│ ├── yfinance_news.py
|
|
│ └── yfinance_scanner.py
|
|
├── graph/
|
|
│ ├── trading_graph.py # TradingAgentsGraph class
|
|
│ ├── scanner_graph.py # ScannerGraph class
|
|
│ ├── setup.py # GraphSetup — trading graph builder
|
|
│ ├── scanner_setup.py # ScannerGraphSetup — scanner graph builder
|
|
│ ├── conditional_logic.py # ConditionalLogic — debate/risk routing
|
|
│ ├── propagation.py # Propagator
|
|
│ ├── reflection.py # Reflector
|
|
│ └── signal_processing.py # SignalProcessor
|
|
├── llm_clients/ # Multi-provider LLM factory
|
|
│ └── (create_llm_client dispatch)
|
|
└── pipeline/
|
|
├── __init__.py
|
|
└── macro_bridge.py # MacroBridge, data classes, pipeline orchestration
|
|
|
|
cli/
|
|
└── main.py # Typer app, MessageBuffer, Rich UI, 3 commands
|
|
```
|
|
|
|
## Agent Factory Inventory (17 factories + 1 utility)
|
|
|
|
| Factory | File | LLM Tier | Extra Params |
|
|
|---------|------|----------|-------------|
|
|
| `create_fundamentals_analyst` | `agents/analysts/fundamentals_analyst.py` | quick | — |
|
|
| `create_market_analyst` | `agents/analysts/market_analyst.py` | quick | — |
|
|
| `create_news_analyst` | `agents/analysts/news_analyst.py` | quick | — |
|
|
| `create_social_media_analyst` | `agents/analysts/social_media_analyst.py` | quick | — |
|
|
| `create_bull_researcher` | `agents/researchers/bull_researcher.py` | mid | `memory` |
|
|
| `create_bear_researcher` | `agents/researchers/bear_researcher.py` | mid | `memory` |
|
|
| `create_research_manager` | `agents/managers/research_manager.py` | deep | `memory` |
|
|
| `create_trader` | `agents/trader/trader.py` | mid | `memory` |
|
|
| `create_aggressive_debator` | `agents/risk_mgmt/aggressive_debator.py` | quick | — |
|
|
| `create_conservative_debator` | `agents/risk_mgmt/conservative_debator.py` | quick | — |
|
|
| `create_neutral_debator` | `agents/risk_mgmt/neutral_debator.py` | quick | — |
|
|
| `create_risk_manager` | `agents/managers/risk_manager.py` | deep | `memory` |
|
|
| `create_geopolitical_scanner` | `agents/scanners/geopolitical_scanner.py` | quick | — |
|
|
| `create_market_movers_scanner` | `agents/scanners/market_movers_scanner.py` | quick | — |
|
|
| `create_sector_scanner` | `agents/scanners/sector_scanner.py` | quick | — |
|
|
| `create_industry_deep_dive` | `agents/scanners/industry_deep_dive.py` | mid | — |
|
|
| `create_macro_synthesis` | `agents/scanners/macro_synthesis.py` | deep | — |
|
|
| `create_msg_delete` | `agents/utils/agent_utils.py` | — | No LLM param |
|
|
|
|
## Extension Guides
|
|
|
|
### Adding a New Analyst
|
|
1. Create `tradingagents/agents/analysts/new_analyst.py` with `create_new_analyst(llm)`
|
|
2. Add tools to `tradingagents/agents/utils/` and register in `agent_utils.py`
|
|
3. Register tool node in `trading_graph.py:_create_tool_nodes()`
|
|
4. Add node and edges in `graph/setup.py:setup_graph()`
|
|
5. Add conditional routing in `graph/conditional_logic.py`
|
|
6. Add to `cli/main.py` `ANALYST_MAPPING` and `REPORT_SECTIONS`
|
|
|
|
### Adding a New Scanner
|
|
1. Create `tradingagents/agents/scanners/new_scanner.py` with `create_new_scanner(llm)`
|
|
2. Export from `agents/scanners/__init__.py`
|
|
3. Add to `scanner_graph.py` agents dict
|
|
4. Add node and edges in `graph/scanner_setup.py`
|
|
5. Add state field with `_last_value` reducer to `scanner_states.py`
|
|
|
|
### Adding a New Data Vendor
|
|
1. Create `tradingagents/dataflows/newvendor_common.py` (exception hierarchy, rate limiter)
|
|
2. Create per-domain modules (`newvendor_stock.py`, `newvendor_scanner.py`, etc.)
|
|
3. Add vendor functions to `VENDOR_METHODS` in `interface.py`
|
|
4. Add vendor to `VENDOR_LIST` in `interface.py`
|
|
5. Add exception types to the catch tuple in `route_to_vendor`
|
|
6. Add config category in `default_config.py` `data_vendors`
|
|
|
|
### Adding a New LLM Provider
|
|
1. Add client creation logic to `tradingagents/llm_clients/`
|
|
2. Add provider-specific kwargs handling in `trading_graph.py:_get_provider_kwargs()` and `scanner_graph.py:_get_provider_kwargs()`
|
|
3. Add API key to `.env.example`
|
|
|
|
### Adding a New Config Key
|
|
1. Add to `DEFAULT_CONFIG` dict in `default_config.py` with `_env()` or `_env_int()` override
|
|
2. Add to `.env.example` with documentation
|
|
3. Update `CLAUDE.md` if it's a frequently-used key
|
|
|
|
## CLI Commands
|
|
|
|
| Command | Function | Description |
|
|
|---------|----------|-------------|
|
|
| `analyze` | `run_analysis()` | Interactive per-ticker multi-agent analysis with Rich live UI |
|
|
| `scan` | `run_scan(date)` | 3-phase macro scanner, saves 5 report files |
|
|
| `pipeline` | `run_pipeline()` | Full pipeline: scan JSON → filter by conviction → per-ticker deep dive |
|
|
|
|
## Test Organization
|
|
|
|
| Test File | Type | What It Covers | Markers |
|
|
|-----------|------|---------------|---------|
|
|
| `test_alpha_vantage_exceptions.py` | Mixed | AV exception hierarchy, `_make_api_request` errors | `integration` on HTTP tests |
|
|
| `test_alpha_vantage_integration.py` | Unit | Full AV data layer (all mocked) | — |
|
|
| `test_alpha_vantage_scanner.py` | Integration | Live AV scanner functions | `integration` |
|
|
| `test_config_wiring.py` | Unit | `AgentState` fields, tool exports, debate wiring | — |
|
|
| `test_debate_rounds.py` | Unit | `ConditionalLogic` routing at various round counts | — |
|
|
| `test_e2e_api_integration.py` | Unit | Vendor routing layer (all mocked) | — |
|
|
| `test_env_override.py` | Unit | `TRADINGAGENTS_*` env var overrides | — |
|
|
| `test_finnhub_integration.py` | Unit | Full Finnhub data layer (all mocked) | — |
|
|
| `test_finnhub_live_integration.py` | Integration | Live Finnhub endpoints | `integration`, `paid_tier` |
|
|
| `test_industry_deep_dive.py` | Mixed | `_extract_top_sectors`, nudge mechanism, enriched output | — |
|
|
| `test_json_utils.py` | Unit | `extract_json()` — markdown, think blocks, edge cases | — |
|
|
| `test_macro_bridge.py` | Unit | Pipeline: parse, filter, render, save | — |
|
|
| `test_macro_regime.py` | Mixed | Macro signals, regime classification, report format | `integration` on live test |
|
|
| `test_peer_comparison.py` | Mixed | Peer comparison functions | `integration` on live test |
|
|
| `test_scanner_comprehensive.py` | Integration | All 5 scanner tools + CLI output naming | — |
|
|
| `test_scanner_fallback.py` | Mixed | yfinance perf, AV failure mode, fallback routing | `integration` on some |
|
|
| `test_scanner_graph.py` | Unit | `ScannerGraph` import/instantiation, graph compilation | — |
|
|
| `test_scanner_mocked.py` | Unit | All yfinance + AV scanner functions (all mocked) | — |
|
|
| `test_scanner_routing.py` | Integration | Live routing with AV config | `integration` |
|
|
| `test_scanner_tools.py` | Integration | Scanner tool imports + live invocation | — |
|
|
| `test_ttm_analysis.py` | Mixed | TTM metrics computation, report format | `integration` on live test |
|
|
| `test_vendor_failfast.py` | Unit | ADR 011 fail-fast behavior, error chaining | — |
|
|
| `test_yfinance_integration.py` | Unit | Full yfinance data layer (all mocked) | — |
|
|
|
|
Pytest markers: `integration` (live API), `paid_tier` (Finnhub paid subscription), `slow` (long-running). Defined in `conftest.py`.
|