112 lines
7.7 KiB
Markdown
112 lines
7.7 KiB
Markdown
<!-- Last verified: 2026-03-19 -->
|
|
|
|
# Glossary
|
|
|
|
## Agents & Workflows
|
|
|
|
| Term | Definition | Source |
|
|
|------|-----------|--------|
|
|
| Trading Graph | Full per-ticker analysis pipeline: analysts → debate → trader → risk → decision | `graph/trading_graph.py` |
|
|
| Scanner Graph | 3-phase macro scanner: parallel scanners → deep dive → synthesis | `graph/scanner_graph.py` |
|
|
| Agent Factory | Closure pattern `create_X(llm)` → returns `_node(state)` function | `agents/analysts/*.py`, `agents/scanners/*.py` |
|
|
| ToolNode | LangGraph-native tool executor — used in trading graph for analyst tools | `langgraph.prebuilt`, wired in `graph/setup.py` |
|
|
| run_tool_loop | Inline tool executor for scanner agents — iterates up to `MAX_TOOL_ROUNDS` | `agents/utils/tool_runner.py` |
|
|
| Nudge | If first LLM response is < `MIN_REPORT_LENGTH` chars with no tool calls, a HumanMessage is appended asking LLM to use tools. Fires at most once. | `agents/utils/tool_runner.py` |
|
|
|
|
## Data Layer
|
|
|
|
| Term | Definition | Source |
|
|
|------|-----------|--------|
|
|
| route_to_vendor | Central dispatch: resolves vendor for a method, calls it, handles fallback for `FALLBACK_ALLOWED` methods | `dataflows/interface.py` |
|
|
| VENDOR_METHODS | Dict mapping method name → vendor → function reference. Direct function refs, not module paths. | `dataflows/interface.py` |
|
|
| FALLBACK_ALLOWED | Set of 5 method names that get cross-vendor fallback: `get_stock_data`, `get_market_indices`, `get_sector_performance`, `get_market_movers`, `get_industry_performance` | `dataflows/interface.py` |
|
|
| TOOLS_CATEGORIES | Dict mapping category name → `{"description": str, "tools": list}`. 6 categories: `core_stock_apis`, `technical_indicators`, `fundamental_data`, `news_data`, `scanner_data`, `calendar_data` | `dataflows/interface.py` |
|
|
| ETF Proxy | SPDR sector ETFs (XLK, XLV, XLF, etc.) used to get sector performance since `Sector.overview` lacks performance data | `yfinance_scanner.py`, `alpha_vantage_scanner.py` |
|
|
|
|
## Configuration
|
|
|
|
| Term | Definition | Source |
|
|
|------|-----------|--------|
|
|
| quick_think | Fast-response LLM tier. Default: `gpt-5-mini` via `openai` | `default_config.py` |
|
|
| mid_think | Balanced-analysis tier. Default: `None` (falls back to quick_think) | `default_config.py` |
|
|
| deep_think | Complex-reasoning tier. Default: `gpt-5.2` via `openai` | `default_config.py` |
|
|
| _env() | Helper: reads `TRADINGAGENTS_<KEY>`, returns default if unset or empty | `default_config.py` |
|
|
| _env_int() | Helper: same as `_env()` but coerces to `int` | `default_config.py` |
|
|
|
|
## Vendor-Specific
|
|
|
|
| Term | Definition | Source |
|
|
|------|-----------|--------|
|
|
| AlphaVantageError | Base exception for AV failures | `dataflows/alpha_vantage_common.py` |
|
|
| FinnhubError | Base exception for Finnhub failures | `dataflows/finnhub_common.py` |
|
|
| APIKeyInvalidError | Auth failure (both AV and Finnhub have one) | `*_common.py` |
|
|
| RateLimitError | Rate limit exceeded (AV: 75/min, Finnhub: 60/min) | `*_common.py` |
|
|
| ThirdPartyError | Generic API error | `*_common.py` |
|
|
| ThirdPartyTimeoutError | Request timeout | `*_common.py` |
|
|
| ThirdPartyParseError | Response parsing failure | `*_common.py` |
|
|
| MSPR | Market Sentiment and Price Return — Finnhub insider transaction metric with no AV/yfinance equivalent | `finnhub_news.py` |
|
|
|
|
## State & Data Classes
|
|
|
|
| Term | Definition | Source |
|
|
|------|-----------|--------|
|
|
| AgentState | Trading graph state (extends `MessagesState`). Fields for reports, debate states, trade decision. | `agents/utils/agent_states.py` |
|
|
| InvestDebateState | TypedDict sub-state for bull/bear debate. Fields: `bull_history`, `bear_history`, `history`, `current_response`, `judge_decision`, `count`. | `agents/utils/agent_states.py` |
|
|
| RiskDebateState | TypedDict sub-state for risk debate. Fields: `aggressive_history`, `conservative_history`, `neutral_history`, `history`, `latest_speaker`, `current_aggressive_response`, `current_conservative_response`, `current_neutral_response`, `judge_decision`, `count`. | `agents/utils/agent_states.py` |
|
|
| ScannerState | Scanner graph state (extends `MessagesState`). All report fields use `_last_value` reducer. | `agents/utils/scanner_states.py` |
|
|
| _last_value | Reducer function: `def _last_value(existing, new) -> new`. Always keeps the newest value. | `agents/utils/scanner_states.py` |
|
|
| FinancialSituationMemory | Memory object for agents that need cross-session recall (bull/bear/trader/judge/risk). | `agents/utils/memory.py` |
|
|
|
|
## Pipeline
|
|
|
|
| Term | Definition | Source |
|
|
|------|-----------|--------|
|
|
| MacroBridge | Facade class: load scan JSON → filter candidates → run per-ticker analysis → save results | `pipeline/macro_bridge.py` |
|
|
| MacroContext | @dataclass: `economic_cycle`, `central_bank_stance`, `geopolitical_risks`, `key_themes`, `executive_summary`, `risk_factors`, `timeframe`, `region` | `pipeline/macro_bridge.py` |
|
|
| StockCandidate | @dataclass: `ticker`, `name`, `sector`, `rationale`, `thesis_angle`, `conviction`, `key_catalysts`, `risks`, `macro_theme` | `pipeline/macro_bridge.py` |
|
|
| TickerResult | @dataclass: per-ticker analysis result with all report fields, populated after `propagate()` | `pipeline/macro_bridge.py` |
|
|
| ConvictionLevel | `Literal["high", "medium", "low"]` | `pipeline/macro_bridge.py` |
|
|
| CONVICTION_RANK | `{"high": 3, "medium": 2, "low": 1}` — used for sorting/filtering | `pipeline/macro_bridge.py` |
|
|
|
|
## CLI
|
|
|
|
| Term | Definition | Source |
|
|
|------|-----------|--------|
|
|
| MessageBuffer | Deque-based singleton tracking agent statuses, reports, tool calls for Rich live UI | `cli/main.py` |
|
|
| StatsCallbackHandler | Token and timing statistics handler for display | `cli/stats_handler.py` |
|
|
| FIXED_AGENTS | Dict grouping non-analyst agents by team: Research Team, Trading Team, Risk Management, Portfolio Management | `cli/main.py` |
|
|
| ANALYST_MAPPING | Dict: `"market"` → `"Market Analyst"`, `"social"` → `"Social Analyst"`, etc. | `cli/main.py` |
|
|
|
|
## Observability
|
|
|
|
| Term | Definition | Source |
|
|
|------|-----------|--------|
|
|
| RunLogger | Accumulates structured events (llm, tool, vendor, report) for a single CLI run. Thread-safe. | `observability.py` |
|
|
| _LLMCallbackHandler | LangChain `BaseCallbackHandler` that feeds LLM call events (model, tokens, latency) into a `RunLogger` | `observability.py` |
|
|
| _Event | @dataclass: `kind`, `ts`, `data` — one JSON-line per event | `observability.py` |
|
|
| set_run_logger / get_run_logger | Thread-local context for passing `RunLogger` to vendor/tool layers | `observability.py` |
|
|
|
|
## Report Paths
|
|
|
|
| Term | Definition | Source |
|
|
|------|-----------|--------|
|
|
| REPORTS_ROOT | `Path("reports")` — root for all generated artifacts | `report_paths.py` |
|
|
| get_daily_dir | Returns `reports/daily/{date}/` | `report_paths.py` |
|
|
| get_market_dir | Returns `reports/daily/{date}/market/` — scan results | `report_paths.py` |
|
|
| get_ticker_dir | Returns `reports/daily/{date}/{TICKER}/` — per-ticker analysis | `report_paths.py` |
|
|
| get_eval_dir | Returns `reports/daily/{date}/{TICKER}/eval/` — eval logs | `report_paths.py` |
|
|
|
|
## Constants
|
|
|
|
| Constant | Value | Source |
|
|
|----------|-------|--------|
|
|
| MAX_TOOL_ROUNDS | `5` | `agents/utils/tool_runner.py` |
|
|
| MIN_REPORT_LENGTH | `2000` | `agents/utils/tool_runner.py` |
|
|
| max_debate_rounds | `1` (default) | `default_config.py` |
|
|
| max_risk_discuss_rounds | `1` (default) | `default_config.py` |
|
|
| max_recur_limit | `100` (default) | `default_config.py` |
|
|
| AV _RATE_LIMIT | `75` calls/min | `dataflows/alpha_vantage_common.py` |
|
|
| Finnhub _RATE_LIMIT | `60` calls/min | `dataflows/finnhub_common.py` |
|
|
| AV API_BASE_URL | `"https://www.alphavantage.co/query"` | `dataflows/alpha_vantage_common.py` |
|
|
| Finnhub API_BASE_URL | `"https://finnhub.io/api/v1"` | `dataflows/finnhub_common.py` |
|