diff --git a/.env.example b/.env.example
index b6f14ed41..d17ac1c2b 100644
--- a/.env.example
+++ b/.env.example
@@ -16,57 +16,49 @@ MOONSHOT_API_KEY=
GROQ_API_KEY=
NVIDIA_API_KEY=
-# FRED (Federal Reserve macro data: rates, inflation, labor, growth). Free key: https://fred.stlouisfed.org/docs/api/api_key.html
+# SEC EDGAR (US company filings, point-in-time). No key; a contact address SEC can reach you at.
+#SEC_EDGAR_USER_AGENT=Your Name your@email.com
+
+# FRED (Federal Reserve macro data). Free key: https://fred.stlouisfed.org/docs/api/api_key.html
#FRED_API_KEY=
-# Optional: a custom OpenAI-compatible endpoint (vLLM, LM Studio, llama.cpp,
-# relay). Select provider "openai_compatible" and set the base URL; the key is
-# optional (local servers need none).
+# Custom OpenAI-compatible endpoint (vLLM, LM Studio, llama.cpp). Local servers need no key.
#OPENAI_COMPATIBLE_API_KEY=
-# AWS Bedrock (provider "bedrock", install with: pip install ".[bedrock]").
-# Auth: either a Bedrock API key (bearer token, no AWS access keys) OR the AWS
-# credential chain (env keys / ~/.aws/credentials / IAM role / AWS_PROFILE). Set
-# the region either way; a bearer token takes precedence when both are present.
+# AWS Bedrock (pip install ".[bedrock]"). Bearer token, or the AWS credential chain; set the region either way.
#AWS_BEARER_TOKEN_BEDROCK=
#AWS_DEFAULT_REGION=us-west-2
#AWS_PROFILE=
-# Optional: point at a remote Ollama server. When unset, defaults to
-# the local instance at http://localhost:11434/v1. Convention follows
-# the broader Ollama ecosystem; both the CLI dropdown and programmatic
-# client pick this up.
+# Remote Ollama server. Unset uses http://localhost:11434/v1.
#OLLAMA_BASE_URL=http://your-ollama-host:11434/v1
-# Optional: override DEFAULT_CONFIG without editing code.
-# Any TRADINGAGENTS_* variable below, when set, replaces the matching key
-# in tradingagents/default_config.py. Values are coerced to the type of
-# the existing default (bool / int / str), so "true"/"3" work as expected.
-# In the CLI, setting the LLM provider / models / backend URL / language
-# also skips the matching interactive selection step (useful for
-# OpenAI-compatible endpoints like opencode or LM Studio, and unattended runs).
+# Override these DEFAULT_CONFIG keys. Provider, models, language and round counts also skip their CLI prompt.
#TRADINGAGENTS_LLM_PROVIDER=openai
-#TRADINGAGENTS_DEEP_THINK_LLM=gpt-5.4
-#TRADINGAGENTS_QUICK_THINK_LLM=gpt-5.4-mini
+#TRADINGAGENTS_DEEP_THINK_LLM=gpt-5.6
+#TRADINGAGENTS_QUICK_THINK_LLM=gpt-5.6-luna
#TRADINGAGENTS_LLM_BACKEND_URL=
#TRADINGAGENTS_OUTPUT_LANGUAGE=English
#TRADINGAGENTS_MAX_DEBATE_ROUNDS=1
#TRADINGAGENTS_MAX_RISK_ROUNDS=1
#TRADINGAGENTS_CHECKPOINT_ENABLED=false
-# Sampling temperature (lower = less run-to-run variation on models that
-# honor it). Unset leaves each provider at its default. See the README
-# "Reproducibility" note — no setting makes LLM output fully deterministic.
+
+# Paths and alpha benchmark. Unset uses ~/.tradingagents and the regional index.
+#TRADINGAGENTS_RESULTS_DIR=
+#TRADINGAGENTS_CACHE_DIR=
+#TRADINGAGENTS_MEMORY_LOG_PATH=
+#TRADINGAGENTS_BENCHMARK_TICKER=SPY
+
+# Lower temperature means less run-to-run variation on models that honor it.
#TRADINGAGENTS_TEMPERATURE=0.0
-# LLM SDK retry budget forwarded to every provider. Unset leaves each SDK at its
-# own default (usually 2). Raise it to ride out bursty 429 rate-limit throttling
-# on rate-limited deployments (e.g. Azure OpenAI) instead of aborting the run.
+
+# Retry budget for every LLM SDK. Raise it to ride out 429 throttling.
#TRADINGAGENTS_LLM_MAX_RETRIES=6
-# Cap on output tokens forwarded to every provider (Gemini's max_output_tokens
-# too). Unset leaves each provider at its default. Set it to bound a model that
-# emits unbounded reasoning/output and hangs or trips a gateway idle timeout.
+
+# Cap output tokens to bound a model that runs long and trips a timeout.
#TRADINGAGENTS_MAX_TOKENS=8192
-# Provider-specific reasoning/thinking depth (optional; unset = provider
-# default). Setting one also skips the matching interactive prompt.
+
+# Reasoning depth per provider; setting one skips its prompt.
#TRADINGAGENTS_OPENAI_REASONING_EFFORT=medium
#TRADINGAGENTS_GOOGLE_THINKING_LEVEL=high
#TRADINGAGENTS_ANTHROPIC_EFFORT=high
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9071c0445..6bd57ecf6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,72 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
Breaking changes within the 0.x line are called out explicitly.
+## [0.5.0] — 2026-09-18
+
+Point-in-time integrity across every dated path, decisions that are recorded as
+they were made, backtesting over a grid of tickers and dates, the caller's
+portfolio as run input, and SEC EDGAR fundamentals served as filed.
+
+### Highlights
+
+- **Fundamentals as filed.** SEC EDGAR serves US company statements as they stood on the run's date: a period that has ended but has not been filed is not served, and a figure restated later still reads as first reported. Keyless, opt-in via the vendor chain.
+- **Backtesting.** `run_backtest` runs the pipeline over a ticker and date grid into its own decision log, and `summarize` scores the settled cells; `tradingagents backtest` does the same from the CLI.
+- **Portfolio context.** `propagate(..., portfolio=...)` and `--portfolio` let the trader, risk and portfolio agents size against real holdings. A run without one is never treated as a flat book.
+- **Decisions are recorded as made.** An unreadable decision is flagged for review everywhere instead of becoming a tradeable Hold, and a rating argued against is no longer read as the call.
+
+### Point-in-time and honest attribution
+
+- Dated tools take the run's date from graph state, so an omitted or later date cannot reach a vendor. (#1331, #1319, #1118)
+- Insider filings and prediction-market odds are bounded by the run date; insider rows state that a trade becomes public when its Form 4 is filed.
+- A feed that never observed a window reports it as unavailable rather than as an absence, across news, Reddit and StockTwits.
+- The resolved company identity says when it describes today rather than the run date.
+- The verification snapshot quotes the prices the vendor reported, never a gap-filled value.
+- A vendor failure is a vendor failure: yfinance raises instead of returning its errors as text, an outage is not reported as a company with no data, and a chain where every vendor is unavailable says so instead of ending the run.
+- The macro vintage pin is clamped to the vendor's own clock, so a run dated today cannot ask for a vintage it does not have.
+- A historical run is not served a present-day company profile by either fundamentals vendor. (#1300)
+
+### Decisions and evaluation
+
+- The labelled rating decides, whatever separates it, and prose naming several ratings is reviewed rather than guessed.
+- Decision prompts state the shape of their answer, so a provider without structured output still returns a readable decision.
+- A report that was not produced says so, instead of appearing as an empty section.
+- Backtest scoring reads the direction each rating claimed: a Sell that fell is a hit, and Hold reports no hit rate.
+- The outcome window is configurable (`holding_period_days`), and reflection states the window it judges.
+- A settled decision is not logged twice, and a failed reflection no longer stops the next run. (#645)
+- The trader states entry and stop levels as prices, so a percentage no longer fails the whole proposal. (#1288)
+
+### CLI
+
+- `tradingagents backtest`, with `--run-id` to continue an interrupted sweep. (#1234)
+- The previous run's selections come back as prompt defaults. (#1236, #920)
+- A run with no readable rating says so; the live view no longer scrolls; messages that read like Python values are shown. (#649, #784)
+- The state log keeps non-ASCII readable. (#1081)
+
+### Data sources
+
+- SEC EDGAR fundamentals vendor (US filers, keyless).
+- Hong Kong and Shanghai tickers resolve to the symbols Yahoo serves. (#1342, #957, #1260)
+- Reddit is fetched as one combined request per run. (#1286)
+- One OHLCV cache file per symbol. (#1330)
+
+### Models
+
+- Current lineups for every provider: GPT-6 Astra and the GPT-5.6 family, Gemini 3.8 Flash, Claude Opus 5 and Fable 5.1, Grok 4.6, DeepSeek Flash, Qwen 3.8, GLM-5.3, MiniMax M3, Kimi K3 and the current Mistral snapshots.
+- Every provider accepts a model ID the picker does not list.
+- GLM traffic goes to the platform its key belongs to, and Ollama structured output no longer sends a tool_choice it rejects. (#1062)
+
+### Changed
+
+- The memory log records `REVIEW` for a decision with no readable rating, where it previously recorded `Hold`.
+- Optional fields the model did not provide are named as such rather than omitted.
+- Removed dependencies nothing imports: backtrader, redis, setuptools, langchain-experimental, parsel, tqdm. (#1353, #1070)
+
+### Contributors
+
+Thanks to everyone who reported these or sent a fix:
+
+[@akashkpfreelancer](https://github.com/akashkpfreelancer), [@angziii](https://github.com/angziii), [@anupamme](https://github.com/anupamme), [@AyushKar2005](https://github.com/AyushKar2005), [@bulkypanda](https://github.com/bulkypanda), [@CadeYu](https://github.com/CadeYu), [@chiang21fcb](https://github.com/chiang21fcb), [@dajiaohuang](https://github.com/dajiaohuang), [@dewrama](https://github.com/dewrama), [@DogInfantry](https://github.com/DogInfantry), [@emitov](https://github.com/emitov), [@farukerdem34](https://github.com/farukerdem34), [@flydragon2018](https://github.com/flydragon2018), [@fusshell](https://github.com/fusshell), [@Ganesh1729-ui](https://github.com/Ganesh1729-ui), [@gyx09212214-prog](https://github.com/gyx09212214-prog), [@hamzabudeir](https://github.com/hamzabudeir), [@ihsieh31](https://github.com/ihsieh31), [@jaylew20250206](https://github.com/jaylew20250206), [@kaushik-yadav](https://github.com/kaushik-yadav), [@kbnnf](https://github.com/kbnnf), [@kevinkda](https://github.com/kevinkda), [@LudwigJMarx](https://github.com/LudwigJMarx), [@lx7720](https://github.com/lx7720), [@malandrindev](https://github.com/malandrindev), [@mhd325ic-hash](https://github.com/mhd325ic-hash), [@minhdn90](https://github.com/minhdn90), [@miznan](https://github.com/miznan), [@mmssix](https://github.com/mmssix), [@mrbob-git](https://github.com/mrbob-git), [@newnewself](https://github.com/newnewself), [@prithvirajrh](https://github.com/prithvirajrh), [@PyriteResearch](https://github.com/PyriteResearch), [@Rajatendu1](https://github.com/Rajatendu1), [@Recnelis0](https://github.com/Recnelis0), [@Rodvask](https://github.com/Rodvask), [@samhoooo](https://github.com/samhoooo), [@sheiun-xu](https://github.com/sheiun-xu), [@shivsin25](https://github.com/shivsin25), [@SmileShaun](https://github.com/SmileShaun), [@SonnyRajagopalan](https://github.com/SonnyRajagopalan), [@taro0915](https://github.com/taro0915), [@wupengbo125](https://github.com/wupengbo125), [@wxggzz](https://github.com/wxggzz), [@Yixiang-Wu](https://github.com/Yixiang-Wu), [@ZahirBodrike](https://github.com/ZahirBodrike), [@ZHUYAWEI](https://github.com/ZHUYAWEI), [@zkwang616](https://github.com/zkwang616).
+
## [0.4.0] — 2026-08-31
Look-ahead and point-in-time fixes across the data and memory layers, clearer
diff --git a/README.md b/README.md
index 505b69df4..6cd125f3e 100644
--- a/README.md
+++ b/README.md
@@ -30,8 +30,13 @@
# TradingAgents: Multi-Agents LLM Financial Trading Framework
## News
-- [2026-08] **TradingAgents v0.4.0** released with look-ahead / point-in-time fixes across FRED macro, social sentiment, and the decision-log memory; clearer decision signals; working CLI checkpoint resume; Trader price grounding; and the GPT-5.6 and GLM-5.3 models. See [CHANGELOG.md](CHANGELOG.md) for the full list.
+- [2026-09] **TradingAgents v0.5.0** released with point-in-time integrity across every dated path, SEC EDGAR fundamentals served as filed, backtesting over a ticker and date grid, portfolio-aware runs, and current model lineups across every provider. See [CHANGELOG.md](CHANGELOG.md) for the full list.
+- [2026-08] **TradingAgents v0.4.0** released with look-ahead / point-in-time fixes across FRED macro, social sentiment, and the decision-log memory; clearer decision signals; working CLI checkpoint resume; Trader price grounding; and the GPT-5.6 and GLM-5.3 models.
- [2026-07] **TradingAgents v0.3.1** released with correctness and stability fixes: Alpha Vantage look-ahead filtering, graph-router crash-safety, graph-shape-aware checkpoint resume, working crypto sentiment sources, a configurable LLM retry budget, Bedrock API-key auth, and Claude Sonnet 5 / Fable 5 support.
+
+
+Earlier releases
+
- [2026-06] **TradingAgents v0.3.0** released with a verified data-access contract, an expanded provider registry (NVIDIA, Kimi, Groq, Mistral, Bedrock, and any OpenAI-compatible endpoint), FRED and Polymarket data vendors, a current-generation model catalog, and a CI gate.
- [2026-05] **TradingAgents v0.2.5** released with the grounded Sentiment Analyst, GPT-5.5 etc. model coverage, Qwen/GLM/MiniMax dual-region support, `TRADINGAGENTS_*` env-var configurability with API-key auto-detection, remote Ollama support, non-US alpha benchmarks, and ticker path-traversal hardening.
- [2026-04] **TradingAgents v0.2.4** released with structured-output agents (Research Manager, Trader, Portfolio Manager), LangGraph checkpoint resume, persistent decision log, DeepSeek/Qwen/GLM/Azure provider support, Docker, and a Windows UTF-8 encoding fix.
@@ -40,6 +45,8 @@
- [2026-02] **TradingAgents v0.2.0** released with multi-provider LLM support (GPT-5.x, Gemini 3.x, Claude 4.x, Grok 4.x) and improved system architecture.
- [2026-01] **Trading-R1** [Technical Report](https://arxiv.org/abs/2509.11420) released, with [Terminal](https://github.com/TauricResearch/Trading-R1) expected to land soon.
+
+
🚀 [TradingAgents](#tradingagents-framework) | ⚡ [Installation & CLI](#installation-and-cli) | 🎬 [Demo](https://www.youtube.com/watch?v=90gr5lwjIho) | 📦 [Package Usage](#tradingagents-package) | 🤝 [Contributing](#contributing) | 📄 [Citation](#citation)
@@ -110,7 +117,13 @@ conda create -n tradingagents python=3.12
conda activate tradingagents
```
-Install the package and its dependencies:
+Or with [uv](https://docs.astral.sh/uv/):
+```bash
+uv venv --python 3.12
+source .venv/bin/activate
+```
+
+Install the package and its dependencies (`uv pip install .` with uv):
```bash
pip install .
```
@@ -123,6 +136,8 @@ cp .env.example .env # add your API keys
docker compose run --rm tradingagents
```
+After updating the repository, rebuild the image with `docker compose build`.
+
For local models with Ollama:
```bash
docker compose --profile ollama run --rm tradingagents-ollama
@@ -145,6 +160,11 @@ export ZHIPU_CN_API_KEY=... # GLM via BigModel (China, open.bigmodel.cn)
export MINIMAX_API_KEY=... # MiniMax — Global (api.minimax.io)
export MINIMAX_CN_API_KEY=... # MiniMax — China (api.minimaxi.com)
export OPENROUTER_API_KEY=... # OpenRouter
+export MISTRAL_API_KEY=... # Mistral
+export MOONSHOT_API_KEY=... # Kimi (Moonshot)
+export GROQ_API_KEY=... # Groq
+export NVIDIA_API_KEY=... # NVIDIA NIM
+export FRED_API_KEY=... # FRED macro data (free, optional)
export ALPHA_VANTAGE_API_KEY=... # Alpha Vantage
```
@@ -168,7 +188,7 @@ Launch the interactive CLI:
tradingagents # installed command
python -m cli.main # alternative: run directly from source
```
-You will see a screen where you can select your desired tickers, analysis date, LLM provider, research depth, and more.
+You will see a screen where you can select your desired tickers, analysis date, LLM provider, research depth, and more. Your previous run's answers come back as the defaults, so pressing Enter accepts them. The `TRADINGAGENTS_*` variables in `.env` still skip their step entirely.
### Markets and tickers
@@ -211,7 +231,7 @@ from tradingagents.default_config import DEFAULT_CONFIG
ta = TradingAgentsGraph(debug=True, config=DEFAULT_CONFIG.copy())
# forward propagate
-_, decision = ta.propagate("NVDA", "2026-01-15")
+_, decision = ta.propagate("NVDA", "2026-09-01")
print(decision)
```
@@ -228,40 +248,98 @@ config["quick_think_llm"] = "gpt-5.6-luna" # Model for quick tasks
config["max_debate_rounds"] = 2
ta = TradingAgentsGraph(debug=True, config=config)
-_, decision = ta.propagate("NVDA", "2026-01-15")
+_, decision = ta.propagate("NVDA", "2026-09-01")
print(decision)
```
See `tradingagents/default_config.py` for all configuration options.
+### Fundamentals as filed
+
+US company statements can come from SEC EDGAR, which records the date every figure was filed. A run dated in the past then reads the statements exactly as they stood that day: a fiscal year that has ended but has not been filed yet is not served, and a figure restated later still reads as first reported. Apple's 2008 total assets were filed as $39.6B and restated to $36.2B in 2010, so a run dated in between reads $39.6B.
+
+EDGAR needs no account or API key. Add the vendor to the chain:
+
+```python
+config["data_vendors"]["fundamental_data"] = "sec_edgar,yfinance"
+```
+
+SEC asks callers to identify themselves and refuses requests that carry no contact address, so a default one is sent. Set your own so SEC can reach you rather than the project:
+
+```bash
+SEC_EDGAR_USER_AGENT="Your Name your@email.com"
+```
+
+It covers companies that file with the SEC, including foreign companies listed in the US. Anything else, such as Hong Kong or A-share listings, falls through to the next vendor in the chain. EDGAR's machine-readable filings begin in 2009, and a fourth quarter is reported as unavailable rather than derived, because filers publish it only inside the annual figure.
+
+### Current holdings
+
+By default the agents do not know what you hold, so their guidance is written for a reader who applies it to their own position. Pass a portfolio to have the trader, the risk analysts and the portfolio manager work against your actual book.
+
+```python
+from tradingagents.portfolio import PortfolioContext
+
+portfolio = PortfolioContext.model_validate({
+ "cash": 25000.0,
+ "currency": "USD",
+ "positions": [{"ticker": "NVDA", "quantity": 120, "average_price": 150.0}],
+})
+_, decision = ta.propagate("NVDA", "2026-09-01", portfolio=portfolio)
+```
+
+The CLI takes the same content as a JSON file: `tradingagents --portfolio my_book.json`.
+
+An empty `positions` list means a flat book, which is different from passing nothing. A run without a portfolio is never treated as flat.
+
## Persistence and Recovery
TradingAgents persists two kinds of state across runs.
### Decision log
-The decision log is always on. Each completed run appends its decision to `~/.tradingagents/memory/trading_memory.md`. On the next run for the same ticker, TradingAgents fetches the realised return (raw and alpha vs SPY), generates a one-paragraph reflection, and injects the most recent same-ticker decisions plus recent cross-ticker lessons into the Portfolio Manager prompt, so each analysis carries forward what worked and what didn't.
+The decision log is always on. Each completed run appends its decision to `~/.tradingagents/memory/trading_memory.md`. On the next run for the same ticker, TradingAgents fetches the realised return (raw, and alpha against the instrument's regional benchmark), generates a one-paragraph reflection, and injects the most recent same-ticker decisions plus recent cross-ticker lessons into the Portfolio Manager prompt, so each analysis carries forward what worked and what didn't.
Override the path with `TRADINGAGENTS_MEMORY_LOG_PATH`.
### Checkpoint resume
-Checkpoint resume is opt-in via `--checkpoint`. When enabled, LangGraph saves state after each node so a crashed or interrupted run resumes from the last successful step instead of starting over. On a resume run you will see `Resuming from step N for on ` in the logs; on a new run you will see `Starting fresh`. Checkpoints are cleared automatically on successful completion.
+Checkpoint resume is opt-in via `--checkpoint`. When enabled, LangGraph saves state after each node so a crashed or interrupted run resumes from the last successful step instead of starting over. The run view says whether it resumed a saved run or started fresh. Checkpoints are cleared automatically on successful completion.
Per-ticker SQLite databases live at `~/.tradingagents/cache/checkpoints/.db` (override the base with `TRADINGAGENTS_CACHE_DIR`). Use `--clear-checkpoints` to reset all of them before a run.
```bash
-tradingagents analyze --checkpoint # enable for this run
-tradingagents analyze --clear-checkpoints # reset before running
+tradingagents --checkpoint # enable for this run
+tradingagents --clear-checkpoints # reset before running
```
```python
config = DEFAULT_CONFIG.copy()
config["checkpoint_enabled"] = True
ta = TradingAgentsGraph(config=config)
-_, decision = ta.propagate("NVDA", "2026-01-15")
+_, decision = ta.propagate("NVDA", "2026-09-01")
```
+## Evaluating decisions over time
+
+One run gives one decision, which cannot tell you whether the system decides well. `run_backtest` runs the same pipeline over a grid of tickers and dates, writes to a decision log of its own, and scores the decisions whose holding window has since traded.
+
+```python
+from tradingagents.backtest import iter_grid, run_backtest, summarize
+from tradingagents.agents.utils.memory import TradingMemoryLog
+
+dates = iter_grid("2026-06-01", "2026-08-01", every_n_days=7)
+result = run_backtest(["NVDA", "AAPL"], dates, config, selected_analysts=["market", "news"])
+print(summarize(TradingMemoryLog({"memory_log_path": str(result.log_path)})).render())
+```
+
+From the CLI:
+
+```bash
+tradingagents backtest NVDA,AAPL --start 2026-06-01 --end 2026-08-01 --every 7
+```
+
+Each cell is scored on realized alpha against the instrument's regional benchmark, grouped by rating. Your own decision log is never written to, and re-running the same grid with `run_id=result.run_id` skips the cells that already ran, so an interrupted sweep continues where it stopped.
+
## Reproducibility
TradingAgents is LLM-driven, so two runs of the same ticker and date can differ. This is expected for a research tool built on language models, not a defect. The variation comes from a few distinct sources, and it helps to separate them.
@@ -270,14 +348,14 @@ Language model sampling is non-deterministic. Even at a fixed temperature, provi
Live data moves. News, StockTwits, and Reddit return different content as time passes, so a run today sees different inputs than a run last week even for the same historical trade date. Pin the analysis date to hold the price and indicator window fixed, but the social and news sources still reflect "now".
-To reduce variation you can lower the sampling temperature. Set `temperature` in your config (or `TRADINGAGENTS_TEMPERATURE` in `.env`); lower values make models that honor it more repeatable. The current curated models are reasoning-first and largely ignore temperature, so for tighter reproducibility use a non-reasoning model, which you can set explicitly via the Custom model ID option.
+To reduce variation you can lower the sampling temperature. Set `temperature` in your config (or `TRADINGAGENTS_TEMPERATURE` in `.env`); lower values make models that honor it more repeatable. The current curated models are reasoning-first and largely ignore temperature, so for tighter reproducibility name a non-reasoning model in your config, or in `TRADINGAGENTS_DEEP_THINK_LLM` and `TRADINGAGENTS_QUICK_THINK_LLM`. Any model ID your provider serves is accepted, whether or not the picker lists it.
```python
config = DEFAULT_CONFIG.copy()
config["llm_provider"] = "openai"
config["temperature"] = 0.0
-# Reasoning models ignore temperature. For tighter reproducibility, set a
-# non-reasoning deep/quick model explicitly (e.g. via the Custom model ID option).
+# Reasoning models ignore temperature. For tighter reproducibility, name a
+# non-reasoning model in deep_think_llm / quick_think_llm.
```
What does not vary anymore: the analyzed company identity is resolved deterministically from the ticker before any agent runs, and the market analyst grounds exact price and indicator claims in a verified data snapshot. Earlier reports of "different companies" or fabricated price levels across runs are addressed by these two mechanisms.
diff --git a/cli/main.py b/cli/main.py
index b64487367..174740ad6 100644
--- a/cli/main.py
+++ b/cli/main.py
@@ -20,6 +20,7 @@ from rich.table import Table
from rich.text import Text
from cli.announcements import display_announcements, fetch_announcements
+from cli.prefs import load_last_run, sanitize, save_last_run
from cli.stats_handler import StatsCallbackHandler
from cli.utils import (
ask_anthropic_effort,
@@ -41,6 +42,9 @@ from cli.utils import (
select_research_depth,
select_shallow_thinking_agent,
)
+from tradingagents.agents.utils.rating import is_review
+from tradingagents.backtest import iter_grid, run_backtest, summarize
+from tradingagents.dataflows.utils import safe_ticker_component
from tradingagents.default_config import DEFAULT_CONFIG
from tradingagents.graph.analyst_execution import (
AnalystWallTimeTracker,
@@ -49,6 +53,7 @@ from tradingagents.graph.analyst_execution import (
sync_analyst_tracker_from_chunk,
)
from tradingagents.graph.trading_graph import TradingAgentsGraph
+from tradingagents.portfolio import load_portfolio
from tradingagents.reporting import write_report_tree
console = Console()
@@ -493,7 +498,14 @@ def update_display(layout, spinner_text=None, stats_handler=None, start_time=Non
def get_user_selections():
- """Get all user selections before starting the analysis display."""
+ """Ask for the run's settings, offering the previous run's answers."""
+ selections = _prompt_selections(load_last_run())
+ save_last_run(selections)
+ return selections
+
+
+def _prompt_selections(prefs):
+ """Walk the selection steps. ``prefs`` prefills, the environment skips."""
# Display ASCII art welcome message
with open(Path(__file__).parent / "static" / "welcome.txt", encoding="utf-8") as f:
welcome_ascii = f.read()
@@ -586,7 +598,7 @@ def get_user_selections():
"Select the language for analyst reports and final decision"
)
)
- output_language = ask_output_language()
+ output_language = ask_output_language(prefs.get("output_language"))
# Step 4: Select analysts
console.print(
@@ -594,7 +606,8 @@ def get_user_selections():
"Step 4: Analysts Team", "Select your LLM analyst agents for the analysis"
)
)
- selected_analysts = select_analysts(asset_type)
+ prefs = sanitize(prefs, asset_type.value)
+ selected_analysts = select_analysts(asset_type, prefs.get("analysts"))
console.print(
f"[green]Selected analysts:[/green] {', '.join(analyst.value for analyst in selected_analysts)}"
)
@@ -619,7 +632,7 @@ def get_user_selections():
"Step 5: Research Depth", "Select your research depth level"
)
)
- selected_research_depth = select_research_depth()
+ selected_research_depth = select_research_depth(prefs.get("research_depth"))
# Step 6: LLM Provider (skipped when set via TRADINGAGENTS_LLM_PROVIDER).
# The backend URL comes from TRADINGAGENTS_LLM_BACKEND_URL when set,
@@ -641,7 +654,7 @@ def get_user_selections():
"Step 6: LLM Provider", "Select your LLM provider"
)
)
- selected_llm_provider, backend_url = select_llm_provider()
+ selected_llm_provider, backend_url = select_llm_provider(prefs.get("llm_provider"))
# Providers with regional endpoints prompt for the region as a secondary
# step so the main dropdown stays clean (mainland China and international
@@ -662,7 +675,9 @@ def get_user_selections():
# The generic OpenAI-compatible endpoint has no default; ask for it if
# neither the menu nor the environment supplied one.
if selected_llm_provider == "openai_compatible" and not backend_url:
- backend_url = prompt_openai_compatible_url()
+ remembered_url = (prefs.get("backend_url")
+ if prefs.get("llm_provider") == selected_llm_provider else None)
+ backend_url = prompt_openai_compatible_url(remembered_url)
# For Ollama, surface the resolved endpoint (OLLAMA_BASE_URL vs default)
# before model selection so it's obvious where we're connecting.
@@ -688,8 +703,13 @@ def get_user_selections():
"Step 7: Thinking Agents", "Select your thinking agents for analysis"
)
)
- selected_shallow_thinker = select_shallow_thinking_agent(selected_llm_provider)
- selected_deep_thinker = select_deep_thinking_agent(selected_llm_provider)
+ remembered = prefs if prefs.get("llm_provider") == selected_llm_provider else {}
+ selected_shallow_thinker = select_shallow_thinking_agent(
+ selected_llm_provider, remembered.get("quick_think_llm")
+ )
+ selected_deep_thinker = select_deep_thinking_agent(
+ selected_llm_provider, remembered.get("deep_think_llm")
+ )
# Step 8: Provider-specific reasoning/thinking configuration. Each knob is
# settable via its TRADINGAGENTS_* env var; when that var is set (or the
@@ -732,8 +752,8 @@ def get_user_selections():
"research_depth": selected_research_depth,
"llm_provider": selected_llm_provider.lower(),
"backend_url": backend_url,
- "shallow_thinker": selected_shallow_thinker,
- "deep_thinker": selected_deep_thinker,
+ "quick_think_llm": selected_shallow_thinker,
+ "deep_think_llm": selected_deep_thinker,
"google_thinking_level": thinking_level,
"openai_reasoning_effort": reasoning_effort,
"anthropic_effort": anthropic_effort,
@@ -900,21 +920,16 @@ def extract_content_string(content):
"""Extract string content from various message formats.
Returns None if no meaningful text content is found.
"""
- import ast
-
def is_empty(val):
- """Check if value is empty using Python's truthiness."""
- if val is None or val == '':
- return True
+ """Whether a value carries nothing to show.
+
+ Text is judged by whether anything was written, not by what it would
+ mean as Python: a report saying "0" or "None" is a message the run
+ produced, and reading it as a falsy literal dropped it from the display.
+ """
if isinstance(val, str):
- s = val.strip()
- if not s:
- return True
- try:
- return not bool(ast.literal_eval(s))
- except (ValueError, SyntaxError):
- return False # Can't parse = real text
- return not bool(val)
+ return not val.strip()
+ return val is None or not bool(val)
if is_empty(content):
return None
@@ -971,6 +986,29 @@ def format_tool_args(args, max_length=80) -> str:
return result[:max_length - 3] + "..."
return result
+def _run_directory(config: dict, ticker: str, trade_date: str) -> Path:
+ """Where this run writes, with the ticker validated as a path component.
+
+ Every other path that interpolates a ticker checks it first; a value of
+ ".." here would place the run outside the results directory.
+ """
+ return Path(config["results_dir"]) / safe_ticker_component(ticker) / trade_date
+
+
+def _announce_checkpoint_state(graph, ticker: str, trade_date: str) -> None:
+ """Say whether this run resumed a saved one, where the user can see it.
+
+ The graph logs this, but nothing in the CLI configures logging and the live
+ view owns the screen, so a resume was invisible.
+ """
+ if getattr(graph, "_resuming", False):
+ message_buffer.add_message(
+ "System", f"Resuming the saved run for {ticker} on {trade_date}"
+ )
+ else:
+ message_buffer.add_message("System", f"Starting fresh for {ticker} on {trade_date}")
+
+
def _build_run_config(selections: dict, checkpoint: bool | None) -> dict:
"""Assemble the run config from interactive selections, honoring env precedence.
@@ -981,12 +1019,19 @@ def _build_run_config(selections: dict, checkpoint: bool | None) -> dict:
# Research depth sets both round counts, but an explicit env override
# (TRADINGAGENTS_MAX_DEBATE_ROUNDS / _MAX_RISK_ROUNDS) wins over the
# interactive selection — leave the env-applied value in place (#977).
- if not os.environ.get("TRADINGAGENTS_MAX_DEBATE_ROUNDS"):
- config["max_debate_rounds"] = selections["research_depth"]
- if not os.environ.get("TRADINGAGENTS_MAX_RISK_ROUNDS"):
- config["max_risk_discuss_rounds"] = selections["research_depth"]
- config["quick_think_llm"] = selections["shallow_thinker"]
- config["deep_think_llm"] = selections["deep_thinker"]
+ for env_var, key in (("TRADINGAGENTS_MAX_DEBATE_ROUNDS", "max_debate_rounds"),
+ ("TRADINGAGENTS_MAX_RISK_ROUNDS", "max_risk_discuss_rounds")):
+ if os.environ.get(env_var):
+ # The depth prompt still appeared (it is skipped only when both are
+ # set), so say which half of the answer the environment overrode.
+ console.print(
+ f"[green]✓ {key} from environment:[/green] {config[key]} "
+ f"(set by {env_var}, so the research depth you chose does not apply to it)"
+ )
+ else:
+ config[key] = selections["research_depth"]
+ config["quick_think_llm"] = selections["quick_think_llm"]
+ config["deep_think_llm"] = selections["deep_think_llm"]
config["backend_url"] = selections["backend_url"]
config["llm_provider"] = selections["llm_provider"].lower()
# Provider-specific thinking configuration
@@ -1001,7 +1046,7 @@ def _build_run_config(selections: dict, checkpoint: bool | None) -> dict:
return config
-def run_analysis(checkpoint: bool | None = None):
+def run_analysis(checkpoint: bool | None = None, portfolio=None):
# First get all user selections
selections = get_user_selections()
@@ -1031,7 +1076,7 @@ def run_analysis(checkpoint: bool | None = None):
start_time = time.time()
# Create result directory
- results_dir = Path(config["results_dir"]) / selections["ticker"] / selections["analysis_date"]
+ results_dir = _run_directory(config, selections["ticker"], selections["analysis_date"])
results_dir.mkdir(parents=True, exist_ok=True)
report_dir = results_dir / "reports"
report_dir.mkdir(parents=True, exist_ok=True)
@@ -1081,7 +1126,9 @@ def run_analysis(checkpoint: bool | None = None):
# Now start the display layout
layout = create_layout()
- with Live(layout, refresh_per_second=4):
+ # The alternate screen keeps a layout taller than the window from redrawing
+ # by scrolling; the final report prints after this block, on the normal screen.
+ with Live(layout, refresh_per_second=4, screen=True):
# Initial display
update_display(layout, stats_handler=stats_handler, start_time=start_time)
@@ -1110,18 +1157,10 @@ def run_analysis(checkpoint: bool | None = None):
)
update_display(layout, spinner_text, stats_handler=stats_handler, start_time=start_time)
- # Initialize state and get graph args with callbacks.
- # Resolve the instrument identity once here so all agents anchor to
- # the real company (#814); the CLI builds state directly rather than
- # going through propagate(), so this must happen on the CLI path too.
- instrument_context = graph.resolve_instrument_context(
- selections["ticker"], selections["asset_type"]
- )
- init_agent_state = graph.propagator.create_initial_state(
- selections["ticker"],
- selections["analysis_date"],
- asset_type=selections["asset_type"],
- instrument_context=instrument_context,
+ # The same initial state propagate() builds: settled decision log, past
+ # context and resolved instrument identity.
+ init_agent_state = graph.create_run_state(
+ selections["ticker"], selections["analysis_date"], selections["asset_type"], portfolio
)
# Pass callbacks to graph config for tool execution tracking
# (LLM tracking is handled separately via LLM constructor)
@@ -1131,7 +1170,7 @@ def run_analysis(checkpoint: bool | None = None):
# actually saves and resumes on the CLI path (#1249); a no-op when
# checkpointing is disabled. Torn down in the finally below.
checkpoint_tid = graph.begin_checkpoint(
- selections["ticker"], selections["analysis_date"], selections["asset_type"]
+ selections["ticker"], selections["analysis_date"], selections["asset_type"], portfolio
)
if checkpoint_tid is not None:
args.setdefault("config", {}).setdefault("configurable", {})["thread_id"] = checkpoint_tid
@@ -1243,21 +1282,23 @@ def run_analysis(checkpoint: bool | None = None):
trace.append(chunk)
- # Clean run: drop this run's checkpoint so a later run starts fresh.
- # A mid-stream failure skips this, keeping the checkpoint for resume.
+ # Streamed chunks are per-node deltas, not full state. Merge them
+ # so every report field populated across the run is present.
+ final_state = {}
+ for chunk in trace:
+ final_state.update(chunk)
+
+ # Clean run: log the decision, then drop this run's checkpoint so a
+ # later run starts fresh. A mid-stream failure skips both, keeping
+ # the checkpoint for resume.
+ graph.record_decision(selections["ticker"], selections["analysis_date"], final_state)
graph.clear_checkpoint_on_success(
- selections["ticker"], selections["analysis_date"], selections["asset_type"]
+ selections["ticker"], selections["analysis_date"], selections["asset_type"], portfolio
)
finally:
# Always restore the plain uncheckpointed graph, even on failure.
graph.end_checkpoint()
- # Streamed chunks are per-node deltas, not full state. Merge them
- # so every report field populated across the run is present.
- final_state = {}
- for chunk in trace:
- final_state.update(chunk)
-
# Update all agent statuses to completed
for agent in message_buffer.agent_status:
message_buffer.update_agent_status(agent, "completed")
@@ -1276,13 +1317,26 @@ def run_analysis(checkpoint: bool | None = None):
# Post-analysis prompts (outside Live context for clean interaction)
console.print("\n[bold cyan]Analysis Complete![/bold cyan]\n")
+
+ # A decision nobody can read is not a position. Say so here rather than
+ # leaving the run to look like a normal result.
+ if is_review(graph.process_signal(final_state.get("final_trade_decision", ""))):
+ console.print(
+ "[yellow]No rating could be read from the final decision, so this run "
+ "is recorded for review rather than as a position. Re-run, or read the "
+ "decision text below and judge it yourself.[/yellow]\n"
+ )
console.print(f"[dim]{analyst_wall_time_tracker.format_summary()}[/dim]")
# Prompt to save report
save_choice = typer.prompt("Save report?", default="Y").strip().upper()
if save_choice in ("Y", "YES", ""):
timestamp = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
- default_path = Path.cwd() / "reports" / f"{selections['ticker']}_{timestamp}"
+ # Under results_dir, not the working directory: in Docker the working
+ # directory is inside the container and the report goes with it, while
+ # results_dir is the mounted volume the rest of the run already writes to.
+ default_path = (Path(config["results_dir"]) / "reports"
+ / f"{safe_ticker_component(selections['ticker'])}_{timestamp}")
save_path_str = typer.prompt(
"Save path (press Enter for default)",
default=str(default_path)
@@ -1301,8 +1355,9 @@ def run_analysis(checkpoint: bool | None = None):
display_complete_report(final_state)
-@app.command()
+@app.callback(invoke_without_command=True)
def analyze(
+ ctx: typer.Context,
checkpoint: bool | None = typer.Option(
None,
"--checkpoint/--no-checkpoint",
@@ -1314,13 +1369,31 @@ def analyze(
"--clear-checkpoints",
help="Delete all saved checkpoints before running (force fresh start).",
),
+ portfolio: str = typer.Option(
+ None,
+ "--portfolio",
+ help="JSON file with current holdings and cash, so the trader, risk and "
+ "portfolio agents size against your actual position.",
+ ),
):
+ """Run an analysis. This is what a bare `tradingagents` does."""
+ if ctx.invoked_subcommand is not None:
+ return
if clear_checkpoints:
from tradingagents.graph.checkpointer import clear_all_checkpoints
n = clear_all_checkpoints(DEFAULT_CONFIG["data_cache_dir"])
console.print(f"[yellow]Cleared {n} checkpoint(s).[/yellow]")
+ portfolio_context = None
+ if portfolio:
+ from tradingagents.portfolio import load_portfolio
+ try:
+ portfolio_context = load_portfolio(portfolio)
+ except ValueError as exc:
+ console.print(f"[red]{exc}[/red]")
+ raise typer.Exit(code=1) from None
+
try:
- run_analysis(checkpoint=checkpoint)
+ run_analysis(checkpoint=checkpoint, portfolio=portfolio_context)
except _NO_CONSOLE_ERRORS:
# A terminal with no console buffer cannot host the interactive prompts.
# Emit one actionable line on stderr instead of a prompt_toolkit
@@ -1334,5 +1407,54 @@ def analyze(
raise typer.Exit(code=1) from None
+@app.command()
+def backtest(
+ tickers: str = typer.Argument(..., help="Comma-separated tickers, e.g. NVDA,AAPL"),
+ start: str = typer.Option(..., "--start", help="First analysis date, YYYY-MM-DD"),
+ end: str = typer.Option(..., "--end", help="Last analysis date, YYYY-MM-DD"),
+ every: int = typer.Option(7, "--every", help="Days between analysis dates"),
+ analysts: str = typer.Option(
+ None, "--analysts", help="Comma-separated analysts to run; omit for all four"
+ ),
+ asset_type: str = typer.Option("stock", "--asset-type", help="stock or crypto"),
+ portfolio: str = typer.Option(
+ None, "--portfolio", help="JSON file with holdings and cash, held constant across the grid"
+ ),
+ run_id: str = typer.Option(
+ None, "--run-id", help="Continue an earlier sweep: its cells are skipped and its log reused"
+ ),
+):
+ """Score past decisions over a grid of tickers and dates."""
+ from tradingagents.agents.utils.memory import TradingMemoryLog
+
+ try:
+ dates = iter_grid(start, end, every)
+ book = load_portfolio(portfolio) if portfolio else None
+ except ValueError as exc:
+ console.print(f"[red]{exc}[/red]")
+ raise typer.Exit(code=1) from None
+
+ names = [t.strip() for t in tickers.split(",") if t.strip()]
+ if not names:
+ console.print("[red]No ticker to analyze; pass them comma-separated, e.g. NVDA,AAPL[/red]")
+ raise typer.Exit(code=1)
+
+ kwargs = {"asset_type": asset_type, "portfolio": book, "run_id": run_id}
+ if analysts:
+ kwargs["selected_analysts"] = [a.strip().lower() for a in analysts.split(",") if a.strip()]
+
+ try:
+ result = run_backtest(names, dates, DEFAULT_CONFIG, **kwargs)
+ except Exception as exc: # a missing key or an unknown analyst is a setup error
+ console.print(f"[red]{exc}[/red]")
+ raise typer.Exit(code=1) from None
+ console.print(summarize(TradingMemoryLog({"memory_log_path": str(result.log_path)})).render())
+ console.print(f"\nRan {result.cells_run} cells, skipped {result.skipped}. Log: {result.log_path}")
+ for ticker, date, reason in result.failures:
+ console.print(f"[yellow]failed:[/yellow] {ticker} {date}: {reason}")
+ for ticker, reason in result.settlement_failures:
+ console.print(f"[yellow]unsettled:[/yellow] {ticker}: {reason}")
+
+
if __name__ == "__main__":
app()
diff --git a/cli/prefs.py b/cli/prefs.py
new file mode 100644
index 000000000..711756f85
--- /dev/null
+++ b/cli/prefs.py
@@ -0,0 +1,91 @@
+"""What the last run chose, offered back as the next run's defaults.
+
+The interactive flow asks the same questions every time, and only some of them
+have an environment variable to skip them (the analyst set has none). Remembered
+answers prefill the prompts so Enter accepts them; they never skip a step, so a
+run always starts on choices the user has seen.
+
+Only answers that are stable between runs are kept. The ticker and the analysis
+date are not: they change every run, and a remembered date would quietly offer a
+stale one.
+
+Every value is checked against the current choices on the way out, because
+models and providers are added and retired between versions. A remembered model
+that is no longer offered is dropped rather than shown.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from cli.models import AnalystType, AssetType
+from cli.utils import _llm_provider_table, filter_analysts_for_asset_type
+from tradingagents.llm_clients.model_catalog import get_model_options
+
+_PREFS_PATH = Path(os.path.expanduser("~")) / ".tradingagents" / "cli_prefs.json"
+
+REMEMBERED = (
+ "output_language", "analysts", "research_depth", "llm_provider",
+ "quick_think_llm", "deep_think_llm", "backend_url",
+)
+
+
+def load_last_run() -> dict:
+ """The previous run's answers, or an empty dict when there is nothing usable.
+
+ Convenience state: an unreadable or corrupt file means no defaults, never an
+ error in the user's way.
+ """
+ try:
+ data = json.loads(_PREFS_PATH.read_text(encoding="utf-8"))
+ return data if isinstance(data, dict) else {}
+ except (OSError, ValueError):
+ return {}
+
+
+def save_last_run(selections: dict) -> None:
+ """Record the answers worth offering next time; failure is never fatal."""
+ kept = {k: v for k, v in selections.items() if k in REMEMBERED and v not in (None, "", [])}
+ kept["analysts"] = [getattr(a, "value", a) for a in kept.get("analysts", [])] or None
+ kept = {k: v for k, v in kept.items() if v is not None}
+ try:
+ _PREFS_PATH.parent.mkdir(parents=True, exist_ok=True)
+ temp = _PREFS_PATH.with_suffix(".tmp")
+ temp.write_text(json.dumps(kept, indent=2), encoding="utf-8")
+ os.replace(temp, _PREFS_PATH) # a concurrent run reads one file or the other
+ except OSError:
+ return
+
+
+def sanitize(prefs: dict, asset_type) -> dict:
+ """Keep only the remembered answers that are still choosable now."""
+ kept: dict = {}
+ if isinstance(prefs.get("output_language"), str):
+ kept["output_language"] = prefs["output_language"]
+ if prefs.get("research_depth") in (1, 3, 5):
+ kept["research_depth"] = prefs["research_depth"]
+
+ known = {a.value for a in AnalystType}
+ analysts = [a for a in prefs.get("analysts") or [] if a in known]
+ allowed = filter_analysts_for_asset_type([AnalystType(a) for a in analysts], AssetType(asset_type))
+ if allowed:
+ kept["analysts"] = [a.value for a in allowed]
+
+ provider = prefs.get("llm_provider")
+ # Region-specific providers (qwen-cn) are picked in a second prompt, so the
+ # base key is what the provider menu matches.
+ base = (provider or "").split("-cn")[0]
+ if base and base in {key for _, key, _ in _llm_provider_table()}:
+ kept["llm_provider"] = provider
+ if isinstance(prefs.get("backend_url"), str) and prefs["backend_url"]:
+ kept["backend_url"] = prefs["backend_url"]
+ for field, mode in (("quick_think_llm", "quick"), ("deep_think_llm", "deep")):
+ try:
+ offered = {model for _, model in get_model_options(base, mode)}
+ except KeyError:
+ continue
+ if prefs.get(field) in offered:
+ kept[field] = prefs[field]
+ return kept
diff --git a/cli/utils.py b/cli/utils.py
index da8524d2d..d3cca0cdf 100644
--- a/cli/utils.py
+++ b/cli/utils.py
@@ -132,8 +132,16 @@ def get_analysis_date() -> str:
return date.strip()
-def select_analysts(asset_type: AssetType = AssetType.STOCK) -> list[AnalystType]:
- """Select analysts using an interactive checkbox."""
+def _matching_choice(options, default):
+ """The option value equal to ``default``, or None to leave the menu as is."""
+ return next((value for _, value in options if value == default), None)
+
+
+def select_analysts(asset_type: AssetType = AssetType.STOCK, default=None) -> list[AnalystType]:
+ """Select analysts using an interactive checkbox.
+
+ ``default`` pre-checks the previous run's analysts; the prompt still shows.
+ """
available_analysts = filter_analysts_for_asset_type(
[value for _, value in ANALYST_ORDER],
asset_type,
@@ -141,7 +149,7 @@ def select_analysts(asset_type: AssetType = AssetType.STOCK) -> list[AnalystType
choices = questionary.checkbox(
"Select Your [Analysts Team]:",
choices=[
- questionary.Choice(display, value=value)
+ questionary.Choice(display, value=value, checked=value.value in (default or []))
for display, value in ANALYST_ORDER
if value in available_analysts
],
@@ -164,7 +172,7 @@ def select_analysts(asset_type: AssetType = AssetType.STOCK) -> list[AnalystType
return choices
-def select_research_depth() -> int:
+def select_research_depth(default=None) -> int:
"""Select research depth using an interactive selection."""
# Define research depth options with their corresponding values
@@ -179,6 +187,7 @@ def select_research_depth() -> int:
choices=[
questionary.Choice(display, value=value) for display, value in DEPTH_OPTIONS
],
+ default=_matching_choice(DEPTH_OPTIONS, default),
instruction="\n- Use arrow keys to navigate\n- Press Enter to select",
style=questionary.Style(
[
@@ -289,7 +298,7 @@ def _prompt_custom_model_id() -> str:
return _require_text("Enter model ID:", "Please enter a model ID.")
-def _select_model(provider: str, mode: str) -> str:
+def _select_model(provider: str, mode: str, default=None) -> str:
"""Select a model for the given provider and mode (quick/deep)."""
if provider.lower() == "openrouter":
return select_openrouter_model(mode)
@@ -306,6 +315,7 @@ def _select_model(provider: str, mode: str) -> str:
questionary.Choice(display, value=value)
for display, value in get_model_options(provider, mode)
],
+ default=_matching_choice(get_model_options(provider, mode), default),
instruction="\n- Use arrow keys to navigate\n- Press Enter to select",
style=questionary.Style(
[
@@ -326,14 +336,14 @@ def _select_model(provider: str, mode: str) -> str:
return choice
-def select_shallow_thinking_agent(provider) -> str:
+def select_shallow_thinking_agent(provider, default=None) -> str:
"""Select shallow thinking llm engine using an interactive selection."""
- return _select_model(provider, "quick")
+ return _select_model(provider, "quick", default)
-def select_deep_thinking_agent(provider) -> str:
+def select_deep_thinking_agent(provider, default=None) -> str:
"""Select deep thinking llm engine using an interactive selection."""
- return _select_model(provider, "deep")
+ return _select_model(provider, "deep", default)
def _llm_provider_table() -> list[tuple[str, str, str | None]]:
"""(display_name, provider_key, base_url) for every supported provider.
@@ -352,7 +362,9 @@ def _llm_provider_table() -> list[tuple[str, str, str | None]]:
("xAI", "xai", "https://api.x.ai/v1"),
("DeepSeek", "deepseek", "https://api.deepseek.com"),
("Qwen", "qwen", "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"),
- ("GLM", "glm", "https://open.bigmodel.cn/api/paas/v4/"),
+ # Z.AI international, the platform ZHIPU_API_KEY belongs to; the CN
+ # platform is the separate glm-cn key, chosen in the region prompt.
+ ("GLM", "glm", "https://api.z.ai/api/paas/v4/"),
("MiniMax", "minimax", "https://api.minimax.io/v1"),
("OpenRouter", "openrouter", "https://openrouter.ai/api/v1"),
("Mistral", "mistral", "https://api.mistral.ai/v1"),
@@ -388,11 +400,12 @@ def resolve_backend_url(
return env_url or menu_url or provider_default_url(provider)
-def prompt_openai_compatible_url() -> str:
+def prompt_openai_compatible_url(default=None) -> str:
"""Prompt for a custom OpenAI-compatible endpoint base URL."""
url = questionary.text(
"Enter the OpenAI-compatible base URL "
"(e.g. http://localhost:8000/v1 for vLLM, http://localhost:1234/v1 for LM Studio):",
+ default=default or "",
validate=lambda x: x.strip().startswith(("http://", "https://"))
or "Enter a URL starting with http:// or https://",
).ask()
@@ -402,9 +415,15 @@ def prompt_openai_compatible_url() -> str:
return url.strip()
-def select_llm_provider() -> tuple[str, str | None]:
+def select_llm_provider(default=None) -> tuple[str, str | None]:
"""Select the LLM provider and its API endpoint."""
PROVIDERS = _llm_provider_table()
+ # A region-specific key (qwen-cn) is chosen in a later prompt; the menu
+ # lists the base provider.
+ base = (default or "").split("-cn")[0]
+ preselected = next(
+ ((key, url) for _, key, url in PROVIDERS if key == base), None
+ )
choice = questionary.select(
"Select your LLM Provider:",
@@ -412,6 +431,7 @@ def select_llm_provider() -> tuple[str, str | None]:
questionary.Choice(display, value=(provider_key, url))
for display, provider_key, url in PROVIDERS
],
+ default=preselected,
instruction="\n- Use arrow keys to navigate\n- Press Enter to select",
style=questionary.Style(
[
@@ -458,9 +478,9 @@ def ask_anthropic_effort() -> str | None:
return questionary.select(
"Select Effort Level:",
choices=[
- questionary.Choice("High (recommended)", "high"),
- questionary.Choice("Medium (balanced)", "medium"),
- questionary.Choice("Low (faster, cheaper)", "low"),
+ questionary.Choice("High (recommended)", "high"),
+ questionary.Choice("Medium (balanced)", "medium"),
+ questionary.Choice("Low (faster, cheaper)", "low"),
],
style=questionary.Style([
("selected", "fg:cyan noinherit"),
@@ -479,8 +499,8 @@ def ask_gemini_thinking_config() -> str | None:
return questionary.select(
"Select Thinking Mode:",
choices=[
- questionary.Choice("Enable Thinking (recommended)", "high"),
- questionary.Choice("Minimal/Disable Thinking", "minimal"),
+ questionary.Choice("Enable Thinking (recommended)", "high"),
+ questionary.Choice("Minimal/Disable Thinking", "minimal"),
],
style=questionary.Style([
("selected", "fg:green noinherit"),
@@ -643,31 +663,41 @@ def ensure_api_key(provider: str) -> str | None:
return None
env_path = find_dotenv(usecwd=True) or str(Path.cwd() / ".env")
- Path(env_path).touch(exist_ok=True)
+ # The file holds credentials, so make it owner-only before writing: create
+ # it 0600 when absent, and tighten an existing one (set_key keeps the mode).
+ if not os.path.exists(env_path):
+ os.close(os.open(env_path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600))
+ os.chmod(env_path, 0o600)
set_key(env_path, env_var, key)
os.environ[env_var] = key
console.print(f"[green]Saved {env_var} to {env_path}[/green]")
return key
-def ask_output_language() -> str:
- """Ask for report output language."""
+def ask_output_language(default=None) -> str:
+ """Ask for report output language.
+
+ ``default`` is offered only when it is one of the listed languages: a custom
+ one entered last time is free text, which the menu cannot preselect.
+ """
+ choices = [
+ questionary.Choice("English (default)", "English"),
+ questionary.Choice("Chinese (中文)", "Chinese"),
+ questionary.Choice("Japanese (日本語)", "Japanese"),
+ questionary.Choice("Korean (한국어)", "Korean"),
+ questionary.Choice("Hindi (हिन्दी)", "Hindi"),
+ questionary.Choice("Spanish (Español)", "Spanish"),
+ questionary.Choice("Portuguese (Português)", "Portuguese"),
+ questionary.Choice("French (Français)", "French"),
+ questionary.Choice("German (Deutsch)", "German"),
+ questionary.Choice("Arabic (العربية)", "Arabic"),
+ questionary.Choice("Russian (Русский)", "Russian"),
+ questionary.Choice("Custom language", "custom"),
+ ]
choice = questionary.select(
"Select Output Language:",
- choices=[
- questionary.Choice("English (default)", "English"),
- questionary.Choice("Chinese (中文)", "Chinese"),
- questionary.Choice("Japanese (日本語)", "Japanese"),
- questionary.Choice("Korean (한국어)", "Korean"),
- questionary.Choice("Hindi (हिन्दी)", "Hindi"),
- questionary.Choice("Spanish (Español)", "Spanish"),
- questionary.Choice("Portuguese (Português)", "Portuguese"),
- questionary.Choice("French (Français)", "French"),
- questionary.Choice("German (Deutsch)", "German"),
- questionary.Choice("Arabic (العربية)", "Arabic"),
- questionary.Choice("Russian (Русский)", "Russian"),
- questionary.Choice("Custom language", "custom"),
- ],
+ choices=choices,
+ default=_matching_choice([(c.title, c.value) for c in choices], default),
style=questionary.Style([
("selected", "fg:yellow noinherit"),
("highlighted", "fg:yellow noinherit"),
diff --git a/main.py b/main.py
index c9d3ab038..d3a13d678 100644
--- a/main.py
+++ b/main.py
@@ -12,8 +12,7 @@ config = DEFAULT_CONFIG.copy()
ta = TradingAgentsGraph(debug=True, config=config)
# forward propagate
-_, decision = ta.propagate("NVDA", "2024-05-10")
+_, decision = ta.propagate("NVDA", "2026-09-01")
print(decision)
# Memorize mistakes and reflect
-# ta.reflect_and_remember(1000) # parameter is the position returns
diff --git a/pyproject.toml b/pyproject.toml
index a543311e5..1b15d65b6 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,31 +4,25 @@ build-backend = "setuptools.build_meta"
[project]
name = "tradingagents"
-version = "0.4.0"
+version = "0.5.0"
description = "TradingAgents: Multi-Agents LLM Financial Trading Framework"
readme = "README.md"
requires-python = ">=3.10"
dependencies = [
"langchain-core>=0.3.81",
- "backtrader>=1.9.78.123",
"langchain-anthropic>=0.3.15",
- "langchain-experimental>=0.3.4",
"langchain-google-genai>=4.0.0",
"langchain-openai>=0.3.23",
"langgraph>=0.4.8",
"langgraph-checkpoint-sqlite>=2.0.0",
"pandas>=2.3.0",
- "parsel>=1.10.0",
"python-dotenv>=1.0.0",
"pytz>=2025.2",
"questionary>=2.1.0",
- "redis>=6.2.0",
"requests>=2.32.4",
"rich>=14.0.0",
"typer>=0.21.0",
- "setuptools>=80.9.0",
"stockstats>=0.6.5",
- "tqdm>=4.67.1",
"typing-extensions>=4.14.0",
"yfinance>=1.4.1",
]
diff --git a/scripts/smoke_structured_output.py b/scripts/smoke_structured_output.py
deleted file mode 100644
index f225381f9..000000000
--- a/scripts/smoke_structured_output.py
+++ /dev/null
@@ -1,174 +0,0 @@
-"""End-to-end smoke for structured-output agents against a real LLM provider.
-
-Runs the three decision-making agents (Research Manager, Trader, Portfolio
-Manager) directly with their structured-output bindings and prints the
-typed Pydantic instance + the rendered markdown for each. Use this to
-verify a provider's native structured-output mode (json_schema for
-OpenAI / xAI / DeepSeek / Qwen / GLM, response_schema for Gemini, tool-use
-for Anthropic) returns clean instances on the schemas we ship.
-
-Usage:
- OPENAI_API_KEY=... python scripts/smoke_structured_output.py openai
- GOOGLE_API_KEY=... python scripts/smoke_structured_output.py google
- ANTHROPIC_API_KEY=... python scripts/smoke_structured_output.py anthropic
- DEEPSEEK_API_KEY=... python scripts/smoke_structured_output.py deepseek
-
-The script does NOT call propagate(), to keep the surface tight and the
-cost low — it exercises only the three structured-output calls we just
-added, plus the heuristic SignalProcessor.
-"""
-
-from __future__ import annotations
-
-import argparse
-import sys
-
-from tradingagents.agents.managers.portfolio_manager import create_portfolio_manager
-from tradingagents.agents.managers.research_manager import create_research_manager
-from tradingagents.agents.trader.trader import create_trader
-from tradingagents.graph.signal_processing import SignalProcessor
-from tradingagents.llm_clients import create_llm_client
-
-PROVIDER_DEFAULTS = {
- "openai": ("gpt-5.4-mini", None),
- "google": ("gemini-3.5-flash", None),
- "anthropic": ("claude-sonnet-4-6", None),
- "deepseek": ("deepseek-v4-flash", None),
- "qwen": ("qwen3.7-plus", None),
- "glm": ("glm-5", None),
- "xai": ("grok-4.3", None),
-}
-
-
-# Minimal but realistic state for the three agents.
-DEBATE_HISTORY = """
-Bull Analyst: NVDA's data-center revenue grew 60% YoY last quarter, driven by
-Blackwell ramp; sovereign AI deals with multiple governments add a $40B+
-multi-year tailwind. Margins remain above peer average.
-
-Bear Analyst: Concentration risk is real — top three customers are >40% of
-revenue. Any pause in hyperscaler capex would compress the multiple. China
-export restrictions still cap a meaningful portion of demand.
-"""
-
-
-def _make_rm_state():
- return {
- "company_of_interest": "NVDA",
- "investment_debate_state": {
- "history": DEBATE_HISTORY,
- "bull_history": "Bull Analyst: NVDA's data-center revenue grew 60% YoY...",
- "bear_history": "Bear Analyst: Concentration risk is real...",
- "current_response": "",
- "judge_decision": "",
- "count": 1,
- },
- }
-
-
-def _make_trader_state(investment_plan: str):
- return {
- "company_of_interest": "NVDA",
- "investment_plan": investment_plan,
- }
-
-
-def _make_pm_state(investment_plan: str, trader_plan: str):
- return {
- "company_of_interest": "NVDA",
- "past_context": "",
- "risk_debate_state": {
- "history": "Aggressive: lean in. Conservative: trim. Neutral: balanced sizing.",
- "aggressive_history": "Aggressive: ...",
- "conservative_history": "Conservative: ...",
- "neutral_history": "Neutral: ...",
- "judge_decision": "",
- "current_aggressive_response": "",
- "current_conservative_response": "",
- "current_neutral_response": "",
- "count": 1,
- },
- "market_report": "Market report.",
- "sentiment_report": "Sentiment report.",
- "news_report": "News report.",
- "fundamentals_report": "Fundamentals report.",
- "investment_plan": investment_plan,
- "trader_investment_plan": trader_plan,
- }
-
-
-def _print_section(title: str, content: str) -> None:
- bar = "=" * 70
- print(f"\n{bar}\n{title}\n{bar}\n{content}")
-
-
-def main() -> int:
- parser = argparse.ArgumentParser(description=__doc__)
- parser.add_argument("provider", choices=list(PROVIDER_DEFAULTS.keys()))
- parser.add_argument("--deep-model", default=None, help="Override deep_think_llm")
- parser.add_argument("--quick-model", default=None, help="Override quick_think_llm")
- args = parser.parse_args()
-
- default_model, _ = PROVIDER_DEFAULTS[args.provider]
- deep_model = args.deep_model or default_model
- quick_model = args.quick_model or default_model
-
- print(f"Provider: {args.provider}")
- print(f"Deep model: {deep_model}")
- print(f"Quick model: {quick_model}")
-
- # Build the LLM clients via the framework's factory.
- deep_client = create_llm_client(provider=args.provider, model=deep_model)
- quick_client = create_llm_client(provider=args.provider, model=quick_model)
- deep_llm = deep_client.get_llm()
- quick_llm = quick_client.get_llm()
-
- # 1) Research Manager
- rm = create_research_manager(deep_llm)
- rm_result = rm(_make_rm_state())
- investment_plan = rm_result["investment_plan"]
- _print_section("[1] Research Manager — investment_plan", investment_plan)
-
- # 2) Trader (consumes RM's plan)
- trader = create_trader(quick_llm)
- trader_result = trader(_make_trader_state(investment_plan))
- trader_plan = trader_result["trader_investment_plan"]
- _print_section("[2] Trader — trader_investment_plan", trader_plan)
-
- # 3) Portfolio Manager (consumes both)
- pm = create_portfolio_manager(deep_llm)
- pm_result = pm(_make_pm_state(investment_plan, trader_plan))
- final_decision = pm_result["final_trade_decision"]
- _print_section("[3] Portfolio Manager — final_trade_decision", final_decision)
-
- # 4) SignalProcessor extracts the rating with zero LLM calls.
- sp = SignalProcessor()
- rating = sp.process_signal(final_decision)
- _print_section("[4] SignalProcessor → rating", rating)
-
- # 5) Lightweight checks: each rendered output should carry the expected
- # section headers so downstream consumers (memory log, CLI display,
- # saved reports) keep working.
- checks = [
- ("Research Manager", investment_plan, ["**Recommendation**:"]),
- ("Trader", trader_plan, ["**Action**:", "FINAL TRANSACTION PROPOSAL:"]),
- ("Portfolio Manager", final_decision, ["**Rating**:", "**Executive Summary**:", "**Investment Thesis**:"]),
- ]
- print("\n" + "=" * 70 + "\nStructure checks\n" + "=" * 70)
- failures = 0
- for name, text, required in checks:
- for marker in required:
- ok = marker in text
- print(f" {'PASS' if ok else 'FAIL'} {name}: contains {marker!r}")
- failures += int(not ok)
-
- print()
- if failures:
- print(f"Smoke FAILED: {failures} structure check(s) missing.")
- return 1
- print("Smoke PASSED: structured output → rendered markdown chain works for", args.provider)
- return 0
-
-
-if __name__ == "__main__":
- sys.exit(main())
diff --git a/test.py b/test.py
deleted file mode 100644
index f0b93184c..000000000
--- a/test.py
+++ /dev/null
@@ -1,14 +0,0 @@
-import time
-
-from tradingagents.dataflows.y_finance import (
- get_stock_stats_indicators_window,
-)
-
-print("Testing optimized implementation with 30-day lookback:")
-start_time = time.time()
-result = get_stock_stats_indicators_window("AAPL", "macd", "2024-11-01", 30)
-end_time = time.time()
-
-print(f"Execution time: {end_time - start_time:.2f} seconds")
-print(f"Result length: {len(result)} characters")
-print(result)
diff --git a/tests/test_alpha_vantage_hardening.py b/tests/test_alpha_vantage_hardening.py
index 494f2bac6..3bc90164f 100644
--- a/tests/test_alpha_vantage_hardening.py
+++ b/tests/test_alpha_vantage_hardening.py
@@ -13,9 +13,12 @@ import pytest
import tradingagents.dataflows.alpha_vantage_common as av
import tradingagents.dataflows.alpha_vantage_fundamentals as avf
import tradingagents.dataflows.alpha_vantage_stock as avs
+import tradingagents.dataflows.utils as utils
class _FakeResponse:
+ status_code = 200
+
def __init__(self, text):
self.text = text
@@ -34,7 +37,7 @@ def _patched_get(body, capture=None):
@pytest.mark.unit
def test_request_passes_timeout(monkeypatch):
captured = {}
- monkeypatch.setattr(av.requests, "get", _patched_get("Date,Close\n2025-01-02,1.0", captured))
+ monkeypatch.setattr(utils.requests, "get", _patched_get("Date,Close\n2025-01-02,1.0", captured))
av._make_api_request("TIME_SERIES_DAILY", {"symbol": "AAPL"})
assert captured.get("timeout") == av.REQUEST_TIMEOUT # #990
@@ -42,7 +45,7 @@ def test_request_passes_timeout(monkeypatch):
@pytest.mark.unit
def test_rate_limit_detected(monkeypatch):
body = '{"Information": "Our standard API rate limit is 25 requests per day. ... your API key ..."}'
- monkeypatch.setattr(av.requests, "get", _patched_get(body))
+ monkeypatch.setattr(utils.requests, "get", _patched_get(body))
with pytest.raises(av.AlphaVantageRateLimitError):
av._make_api_request("TIME_SERIES_DAILY", {"symbol": "AAPL"})
@@ -53,11 +56,11 @@ def test_invalid_key_not_mislabeled_as_rate_limit(monkeypatch):
# (transient) rate limit, but surface as a real configuration error (#991).
body = ('{"Information": "the parameter apikey is invalid or missing. '
'Please claim your free API key on (https://www.alphavantage.co/support/#api-key)."}')
- monkeypatch.setattr(av.requests, "get", _patched_get(body))
+ monkeypatch.setattr(utils.requests, "get", _patched_get(body))
with pytest.raises(av.AlphaVantageNotConfiguredError):
av._make_api_request("TIME_SERIES_DAILY", {"symbol": "AAPL"})
with pytest.raises(av.AlphaVantageRateLimitError): # sanity: rate-limit path still distinct
- monkeypatch.setattr(av.requests, "get", _patched_get('{"Note": "API call frequency is 5 calls per minute."}'))
+ monkeypatch.setattr(utils.requests, "get", _patched_get('{"Note": "API call frequency is 5 calls per minute."}'))
av._make_api_request("TIME_SERIES_DAILY", {"symbol": "AAPL"})
@@ -133,3 +136,78 @@ def test_unparseable_body_is_never_served_untrimmed(monkeypatch):
def test_empty_body_still_passes_through(monkeypatch):
monkeypatch.setattr(avs, "_make_api_request", lambda *a, **k: "")
assert avs.get_stock("IBM", "2024-05-09", "2024-05-10") == ""
+
+
+def test_request_error_message_carries_no_key(monkeypatch):
+ # Alpha Vantage also sends its key in the URL (#1324).
+ import requests
+ key = "AVKEY1234567890XYZ"
+ monkeypatch.setenv("ALPHA_VANTAGE_API_KEY", key)
+
+ def boom(*a, **k):
+ raise requests.Timeout(f"Read timed out. url: https://www.alphavantage.co/query?apikey={key}")
+
+ monkeypatch.setattr(utils.requests, "get", boom)
+ with pytest.raises(requests.Timeout) as caught:
+ av._make_api_request("OVERVIEW", {"symbol": "IBM"})
+ assert key not in str(caught.value)
+
+
+@pytest.mark.unit
+def test_global_news_omitted_optionals_use_the_configured_defaults(monkeypatch):
+ """The tool passes None for an omitted look_back_days or limit (#1326)."""
+ from tradingagents.dataflows import alpha_vantage_news
+
+ monkeypatch.setattr(alpha_vantage_news, "get_config",
+ lambda: {"global_news_lookback_days": 3, "global_news_article_limit": 9})
+ seen = {}
+ monkeypatch.setattr(alpha_vantage_news, "_make_api_request", lambda fn, params: seen.update(params) or "{}")
+
+ alpha_vantage_news.get_global_news("2026-08-14", None, None)
+
+ assert seen["time_from"].startswith("20260811") and seen["limit"] == "9"
+
+
+@pytest.mark.unit
+def test_the_news_window_includes_the_analysis_day(monkeypatch):
+ """time_to was midnight at the start of the end date, so everything
+ published during the analysis day, the most decision-relevant day, was
+ excluded. The yfinance path includes it."""
+ from tradingagents.dataflows import alpha_vantage_news
+
+ seen = {}
+ monkeypatch.setattr(alpha_vantage_news, "_make_api_request",
+ lambda fn, params: seen.update(params) or "{}")
+
+ alpha_vantage_news.get_news("AAPL", "2026-03-10", "2026-03-14")
+
+ assert seen["time_from"] == "20260310T0000"
+ assert seen["time_to"] == "20260314T2359"
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("indicator", ["vwma", "mfi"])
+def test_an_indicator_this_vendor_lacks_lets_the_next_one_serve_it(indicator):
+ """Returning prose counts as success to the router, so the chain stops at a
+ vendor that cannot compute the indicator while the next one can."""
+ from tradingagents.dataflows import alpha_vantage_indicator
+ from tradingagents.dataflows.errors import VendorError
+
+ with pytest.raises(VendorError):
+ alpha_vantage_indicator.get_indicator("AAPL", indicator, "2026-05-08", 30)
+
+
+@pytest.mark.unit
+def test_ticker_news_asks_for_only_as_many_articles_as_configured(monkeypatch):
+ """The endpoint returns 50 articles with per-article sentiment arrays by
+ default, and the whole payload went into the prompt."""
+ from tradingagents.dataflows import alpha_vantage_news
+
+ monkeypatch.setattr(alpha_vantage_news, "get_config", lambda: {"news_article_limit": 8})
+ seen = {}
+ monkeypatch.setattr(alpha_vantage_news, "_make_api_request",
+ lambda fn, params: seen.update(params) or "{}")
+
+ alpha_vantage_news.get_news("AAPL", "2026-03-10", "2026-03-14")
+
+ assert seen["limit"] == "8"
diff --git a/tests/test_anthropic_effort.py b/tests/test_anthropic_effort.py
index 04db66d4c..7d98c7d78 100644
--- a/tests/test_anthropic_effort.py
+++ b/tests/test_anthropic_effort.py
@@ -60,7 +60,7 @@ class TestEffortGate:
@pytest.mark.parametrize(
"model",
# Claude 5 family uses single-number version IDs; all are effort-capable.
- ["claude-sonnet-5", "claude-fable-5", "claude-mythos-5"],
+ ["claude-sonnet-5", "claude-fable-5", "claude-mythos-5", "claude-opus-5", "claude-fable-5-1"],
)
def test_claude_5_family_receives_effort(self, monkeypatch, model):
captured = _capture_kwargs(monkeypatch)
diff --git a/tests/test_api_key_env.py b/tests/test_api_key_env.py
index 7361ea7b5..8bd0154a6 100644
--- a/tests/test_api_key_env.py
+++ b/tests/test_api_key_env.py
@@ -3,6 +3,7 @@
from __future__ import annotations
import os
+import stat
from unittest.mock import patch
import pytest
@@ -146,3 +147,47 @@ def test_ensure_api_key_updates_existing_env_file(monkeypatch, tmp_path, cli_uti
assert "OPENAI_API_KEY" in content and "sk-existing" in content
assert "OTHER=value" in content
assert "OPENROUTER_API_KEY" in content and "sk-openrouter-new" in content
+
+
+def _prompt_key(cli_utils, monkeypatch, tmp_path, key="sk-typed-in"):
+ monkeypatch.chdir(tmp_path)
+ monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+ monkeypatch.setattr(cli_utils, "find_dotenv", lambda **k: "")
+ with patch.object(cli_utils, "questionary") as mock_q:
+ mock_q.password.return_value.ask.return_value = key
+ cli_utils.ensure_api_key("openai")
+
+
+@pytest.mark.skipif(os.name == "nt", reason="POSIX file modes")
+def test_saved_key_file_is_owner_only(monkeypatch, cli_utils, tmp_path):
+ # The prompt writes a real credential; the file must not be readable by
+ # other local users whatever the umask is.
+ old = os.umask(0o002)
+ try:
+ _prompt_key(cli_utils, monkeypatch, tmp_path)
+ finally:
+ os.umask(old)
+ env = tmp_path / ".env"
+ assert "sk-typed-in" in env.read_text()
+ assert stat.S_IMODE(env.stat().st_mode) == 0o600
+
+
+@pytest.mark.skipif(os.name == "nt", reason="POSIX file modes")
+def test_existing_key_file_is_tightened_before_writing(monkeypatch, cli_utils, tmp_path):
+ env = tmp_path / ".env"
+ env.write_text("OTHER=1\n")
+ os.chmod(env, 0o664)
+ _prompt_key(cli_utils, monkeypatch, tmp_path)
+ assert stat.S_IMODE(env.stat().st_mode) == 0o600
+ assert "OTHER=1" in env.read_text()
+
+
+
+@pytest.mark.skipif(os.name == "nt", reason="POSIX file modes")
+def test_read_only_key_file_is_still_updated(monkeypatch, cli_utils, tmp_path):
+ env = tmp_path / ".env"
+ env.write_text("OTHER=1\n")
+ os.chmod(env, 0o400)
+ _prompt_key(cli_utils, monkeypatch, tmp_path)
+ assert "sk-typed-in" in env.read_text()
+ assert stat.S_IMODE(env.stat().st_mode) == 0o600
diff --git a/tests/test_backtest.py b/tests/test_backtest.py
new file mode 100644
index 000000000..cebb63134
--- /dev/null
+++ b/tests/test_backtest.py
@@ -0,0 +1,248 @@
+"""Backtesting: many single-shot decisions, scored by the decision log.
+
+A run already records its rating and later settles it with realized and alpha
+return against the regional benchmark. A backtest is that machinery over a grid
+of tickers and dates, aggregated. It evaluates decision quality; it does not
+simulate a portfolio, so there is no execution, no fees and no equity curve.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from tradingagents.agents.utils.memory import TradingMemoryLog
+from tradingagents.backtest import iter_grid, run_backtest, summarize
+
+DECISION = "Rating: Buy\n\nbuy it"
+
+
+@pytest.mark.unit
+def test_grid_spacing_and_canonical_dates():
+ assert iter_grid("2026-01-05", "2026-01-20", every_n_days=7) == ["2026-01-05", "2026-01-12", "2026-01-19"]
+
+
+@pytest.mark.unit
+def test_grid_stops_at_today(monkeypatch):
+ import tradingagents.backtest as bt
+
+ monkeypatch.setattr(bt, "get_current_date", lambda: "2026-01-10")
+ assert iter_grid("2026-01-05", "2026-02-20", every_n_days=5) == ["2026-01-05", "2026-01-10"]
+
+
+@pytest.mark.unit
+def test_grid_rejects_a_non_canonical_date():
+ with pytest.raises(ValueError, match="YYYY-MM-DD"):
+ iter_grid("2026-1-5", "2026-01-20")
+
+
+class _FakeGraph:
+ """Stands in for TradingAgentsGraph, writing to the log the harness gave it."""
+
+ instances: list = []
+ fail_on: set = set()
+
+ def __init__(self, selected_analysts=None, config=None, **kw):
+ self.analysts = list(selected_analysts) if selected_analysts else None
+ self.config = config
+ self.memory_log = TradingMemoryLog(config)
+ self.calls = []
+ self.settled = []
+ _FakeGraph.instances.append(self)
+
+ def propagate(self, ticker, trade_date, asset_type="stock", portfolio=None):
+ self.calls.append((ticker, trade_date))
+ if (ticker, trade_date) in _FakeGraph.fail_on:
+ raise RuntimeError("vendor exploded")
+ self.memory_log.store_decision(ticker, trade_date, DECISION)
+ return {"final_trade_decision": DECISION}, "Buy"
+
+ def settle_pending(self, ticker):
+ self.settled.append(ticker)
+
+
+@pytest.fixture(autouse=True)
+def _fake_graph(monkeypatch, tmp_path):
+ import tradingagents.backtest as bt
+
+ _FakeGraph.instances = []
+ _FakeGraph.fail_on = set()
+ monkeypatch.setattr(bt, "TradingAgentsGraph", _FakeGraph)
+ return _FakeGraph
+
+
+def _config(tmp_path):
+ return {"results_dir": str(tmp_path / "results"),
+ "memory_log_path": str(tmp_path / "live_trading_memory.md")}
+
+
+@pytest.mark.unit
+def test_the_live_decision_log_is_never_written(tmp_path):
+ config = _config(tmp_path)
+ result = run_backtest(["NVDA"], ["2026-01-05", "2026-01-12"], config)
+
+ assert not (tmp_path / "live_trading_memory.md").exists()
+ assert result.log_path.exists() and result.cells_run == 2
+
+
+@pytest.mark.unit
+def test_a_cell_already_in_the_log_is_not_run_again(tmp_path):
+ config = _config(tmp_path)
+ first = run_backtest(["NVDA"], ["2026-01-05"], config)
+
+ again = run_backtest(["NVDA"], ["2026-01-05", "2026-01-12"], config, run_id=first.run_id)
+
+ assert again.cells_run == 1 and again.skipped == 1
+ assert _FakeGraph.instances[-1].calls == [("NVDA", "2026-01-12")]
+
+
+@pytest.mark.unit
+def test_every_ticker_is_settled_after_the_grid(tmp_path):
+ """Settlement runs at the start of the next same-ticker run, so the last
+ date of each ticker would stay pending without an explicit pass."""
+ run_backtest(["NVDA", "AAPL"], ["2026-01-05", "2026-01-12"], _config(tmp_path))
+ assert sorted(_FakeGraph.instances[-1].settled) == ["AAPL", "NVDA"]
+
+
+@pytest.mark.unit
+def test_a_failed_cell_does_not_abort_the_sweep(tmp_path):
+ _FakeGraph.fail_on = {("NVDA", "2026-01-05")}
+ result = run_backtest(["NVDA"], ["2026-01-05", "2026-01-12"], _config(tmp_path))
+
+ assert result.cells_run == 1
+ assert result.failures == [("NVDA", "2026-01-05", "vendor exploded")]
+
+
+# --- reading the result ------------------------------------------------------
+
+def _log_with(tmp_path, rows):
+ log = TradingMemoryLog({"memory_log_path": str(tmp_path / "m.md")})
+ for ticker, date, decision, outcome in rows:
+ log.store_decision(ticker, date, decision)
+ if outcome is not None:
+ log.update_with_outcome(ticker, date, outcome[0], outcome[1], 5, "note", "2026-02-01")
+ return log
+
+
+@pytest.mark.unit
+def test_summary_scores_resolved_cells_and_keeps_pending_out_of_the_average(tmp_path):
+ log = _log_with(tmp_path, [
+ ("NVDA", "2026-01-05", "Rating: Buy\n\nx", (0.10, 0.04)),
+ ("NVDA", "2026-01-12", "Rating: Buy\n\nx", (-0.02, -0.02)),
+ ("AAPL", "2026-01-05", "Rating: Sell\n\nx", None),
+ ])
+
+ summary = summarize(log)
+
+ assert summary.resolved == 2 and summary.pending == 1
+ buys = summary.by_rating["Buy"]
+ assert buys.count == 2 and buys.hit_rate == 0.5 and round(buys.mean_alpha, 4) == 0.01
+ assert "Sell" not in summary.by_rating # unsettled: nothing to score yet
+
+
+@pytest.mark.unit
+def test_summary_states_what_it_cannot_prove(tmp_path):
+ text = summarize(_log_with(tmp_path, [("NVDA", "2026-01-05", DECISION, (0.1, 0.05))])).render()
+ assert "not archived" in text
+ assert "one" in text.lower() and "sampl" in text.lower()
+
+
+@pytest.mark.unit
+def test_the_analyst_set_under_test_is_the_one_that_runs(tmp_path):
+ """A backtest of a two-analyst setup must not silently run four."""
+ run_backtest(["NVDA"], ["2026-01-05"], _config(tmp_path), selected_analysts=["market", "news"])
+ assert _FakeGraph.instances[-1].analysts == ["market", "news"]
+
+
+@pytest.mark.unit
+def test_a_run_id_cannot_escape_the_results_directory(tmp_path):
+ """run_id becomes a path segment, so it is validated like a ticker is."""
+ with pytest.raises(ValueError):
+ run_backtest(["NVDA"], ["2026-01-05"], _config(tmp_path), run_id="../../escaped")
+ with pytest.raises(ValueError):
+ run_backtest(["NVDA"], ["2026-01-05"], _config(tmp_path), run_id="/etc/cron.d/x")
+
+
+@pytest.mark.unit
+def test_a_failed_settlement_does_not_lose_the_remaining_tickers(tmp_path, monkeypatch):
+ """Settlement reflects with an LLM, so it can fail; the sweep still returns
+ its result and every other ticker still gets settled."""
+ settled = []
+
+ def _settle(self, ticker):
+ if ticker == "NVDA":
+ raise RuntimeError("reflector timed out")
+ settled.append(ticker)
+
+ monkeypatch.setattr(_FakeGraph, "settle_pending", _settle, raising=False)
+ result = run_backtest(["NVDA", "AAPL"], ["2026-01-05"], _config(tmp_path))
+
+ assert result.cells_run == 2
+ assert settled == ["AAPL"]
+ assert result.settlement_failures == [("NVDA", "reflector timed out")]
+
+
+@pytest.mark.unit
+def test_pending_note_appears_only_when_something_is_pending(tmp_path):
+ settled = [("NVDA", "2026-01-05", DECISION, (0.1, 0.05))]
+ assert "Pending" not in summarize(_log_with(tmp_path, settled)).render()
+ assert "Pending" in summarize(_log_with(tmp_path, settled + [("AAPL", "2026-01-05", DECISION, None)])).render()
+
+
+# --- scoring reads the direction the rating claimed ---------------------------
+
+def _scored(tmp_path, rows):
+ log = _log_with(tmp_path, rows)
+ return summarize(log).by_rating
+
+
+@pytest.mark.unit
+def test_a_bearish_call_that_fell_counts_as_right(tmp_path):
+ """Alpha below the benchmark is the outcome a Sell predicted; scoring it as
+ a miss reported the system as wrong exactly when it was right."""
+ scores = _scored(tmp_path, [
+ ("NVDA", "2026-01-05", "**Rating**: Sell\n\nx", (-0.08, -0.05)),
+ ("AAPL", "2026-01-05", "**Rating**: Underweight\n\nx", (-0.03, -0.02)),
+ ])
+ assert scores["Sell"].hit_rate == 1.0
+ assert scores["Underweight"].hit_rate == 1.0
+
+
+@pytest.mark.unit
+def test_a_bearish_call_that_rose_counts_as_wrong(tmp_path):
+ scores = _scored(tmp_path, [("NVDA", "2026-01-05", "**Rating**: Sell\n\nx", (0.08, 0.05))])
+ assert scores["Sell"].hit_rate == 0.0
+
+
+@pytest.mark.unit
+def test_a_bullish_call_is_scored_the_same_way_as_before(tmp_path):
+ scores = _scored(tmp_path, [
+ ("NVDA", "2026-01-05", "**Rating**: Buy\n\nx", (0.10, 0.04)),
+ ("AAPL", "2026-01-05", "**Rating**: Buy\n\nx", (-0.02, -0.02)),
+ ])
+ assert scores["Buy"].hit_rate == 0.5
+
+
+@pytest.mark.unit
+def test_hold_claims_no_direction_so_it_gets_no_hit_rate(tmp_path):
+ scores = _scored(tmp_path, [("NVDA", "2026-01-05", "**Rating**: Hold\n\nx", (0.01, 0.005))])
+ assert scores["Hold"].hit_rate is None
+ assert scores["Hold"].mean_alpha == 0.005
+
+
+@pytest.mark.unit
+def test_the_report_names_the_window_the_scores_cover(tmp_path):
+ text = summarize(_log_with(tmp_path, [
+ ("NVDA", "2026-01-05", "**Rating**: Buy\n\nx", (0.1, 0.05))])).render()
+ assert "5" in text and "day" in text.lower()
+ assert "Hold" not in text or "no direction" in text.lower()
+
+
+@pytest.mark.unit
+def test_the_window_reported_is_the_one_the_outcomes_used(tmp_path):
+ """The log records the window each outcome was measured over; the summary
+ must not claim a different one."""
+ log = TradingMemoryLog({"memory_log_path": str(tmp_path / "m.md")})
+ log.store_decision("NVDA", "2026-01-05", "**Rating**: Buy\n\nx")
+ log.update_with_outcome("NVDA", "2026-01-05", 0.1, 0.04, 21, "note", "2026-02-01")
+
+ assert "21 trading days" in summarize(log).render()
diff --git a/tests/test_checkpoint_lifecycle.py b/tests/test_checkpoint_lifecycle.py
index 1e5e2adf5..4933b5b67 100644
--- a/tests/test_checkpoint_lifecycle.py
+++ b/tests/test_checkpoint_lifecycle.py
@@ -153,3 +153,20 @@ def test_cli_style_usage_saves_then_resumes():
# Cleared on success -> a later run starts fresh.
assert checkpoint_step(tmp, "AAPL", "2026-05-08", sig) is None
+
+
+@pytest.mark.unit
+def test_clearing_removes_the_database_sidecars(tmp_path):
+ """SQLite writes -wal and -shm next to the database; leaving them behind
+ means a cleared checkpoint still has committed state on disk."""
+ from tradingagents.graph.checkpointer import clear_all_checkpoints
+
+ cp = tmp_path / "checkpoints"
+ cp.mkdir(parents=True)
+ for suffix in (".db", ".db-wal", ".db-shm"):
+ (cp / f"NVDA{suffix}").write_text("x")
+
+ cleared = clear_all_checkpoints(str(tmp_path))
+
+ assert cleared == 1
+ assert list(cp.iterdir()) == []
diff --git a/tests/test_cli_commands.py b/tests/test_cli_commands.py
new file mode 100644
index 000000000..c0fb5f727
--- /dev/null
+++ b/tests/test_cli_commands.py
@@ -0,0 +1,153 @@
+"""The CLI keeps running an analysis with no arguments, and gains `backtest`.
+
+Every documented invocation is bare (`tradingagents --checkpoint`), so analysis
+has to stay the default action while a second command exists alongside it.
+"""
+
+from __future__ import annotations
+
+import pytest
+from typer.testing import CliRunner
+
+import cli.main as m
+
+
+@pytest.fixture
+def runner(monkeypatch):
+ monkeypatch.setattr(m, "run_analysis", lambda **kw: calls.append(("analysis", kw)))
+ calls.clear()
+ return CliRunner()
+
+
+calls: list = []
+
+
+@pytest.mark.unit
+def test_no_arguments_still_runs_an_analysis(runner):
+ assert runner.invoke(m.app, []).exit_code == 0
+ assert calls == [("analysis", {"checkpoint": None, "portfolio": None})]
+
+
+@pytest.mark.unit
+def test_options_still_parse_without_a_subcommand(runner):
+ assert runner.invoke(m.app, ["--checkpoint"]).exit_code == 0
+ assert calls[0][1]["checkpoint"] is True
+
+
+@pytest.mark.unit
+def test_backtest_does_not_also_run_an_analysis(runner, monkeypatch, tmp_path):
+ swept = []
+ monkeypatch.setattr(m, "run_backtest", lambda *a, **kw: swept.append((a, kw)) or _Result(tmp_path))
+ monkeypatch.setattr(m, "summarize", lambda log: _Summary())
+
+ result = runner.invoke(m.app, ["backtest", "NVDA,AAPL", "--start", "2026-06-01",
+ "--end", "2026-06-15", "--every", "7"])
+
+ assert result.exit_code == 0, result.output
+ assert calls == [] # the interactive analysis must not run
+ (tickers, dates, _config), kwargs = swept[0]
+ assert tickers == ["NVDA", "AAPL"]
+ assert dates == ["2026-06-01", "2026-06-08", "2026-06-15"]
+ assert "scored" in result.output
+
+
+@pytest.mark.unit
+def test_backtest_reports_a_bad_date_instead_of_a_traceback(runner):
+ result = runner.invoke(m.app, ["backtest", "NVDA", "--start", "June", "--end", "2026-06-15"])
+ assert result.exit_code == 1
+ assert "YYYY-MM-DD" in result.output
+
+
+@pytest.mark.unit
+def test_help_lists_the_backtest_command(runner):
+ assert "backtest" in runner.invoke(m.app, ["--help"]).output
+
+
+class _Result:
+ def __init__(self, tmp_path):
+ self.run_id = "20260916_000000"
+ self.log_path = tmp_path / "trading_memory.md"
+ self.cells_run = 2
+ self.skipped = 0
+ self.failures = []
+ self.settlement_failures = []
+
+
+class _Summary:
+ def render(self):
+ return "scored 2 cells"
+
+
+@pytest.mark.unit
+def test_every_command_is_registered_when_run_as_a_module():
+ """README documents `python -m cli.main`, which executes the file top to
+ bottom, so a command defined after the __main__ block would not exist."""
+ import re
+ import subprocess
+ import sys
+
+ out = subprocess.run([sys.executable, "-m", "cli.main", "backtest", "--help"],
+ capture_output=True, text=True, timeout=120)
+ assert out.returncode == 0, out.stderr[-400:]
+ # Where the terminal takes colour, help styles each option and splits
+ # "--start" across escape sequences, so read the text without them.
+ plain = re.sub(r"\x1b\[[0-9;]*m", "", out.stdout)
+ assert "--start" in plain
+
+
+@pytest.mark.unit
+def test_the_cli_says_whether_a_run_resumed(monkeypatch):
+ """The README promises the user can tell a resumed run from a fresh one.
+ The graph logs it, but nothing configures logging, so it was never shown."""
+ import cli.main as m
+
+ messages = []
+ monkeypatch.setattr(m.message_buffer, "add_message",
+ lambda kind, text: messages.append(text), raising=False)
+
+ m._announce_checkpoint_state(type("G", (), {"_resuming": True})(), "NVDA", "2026-01-10")
+ m._announce_checkpoint_state(type("G", (), {"_resuming": False})(), "NVDA", "2026-01-10")
+
+ assert any("resum" in text.lower() for text in messages)
+ assert any("fresh" in text.lower() for text in messages)
+
+
+@pytest.mark.unit
+def test_backtest_can_continue_an_interrupted_sweep(runner, monkeypatch, tmp_path):
+ """Resuming is what makes a long sweep practical, and the Python API has it."""
+ swept = []
+ monkeypatch.setattr(m, "run_backtest", lambda *a, **kw: swept.append(kw) or _Result(tmp_path))
+ monkeypatch.setattr(m, "summarize", lambda log: _Summary())
+
+ result = runner.invoke(m.app, ["backtest", "NVDA", "--start", "2026-06-01",
+ "--end", "2026-06-08", "--run-id", "20260617_120000"])
+
+ assert result.exit_code == 0, result.output
+ assert swept[0]["run_id"] == "20260617_120000"
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("args, expected", [
+ (["backtest", "NVDA", "--start", "2026-08-01", "--end", "2026-06-08"], "before"),
+ (["backtest", ",,", "--start", "2026-06-01", "--end", "2026-06-08"], "ticker"),
+])
+def test_backtest_rejects_input_that_would_sweep_nothing(runner, args, expected):
+ """An inverted range or an empty ticker list reported a clean zero-cell run,
+ which reads as 'nothing to find' rather than 'you asked for nothing'."""
+ result = runner.invoke(m.app, args)
+ assert result.exit_code == 1
+ assert expected in result.output.lower()
+
+
+@pytest.mark.unit
+def test_backtest_reports_a_setup_failure_in_one_line(runner, monkeypatch):
+ """A missing key or a bad analyst name produced a raw traceback."""
+ def _explode(*a, **kw):
+ raise ValueError("API key for provider 'openai' is not set")
+
+ monkeypatch.setattr(m, "run_backtest", _explode)
+ result = runner.invoke(m.app, ["backtest", "NVDA", "--start", "2026-06-01", "--end", "2026-06-08"])
+
+ assert result.exit_code == 1
+ assert "API key" in result.output
+ assert "Traceback" not in result.output
diff --git a/tests/test_cli_config_precedence.py b/tests/test_cli_config_precedence.py
index e2ba90d14..873810098 100644
--- a/tests/test_cli_config_precedence.py
+++ b/tests/test_cli_config_precedence.py
@@ -14,8 +14,8 @@ import cli.main as m
# Minimal selections dict shaped like get_user_selections()'s return value.
SELECTIONS = {
"research_depth": 5,
- "shallow_thinker": "gpt-5.4-mini",
- "deep_thinker": "gpt-5.5",
+ "quick_think_llm": "gpt-5.4-mini",
+ "deep_think_llm": "gpt-5.5",
"backend_url": None,
"llm_provider": "openai",
"google_thinking_level": None,
@@ -67,3 +67,41 @@ def test_checkpoint_flag_overrides_env(flag):
with mock.patch.object(m, "DEFAULT_CONFIG", patched):
cfg = m._build_run_config(SELECTIONS, checkpoint=flag)
assert cfg["checkpoint_enabled"] is flag
+
+
+@pytest.mark.unit
+def test_glm_resolves_to_the_endpoint_its_key_belongs_to():
+ """The provider table, the client registry and the key mapping must name the
+ same platform: glm is Z.AI international (ZHIPU_API_KEY) and glm-cn is
+ BigModel China. A mismatch sends the key to the other platform and every
+ call fails auth."""
+ from cli.utils import resolve_backend_url
+ from tradingagents.llm_clients.api_key_env import get_api_key_env
+ from tradingagents.llm_clients.openai_client import OPENAI_COMPATIBLE_PROVIDERS
+
+ assert resolve_backend_url("glm", None, None) == OPENAI_COMPATIBLE_PROVIDERS["glm"].base_url
+ assert get_api_key_env("glm") == "ZHIPU_API_KEY"
+ assert "z.ai" in OPENAI_COMPATIBLE_PROVIDERS["glm"].base_url
+ assert "bigmodel.cn" in OPENAI_COMPATIBLE_PROVIDERS["glm-cn"].base_url
+
+
+@pytest.mark.unit
+def test_a_half_set_round_count_says_which_value_won(capsys, monkeypatch):
+ """With only one of the two round-count variables set, the depth prompt is
+ still shown but half the answer is discarded; the user was never told."""
+ import cli.main as m
+
+ monkeypatch.setenv("TRADINGAGENTS_MAX_DEBATE_ROUNDS", "1")
+ monkeypatch.delenv("TRADINGAGENTS_MAX_RISK_ROUNDS", raising=False)
+ printed = []
+ monkeypatch.setattr(m.console, "print", lambda *a, **k: printed.append(str(a[0]) if a else ""))
+
+ config = m._build_run_config({
+ "ticker": "NVDA", "analysis_date": "2026-09-01", "asset_type": "stock",
+ "analysts": [], "research_depth": 5, "llm_provider": "openai",
+ "quick_think_llm": "gpt-5.6-luna", "deep_think_llm": "gpt-5.6",
+ "backend_url": None, "output_language": "English",
+ }, None)
+
+ assert config["max_risk_discuss_rounds"] == 5
+ assert any("TRADINGAGENTS_MAX_DEBATE_ROUNDS" in line for line in printed), printed
diff --git a/tests/test_cli_decision_log.py b/tests/test_cli_decision_log.py
new file mode 100644
index 000000000..719fcba29
--- /dev/null
+++ b/tests/test_cli_decision_log.py
@@ -0,0 +1,167 @@
+"""The CLI must use the decision log the same way propagate() does.
+
+The CLI streams the graph itself instead of calling propagate(), so memory steps
+that lived only in propagate() never ran on the primary entry point: pending
+decisions were not settled, the Portfolio Manager got no past context, and the
+finished decision was not recorded. Both paths now build their initial state and
+record their decision through the same graph methods.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from tradingagents.agents.utils.memory import TradingMemoryLog
+from tradingagents.graph.trading_graph import TradingAgentsGraph
+
+
+def _bare_graph(tmp_path):
+ """A graph without __init__ (no LLM clients), wired to a temp log."""
+ graph = object.__new__(TradingAgentsGraph)
+ graph.config = {"memory_log_path": str(tmp_path / "trading_memory.md")}
+ graph.memory_log = TradingMemoryLog(graph.config)
+ return graph
+
+
+@pytest.mark.unit
+def test_create_run_state_settles_pending_and_carries_context(tmp_path, monkeypatch):
+ from tradingagents.graph.propagation import Propagator
+
+ graph = _bare_graph(tmp_path)
+ graph.propagator = Propagator()
+ settled = []
+ monkeypatch.setattr(graph, "_resolve_pending_entries", settled.append, raising=False)
+ monkeypatch.setattr(graph, "resolve_instrument_context", lambda t, a="stock", d=None: f"id:{t}", raising=False)
+ monkeypatch.setattr(graph, "_memory_as_of", lambda d: d, raising=False)
+ graph.memory_log.store_decision("NVDA", "2026-01-05", "Rating: Buy\nold call")
+ graph.memory_log.update_with_outcome("NVDA", "2026-01-05", 0.01, 0.005, 5, "great trade", "2026-01-12")
+
+ state = graph.create_run_state("NVDA", "2026-02-01")
+
+ assert settled == ["NVDA"]
+ assert "great trade" in state["past_context"]
+ assert state["instrument_context"] == "id:NVDA"
+ assert state["company_of_interest"] == "NVDA"
+
+
+@pytest.mark.unit
+def test_record_decision_appends_a_pending_entry(tmp_path):
+ graph = _bare_graph(tmp_path)
+ graph.record_decision("NVDA", "2026-01-10", {"final_trade_decision": "Rating: Buy\n\nBuy NVDA."})
+ entries = graph.memory_log.load_entries()
+ assert [(e["ticker"], e["pending"], e["rating"]) for e in entries] == [("NVDA", True, "Buy")]
+
+
+@pytest.mark.unit
+def test_record_decision_skips_a_run_without_a_decision(tmp_path):
+ graph = _bare_graph(tmp_path)
+ graph.record_decision("NVDA", "2026-01-10", {})
+ assert graph.memory_log.load_entries() == []
+
+
+# --- the CLI path ----------------------------------------------------------------
+
+class _FakeGraph:
+ """Records the lifecycle calls run_analysis makes."""
+
+ def __init__(self):
+ self.calls = []
+ self.graph = self
+ self.propagator = self
+
+ def create_run_state(self, ticker, trade_date, asset_type="stock", portfolio=None):
+ self.calls.append(("create_run_state", ticker, trade_date))
+ return {"messages": [], "company_of_interest": ticker}
+
+ def process_signal(self, text):
+ from tradingagents.graph.signal_processing import SignalProcessor
+ return SignalProcessor.process_signal(None, text)
+
+ def record_decision(self, ticker, trade_date, final_state):
+ self.calls.append(("record_decision", ticker, trade_date, final_state.get("final_trade_decision")))
+
+ def get_graph_args(self, callbacks=None):
+ return {}
+
+ def begin_checkpoint(self, *a, **k):
+ return None
+
+ def checkpoint_input(self, state):
+ return state
+
+ def clear_checkpoint_on_success(self, *a, **k):
+ self.calls.append(("clear_checkpoint",))
+
+ def end_checkpoint(self):
+ pass
+
+ def stream(self, graph_input, **kwargs):
+ yield {"messages": [], "market_report": "M"}
+ yield {"messages": [], "final_trade_decision": "Rating: Buy\n\nBuy NVDA."}
+
+
+class _NullLive:
+ def __init__(self, *a, **k):
+ pass
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, *a):
+ return False
+
+
+class _FakeBuffer:
+ def __init__(self):
+ self.messages = []
+ self.tool_calls = []
+ self.report_sections = {}
+ self.agent_status = {}
+ self.selected_analysts = []
+ self._processed_message_ids = set()
+
+ def init_for_analysis(self, selected_analysts):
+ self.selected_analysts = [a.lower() for a in selected_analysts]
+
+ def add_message(self, kind, content):
+ self.messages.append((0.0, kind, content))
+
+ def add_tool_call(self, name, args):
+ self.tool_calls.append((0.0, name, args))
+
+ def update_report_section(self, *a):
+ pass
+
+ def update_agent_status(self, agent, status):
+ self.agent_status[agent] = status
+
+
+@pytest.mark.unit
+def test_cli_run_uses_the_decision_log_like_propagate(tmp_path, monkeypatch):
+ import cli.main as m
+ from cli.models import AnalystType
+
+ fake = _FakeGraph()
+ monkeypatch.setattr(m, "TradingAgentsGraph", lambda *a, **k: fake)
+ monkeypatch.setattr(m, "message_buffer", _FakeBuffer())
+ monkeypatch.setattr(m, "create_layout", lambda: None)
+ monkeypatch.setattr(m, "update_display", lambda *a, **k: None)
+ monkeypatch.setattr(m, "Live", _NullLive)
+ monkeypatch.setattr(m, "get_user_selections", lambda: {
+ "ticker": "NVDA", "analysis_date": "2026-01-10",
+ "analysts": [AnalystType.MARKET], "asset_type": "stock",
+ })
+ monkeypatch.setattr(m, "_build_run_config", lambda selections, checkpoint: {
+ "data_cache_dir": str(tmp_path / "cache"), "results_dir": str(tmp_path / "results"),
+ })
+ monkeypatch.setattr(m.typer, "prompt", lambda *a, **k: "N")
+
+ m.run_analysis()
+
+ assert fake.calls == [
+ ("create_run_state", "NVDA", "2026-01-10"),
+ # The decision is recorded from the merged stream, before the checkpoint
+ # is cleared, matching propagate().
+ ("record_decision", "NVDA", "2026-01-10", "Rating: Buy\n\nBuy NVDA."),
+ ("clear_checkpoint",),
+ ]
diff --git a/tests/test_cli_display.py b/tests/test_cli_display.py
new file mode 100644
index 000000000..6c7eadd65
--- /dev/null
+++ b/tests/test_cli_display.py
@@ -0,0 +1,77 @@
+"""What the live display shows, and what the run log keeps.
+
+The display drops a message it judges empty, and the state log is written for a
+person to read afterwards. Both got that wrong in ways that hide real content.
+"""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from cli.main import extract_content_string
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("text", ["0", "False", "None", "[]", "{}", "0.0"])
+def test_a_message_that_reads_like_a_python_value_is_still_text(text):
+ """These were parsed as Python and judged empty, so the message vanished."""
+ assert extract_content_string(text) == text
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("value, expected", [
+ (" Hold ", "Hold"),
+ ("", None),
+ (" ", None),
+ (None, None),
+ ([], None),
+ ({}, None),
+ ({"text": "from a dict"}, "from a dict"),
+ ([{"type": "text", "text": "part one"}, {"type": "text", "text": "part two"}], "part one part two"),
+])
+def test_the_other_shapes_are_unchanged(value, expected):
+ assert extract_content_string(value) == expected
+
+
+@pytest.mark.unit
+def test_the_state_log_keeps_non_ascii_readable(tmp_path):
+ """Reports can be in any language; the log is read by a person."""
+ from tradingagents.graph.trading_graph import TradingAgentsGraph
+
+ graph = object.__new__(TradingAgentsGraph)
+ graph.config = {"results_dir": str(tmp_path)}
+ graph.ticker = "600519.SS"
+ graph.log_states_dict = {}
+
+ graph._log_state("2026-09-01", {
+ "company_of_interest": "600519.SS", "trade_date": "2026-09-01",
+ "market_report": "市场", "sentiment_report": "情绪", "news_report": "新闻",
+ "fundamentals_report": "基本面", "investment_plan": "计划",
+ "trader_investment_plan": "交易计划", "final_trade_decision": "评级: 买入",
+ "investment_debate_state": {"bull_history": "", "bear_history": "", "history": "",
+ "current_response": "", "judge_decision": "", "count": 0},
+ "risk_debate_state": {"aggressive_history": "", "conservative_history": "",
+ "neutral_history": "", "history": "", "judge_decision": "",
+ "latest_speaker": "", "current_aggressive_response": "",
+ "current_conservative_response": "", "current_neutral_response": "",
+ "count": 0},
+ })
+
+ written = next(tmp_path.rglob("full_states_log*.json")).read_text(encoding="utf-8")
+ assert "买入" in written
+ assert "\\u" not in written
+ assert json.loads(written) # still valid JSON
+
+
+@pytest.mark.unit
+def test_the_live_display_does_not_scroll_the_terminal():
+ """A layout taller than the window makes rich redraw by scrolling, which
+ reads as flicker; the alternate screen holds it in place (#784). The final
+ report prints after the live view ends, so nothing is lost when it closes."""
+ import inspect
+
+ import cli.main as m
+
+ assert "screen=True" in inspect.getsource(m.run_analysis)
diff --git a/tests/test_cli_env_skip.py b/tests/test_cli_env_skip.py
index c98c24549..b3d50d956 100644
--- a/tests/test_cli_env_skip.py
+++ b/tests/test_cli_env_skip.py
@@ -77,8 +77,8 @@ class TestCliSkipsPromptsFromEnv(unittest.TestCase):
# The env values flow into the returned selections.
self.assertEqual(sel["llm_provider"], "openai")
self.assertEqual(sel["backend_url"], "https://opencode.ai/zen/go/v1")
- self.assertEqual(sel["shallow_thinker"], "deepseek-v4-pro")
- self.assertEqual(sel["deep_thinker"], "kimi-k2.5")
+ self.assertEqual(sel["quick_think_llm"], "deepseek-v4-pro")
+ self.assertEqual(sel["deep_think_llm"], "kimi-k2.5")
self.assertEqual(sel["output_language"], "Japanese")
diff --git a/tests/test_cli_prefs.py b/tests/test_cli_prefs.py
new file mode 100644
index 000000000..1ba6c1f50
--- /dev/null
+++ b/tests/test_cli_prefs.py
@@ -0,0 +1,169 @@
+"""The CLI remembers what you chose last time and offers it back.
+
+Prefill only: every prompt still appears, so a run never starts on a choice the
+user did not see. Environment variables keep skipping their step outright and
+win over anything remembered. Remembered values are validated against the
+current choices each time, since models and providers come and go between
+versions and a stale one must not be offered.
+"""
+
+from __future__ import annotations
+
+from unittest import mock
+
+import pytest
+
+from cli.models import AnalystType
+from cli.prefs import load_last_run, sanitize, save_last_run
+
+SAVED = {
+ "output_language": "English",
+ "analysts": ["market", "fundamentals"],
+ "research_depth": 3,
+ "llm_provider": "openai",
+ "quick_think_llm": "gpt-5.6-mini",
+ "deep_think_llm": "gpt-5.6",
+}
+
+
+@pytest.fixture(autouse=True)
+def _home(tmp_path, monkeypatch):
+ monkeypatch.setattr("cli.prefs._PREFS_PATH", tmp_path / "cli_prefs.json")
+ return tmp_path
+
+
+@pytest.mark.unit
+def test_round_trip():
+ save_last_run(SAVED)
+ assert load_last_run() == SAVED
+
+
+@pytest.mark.unit
+def test_missing_file_is_not_an_error():
+ assert load_last_run() == {}
+
+
+@pytest.mark.unit
+def test_a_corrupt_file_degrades_to_no_memory(_home):
+ (_home / "cli_prefs.json").write_text("{not json")
+ assert load_last_run() == {}
+
+
+@pytest.mark.unit
+def test_a_half_written_file_cannot_be_observed(_home):
+ """Two runs finishing together must never leave a torn file behind."""
+ save_last_run(SAVED)
+ save_last_run({**SAVED, "research_depth": 5})
+ assert load_last_run()["research_depth"] == 5
+ assert list((_home).glob("*.tmp*")) == []
+
+
+# --- validation against the current choices ---------------------------------
+
+@pytest.mark.unit
+def test_a_model_that_no_longer_exists_is_dropped():
+ # gpt-5.4 is still accepted by config, but is no longer in the picker's list.
+ kept = sanitize({**SAVED, "quick_think_llm": "gpt-5.4"}, "stock")
+ assert "quick_think_llm" not in kept
+ assert kept["deep_think_llm"] == "gpt-5.6" # the valid sibling survives
+
+
+@pytest.mark.unit
+def test_an_unknown_provider_drops_itself_and_its_models():
+ kept = sanitize({**SAVED, "llm_provider": "no-such-provider"}, "stock")
+ assert "llm_provider" not in kept
+ assert "quick_think_llm" not in kept and "deep_think_llm" not in kept
+
+
+@pytest.mark.unit
+def test_analysts_are_narrowed_to_the_asset_type():
+ kept = sanitize(SAVED, "crypto")
+ assert AnalystType.FUNDAMENTALS.value not in kept["analysts"]
+ assert AnalystType.MARKET.value in kept["analysts"]
+
+
+@pytest.mark.unit
+def test_junk_values_are_dropped_rather_than_offered():
+ kept = sanitize({"research_depth": 99, "analysts": ["astrology"], "output_language": 5}, "stock")
+ assert kept == {}
+
+
+@pytest.mark.unit
+def test_a_region_specific_provider_survives():
+ kept = sanitize({**SAVED, "llm_provider": "qwen-cn", "quick_think_llm": None}, "stock")
+ assert kept["llm_provider"] == "qwen-cn"
+
+
+# --- wiring ------------------------------------------------------------------
+
+def _answer_every_prompt(monkeypatch):
+ """Drive the real selection flow, answering each prompt with a fixed value."""
+ import cli.main as m
+
+ monkeypatch.setattr(m, "fetch_announcements", lambda: [])
+ monkeypatch.setattr(m, "display_announcements", lambda *a: None)
+ monkeypatch.setattr(m, "get_ticker", lambda: "NVDA")
+ monkeypatch.setattr(m, "get_analysis_date", lambda: "2026-09-01")
+ monkeypatch.setattr(m, "ask_output_language", lambda default=None: "English")
+ monkeypatch.setattr(m, "select_analysts", lambda asset_type, default=None: [AnalystType.MARKET])
+ monkeypatch.setattr(m, "select_research_depth", lambda default=None: 3)
+ monkeypatch.setattr(m, "select_llm_provider", lambda default=None: ("openai", None))
+ monkeypatch.setattr(m, "select_shallow_thinking_agent", lambda p, default=None: "gpt-5.6-mini")
+ monkeypatch.setattr(m, "select_deep_thinking_agent", lambda p, default=None: "gpt-5.6")
+ monkeypatch.setattr(m, "ask_openai_reasoning_effort", lambda: "medium")
+ return m
+
+
+@pytest.mark.unit
+def test_selections_are_remembered_after_a_run(monkeypatch):
+ """Drives the real flow: a stubbed selections dict would hide a key mismatch."""
+ m = _answer_every_prompt(monkeypatch)
+
+ m.get_user_selections()
+
+ remembered = load_last_run()
+ assert remembered["analysts"] == ["market"]
+ assert remembered["quick_think_llm"] == "gpt-5.6-mini"
+ assert remembered["deep_think_llm"] == "gpt-5.6"
+ assert remembered["llm_provider"] == "openai"
+ assert "ticker" not in remembered # changes every run; never remembered
+ assert "analysis_date" not in remembered # a stale date must not be offered
+
+
+@pytest.mark.unit
+def test_a_custom_language_is_remembered_without_breaking_the_next_run():
+ """A free-text answer is not one of the menu's choices, and questionary
+ rejects a default it cannot find, so offering it back would crash startup."""
+ from cli.utils import ask_output_language
+
+ save_last_run({"output_language": "Turkish"})
+ with mock.patch("cli.utils.questionary.select") as select:
+ select.return_value.ask.return_value = "English"
+ ask_output_language(load_last_run()["output_language"])
+ assert select.call_args.kwargs["default"] is None
+
+
+@pytest.mark.unit
+def test_a_remembered_endpoint_is_offered_back(monkeypatch):
+ """Users of a local or custom endpoint retyped the URL every run: it was
+ remembered and validated, then never read."""
+ import cli.main as m
+
+ save_last_run({"llm_provider": "openai_compatible", "backend_url": "http://localhost:1234/v1"})
+ offered = {}
+ monkeypatch.setattr(m, "select_llm_provider", lambda default=None: ("openai_compatible", None))
+ monkeypatch.setattr(m, "prompt_openai_compatible_url",
+ lambda default=None: offered.setdefault("default", default) or "http://x/v1")
+ monkeypatch.setattr(m, "fetch_announcements", lambda: [])
+ monkeypatch.setattr(m, "display_announcements", lambda *a: None)
+ monkeypatch.setattr(m, "get_ticker", lambda: "NVDA")
+ monkeypatch.setattr(m, "get_analysis_date", lambda: "2026-09-01")
+ monkeypatch.setattr(m, "ask_output_language", lambda default=None: "English")
+ monkeypatch.setattr(m, "select_analysts", lambda asset_type, default=None: [AnalystType.MARKET])
+ monkeypatch.setattr(m, "select_research_depth", lambda default=None: 1)
+ monkeypatch.setattr(m, "select_shallow_thinking_agent", lambda p, default=None: "local-model")
+ monkeypatch.setattr(m, "select_deep_thinking_agent", lambda p, default=None: "local-model")
+
+ m.get_user_selections()
+
+ assert offered["default"] == "http://localhost:1234/v1"
diff --git a/tests/test_cli_symbol_handling.py b/tests/test_cli_symbol_handling.py
index e599a4e09..950468cdc 100644
--- a/tests/test_cli_symbol_handling.py
+++ b/tests/test_cli_symbol_handling.py
@@ -60,3 +60,16 @@ def test_cli_normalize_delegates_to_data_layer():
# CLI must produce the same canonical symbol the data path will price.
for raw in ("XAUUSD", "BTCUSD", "btc-usdt", "AAPL"):
assert normalize_ticker_symbol(raw) == normalize_symbol(raw)
+
+
+@pytest.mark.unit
+def test_the_run_directory_cannot_escape_the_results_directory(tmp_path, monkeypatch):
+ """Every other path that interpolates a ticker validates it first; the CLI's
+ own results tree did not, so a ticker of '..' wrote a level up."""
+ import cli.main as m
+
+ with pytest.raises(ValueError):
+ m._run_directory({"results_dir": str(tmp_path)}, "..", "2026-09-01")
+
+ ok = m._run_directory({"results_dir": str(tmp_path)}, "NVDA", "2026-09-01")
+ assert str(ok).startswith(str(tmp_path))
diff --git a/tests/test_fred.py b/tests/test_fred.py
index a4ffbd213..a4ec29962 100644
--- a/tests/test_fred.py
+++ b/tests/test_fred.py
@@ -8,6 +8,7 @@ import unittest
from unittest import mock
import pytest
+import requests
import tradingagents.dataflows.config as config_module
import tradingagents.default_config as default_config
@@ -233,3 +234,53 @@ class FredRoutingTests(unittest.TestCase):
if __name__ == "__main__":
unittest.main()
+
+
+_KEY = "abcdef0123456789abcdef0123456789"
+
+
+@pytest.mark.unit
+class TestKeyKeptOutOfErrors:
+ """The key travels as a query parameter, and requests quotes the full URL in
+ its error messages, so any log or traceback would carry it (#1324)."""
+
+ def _raises(self, side_effect):
+ with mock.patch.dict("os.environ", {"FRED_API_KEY": _KEY}), \
+ mock.patch("tradingagents.dataflows.utils.requests.get", side_effect=side_effect), \
+ pytest.raises(requests.RequestException) as caught:
+ fred._request("series", {"series_id": "DGS10"})
+ return caught.value
+
+ def test_http_error_message_carries_no_key(self):
+ response = mock.Mock(status_code=502)
+ response.raise_for_status.side_effect = requests.HTTPError(
+ f"502 Server Error for url: https://api.stlouisfed.org/fred/series?api_key={_KEY}",
+ response=response,
+ )
+ with mock.patch.dict("os.environ", {"FRED_API_KEY": _KEY}), \
+ mock.patch("tradingagents.dataflows.utils.requests.get", return_value=response), \
+ pytest.raises(requests.HTTPError) as caught:
+ fred._request("series", {"series_id": "DGS10"})
+ exc = caught.value
+ assert _KEY not in str(exc) and _KEY not in repr(exc)
+ # The response and request carry the full URL, so they are not attached.
+ assert exc.response is None and exc.request is None
+ assert exc.__cause__ is None and exc.__context__ is None # no chain holds the key
+
+ def test_connection_error_before_any_response_carries_no_key(self):
+ exc = self._raises(requests.ConnectionError(
+ f"Max retries exceeded with url: /fred/series?series_id=DGS10&api_key={_KEY}"))
+ assert isinstance(exc, requests.ConnectionError)
+ assert _KEY not in str(exc) and exc.__context__ is None
+
+
+@pytest.mark.unit
+def test_error_without_the_key_in_its_message_still_drops_the_request():
+ # Some timeout messages omit the URL, but the attached request still has it.
+ import requests as rq
+ req = rq.Request("GET", f"https://api.stlouisfed.org/fred/series?api_key={_KEY}").prepare()
+ with mock.patch.dict("os.environ", {"FRED_API_KEY": _KEY}), \
+ mock.patch("tradingagents.dataflows.utils.requests.get", side_effect=rq.Timeout("Read timed out.", request=req)), \
+ pytest.raises(rq.Timeout) as caught:
+ fred._request("series", {"series_id": "DGS10"})
+ assert caught.value.request is None
diff --git a/tests/test_google_thinking_level.py b/tests/test_google_thinking_level.py
index f24ceff2f..e711c2aab 100644
--- a/tests/test_google_thinking_level.py
+++ b/tests/test_google_thinking_level.py
@@ -1,8 +1,8 @@
"""Gemini thinking_level forwarding (Gemini 3.x).
The catalog is Gemini 3.x only, which takes the string ``thinking_level``
-directly. Pro accepts low/high; Flash also accepts minimal/medium — an
-unsupported "minimal" on Pro is mapped to "low".
+directly. Pro, Gemini 3.8+ and the -latest aliases reject "minimal" with a 400,
+so it is mapped to "low" there; numbered Flash models before 3.8 accept it.
"""
from unittest import mock
@@ -35,6 +35,22 @@ def test_pro_remaps_minimal_to_low():
assert kw["thinking_level"] == "low" # Pro doesn't accept "minimal"
+def test_flash_38_remaps_minimal_to_low():
+ kw = _captured_kwargs("gemini-3.8-flash", thinking_level="minimal")
+ assert kw["thinking_level"] == "low" # 3.8 Flash 400s on "minimal"
+
+
+def test_flash_38_keeps_supported_levels():
+ kw = _captured_kwargs("gemini-3.8-flash", thinking_level="high")
+ assert kw["thinking_level"] == "high"
+
+
+@pytest.mark.parametrize("alias", ["gemini-flash-latest", "gemini-pro-latest"])
+def test_latest_alias_remaps_minimal_to_low(alias):
+ # Aliases move between generations; gemini-flash-latest 400s on "minimal".
+ assert _captured_kwargs(alias, thinking_level="minimal")["thinking_level"] == "low"
+
+
def test_pro_keeps_high():
kw = _captured_kwargs("gemini-3.1-pro-preview", thinking_level="high")
assert kw["thinking_level"] == "high"
diff --git a/tests/test_market_data_validator.py b/tests/test_market_data_validator.py
index 40b6349e2..c26d6f537 100644
--- a/tests/test_market_data_validator.py
+++ b/tests/test_market_data_validator.py
@@ -29,7 +29,7 @@ class TestVerifiedSnapshot:
pd.DataFrame({"Date": [pd.Timestamp("2026-06-01")], "Open": [999.0],
"High": [999.0], "Low": [999.0], "Close": [999.0], "Volume": [999]}),
], ignore_index=True)
- monkeypatch.setattr(validator, "load_ohlcv", lambda s, d: data)
+ monkeypatch.setattr(validator, "load_ohlcv", lambda s, d, fill_gaps=True: data)
snap = validator.build_verified_market_snapshot("COF", "2026-05-13")
assert "Verified market data snapshot for COF" in snap
@@ -39,24 +39,24 @@ class TestVerifiedSnapshot:
assert "boll_lb" in snap # indicators present
def test_uses_previous_trading_day_when_date_is_weekend(self, monkeypatch):
- monkeypatch.setattr(validator, "load_ohlcv", lambda s, d: _sample_ohlcv())
+ monkeypatch.setattr(validator, "load_ohlcv", lambda s, d, fill_gaps=True: _sample_ohlcv())
# 2026-05-16 is a Saturday; latest row should be Fri 2026-05-15
snap = validator.build_verified_market_snapshot("COF", "2026-05-16")
assert "Latest trading row used: 2026-05-15" in snap
assert "Recent verified closes" in snap
def test_raises_when_no_rows_on_or_before_date(self, monkeypatch):
- monkeypatch.setattr(validator, "load_ohlcv", lambda s, d: _sample_ohlcv())
+ monkeypatch.setattr(validator, "load_ohlcv", lambda s, d, fill_gaps=True: _sample_ohlcv())
with pytest.raises(ValueError):
validator.build_verified_market_snapshot("COF", "2020-01-01")
def test_raises_on_empty_data(self, monkeypatch):
- monkeypatch.setattr(validator, "load_ohlcv", lambda s, d: pd.DataFrame())
+ monkeypatch.setattr(validator, "load_ohlcv", lambda s, d, fill_gaps=True: pd.DataFrame())
with pytest.raises(ValueError):
validator.build_verified_market_snapshot("COF", "2026-05-13")
def test_look_back_window_capped_at_30(self, monkeypatch):
- monkeypatch.setattr(validator, "load_ohlcv", lambda s, d: _sample_ohlcv())
+ monkeypatch.setattr(validator, "load_ohlcv", lambda s, d, fill_gaps=True: _sample_ohlcv())
snap = validator.build_verified_market_snapshot("COF", "2026-05-20", look_back_days=999)
# last-N closes table has at most 30 data rows
close_rows = [ln for ln in snap.splitlines() if ln.startswith("| 2026-")]
@@ -69,7 +69,7 @@ class TestTool:
from tradingagents.agents.utils.market_data_validation_tools import (
get_verified_market_snapshot,
)
- monkeypatch.setattr(validator, "load_ohlcv", lambda s, d: _sample_ohlcv())
+ monkeypatch.setattr(validator, "load_ohlcv", lambda s, d, fill_gaps=True: _sample_ohlcv())
out = get_verified_market_snapshot.invoke(
{"symbol": "COF", "curr_date": "2026-05-20"}
)
diff --git a/tests/test_memory_log.py b/tests/test_memory_log.py
index 3db0ac531..b4d6af6f3 100644
--- a/tests/test_memory_log.py
+++ b/tests/test_memory_log.py
@@ -136,6 +136,23 @@ class TestTradingMemoryLogCore:
log.store_decision("NVDA", "2026-01-10", DECISION_BUY)
assert len(log.load_entries()) == 1
+ def test_store_decision_idempotent_after_the_entry_resolves(self, tmp_path):
+ """A settled entry still blocks a duplicate.
+
+ The guard matched only pending entries, so re-running a ticker and date
+ whose outcome had already been settled appended a second entry: the same
+ decision counted twice in past context and in any aggregate over the log.
+ """
+ log = make_log(tmp_path)
+ log.store_decision("NVDA", "2026-01-10", DECISION_BUY)
+ log.update_with_outcome("NVDA", "2026-01-10", 0.05, 0.02, 5, "worked", "2026-01-17")
+
+ log.store_decision("NVDA", "2026-01-10", DECISION_BUY)
+
+ entries = log.load_entries()
+ assert len(entries) == 1
+ assert entries[0]["pending"] is False # the settled record is kept, not replaced
+
def test_batch_update_resolves_multiple_entries(self, tmp_path):
"""batch_update_with_outcomes resolves multiple pending entries in one write."""
log = make_log(tmp_path)
@@ -176,10 +193,14 @@ class TestTradingMemoryLogCore:
log.store_decision("AAPL", "2026-01-11", DECISION_OVERWEIGHT)
assert log.load_entries()[0]["rating"] == "Overweight"
- def test_rating_fallback_hold(self, tmp_path):
+ def test_an_unreadable_decision_is_tagged_for_review(self, tmp_path):
+ """Not a Hold: a fabricated rating is quoted back to the next run as a
+ call that was never made, and counted in the backtest figures."""
+ from tradingagents.agents.utils.rating import RATING_REVIEW
+
log = make_log(tmp_path)
log.store_decision("MSFT", "2026-01-12", DECISION_NO_RATING)
- assert log.load_entries()[0]["rating"] == "Hold"
+ assert log.load_entries()[0]["rating"] == RATING_REVIEW
def test_rating_priority_over_prose(self, tmp_path):
"""'Rating: X' label wins even when an opposing rating word appears earlier in prose."""
@@ -589,6 +610,13 @@ class TestDeferredReflection:
assert TradingAgentsGraph._resolve_benchmark(mock_graph, "RELIANCE.NS") == "^NSEI"
assert TradingAgentsGraph._resolve_benchmark(mock_graph, "AZN.L") == "^FTSE"
+ def test_explicit_benchmark_is_resolved_like_any_other_symbol(self):
+ """A configured benchmark takes the same alias mapping as the ticker, or
+ the return lookup finds nothing and the decision never settles."""
+ mock_graph = MagicMock(spec=TradingAgentsGraph)
+ mock_graph.config = {"benchmark_ticker": "SPX500", "benchmark_map": {"": "SPY"}}
+ assert TradingAgentsGraph._resolve_benchmark(mock_graph, "NVDA") == "^GSPC"
+
def test_resolve_benchmark_china_a_shares(self):
"""A-share tickers route to their exchange composite (uses the real
default benchmark_map, since A-share support relies on it)."""
@@ -598,6 +626,8 @@ class TestDeferredReflection:
"benchmark_map": DEFAULT_CONFIG["benchmark_map"]}
assert TradingAgentsGraph._resolve_benchmark(mock_graph, "600519.SS") == "000001.SS"
assert TradingAgentsGraph._resolve_benchmark(mock_graph, "000001.SZ") == "399001.SZ"
+ # .SH is the exchange's own suffix; Yahoo spells Shanghai .SS (#1260)
+ assert TradingAgentsGraph._resolve_benchmark(mock_graph, "600519.SH") == "000001.SS"
def test_resolve_benchmark_us_ticker_defaults_to_spy(self):
"""US tickers (no dotted suffix) take the empty-suffix entry."""
@@ -665,6 +695,7 @@ class TestDeferredReflection:
log = make_log(tmp_path)
log.store_decision("AAPL", "2026-01-10", DECISION_BUY)
mock_graph = MagicMock(spec=TradingAgentsGraph)
+ mock_graph.config = {}
mock_graph.memory_log = log
mock_graph._fetch_returns = MagicMock(return_value=(0.05, 0.02, 5, "2026-01-12"))
TradingAgentsGraph._resolve_pending_entries(mock_graph, "NVDA")
@@ -678,6 +709,7 @@ class TestDeferredReflection:
mock_reflector = MagicMock()
mock_reflector.reflect_on_final_decision.return_value = "Momentum confirmed."
mock_graph = MagicMock(spec=TradingAgentsGraph)
+ mock_graph.config = {}
mock_graph.memory_log = log
mock_graph.reflector = mock_reflector
mock_graph._fetch_returns = MagicMock(return_value=(0.05, 0.02, 5, "2026-01-12"))
@@ -697,6 +729,7 @@ class TestDeferredReflection:
log.store_decision("NVDA", "2026-01-05", DECISION_BUY)
mock_reflector = MagicMock()
mock_graph = MagicMock(spec=TradingAgentsGraph)
+ mock_graph.config = {}
mock_graph.memory_log = log
mock_graph.reflector = mock_reflector
mock_graph._fetch_returns = MagicMock(return_value=(None, None, None, None))
@@ -903,8 +936,107 @@ class TestLegacyRemoval:
mock_graph._run_graph = functools.partial(
TradingAgentsGraph._run_graph, mock_graph
)
+ mock_graph.record_decision = functools.partial(
+ TradingAgentsGraph.record_decision, mock_graph
+ )
TradingAgentsGraph.propagate(mock_graph, "NVDA", "2026-01-10")
entries = mock_graph.memory_log.load_entries()
assert len(entries) == 1
assert entries[0]["ticker"] == "NVDA"
assert entries[0]["pending"] is True
+
+
+@pytest.mark.unit
+def test_a_failed_reflection_leaves_the_entry_pending_and_lets_the_run_start(tmp_path, monkeypatch):
+ """Settling past decisions happens on the way into a new run, and reflection
+ calls an LLM. A transient failure there must not stop the new analysis."""
+ from tradingagents.agents.utils.memory import TradingMemoryLog
+ from tradingagents.graph.trading_graph import TradingAgentsGraph
+
+ graph = object.__new__(TradingAgentsGraph)
+ graph.config = {"memory_log_path": str(tmp_path / "m.md")}
+ graph.memory_log = TradingMemoryLog(graph.config)
+ graph.memory_log.store_decision("NVDA", "2026-01-05", "Rating: Buy\n\nx")
+ graph.memory_log.store_decision("NVDA", "2026-01-12", "Rating: Sell\n\ny")
+ monkeypatch.setattr(graph, "_resolve_benchmark", lambda t: "SPY", raising=False)
+ monkeypatch.setattr(graph, "_fetch_returns",
+ lambda t, d, holding_days=5, benchmark=None: (0.01, 0.005, holding_days, "2026-01-19"), raising=False)
+
+ class _Reflector:
+ calls = 0
+
+ def reflect_on_final_decision(self, **kw):
+ _Reflector.calls += 1
+ if _Reflector.calls == 1:
+ raise RuntimeError("provider timed out")
+ return "second one worked"
+
+ graph.reflector = _Reflector()
+
+ graph._resolve_pending_entries("NVDA") # must not raise
+
+ entries = graph.memory_log.load_entries()
+ assert [e["pending"] for e in entries] == [True, False] # the failed one waits for next time
+
+
+@pytest.mark.unit
+def test_the_holding_window_is_configurable(tmp_path, monkeypatch):
+ """A decision written for months should not be graded at a week without the
+ operator choosing that window."""
+ from tradingagents.agents.utils.memory import TradingMemoryLog
+ from tradingagents.graph.trading_graph import TradingAgentsGraph
+
+ graph = object.__new__(TradingAgentsGraph)
+ graph.config = {"memory_log_path": str(tmp_path / "m.md"), "holding_period_days": 21}
+ graph.memory_log = TradingMemoryLog(graph.config)
+ graph.memory_log.store_decision("NVDA", "2026-01-05", "**Rating**: Buy\n\nx")
+ monkeypatch.setattr(graph, "_resolve_benchmark", lambda t: "SPY", raising=False)
+ asked = {}
+
+ def _returns(ticker, date, holding_days=5, benchmark=None):
+ asked["holding_days"] = holding_days
+ return 0.05, 0.02, holding_days, "2026-02-02"
+
+ monkeypatch.setattr(graph, "_fetch_returns", _returns, raising=False)
+ graph.reflector = type("R", (), {"reflect_on_final_decision": lambda self, **kw: "lesson"})()
+
+ graph._resolve_pending_entries("NVDA")
+
+ assert asked["holding_days"] == 21
+ assert graph.memory_log.load_entries()[0]["holding"] == "21d"
+
+
+@pytest.mark.unit
+def test_the_reflection_states_the_window_it_judges():
+ """Judging a months-long thesis on a week's alpha, without saying so, turns
+ a scope mismatch into a lesson that the call was wrong."""
+ from tradingagents.graph.reflection import Reflector
+
+ prompt = Reflector(None)._system_prompt(holding_days=5)
+ assert "5" in prompt and "trading day" in prompt
+
+
+@pytest.mark.unit
+def test_a_longer_window_asks_for_enough_price_history(monkeypatch):
+ """Trading days are not calendar days: a 21-day window needs about a month
+ of bars, and asking for 28 days left every outcome unsettled."""
+ from tradingagents.graph.trading_graph import TradingAgentsGraph
+
+ graph = object.__new__(TradingAgentsGraph)
+ asked = {}
+
+ class _Ticker:
+ def __init__(self, symbol):
+ self.symbol = symbol
+
+ def history(self, start, end):
+ asked["start"], asked["end"] = start, end
+ import pandas as pd
+ days = pd.bdate_range(start, end)
+ return pd.DataFrame({"Close": range(len(days))}, index=days)
+
+ monkeypatch.setattr("tradingagents.graph.trading_graph.yf.Ticker", _Ticker)
+
+ raw, alpha, days, resolved = graph._fetch_returns("NVDA", "2026-06-01", 21, benchmark="SPY")
+
+ assert days == 21 and resolved is not None, (raw, alpha, days, resolved)
diff --git a/tests/test_model_validation.py b/tests/test_model_validation.py
index 5392d7cd9..4f6ded8fa 100644
--- a/tests/test_model_validation.py
+++ b/tests/test_model_validation.py
@@ -53,3 +53,48 @@ class ModelValidationTests(unittest.TestCase):
client.get_llm()
self.assertEqual(caught, [])
+
+
+def test_legacy_ids_stay_valid_without_being_offered():
+ from tradingagents.llm_clients.model_catalog import LEGACY_MODELS, MODEL_OPTIONS
+ from tradingagents.llm_clients.validators import validate_model
+
+ for provider, ids in LEGACY_MODELS.items():
+ offered = {v for opts in MODEL_OPTIONS[provider].values() for _, v in opts}
+ for model in ids:
+ assert validate_model(provider, model), model
+ assert model not in offered, f"{model} is legacy but still in the picker"
+
+
+@pytest.mark.unit
+def test_an_explicit_alias_of_a_listed_model_is_known():
+ """gpt-5.6 is served under its own name and as gpt-5.6-sol; naming the
+ explicit one should not warn that the model is unknown."""
+ from tradingagents.llm_clients.validators import validate_model
+
+ assert validate_model("openai", "gpt-5.6-sol")
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("provider", ["openai", "anthropic", "google", "xai"])
+@pytest.mark.parametrize("mode", ["quick", "deep"])
+def test_every_provider_lets_you_name_your_own_model(provider, mode):
+ """The docs tell users to name any model their provider serves; the picker
+ has to offer that too, or a new model is unreachable until we ship a list."""
+ from tradingagents.llm_clients.model_catalog import get_model_options
+
+ assert "custom" in [value for _, value in get_model_options(provider, mode)]
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("provider, model", [
+ ("xai", "grok-4.20-0309-reasoning"),
+ ("deepseek", "deepseek-v4-flash"),
+ ("qwen", "qwen3.7-max"),
+])
+def test_a_retired_model_id_still_runs_without_a_warning(provider, model):
+ """A config written against an earlier release keeps working: the provider
+ still serves these, they are just no longer offered in the picker."""
+ from tradingagents.llm_clients.validators import validate_model
+
+ assert validate_model(provider, model)
diff --git a/tests/test_news_lookahead.py b/tests/test_news_lookahead.py
index 367566edc..2d7106415 100644
--- a/tests/test_news_lookahead.py
+++ b/tests/test_news_lookahead.py
@@ -101,5 +101,159 @@ def test_global_news_empty_after_filter_is_informative(monkeypatch):
monkeypatch.setattr(ynews.yf, "Search", FakeSearch)
out = ynews.get_global_news_yfinance("2025-05-09", look_back_days=7, limit=10)
- assert "No global news found" in out
assert "###" not in out # no empty article body
+ # Only a later article came back, so the feed does not reach this window.
+ assert "unavailable" in out and "not an absence" in out
+
+
+
+def _ticker_with(articles, monkeypatch):
+ class FakeTicker:
+ def __init__(self, *a, **k):
+ pass
+
+ def get_news(self, count=20):
+ return articles
+
+ monkeypatch.setattr(ynews.yf, "Ticker", FakeTicker)
+
+
+@pytest.mark.unit
+def test_ticker_news_window_before_feed_coverage_is_unavailable(monkeypatch):
+ # Yahoo serves only recent articles: a historical window gets none of them,
+ # which must read as "cannot answer", not "no news happened".
+ recent = [{"title": "RECENT", "publisher": "P", "link": "l",
+ "providerPublishTime": _epoch("2026-09-10")}]
+ _ticker_with(recent, monkeypatch)
+ out = ynews.get_news_yfinance("AAPL", "2026-08-07", "2026-08-14")
+ assert "RECENT" not in out
+ assert "unavailable" in out and "not an absence" in out
+ assert "2026-09-10" in out # says how far back the feed actually reaches
+
+
+@pytest.mark.unit
+def test_ticker_news_covered_but_empty_window_is_a_real_absence(monkeypatch):
+ articles = [{"title": "RECENT", "publisher": "P", "link": "l",
+ "providerPublishTime": _epoch("2026-09-10")},
+ {"title": "OLDER", "publisher": "P", "link": "l",
+ "providerPublishTime": _epoch("2026-07-01")}]
+ _ticker_with(articles, monkeypatch)
+ out = ynews.get_news_yfinance("AAPL", "2026-08-07", "2026-08-14")
+ assert "No news found" in out
+ assert "unavailable" not in out
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("dates, expect_gap", [
+ ([], True), # empty feed: covers at most now
+ ([None], True), # undated only: same
+ ([datetime(2026, 5, 20, tzinfo=timezone.utc)], True), # all after the window
+ ([datetime(2026, 5, 4, tzinfo=timezone.utc)], True), # starts mid-window: partial
+ ([datetime(2026, 5, 1, 18, tzinfo=timezone.utc)], False), # reaches the first day
+ ([datetime(2026, 5, 20, tzinfo=timezone.utc),
+ datetime(2026, 4, 1, tzinfo=timezone.utc)], False), # coverage reaches back
+])
+def test_coverage_gap_boundaries(dates, expect_gap):
+ from tradingagents.dataflows.date_window import coverage_gap
+
+ out = coverage_gap(dates, "2026-05-01", "2026-05-08", "Feed", "items")
+ assert (out is not None) is expect_gap
+ if expect_gap:
+ assert "unavailable for 2026-05-01..2026-05-08" in out and "not an absence" in out
+
+
+
+@pytest.mark.unit
+def test_ticker_news_empty_feed_for_a_past_window_is_unavailable(monkeypatch):
+ _ticker_with([], monkeypatch)
+ out = ynews.get_news_yfinance("AAPL", "2026-08-07", "2026-08-14")
+ assert "unavailable" in out and "not an absence" in out
+
+
+@pytest.mark.unit
+def test_ticker_news_null_feed_is_handled(monkeypatch):
+ # Yahoo can return None instead of a list; that is unavailability, not an error.
+ _ticker_with(None, monkeypatch)
+ out = ynews.get_news_yfinance("AAPL", "2026-08-07", "2026-08-14")
+ assert "unavailable" in out and "Error" not in out
+
+
+@pytest.mark.unit
+def test_global_news_empty_feed_for_a_past_window_is_unavailable(monkeypatch):
+ class FakeSearch:
+ def __init__(self, *a, **k):
+ self.news = []
+
+ monkeypatch.setattr(ynews.yf, "Search", FakeSearch)
+ out = ynews.get_global_news_yfinance("2025-05-09", look_back_days=7, limit=10)
+ assert "unavailable" in out and "not an absence" in out
+
+
+@pytest.mark.unit
+def test_global_news_does_not_infer_coverage_from_a_stale_search_hit(monkeypatch):
+ # Global news merges fuzzy searches; one old hit before the window says
+ # nothing about the days in between, so the window stays unavailable.
+ stale = {"title": "STALE", "publisher": "P", "link": "l", "providerPublishTime": _epoch("2025-01-01")}
+ fresh = {"title": "FRESH", "publisher": "P", "link": "l", "providerPublishTime": _epoch("2025-06-01")}
+
+ class FakeSearch:
+ def __init__(self, *a, **k):
+ self.news = [fresh, stale]
+
+ monkeypatch.setattr(ynews.yf, "Search", FakeSearch)
+ out = ynews.get_global_news_yfinance("2025-05-09", look_back_days=7, limit=10)
+ assert "unavailable" in out and "No global news found" not in out
+
+
+@pytest.mark.unit
+def test_coverage_gap_future_window_is_unavailable():
+ from datetime import timedelta
+
+ from tradingagents.dataflows.date_window import coverage_gap
+ today = datetime.now(timezone.utc).date()
+ out = coverage_gap([], str(today), str(today + timedelta(days=3)), "Feed", "items")
+ assert out is not None and "past today" in out
+
+
+@pytest.mark.unit
+def test_out_of_window_articles_do_not_consume_the_article_budget(monkeypatch):
+ """The limit counts articles the run may see, not candidates fetched (#1356).
+
+ Out-of-window items were counted first, so they filled the budget, stopped
+ the remaining searches, and the in-window news was reported as absent.
+ """
+ stale = [{"title": f"OLD {i}", "publisher": "P", "link": "l",
+ "providerPublishTime": _epoch("2025-01-01")} for i in range(2)]
+ wanted = {"title": "IN WINDOW", "publisher": "P", "link": "l",
+ "providerPublishTime": _epoch("2025-05-08")}
+ pages = [stale, [wanted]]
+
+ class FakeSearch:
+ def __init__(self, *a, **k):
+ self.news = pages.pop(0) if pages else []
+
+ monkeypatch.setattr(ynews.yf, "Search", FakeSearch)
+ monkeypatch.setattr(ynews, "get_config", lambda: {
+ "global_news_lookback_days": 7, "global_news_article_limit": 2,
+ "global_news_queries": ["markets", "economy"],
+ })
+
+ out = ynews.get_global_news_yfinance("2025-05-09")
+
+ assert "IN WINDOW" in out
+ assert "OLD 0" not in out
+
+
+@pytest.mark.unit
+def test_the_article_limit_still_caps_what_is_returned(monkeypatch):
+ articles = [{"title": f"NEWS {i}", "publisher": "P", "link": "l",
+ "providerPublishTime": _epoch("2025-05-08")} for i in range(5)]
+
+ class FakeSearch:
+ def __init__(self, *a, **k):
+ self.news = articles
+
+ monkeypatch.setattr(ynews.yf, "Search", FakeSearch)
+ out = ynews.get_global_news_yfinance("2025-05-09", look_back_days=7, limit=3)
+
+ assert out.count("### ") == 3
diff --git a/tests/test_ohlcv_cache_freshness.py b/tests/test_ohlcv_cache_freshness.py
index 65a417f26..a30dc78d7 100644
--- a/tests/test_ohlcv_cache_freshness.py
+++ b/tests/test_ohlcv_cache_freshness.py
@@ -1,80 +1,72 @@
-"""Same-day OHLCV cache must not serve a stale snapshot all day (#1150).
+"""The OHLCV cache: one file per symbol, fresh only on the day it was written.
-The cache file is keyed per day, so a run started before the day's bar was final
-would be reused by every later run, feeding a stale close into technical
-analysis. Two cases matter for a current-day request: the bar may be missing, or
-present but still in progress (Yahoo publishes a partial daily candle intraday).
-Refresh is bounded by a TTL so repeated runs cannot hammer the vendor.
+A current-day request also refetches past a TTL, so a run started before the
+day's bar was final is not served that snapshot all day (#1150). Keying the file
+by symbol rather than by day keeps the cache from growing a file per symbol per
+day (#1330).
"""
from __future__ import annotations
import os
-import time
import pandas as pd
import pytest
import tradingagents.dataflows.stockstats_utils as su
-TODAY = pd.Timestamp("2026-07-18")
+NOW = pd.Timestamp("2026-07-18 12:00")
STALE = su.OHLCV_CACHE_TTL_SECONDS + 60
-def _write(tmp_path, name="cache.csv", age_seconds=0.0, last_date="2026-07-17"):
+def _write(tmp_path, name="AAPL-YFin-data.csv", age_seconds=0.0, last_date="2026-07-17"):
f = tmp_path / name
- pd.DataFrame({"Date": [last_date], "Close": [1.0]}).to_csv(f, index=False)
- if age_seconds:
- old = time.time() - age_seconds
- os.utime(f, (old, old))
- return str(f)
+ pd.DataFrame({"Date": [last_date], "Close": [100.0]}).to_csv(f, index=False)
+ written = NOW.timestamp() - age_seconds
+ os.utime(f, (written, written))
+ return f
+
+
+def _load(tmp_path, monkeypatch, curr_date, download):
+ monkeypatch.setattr(su, "get_config", lambda: {"data_cache_dir": str(tmp_path)})
+ monkeypatch.setattr(su.pd.Timestamp, "today", staticmethod(lambda: NOW))
+ monkeypatch.setattr(su.yf, "download", download)
+ return su.load_ohlcv("AAPL", curr_date)
+
+
+def _fail_download(*a, **k):
+ raise AssertionError("fresh cache must not refetch")
@pytest.mark.unit
-def test_current_day_cache_past_ttl_is_refreshed(tmp_path):
- # Bar missing (rows stop at yesterday) and file older than the TTL -> refetch.
- assert su._needs_same_day_refresh(_write(tmp_path, age_seconds=STALE), TODAY, TODAY) is True
-
-
-@pytest.mark.unit
-def test_partial_current_day_bar_is_still_refreshed(tmp_path):
- # Today's row is present but may be an in-progress candle whose Close is not
- # the closing price. Row inspection can't distinguish it, so the TTL governs.
+def test_current_day_cache_past_ttl_is_not_fresh(tmp_path):
+ # Today's bar missing or still in progress: row inspection can't tell, so the TTL governs.
+ assert su._cache_is_fresh(_write(tmp_path, age_seconds=STALE), NOW.normalize(), NOW) is False
f = _write(tmp_path, age_seconds=STALE, last_date="2026-07-18")
- assert su._needs_same_day_refresh(f, TODAY, TODAY) is True
+ assert su._cache_is_fresh(f, NOW.normalize(), NOW) is False
@pytest.mark.unit
-def test_recent_cache_is_not_refetched(tmp_path):
+def test_recent_cache_is_fresh(tmp_path):
# Written moments ago: don't hammer the vendor (weekend/holiday guard).
- assert su._needs_same_day_refresh(_write(tmp_path), TODAY, TODAY) is False
+ assert su._cache_is_fresh(_write(tmp_path), NOW.normalize(), NOW) is True
@pytest.mark.unit
-def test_historical_request_always_uses_cache(tmp_path):
- # Past dates are immutable: never refetch, however old the file is.
- past = pd.Timestamp("2026-05-01")
+def test_historical_request_uses_todays_cache_past_the_ttl(tmp_path):
f = _write(tmp_path, age_seconds=STALE, last_date="2026-04-30")
- assert su._needs_same_day_refresh(f, past, TODAY) is False
+ assert su._cache_is_fresh(f, pd.Timestamp("2026-05-01"), NOW) is True
+
+
+@pytest.mark.unit
+def test_a_download_from_an_earlier_day_is_not_fresh(tmp_path):
+ f = _write(tmp_path, age_seconds=13 * 3600) # yesterday 23:00
+ assert su._cache_is_fresh(f, pd.Timestamp("2026-05-01"), NOW) is False
@pytest.mark.unit
def test_load_ohlcv_refetches_stale_same_day_cache(tmp_path, monkeypatch):
- """End-to-end: the helper is actually wired into load_ohlcv's cache branch.
-
- Without this, the unit tests above would still pass if the helper were never
- called from the real code path.
- """
- monkeypatch.setattr(su, "get_config", lambda: {"data_cache_dir": str(tmp_path)})
- monkeypatch.setattr(su.pd.Timestamp, "today", staticmethod(lambda: TODAY))
-
- # Pre-seed the cache file load_ohlcv will look for, aged past the TTL.
- start = (TODAY - pd.DateOffset(years=5)).strftime("%Y-%m-%d")
- end = (TODAY + pd.Timedelta(days=1)).strftime("%Y-%m-%d")
- cache_file = tmp_path / f"AAPL-YFin-data-{start}-{end}.csv"
- pd.DataFrame({"Date": ["2026-07-17"], "Close": [100.0]}).to_csv(cache_file, index=False)
- old = time.time() - STALE
- os.utime(cache_file, (old, old))
-
+ """End-to-end: the freshness check is wired into load_ohlcv's cache branch."""
+ _write(tmp_path, age_seconds=STALE)
calls = []
def _fake_download(*a, **k):
@@ -83,27 +75,31 @@ def test_load_ohlcv_refetches_stale_same_day_cache(tmp_path, monkeypatch):
{"Date": pd.to_datetime(["2026-07-17", "2026-07-18"]), "Close": [100.0, 222.0]}
).set_index("Date")
- monkeypatch.setattr(su.yf, "download", _fake_download)
-
- out = su.load_ohlcv("AAPL", TODAY.strftime("%Y-%m-%d"))
-
+ out = _load(tmp_path, monkeypatch, "2026-07-18", _fake_download)
assert calls, "stale same-day cache must trigger a refetch"
assert 222.0 in out["Close"].values, "refreshed close must reach the caller"
@pytest.mark.unit
def test_load_ohlcv_reuses_fresh_same_day_cache(tmp_path, monkeypatch):
- # Mirror image: a fresh cache must NOT trigger a download.
+ _write(tmp_path, last_date="2026-07-18")
+ _load(tmp_path, monkeypatch, "2026-07-18", _fail_download)
+
+
+@pytest.mark.unit
+def test_one_cache_file_per_symbol_across_days(tmp_path, monkeypatch):
+ """A later day's download replaces the symbol's file instead of adding one (#1330)."""
monkeypatch.setattr(su, "get_config", lambda: {"data_cache_dir": str(tmp_path)})
- monkeypatch.setattr(su.pd.Timestamp, "today", staticmethod(lambda: TODAY))
+ frame = pd.DataFrame({"Date": pd.to_datetime(["2026-07-16", "2026-07-17"]), "Close": [1.0, 2.0]})
+ downloads = []
+ monkeypatch.setattr(su.yf, "download", lambda *a, **k: downloads.append(1) or frame.set_index("Date"))
- start = (TODAY - pd.DateOffset(years=5)).strftime("%Y-%m-%d")
- end = (TODAY + pd.Timedelta(days=1)).strftime("%Y-%m-%d")
- cache_file = tmp_path / f"AAPL-YFin-data-{start}-{end}.csv"
- pd.DataFrame({"Date": ["2026-07-18"], "Close": [100.0]}).to_csv(cache_file, index=False)
+ for day in ("2026-07-18 10:00", "2026-07-19 10:00", "2026-07-20 10:00"):
+ now = pd.Timestamp(day)
+ monkeypatch.setattr(su.pd.Timestamp, "today", staticmethod(lambda now=now: now))
+ su.load_ohlcv("AAPL", "2026-07-17")
+ written = list(tmp_path.glob("AAPL-*.csv"))
+ os.utime(written[0], (now.timestamp(), now.timestamp()))
- def _fail_download(*a, **k):
- raise AssertionError("fresh cache must not refetch")
-
- monkeypatch.setattr(su.yf, "download", _fail_download)
- su.load_ohlcv("AAPL", TODAY.strftime("%Y-%m-%d"))
+ assert len(downloads) == 3, "each new day refetches"
+ assert [p.name for p in tmp_path.iterdir()] == ["AAPL-YFin-data.csv"]
diff --git a/tests/test_ohlcv_latest_bar.py b/tests/test_ohlcv_latest_bar.py
index cf9bca676..548264cc5 100644
--- a/tests/test_ohlcv_latest_bar.py
+++ b/tests/test_ohlcv_latest_bar.py
@@ -13,6 +13,8 @@ anywhere counts as no data and the staleness check judges the rest.
"""
from __future__ import annotations
+import os
+
import pandas as pd
import pytest
@@ -89,9 +91,9 @@ def _run_load(monkeypatch, tmp_path, frame, curr_date):
monkeypatch.setattr(su, "get_config", lambda: {"data_cache_dir": str(tmp_path)})
today = pd.Timestamp(curr_date)
monkeypatch.setattr(su.pd.Timestamp, "today", staticmethod(lambda: today))
- start = (today - pd.DateOffset(years=5)).strftime("%Y-%m-%d")
- end = (today + pd.Timedelta(days=1)).strftime("%Y-%m-%d")
- (tmp_path / f"AAPL-YFin-data-{start}-{end}.csv").write_text(frame.to_csv(index=False))
+ cache_file = tmp_path / "AAPL-YFin-data.csv"
+ cache_file.write_text(frame.to_csv(index=False))
+ os.utime(cache_file, (today.timestamp(), today.timestamp()))
def _fail_download(*a, **k):
raise AssertionError("should use the seeded cache, not download")
@@ -165,3 +167,34 @@ def test_tz_aware_latest_bar_is_kept_at_the_cutoff(monkeypatch, tmp_path):
out = _run_load(monkeypatch, tmp_path, frame, "2026-05-08")
assert out["Close"].iloc[-1] == 101.5
assert out["Date"].iloc[-1] == pd.Timestamp("2026-05-08")
+
+
+@pytest.mark.unit
+def test_the_snapshot_does_not_present_a_filled_price_as_reported(monkeypatch, tmp_path):
+ """Gap filling exists so indicators compute on a continuous series. The
+ verification snapshot is the one place a number must be what the vendor
+ reported, or the module built to stop invented prices supplies them."""
+ from tradingagents.dataflows import market_data_validator as mdv, stockstats_utils as su
+
+ frame = pd.DataFrame({
+ "Date": ["2026-05-06", "2026-05-07", "2026-05-08"],
+ "Open": [100.0, 104.5, ""], # the latest bar has not settled
+ "High": [101.0, 105.5, ""],
+ "Low": [99.0, 103.5, ""],
+ "Close": [100.5, 105.0, 106.0],
+ "Volume": [1000000, 1000000, ""],
+ })
+ today = pd.Timestamp("2026-05-08 12:00")
+ monkeypatch.setattr(su, "get_config", lambda: {"data_cache_dir": str(tmp_path)})
+ monkeypatch.setattr(su.pd.Timestamp, "today", staticmethod(lambda: today))
+ cache = tmp_path / "AAPL-YFin-data.csv"
+ cache.write_text(frame.to_csv(index=False))
+ os.utime(cache, (today.timestamp(), today.timestamp()))
+ monkeypatch.setattr(su.yf, "download", lambda *a, **k: (_ for _ in ()).throw(
+ AssertionError("should read the seeded cache")))
+
+ out = mdv.build_verified_market_snapshot("AAPL", "2026-05-08", 3)
+
+ row = out.split("Latest verified OHLCV row")[1].split("###")[0]
+ assert "104.50" not in row and "105.50" not in row # the previous session's numbers
+ assert "106.00" in row # the close the vendor did report
diff --git a/tests/test_ollama_base_url.py b/tests/test_ollama_base_url.py
index c54162da6..3c949e63c 100644
--- a/tests/test_ollama_base_url.py
+++ b/tests/test_ollama_base_url.py
@@ -197,3 +197,28 @@ def test_ollama_offers_custom_model_id():
assert "custom" in values, f"Ollama {mode!r} missing 'custom' option: {entries}"
# Custom option is last so it doesn't push the curated defaults off-screen
assert values[-1] == "custom", f"'custom' should be last entry: {values}"
+
+
+@pytest.mark.unit
+def test_structured_output_suppresses_object_tool_choice(monkeypatch):
+ """Ollama rejects the object-form tool_choice like other local servers
+ (#1062), and a local model ID has no capability entry saying otherwise, so
+ it takes the same client as the generic local endpoint."""
+ from langchain_openai import ChatOpenAI
+ from pydantic import BaseModel
+
+ from tradingagents.llm_clients import create_llm_client
+
+ class Schema(BaseModel):
+ x: int
+
+ captured = {}
+ monkeypatch.setattr(
+ ChatOpenAI,
+ "with_structured_output",
+ lambda self, schema, method=None, **kw: captured.update({"method": method, **kw}) or "BOUND",
+ )
+
+ create_llm_client(provider="ollama", model="qwen3:30b").get_llm().with_structured_output(Schema)
+
+ assert captured["tool_choice"] is None
diff --git a/tests/test_openai_reasoning_effort.py b/tests/test_openai_reasoning_effort.py
index f58a4e20c..1d452ba27 100644
--- a/tests/test_openai_reasoning_effort.py
+++ b/tests/test_openai_reasoning_effort.py
@@ -17,9 +17,10 @@ from tradingagents.llm_clients.openai_client import (
"model,expected",
[
("gpt-5.5", True), ("gpt-5.4", True), ("gpt-5.4-mini", True),
- ("gpt-5.5-pro", True), ("o1", True), ("o3-mini", True),
+ ("gpt-5.5-pro", True), ("gpt-6-astra", True), ("o1", True), ("o3-mini", True),
("gpt-4.1", False), ("gpt-4o", False), ("gpt-4o-mini", False),
- ("gpt-3.5-turbo", False),
+ ("gpt-3.5-turbo", False), ("gpt-10", True),
+ ("gpt-5foo", False), ("gpt-60x", False), ("o3rd-party", False),
],
)
def test_supports_reasoning_effort(model, expected):
diff --git a/tests/test_portfolio_context.py b/tests/test_portfolio_context.py
new file mode 100644
index 000000000..12305a8ec
--- /dev/null
+++ b/tests/test_portfolio_context.py
@@ -0,0 +1,240 @@
+"""Portfolio context: what the caller holds, threaded into the decision agents.
+
+Decisions were made with no knowledge of the current book, so "add to a full
+position" and "open a new one" read alike. The context is optional and carries
+three distinct states: a position, a flat book, and no context at all. Nothing
+may present the third as the second. The research team stays blind so the bull
+and bear cases are not anchored by the caller's position.
+"""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from tradingagents.agents.utils.agent_utils import get_portfolio_context_from_state
+from tradingagents.portfolio import PortfolioContext, load_portfolio
+
+HOLDING = {
+ "cash": 25000.0,
+ "currency": "USD",
+ "positions": [
+ {"ticker": "AAPL", "quantity": 120, "average_price": 150.0},
+ {"ticker": "MSFT", "quantity": 10},
+ ],
+}
+
+
+@pytest.mark.unit
+def test_position_in_the_analyzed_instrument_leads_the_render():
+ text = PortfolioContext.model_validate(HOLDING).render("AAPL")
+ assert "120" in text and "150" in text
+ assert "MSFT" in text and "25,000" in text and "USD" in text
+
+
+@pytest.mark.unit
+def test_flat_book_says_no_position_rather_than_omitting_it():
+ text = PortfolioContext.model_validate({"cash": 1000.0, "positions": []}).render("AAPL")
+ assert "No current position in AAPL" in text
+
+
+@pytest.mark.unit
+def test_a_ticker_held_under_another_spelling_is_matched():
+ text = PortfolioContext.model_validate({"positions": [{"ticker": "aapl", "quantity": 5}]}).render("AAPL")
+ assert "No current position" not in text and "5" in text
+
+
+@pytest.mark.unit
+def test_absent_context_is_reported_as_not_provided():
+ notice = get_portfolio_context_from_state({"company_of_interest": "AAPL"})
+ assert "not provided" in notice.lower()
+ assert "no position" not in notice.lower() # missing must not read as flat
+
+
+@pytest.mark.unit
+def test_rendered_context_reaches_the_agents_from_state():
+ block = get_portfolio_context_from_state({"portfolio_context": "Portfolio: flat", "company_of_interest": "AAPL"})
+ assert block == "Portfolio: flat"
+
+
+@pytest.mark.unit
+def test_load_rejects_a_malformed_file_with_a_clear_error(tmp_path):
+ bad = tmp_path / "p.json"
+ bad.write_text(json.dumps({"positions": [{"quantity": 5}]}))
+ with pytest.raises(ValueError, match="portfolio"):
+ load_portfolio(bad)
+
+
+@pytest.mark.unit
+def test_load_reads_a_valid_file(tmp_path):
+ good = tmp_path / "p.json"
+ good.write_text(json.dumps(HOLDING))
+ assert load_portfolio(good).positions[0].ticker == "AAPL"
+
+
+# --- threading through the graph --------------------------------------------
+
+def _bare_graph(tmp_path):
+ from tradingagents.agents.utils.memory import TradingMemoryLog
+ from tradingagents.graph.propagation import Propagator
+ from tradingagents.graph.trading_graph import TradingAgentsGraph
+
+ graph = object.__new__(TradingAgentsGraph)
+ graph.config = {"memory_log_path": str(tmp_path / "m.md"), "max_debate_rounds": 1,
+ "max_risk_discuss_rounds": 1}
+ graph.memory_log = TradingMemoryLog(graph.config)
+ graph.propagator = Propagator()
+ graph.selected_analysts = ["market"]
+ graph._resolve_pending_entries = lambda t: None
+ graph.resolve_instrument_context = lambda t, a="stock", d=None: ""
+ graph._memory_as_of = lambda d: None
+ return graph
+
+
+@pytest.mark.unit
+def test_create_run_state_renders_the_portfolio_once(tmp_path):
+ graph = _bare_graph(tmp_path)
+ state = graph.create_run_state("AAPL", "2026-08-14", portfolio=PortfolioContext.model_validate(HOLDING))
+ assert "120" in state["portfolio_context"]
+ assert graph.create_run_state("AAPL", "2026-08-14")["portfolio_context"] == ""
+
+
+@pytest.mark.unit
+def test_checkpoint_signature_changes_with_the_portfolio(tmp_path):
+ graph = _bare_graph(tmp_path)
+ none = graph._run_signature("stock")
+ flat = graph._run_signature("stock", PortfolioContext())
+ held = graph._run_signature("stock", PortfolioContext.model_validate(HOLDING))
+ assert len({none, flat, held}) == 3
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("module, factory", [
+ ("tradingagents.agents.trader.trader", "create_trader"),
+ ("tradingagents.agents.managers.portfolio_manager", "create_portfolio_manager"),
+ ("tradingagents.agents.risk_mgmt.aggressive_debator", "create_aggressive_debator"),
+ ("tradingagents.agents.risk_mgmt.conservative_debator", "create_conservative_debator"),
+ ("tradingagents.agents.risk_mgmt.neutral_debator", "create_neutral_debator"),
+])
+def test_decision_agents_see_the_portfolio(module, factory, monkeypatch):
+ """The prompt each decision agent sends carries the portfolio block."""
+ import importlib
+
+ mod = importlib.import_module(module)
+ seen = []
+
+ class _LLM:
+ def invoke(self, prompt, *a, **k):
+ seen.append(prompt if isinstance(prompt, str) else json.dumps(str(prompt)))
+ from langchain_core.messages import AIMessage
+ return AIMessage("Rating: Hold\n\nnothing to do")
+
+ def with_structured_output(self, *a, **k):
+ raise NotImplementedError # force the free-text path
+
+ state = {
+ "company_of_interest": "AAPL", "trade_date": "2026-08-14", "asset_type": "stock",
+ "instrument_context": "", "market_report": "M", "sentiment_report": "S",
+ "news_report": "N", "fundamentals_report": "F", "investment_plan": "P",
+ "trader_investment_plan": "T", "past_context": "",
+ "portfolio_context": "PORTFOLIO_BLOCK_MARKER",
+ "investment_debate_state": {"history": "", "judge_decision": "", "count": 0},
+ "risk_debate_state": {"history": "", "latest_speaker": "", "count": 0,
+ "aggressive_history": "", "conservative_history": "", "neutral_history": "",
+ "current_aggressive_response": "", "current_conservative_response": "",
+ "current_neutral_response": "", "judge_decision": ""},
+ }
+ node = getattr(mod, factory)(_LLM())
+ node(state)
+ assert any("PORTFOLIO_BLOCK_MARKER" in p for p in seen), f"{factory} prompt lacks the portfolio block"
+
+
+@pytest.mark.unit
+def test_research_team_stays_blind_to_the_portfolio():
+ import inspect
+
+ from tradingagents.agents.researchers import bear_researcher, bull_researcher
+ for mod in (bull_researcher, bear_researcher):
+ assert "portfolio_context" not in inspect.getsource(mod)
+
+
+@pytest.mark.unit
+def test_completed_run_clears_the_checkpoint_it_wrote(tmp_path, monkeypatch):
+ """The clear must key on the same portfolio the run was checkpointed under.
+
+ Keyed on a different one it deletes nothing, and the next identical call
+ resumes the finished thread and returns the old decision without running.
+ """
+ import tradingagents.graph.trading_graph as tg
+
+ graph = _bare_graph(tmp_path)
+ graph.config.update({"checkpoint_enabled": True, "data_cache_dir": str(tmp_path),
+ "results_dir": str(tmp_path)})
+ graph.debug = False
+ graph._resuming = False
+ graph.propagator.get_graph_args = lambda callbacks=None: {}
+ graph.process_signal = lambda d: "Hold"
+ graph._log_state = lambda *a, **k: None
+ graph.graph = type("G", (), {"invoke": lambda self, i, **k: {"final_trade_decision": "Rating: Hold\n\nx"}})()
+ book = PortfolioContext.model_validate(HOLDING)
+
+ written = graph._run_signature("stock", book) # what begin_checkpoint keys on
+ cleared = []
+ monkeypatch.setattr(tg, "clear_checkpoint", lambda d, t, dt, signature: cleared.append(signature))
+
+ graph._run_graph("AAPL", "2026-08-14", "stock", checkpoint_thread_id=None, portfolio=book)
+
+ assert cleared == [written]
+
+
+@pytest.mark.unit
+def test_research_layer_sizes_against_a_standard_allocation():
+ """The research team is blind to the book, so its plan cannot promise
+ position-relative sizing: it sizes against a standard allocation instead."""
+ from tradingagents.agents.schemas import ResearchPlan
+
+ description = ResearchPlan.model_fields["strategic_actions"].description
+ assert "standard allocation" in description
+ assert "does not see the caller's holdings" in description
+
+
+@pytest.mark.unit
+def test_partial_portfolio_states_only_what_it_was_given():
+ """Cash omitted is not cash zero; the line is absent rather than invented."""
+ text = PortfolioContext.model_validate({"positions": [{"ticker": "AAPL", "quantity": 5}]}).render("AAPL")
+ assert "Cash" not in text
+ assert "5" in text
+
+
+@pytest.mark.unit
+def test_cli_rejects_an_unusable_portfolio_file_before_running(tmp_path, monkeypatch):
+ from typer.testing import CliRunner
+
+ import cli.main as m
+
+ bad = tmp_path / "bad.json"
+ bad.write_text('{"positions": [{"quantity": 5}]}')
+ ran = []
+ monkeypatch.setattr(m, "run_analysis", lambda **k: ran.append(k))
+
+ result = CliRunner().invoke(m.app, ["--portfolio", str(bad)])
+
+ assert result.exit_code == 1 and ran == []
+
+
+@pytest.mark.unit
+def test_cli_passes_a_valid_portfolio_into_the_run(tmp_path, monkeypatch):
+ from typer.testing import CliRunner
+
+ import cli.main as m
+
+ good = tmp_path / "good.json"
+ good.write_text(json.dumps(HOLDING))
+ ran = []
+ monkeypatch.setattr(m, "run_analysis", lambda **k: ran.append(k))
+
+ result = CliRunner().invoke(m.app, ["--portfolio", str(good)])
+
+ assert result.exit_code == 0
+ assert ran[0]["portfolio"].position_in("AAPL").quantity == 120
diff --git a/tests/test_prompt_integrity.py b/tests/test_prompt_integrity.py
new file mode 100644
index 000000000..e26e72185
--- /dev/null
+++ b/tests/test_prompt_integrity.py
@@ -0,0 +1,87 @@
+"""What the agents are actually told.
+
+Three problems the audit found: one analyst's brief reached the model as a Python
+tuple, every analyst was asked for a trade call that nothing reads, and a report
+that was never produced was presented as an empty labelled section, which invites
+the next agent to fill it in from nothing.
+"""
+
+from __future__ import annotations
+
+import importlib
+
+import pytest
+
+ANALYSTS = ["market_analyst", "sentiment_analyst", "news_analyst", "fundamentals_analyst"]
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("name", ANALYSTS)
+def test_an_analyst_brief_is_text_not_a_python_object(name):
+ """A trailing comma made one brief a tuple, so the model was handed its repr
+ (quotes, parens and all) instead of the instruction."""
+ import ast
+ import inspect
+
+ mod = importlib.import_module(f"tradingagents.agents.analysts.{name}")
+ tree = ast.parse(inspect.getsource(mod))
+ briefs = [node.value for node in ast.walk(tree)
+ if isinstance(node, ast.Assign)
+ and getattr(node.targets[0], "id", "") == "system_message"]
+ assert briefs, f"{name} has no system_message"
+ for brief in briefs:
+ assert not isinstance(brief, ast.Tuple), "the brief is a tuple, not text"
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("name", ANALYSTS)
+def test_an_analyst_is_not_asked_for_a_trade_call_nothing_reads(name):
+ """The stop signal is never consumed, and asking for it makes an analyst
+ open with a direction that then travels as evidence."""
+ import inspect
+
+ mod = importlib.import_module(f"tradingagents.agents.analysts.{name}")
+ assert "FINAL TRANSACTION PROPOSAL" not in inspect.getsource(mod)
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("module, factory", [
+ ("tradingagents.agents.researchers.bull_researcher", "create_bull_researcher"),
+ ("tradingagents.agents.researchers.bear_researcher", "create_bear_researcher"),
+ ("tradingagents.agents.risk_mgmt.aggressive_debator", "create_aggressive_debator"),
+ ("tradingagents.agents.risk_mgmt.conservative_debator", "create_conservative_debator"),
+ ("tradingagents.agents.risk_mgmt.neutral_debator", "create_neutral_debator"),
+])
+def test_a_report_that_was_never_produced_says_so(module, factory):
+ """`--analysts market` leaves three reports empty; presenting them as blank
+ sections invites the model to invent the contents."""
+ from langchain_core.messages import AIMessage
+
+ mod = importlib.import_module(module)
+ seen = []
+
+ class _LLM:
+ def invoke(self, prompt, *a, **k):
+ seen.append(prompt if isinstance(prompt, str) else str(prompt))
+ return AIMessage("argument")
+
+ def with_structured_output(self, *a, **k):
+ raise NotImplementedError
+
+ state = {
+ "company_of_interest": "NVDA", "trade_date": "2026-08-14", "asset_type": "stock",
+ "instrument_context": "", "portfolio_context": "", "past_context": "",
+ "market_report": "RSI 61, price 178.", "sentiment_report": "", "news_report": "",
+ "fundamentals_report": "", "investment_plan": "P", "trader_investment_plan": "T",
+ "investment_debate_state": {"bull_history": "", "bear_history": "", "history": "",
+ "current_response": "", "judge_decision": "", "count": 0},
+ "risk_debate_state": {"history": "", "latest_speaker": "", "count": 0,
+ "aggressive_history": "", "conservative_history": "", "neutral_history": "",
+ "current_aggressive_response": "", "current_conservative_response": "",
+ "current_neutral_response": "", "judge_decision": ""},
+ }
+ getattr(mod, factory)(_LLM())(state)
+
+ prompt = " ".join(seen)
+ assert "not part of this run" in prompt or "not available" in prompt, prompt[:400]
+ assert "RSI 61" in prompt # the report that does exist is still passed through
diff --git a/tests/test_provider_registry.py b/tests/test_provider_registry.py
index 596108a77..36bd4fcbb 100644
--- a/tests/test_provider_registry.py
+++ b/tests/test_provider_registry.py
@@ -7,6 +7,7 @@ import pytest
from tradingagents.llm_clients.openai_client import (
OPENAI_COMPATIBLE_PROVIDERS,
DeepSeekChatOpenAI,
+ LocalCompatibleChatOpenAI,
MinimaxChatOpenAI,
NormalizedChatOpenAI,
is_openai_compatible,
@@ -39,7 +40,7 @@ def test_registry_membership():
("kimi", "https://api.moonshot.ai/v1", NormalizedChatOpenAI, False),
("groq", "https://api.groq.com/openai/v1", NormalizedChatOpenAI, False),
("nvidia", "https://integrate.api.nvidia.com/v1", NormalizedChatOpenAI, False),
- ("ollama", "http://localhost:11434/v1", NormalizedChatOpenAI, False),
+ ("ollama", "http://localhost:11434/v1", LocalCompatibleChatOpenAI, False),
])
def test_registry_spec(provider, base_url, chat_class, responses):
spec = OPENAI_COMPATIBLE_PROVIDERS[provider]
diff --git a/tests/test_rating_integrity.py b/tests/test_rating_integrity.py
new file mode 100644
index 000000000..8d8fcb0cf
--- /dev/null
+++ b/tests/test_rating_integrity.py
@@ -0,0 +1,211 @@
+"""A decision is recorded as the call that was made, or as needing review.
+
+Two readers used to disagree about the same text: the signal said REVIEW while
+the memory log wrote a fabricated Hold. Worse, prose that argued against a Buy
+before concluding Underweight was read as Buy, because the parser took the first
+rating word anywhere in the document. A wrong direction is worse than no
+direction, so an unclear decision is REVIEW everywhere.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from tradingagents.agents.utils.rating import RATING_REVIEW, extract_rating, parse_rating
+
+INVERTED = ("The aggressive analyst pushed hard for a Buy on the AI backlog, but the "
+ "conservative case on margin compression carried the debate. "
+ "Final rating — Underweight. Trim to half weight over the next two weeks.")
+REFUSAL = "I'm sorry, I can't provide a rating for this security."
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("separator", [":", "-", "—", "–", "：", ": **"])
+def test_the_labelled_rating_wins_whatever_separates_it(separator):
+ text = f"Buy arguments were raised and rejected.\n\nRating{separator}Underweight\n\nTrim."
+ assert extract_rating(text) == "Underweight"
+
+
+@pytest.mark.unit
+def test_a_rating_argued_against_is_not_read_as_the_decision():
+ assert extract_rating(INVERTED) == "Underweight"
+
+
+@pytest.mark.unit
+def test_prose_naming_several_ratings_without_a_label_needs_review():
+ """Nothing in the text says which one is the call, so guessing risks
+ reporting the opposite of the decision."""
+ text = "The bull wants Buy, the bear wants Sell, and the committee was split."
+ assert extract_rating(text) is None
+
+
+@pytest.mark.unit
+def test_prose_naming_one_rating_is_taken_as_the_call():
+ assert extract_rating("On balance we stay Underweight until margins recover.") == "Underweight"
+
+
+@pytest.mark.unit
+def test_a_refusal_has_no_rating_and_is_not_defaulted():
+ assert extract_rating(REFUSAL) is None
+ assert parse_rating(REFUSAL) == RATING_REVIEW
+
+
+@pytest.mark.unit
+def test_the_scale_quoted_in_a_prompt_does_not_become_the_rating():
+ """A free-text answer that echoes the rating scale was read as the first
+ tier listed in it."""
+ text = ("**Rating Scale**: Buy, Overweight, Hold, Underweight, Sell.\n\n"
+ "**Rating**: Sell\n\nExit the position.")
+ assert extract_rating(text) == "Sell"
+
+
+# --- the readers agree ------------------------------------------------------
+
+@pytest.mark.unit
+def test_the_memory_log_records_review_rather_than_a_tradeable_hold(tmp_path):
+ from tradingagents.agents.utils.memory import TradingMemoryLog
+
+ log = TradingMemoryLog({"memory_log_path": str(tmp_path / "m.md")})
+ log.store_decision("NVDA", "2026-01-05", REFUSAL)
+
+ entry = log.load_entries()[0]
+ assert entry["rating"] == RATING_REVIEW
+
+
+@pytest.mark.unit
+def test_the_signal_and_the_log_agree_on_the_same_decision(tmp_path):
+ from tradingagents.agents.utils.memory import TradingMemoryLog
+ from tradingagents.graph.signal_processing import SignalProcessor
+
+ log = TradingMemoryLog({"memory_log_path": str(tmp_path / "m.md")})
+ for text in (INVERTED, REFUSAL, "**Rating**: Buy\n\nAccumulate."):
+ log.store_decision("NVDA", f"2026-01-0{len(log.load_entries()) + 1}", text)
+
+ signals = [SignalProcessor.process_signal(None, text)
+ for text in (INVERTED, REFUSAL, "**Rating**: Buy\n\nAccumulate.")]
+ assert [e["rating"] for e in log.load_entries()] == signals
+
+
+@pytest.mark.unit
+def test_an_unscored_decision_is_left_out_of_the_backtest_figures(tmp_path):
+ """REVIEW has no direction, so it cannot count for or against the system."""
+ from tradingagents.agents.utils.memory import TradingMemoryLog
+ from tradingagents.backtest import summarize
+
+ log = TradingMemoryLog({"memory_log_path": str(tmp_path / "m.md")})
+ log.store_decision("NVDA", "2026-01-05", "**Rating**: Buy\n\nx")
+ log.update_with_outcome("NVDA", "2026-01-05", 0.1, 0.04, 5, "note", "2026-02-01")
+ log.store_decision("AAPL", "2026-01-05", REFUSAL)
+ log.update_with_outcome("AAPL", "2026-01-05", 0.1, 0.04, 5, "note", "2026-02-01")
+
+ summary = summarize(log)
+ assert set(summary.by_rating) == {"Buy"}
+
+
+@pytest.mark.unit
+def test_the_cli_says_when_a_run_produced_no_usable_rating(monkeypatch, tmp_path, capsys):
+ """The CLI is the primary entry point; an unreadable decision must be
+ visible there, not only in the log."""
+ import cli.main as m
+ from cli.models import AnalystType
+
+ printed = []
+
+ class _Graph:
+ graph = propagator = None
+
+ def create_run_state(self, *a, **k):
+ return {"messages": []}
+
+ def record_decision(self, *a, **k):
+ pass
+
+ def process_signal(self, text):
+ from tradingagents.graph.signal_processing import SignalProcessor
+ return SignalProcessor.process_signal(None, text)
+
+ def get_graph_args(self, callbacks=None):
+ return {}
+
+ def begin_checkpoint(self, *a, **k):
+ return None
+
+ def checkpoint_input(self, state):
+ return state
+
+ def clear_checkpoint_on_success(self, *a, **k):
+ pass
+
+ def end_checkpoint(self):
+ pass
+
+ def stream(self, *a, **k):
+ yield {"messages": [], "final_trade_decision": REFUSAL}
+
+ fake = _Graph()
+ fake.graph = fake
+ fake.propagator = fake
+ monkeypatch.setattr(m, "TradingAgentsGraph", lambda *a, **k: fake)
+ monkeypatch.setattr(m, "create_layout", lambda: None)
+ monkeypatch.setattr(m, "update_display", lambda *a, **k: None)
+ monkeypatch.setattr(m, "Live", type("L", (), {"__init__": lambda s, *a, **k: None,
+ "__enter__": lambda s: s,
+ "__exit__": lambda s, *a: False}))
+ monkeypatch.setattr(m.console, "print", lambda *a, **k: printed.append(" ".join(str(x) for x in a)))
+ monkeypatch.setattr(m, "display_complete_report", lambda *a, **k: None)
+ monkeypatch.setattr(m.typer, "prompt", lambda *a, **k: "N")
+ monkeypatch.setattr(m, "get_user_selections", lambda: {
+ "ticker": "NVDA", "analysis_date": "2026-01-10",
+ "analysts": [AnalystType.MARKET], "asset_type": "stock",
+ })
+ monkeypatch.setattr(m, "_build_run_config", lambda s, c: {
+ "data_cache_dir": str(tmp_path / "c"), "results_dir": str(tmp_path / "r")})
+
+ m.run_analysis()
+
+ assert any("review" in line.lower() for line in printed), printed[-5:]
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("module, factory, must_name", [
+ ("tradingagents.agents.managers.portfolio_manager", "create_portfolio_manager", "Rating"),
+ ("tradingagents.agents.managers.research_manager", "create_research_manager", "Recommendation"),
+ ("tradingagents.agents.trader.trader", "create_trader", "Action"),
+])
+def test_a_decision_prompt_states_the_shape_of_its_answer(module, factory, must_name):
+ """The field descriptions live in the schema, which a provider without
+ structured output never sees. Without the format in the prompt body, the
+ fallback answer is prose nobody can read a rating from."""
+ import importlib
+
+ from langchain_core.messages import AIMessage
+
+ mod = importlib.import_module(module)
+ seen = []
+
+ class _LLM:
+ def invoke(self, prompt, *a, **k):
+ seen.append(prompt if isinstance(prompt, str) else str(prompt))
+ return AIMessage("**Rating**: Hold\n\nnothing to do")
+
+ def with_structured_output(self, *a, **k):
+ raise NotImplementedError # force the free-text path
+
+ state = {
+ "company_of_interest": "NVDA", "trade_date": "2026-08-14", "asset_type": "stock",
+ "instrument_context": "", "market_report": "M", "sentiment_report": "S",
+ "news_report": "N", "fundamentals_report": "F", "investment_plan": "P",
+ "trader_investment_plan": "T", "past_context": "", "portfolio_context": "",
+ "investment_debate_state": {"bull_history": "b", "bear_history": "r", "history": "h",
+ "current_response": "", "judge_decision": "", "count": 2},
+ "risk_debate_state": {"history": "h", "latest_speaker": "", "count": 3,
+ "aggressive_history": "", "conservative_history": "", "neutral_history": "",
+ "current_aggressive_response": "", "current_conservative_response": "",
+ "current_neutral_response": "", "judge_decision": ""},
+ }
+ getattr(mod, factory)(_LLM())(state)
+
+ prompt = " ".join(seen)
+ assert "## Output" in prompt, "no output-format section in the prompt"
+ section = prompt.split("## Output", 1)[1]
+ assert f"**{must_name}**" in section, section[:300]
diff --git a/tests/test_reddit_fallback.py b/tests/test_reddit_fallback.py
index a2bc2cc25..fedd08160 100644
--- a/tests/test_reddit_fallback.py
+++ b/tests/test_reddit_fallback.py
@@ -1,5 +1,5 @@
-"""Tests for the RSS-first Reddit fetcher, its 429 backoff, the opt-in JSON
-path's degradation (#862), and chunked-transfer error handling (#1024)."""
+"""Tests for the Reddit RSS fetcher: one combined request, its 429 backoff, and
+chunked-transfer error handling (#1024)."""
from __future__ import annotations
@@ -80,48 +80,15 @@ class TestRssParsing:
posts = reddit._fetch_subreddit_rss("NVDA", "stocks", limit=5, timeout=5.0)
assert len(posts) == 2
assert posts[0]["title"] == "NVDA earnings beat, stock pops"
- assert posts[0]["source"] == "rss"
- assert posts[0]["score"] is None
- assert posts[0]["num_comments"] is None
assert posts[0]["created_utc"] > 0
assert "datacenter unit" in posts[0]["selftext"]
+ assert posts[0]["subreddit"] == "stocks"
def test_malformed_xml_reports_unavailable(self):
with patch.object(reddit, "urlopen", return_value=_resp(lambda: b"<>")):
assert reddit._fetch_subreddit_rss("NVDA", "stocks", 5, 5.0) is None
-@pytest.mark.unit
-class TestFetchSubredditIsRssFirst:
- """The default per-subreddit fetch goes straight to RSS — it must not hit
- the WAF-blocked JSON endpoint, which only burned rate-limit budget."""
-
- def test_delegates_to_rss_without_touching_json(self):
- sentinel = [{"title": "x", "source": "rss", "score": None,
- "num_comments": None, "created_utc": None, "selftext": ""}]
- with patch.object(reddit, "_fetch_subreddit_rss", return_value=sentinel) as rss, \
- patch.object(reddit, "urlopen",
- side_effect=AssertionError("JSON endpoint must not be called")):
- out = reddit._fetch_subreddit("NVDA", "stocks", 5, 5.0)
- rss.assert_called_once()
- assert out is sentinel
-
-
-@pytest.mark.unit
-class TestJsonPathFallsBackToRss:
- """The opt-in JSON path still degrades to RSS on a 403 (kept for #862)."""
-
- def test_403_triggers_rss(self):
- err = HTTPError("url", 403, "Blocked", {}, None)
- rss_posts = [{"title": "x", "source": "rss", "score": None,
- "num_comments": None, "created_utc": None, "selftext": ""}]
- with patch.object(reddit, "urlopen", side_effect=err), \
- patch.object(reddit, "_fetch_subreddit_rss", return_value=rss_posts) as rss:
- out = reddit._fetch_subreddit_json("NVDA", "stocks", 5, 5.0)
- rss.assert_called_once()
- assert out and out[0]["source"] == "rss"
-
-
@pytest.mark.unit
class TestRss429Backoff:
def test_429_then_success_retries_once(self):
@@ -178,12 +145,6 @@ class TestChunkedTransferErrorsHandled:
with patch.object(reddit, "urlopen", return_value=_raise(http.client.IncompleteRead(b""))):
assert reddit._fetch_subreddit_rss("NVDA", "stocks", 5, 5.0) is None
- def test_json_incomplete_read_falls_back_to_rss(self):
- with patch.object(reddit, "urlopen", return_value=_raise(http.client.IncompleteRead(b""))), \
- patch.object(reddit, "_fetch_subreddit_rss", return_value=[]) as rss:
- reddit._fetch_subreddit_json("NVDA", "stocks", 5, 5.0)
- rss.assert_called_once()
-
def test_oversized_rss_feed_is_refused_not_parsed(self):
# A hostile/misbehaving endpoint streaming an unbounded body must not be
# read into memory before parsing; overflow degrades to an empty feed.
@@ -201,25 +162,12 @@ class TestFormatterHandlesRssPosts:
"created_utc": reddit._iso_to_timestamp("2026-05-20T14:30:00Z"),
"selftext": "great quarter", "source": "rss",
}]
- with patch.object(reddit, "_fetch_subreddit", return_value=rss_posts):
- out = reddit.fetch_reddit_posts("NVDA", subreddits=("stocks",), inter_request_delay=0)
- assert "via RSS feed" in out
- assert "↑" not in out # no fake score arrow
+ with patch.object(reddit, "_fetch_subreddit_rss", return_value=rss_posts):
+ out = reddit.fetch_reddit_posts("NVDA", subreddits=("stocks",))
+ assert "↑" not in out # RSS has no scores; none are invented
assert "NVDA pops" in out
assert "great quarter" in out
- def test_json_posts_still_show_counts(self):
- json_posts = [{
- "title": "NVDA pops", "score": 1234, "num_comments": 56,
- "created_utc": reddit._iso_to_timestamp("2026-05-20T14:30:00Z"),
- "selftext": "",
- }]
- with patch.object(reddit, "_fetch_subreddit", return_value=json_posts):
- out = reddit.fetch_reddit_posts("NVDA", subreddits=("stocks",), inter_request_delay=0)
- assert "1234↑" in out
- assert "56c" in out
- assert "via RSS" not in out
-
@pytest.mark.unit
class TestCryptoSearchTerm:
@@ -228,12 +176,12 @@ class TestCryptoSearchTerm:
def _captured_ticker(self, ticker):
seen = {}
- def fake_fetch(t, sub, limit, timeout, **kwargs):
+ def fake_fetch(t, subs, limit, timeout, **kwargs):
seen["ticker"] = t
return []
- with patch.object(reddit, "_fetch_subreddit", side_effect=fake_fetch):
- reddit.fetch_reddit_posts(ticker, subreddits=("stocks",), inter_request_delay=0)
+ with patch.object(reddit, "_fetch_subreddit_rss", side_effect=fake_fetch):
+ reddit.fetch_reddit_posts(ticker, subreddits=("stocks",))
return seen["ticker"]
def test_crypto_pair_searches_base(self):
@@ -244,61 +192,83 @@ class TestCryptoSearchTerm:
@pytest.mark.unit
-class TestFailedFetchIsNotSilence:
- """A throttled fetch must not be rendered as "no posts found" (#1295).
+class TestOneRequestForAllSubreddits:
+ """Reddit's anonymous RSS allows about one request per minute per IP, so a
+ request per subreddit spent a back-off on nearly every run. One combined
+ feed (``r/a+b+c``) carries each entry's subreddit, so nothing is lost."""
- Returning [] for both a failed request and a genuinely empty search made the
- sentiment analyst read rate limiting as real silence ("r/stocks and
- r/investing are silent"), which is a signal that was never observed.
- """
+ def _post(self, sub, title="NVDA pops"):
+ return {"title": title, "score": None, "num_comments": None,
+ "created_utc": reddit._iso_to_timestamp("2026-05-20T14:30:00Z"),
+ "selftext": "", "source": "rss", "subreddit": sub}
- _POST = {
- "title": "NVDA pops", "score": None, "num_comments": None,
- "created_utc": reddit._iso_to_timestamp("2026-05-20T14:30:00Z"),
- "selftext": "", "source": "rss",
- }
+ def test_all_subreddits_share_one_request(self):
+ calls = []
- def _run(self, results):
- """Drive fetch_reddit_posts with a per-subreddit result sequence."""
- subs = tuple(f"s{i}" for i in range(len(results)))
- with patch.object(reddit, "_fetch_subreddit", side_effect=list(results)):
- return reddit.fetch_reddit_posts(
- "NVDA", subreddits=subs, inter_request_delay=0
- )
+ def record(t, subs, limit, timeout):
+ calls.append((subs, limit))
+ return []
- def test_failed_subreddit_is_marked_unavailable_not_empty(self):
- out = self._run([None, [self._POST]])
- assert "unavailable" in out
- assert "no posts found" not in out.split("unavailable")[0]
+ with patch.object(reddit, "_fetch_subreddit_rss", side_effect=record):
+ reddit.fetch_reddit_posts("NVDA", subreddits=("a", "b", "c"), limit_per_sub=5)
+ # One full page, so a busy subreddit cannot crowd the others out.
+ assert calls == [("a+b+c", reddit._FEED_PAGE)]
- def test_all_sources_failing_does_not_claim_no_posts(self):
- out = self._run([None, None])
+ def test_posts_are_grouped_back_by_subreddit(self):
+ posts = [self._post("b", "FROM B"), self._post("a", "FROM A")]
+ with patch.object(reddit, "_fetch_subreddit_rss", return_value=posts):
+ out = reddit.fetch_reddit_posts("NVDA", subreddits=("a", "b"))
+ assert out.index("r/a") < out.index("FROM A") < out.index("r/b") < out.index("FROM B")
+
+ def test_failed_request_is_unavailable_not_silence(self):
+ # #1295: a throttled fetch must not read as "no posts found".
+ with patch.object(reddit, "_fetch_subreddit_rss", return_value=None):
+ out = reddit.fetch_reddit_posts("NVDA", subreddits=("a", "b"))
assert "Reddit unavailable" in out
assert "no Reddit posts found" not in out
- def test_mixed_failure_and_empty_only_claims_silence_for_searched_subs(self):
- # s0 failed, s1 genuinely returned nothing: the "no posts" claim must
- # cover only s1, with s0 reported separately as unavailable.
- out = self._run([None, []])
- assert "r/s1" in out.split("unavailable (fetch failed)")[0]
- assert "unavailable (fetch failed): r/s0" in out
-
def test_genuine_empty_still_reports_no_posts(self):
- out = self._run([[], []])
+ with patch.object(reddit, "_fetch_subreddit_rss", return_value=[]):
+ out = reddit.fetch_reddit_posts("NVDA", subreddits=("a", "b"))
assert "no Reddit posts found" in out
assert "unavailable" not in out
- def test_retry_is_not_spent_again_after_a_failure(self):
- # The 60s back-off must be paid at most once per run, so subsequent
- # subreddits are fetched with retry disabled rather than stalling.
- seen = []
+ def test_subreddit_with_no_posts_is_listed_when_others_have_some(self):
+ with patch.object(reddit, "_fetch_subreddit_rss", return_value=[self._post("a")]):
+ out = reddit.fetch_reddit_posts("NVDA", subreddits=("a", "b"))
+ assert "r/b:
### Reddit posts — r/wallstreetbets, r/stocks, r/investing (past 7 days)
-Community discussion. Engagement signal via upvote score and comment count. Subreddit character matters (r/wallstreetbets is often contrarian/exuberant; r/stocks more measured; r/investing longer-term).
+Community discussion, without vote or comment counts. Subreddit character matters (r/wallstreetbets is often contrarian/exuberant; r/stocks more measured; r/investing longer-term).
{reddit_block}
@@ -168,7 +171,7 @@ Community discussion. Engagement signal via upvote score and comment count. Subr
2. **Look for cross-source divergences.** If news framing is bearish but StockTwits is overwhelmingly bullish, that mismatch is itself a signal — it can mean retail is leaning into a thesis the news flow hasn't caught up to (or vice versa, that retail is chasing while institutions are cautious).
-3. **Weight Reddit posts by engagement.** A 400-upvote / 200-comment thread reflects community attention; a 3-upvote post is noise. Read the body excerpts for context — the title alone often misleads.
+3. **Read Reddit posts for substance.** The feed carries no vote or comment counts, so judge a post by its body excerpt, not its title alone, and do not infer engagement.
4. **Distinguish opinion from event.** A news headline ("Nvidia announces $500M Corning deal") is an event; a StockTwits post ("buying NVDA, this is going to moon") is opinion. Both are inputs but should be weighted differently in your conclusions.
diff --git a/tradingagents/agents/managers/portfolio_manager.py b/tradingagents/agents/managers/portfolio_manager.py
index 75508dca6..c85039236 100644
--- a/tradingagents/agents/managers/portfolio_manager.py
+++ b/tradingagents/agents/managers/portfolio_manager.py
@@ -14,6 +14,7 @@ from tradingagents.agents.schemas import PortfolioDecision, render_pm_decision
from tradingagents.agents.utils.agent_utils import (
get_instrument_context_from_state,
get_language_instruction,
+ get_portfolio_context_from_state,
)
from tradingagents.agents.utils.structured import (
NO_EXTERNAL_TOOLS,
@@ -27,6 +28,7 @@ def create_portfolio_manager(llm):
def portfolio_manager_node(state) -> dict:
instrument_context = get_instrument_context_from_state(state)
+ portfolio_context = get_portfolio_context_from_state(state)
history = state["risk_debate_state"]["history"]
risk_debate_state = state["risk_debate_state"]
@@ -44,6 +46,8 @@ def create_portfolio_manager(llm):
{instrument_context}
+{portfolio_context}
+
---
**Rating Scale** (use exactly one):
@@ -62,7 +66,15 @@ def create_portfolio_manager(llm):
---
-Ground every conclusion in specific evidence from the analysts. Commit to a directional call only when the evidence clearly supports one; choose Hold when the case is balanced, materially conflicting, ambiguous, or insufficient to justify changing exposure, rather than forcing a direction to appear decisive. Weigh the analysts on their merits, independent of speaking order.
+Ground every conclusion in specific evidence from the analysts. The risk debate always contains conflicting stances; deciding which is stronger is the job, so conflict alone is not a reason to Hold. Commit to the stronger case, sized by how decisively it wins. Choose Hold only when the evidence is still balanced after that weighing, or too thin to support a call; do not force a direction to appear decisive. Weigh the analysts on their merits, independent of speaking order.
+
+## Output
+
+Write these sections, in this order, starting with the rating on its own line:
+
+- **Rating**: exactly one of Buy / Overweight / Hold / Underweight / Sell
+- **Executive Summary**: the call and how to act on it
+- **Investment Thesis**: the evidence that decided it, and what would change it
{NO_EXTERNAL_TOOLS}{get_language_instruction()}"""
diff --git a/tradingagents/agents/managers/research_manager.py b/tradingagents/agents/managers/research_manager.py
index 85c2d8e90..0ffd2f4a2 100644
--- a/tradingagents/agents/managers/research_manager.py
+++ b/tradingagents/agents/managers/research_manager.py
@@ -36,13 +36,21 @@ def create_research_manager(llm):
- **Underweight**: Cautious view; recommend trimming exposure
- **Sell**: Strong conviction in the bear thesis; recommend exiting or avoiding the position
-Commit to a directional stance only when the debate's strongest arguments clearly warrant one. Choose Hold when the evidence is balanced, materially conflicting, ambiguous, or insufficient to justify changing exposure; do not manufacture a direction merely to appear decisive. Weigh the bull and bear cases on their merits, independent of which side spoke first or last.
+The debate always contains conflicting arguments; deciding which side is stronger is the job, so conflict alone is not a reason to Hold. Commit to the side with the stronger case, sized by how decisively it wins. Choose Hold only when the evidence is still balanced after that weighing, or too thin to support a call; do not manufacture a direction to appear decisive. Weigh the bull and bear cases on their merits, independent of which side spoke first or last.
---
**Debate History:**
{history}
+## Output
+
+Write these sections, in this order, starting with the recommendation on its own line:
+
+- **Recommendation**: exactly one of Buy / Overweight / Hold / Underweight / Sell
+- **Rationale**: which arguments decided it
+- **Strategic Actions**: concrete steps for the trader, sized against a standard allocation
+
{NO_EXTERNAL_TOOLS}""" + get_language_instruction()
investment_plan = invoke_structured_or_freetext(
diff --git a/tradingagents/agents/researchers/bear_researcher.py b/tradingagents/agents/researchers/bear_researcher.py
index 9e3e2bb23..dddbefa52 100644
--- a/tradingagents/agents/researchers/bear_researcher.py
+++ b/tradingagents/agents/researchers/bear_researcher.py
@@ -2,6 +2,7 @@ from tradingagents.agents.utils.agent_utils import (
get_instrument_context_from_state,
get_language_instruction,
opponent_argument_or_opening,
+ report_or_absent,
)
@@ -14,10 +15,10 @@ def create_bear_researcher(llm):
current_response = opponent_argument_or_opening(
investment_debate_state.get("current_response", ""), "bull analyst"
)
- market_research_report = state["market_report"]
- sentiment_report = state["sentiment_report"]
- news_report = state["news_report"]
- fundamentals_report = state["fundamentals_report"]
+ market_research_report = report_or_absent(state["market_report"], "market")
+ sentiment_report = report_or_absent(state["sentiment_report"], "sentiment")
+ news_report = report_or_absent(state["news_report"], "news")
+ fundamentals_report = report_or_absent(state["fundamentals_report"], "fundamentals")
instrument_context = get_instrument_context_from_state(state)
asset_type = state.get("asset_type", "stock")
target_label = "stock" if asset_type == "stock" else "asset"
diff --git a/tradingagents/agents/researchers/bull_researcher.py b/tradingagents/agents/researchers/bull_researcher.py
index 6987ac81b..28af77ea2 100644
--- a/tradingagents/agents/researchers/bull_researcher.py
+++ b/tradingagents/agents/researchers/bull_researcher.py
@@ -2,6 +2,7 @@ from tradingagents.agents.utils.agent_utils import (
get_instrument_context_from_state,
get_language_instruction,
opponent_argument_or_opening,
+ report_or_absent,
)
@@ -14,10 +15,10 @@ def create_bull_researcher(llm):
current_response = opponent_argument_or_opening(
investment_debate_state.get("current_response", ""), "bear analyst"
)
- market_research_report = state["market_report"]
- sentiment_report = state["sentiment_report"]
- news_report = state["news_report"]
- fundamentals_report = state["fundamentals_report"]
+ market_research_report = report_or_absent(state["market_report"], "market")
+ sentiment_report = report_or_absent(state["sentiment_report"], "sentiment")
+ news_report = report_or_absent(state["news_report"], "news")
+ fundamentals_report = report_or_absent(state["fundamentals_report"], "fundamentals")
instrument_context = get_instrument_context_from_state(state)
asset_type = state.get("asset_type", "stock")
target_label = "stock" if asset_type == "stock" else "asset"
diff --git a/tradingagents/agents/risk_mgmt/aggressive_debator.py b/tradingagents/agents/risk_mgmt/aggressive_debator.py
index ff1efd879..c0555e0b6 100644
--- a/tradingagents/agents/risk_mgmt/aggressive_debator.py
+++ b/tradingagents/agents/risk_mgmt/aggressive_debator.py
@@ -1,7 +1,9 @@
from tradingagents.agents.utils.agent_utils import (
get_instrument_context_from_state,
get_language_instruction,
+ get_portfolio_context_from_state,
opponent_argument_or_opening,
+ report_or_absent,
)
@@ -18,11 +20,12 @@ def create_aggressive_debator(llm):
risk_debate_state.get("current_neutral_response", ""), "neutral analyst"
)
- market_research_report = state["market_report"]
- sentiment_report = state["sentiment_report"]
- news_report = state["news_report"]
- fundamentals_report = state["fundamentals_report"]
+ market_research_report = report_or_absent(state["market_report"], "market")
+ sentiment_report = report_or_absent(state["sentiment_report"], "sentiment")
+ news_report = report_or_absent(state["news_report"], "news")
+ fundamentals_report = report_or_absent(state["fundamentals_report"], "fundamentals")
instrument_context = get_instrument_context_from_state(state)
+ portfolio_context = get_portfolio_context_from_state(state)
trader_decision = state["trader_investment_plan"]
@@ -33,6 +36,7 @@ def create_aggressive_debator(llm):
Your task is to create a compelling case for the trader's decision by questioning and critiquing the conservative and neutral stances to demonstrate why your high-reward perspective offers the best path forward. Incorporate insights from the following sources into your arguments:
{instrument_context}
+{portfolio_context}
Market Research Report: {market_research_report}
Social Media Sentiment Report: {sentiment_report}
Latest World Affairs Report: {news_report}
diff --git a/tradingagents/agents/risk_mgmt/conservative_debator.py b/tradingagents/agents/risk_mgmt/conservative_debator.py
index 77d7d064b..0a9d67541 100644
--- a/tradingagents/agents/risk_mgmt/conservative_debator.py
+++ b/tradingagents/agents/risk_mgmt/conservative_debator.py
@@ -1,7 +1,9 @@
from tradingagents.agents.utils.agent_utils import (
get_instrument_context_from_state,
get_language_instruction,
+ get_portfolio_context_from_state,
opponent_argument_or_opening,
+ report_or_absent,
)
@@ -18,11 +20,12 @@ def create_conservative_debator(llm):
risk_debate_state.get("current_neutral_response", ""), "neutral analyst"
)
- market_research_report = state["market_report"]
- sentiment_report = state["sentiment_report"]
- news_report = state["news_report"]
- fundamentals_report = state["fundamentals_report"]
+ market_research_report = report_or_absent(state["market_report"], "market")
+ sentiment_report = report_or_absent(state["sentiment_report"], "sentiment")
+ news_report = report_or_absent(state["news_report"], "news")
+ fundamentals_report = report_or_absent(state["fundamentals_report"], "fundamentals")
instrument_context = get_instrument_context_from_state(state)
+ portfolio_context = get_portfolio_context_from_state(state)
trader_decision = state["trader_investment_plan"]
@@ -33,6 +36,7 @@ def create_conservative_debator(llm):
Your task is to actively counter the arguments of the Aggressive and Neutral Analysts, highlighting where their views may overlook potential threats or fail to prioritize sustainability. Respond directly to their points, drawing from the following data sources to build a convincing case for a low-risk approach adjustment to the trader's decision:
{instrument_context}
+{portfolio_context}
Market Research Report: {market_research_report}
Social Media Sentiment Report: {sentiment_report}
Latest World Affairs Report: {news_report}
diff --git a/tradingagents/agents/risk_mgmt/neutral_debator.py b/tradingagents/agents/risk_mgmt/neutral_debator.py
index 746c8834e..661b70ab4 100644
--- a/tradingagents/agents/risk_mgmt/neutral_debator.py
+++ b/tradingagents/agents/risk_mgmt/neutral_debator.py
@@ -1,7 +1,9 @@
from tradingagents.agents.utils.agent_utils import (
get_instrument_context_from_state,
get_language_instruction,
+ get_portfolio_context_from_state,
opponent_argument_or_opening,
+ report_or_absent,
)
@@ -18,11 +20,12 @@ def create_neutral_debator(llm):
risk_debate_state.get("current_conservative_response", ""), "conservative analyst"
)
- market_research_report = state["market_report"]
- sentiment_report = state["sentiment_report"]
- news_report = state["news_report"]
- fundamentals_report = state["fundamentals_report"]
+ market_research_report = report_or_absent(state["market_report"], "market")
+ sentiment_report = report_or_absent(state["sentiment_report"], "sentiment")
+ news_report = report_or_absent(state["news_report"], "news")
+ fundamentals_report = report_or_absent(state["fundamentals_report"], "fundamentals")
instrument_context = get_instrument_context_from_state(state)
+ portfolio_context = get_portfolio_context_from_state(state)
trader_decision = state["trader_investment_plan"]
@@ -33,6 +36,7 @@ def create_neutral_debator(llm):
Your task is to challenge both the Aggressive and Conservative Analysts, pointing out where each perspective may be overly optimistic or overly cautious. Use insights from the following data sources to support a moderate, sustainable strategy to adjust the trader's decision:
{instrument_context}
+{portfolio_context}
Market Research Report: {market_research_report}
Social Media Sentiment Report: {sentiment_report}
Latest World Affairs Report: {news_report}
diff --git a/tradingagents/agents/schemas.py b/tradingagents/agents/schemas.py
index e933017d7..fb89aa42b 100644
--- a/tradingagents/agents/schemas.py
+++ b/tradingagents/agents/schemas.py
@@ -39,7 +39,12 @@ def _coerce_optional_float(value):
cannot be salvaged into an absolute level -- reading "15%" as 15 would put a
stop at $15 on a $600 stock -- so it is dropped like a placeholder, leaving
one bad field to null out instead of failing the whole proposal. A formatted
- price is reduced to its number. Anything else passes through to pydantic.
+ price is reduced to its number.
+
+ Anything that is not a single number is dropped the same way. A range
+ ("150-160") or a hedge ("around 150") would otherwise reach pydantic, fail
+ validation, and discard the whole decision, losing every field the model got
+ right along with the price.
"""
if not isinstance(value, str):
return value
@@ -47,7 +52,10 @@ def _coerce_optional_float(value):
if text.lower() in _NULLISH_FLOAT or text.endswith("%"):
return None
cleaned = text.replace(",", "").lstrip("$€£¥").strip()
- return cleaned or None
+ try:
+ return float(cleaned)
+ except ValueError:
+ return None
# ---------------------------------------------------------------------------
@@ -96,11 +104,10 @@ class ResearchPlan(BaseModel):
recommendation: PortfolioRating = Field(
description=(
"The investment recommendation. Exactly one of Buy / Overweight / "
- "Hold / Underweight / Sell. Choose Hold when the evidence is "
- "balanced, materially conflicting, ambiguous, or insufficient to "
- "justify changing exposure; otherwise commit to the side with the "
- "clearly stronger arguments. Do not pick a direction merely to be "
- "decisive."
+ "Hold / Underweight / Sell. Conflicting arguments alone are not a "
+ "reason to Hold: commit to the stronger side, sized by how "
+ "decisively it wins. Choose Hold only when the evidence is still "
+ "balanced after weighing, or too thin to support a call."
),
)
rationale: str = Field(
@@ -113,7 +120,9 @@ class ResearchPlan(BaseModel):
strategic_actions: str = Field(
description=(
"Concrete steps for the trader to implement the recommendation, "
- "including position sizing guidance consistent with the rating."
+ "including sizing guidance relative to a standard allocation. The "
+ "research team does not see the caller's holdings; the trader and "
+ "portfolio manager apply the actual position."
),
)
@@ -191,12 +200,12 @@ def render_trader_proposal(proposal: TraderProposal) -> str:
"",
f"**Reasoning**: {proposal.reasoning}",
]
- if proposal.entry_price is not None:
- parts.extend(["", f"**Entry Price**: {proposal.entry_price}"])
- if proposal.stop_loss is not None:
- parts.extend(["", f"**Stop Loss**: {proposal.stop_loss}"])
- if proposal.position_sizing:
- parts.extend(["", f"**Position Sizing**: {proposal.position_sizing}"])
+ # Named even when absent, so a reader can tell a level the trader chose not
+ # to give from one the schema never asked for.
+ for label, value in (("Entry Price", proposal.entry_price),
+ ("Stop Loss", proposal.stop_loss),
+ ("Position Sizing", proposal.position_sizing)):
+ parts.extend(["", f"**{label}**: {value if value is not None and value != '' else 'not provided'}"])
parts.extend([
"",
f"FINAL TRANSACTION PROPOSAL: **{proposal.action.value.upper()}**",
@@ -221,10 +230,11 @@ class PortfolioDecision(BaseModel):
rating: PortfolioRating = Field(
description=(
"The final position rating. Exactly one of Buy / Overweight / Hold / "
- "Underweight / Sell, picked based on the analysts' debate. Choose "
- "Hold when the case is balanced, materially conflicting, ambiguous, "
- "or insufficient to justify changing exposure, rather than forcing a "
- "direction to appear decisive."
+ "Underweight / Sell, picked based on the analysts' debate. "
+ "Conflicting arguments alone are not a reason to Hold: commit to the "
+ "stronger side, sized by how decisively it wins. Choose Hold only "
+ "when the evidence is still balanced after weighing, or too thin to "
+ "support a call."
),
)
executive_summary: str = Field(
@@ -270,10 +280,11 @@ def render_pm_decision(decision: PortfolioDecision) -> str:
"",
f"**Investment Thesis**: {decision.investment_thesis}",
]
- if decision.price_target is not None:
- parts.extend(["", f"**Price Target**: {decision.price_target}"])
- if decision.time_horizon:
- parts.extend(["", f"**Time Horizon**: {decision.time_horizon}"])
+ # Named even when absent: a missing line reads as a field nobody asked for,
+ # so a reader cannot tell "no target" from "target not reported".
+ target = decision.price_target if decision.price_target is not None else "not provided"
+ parts.extend(["", f"**Price Target**: {target}"])
+ parts.extend(["", f"**Time Horizon**: {decision.time_horizon or 'not provided'}"])
return "\n".join(parts)
diff --git a/tradingagents/agents/trader/trader.py b/tradingagents/agents/trader/trader.py
index dbf1f942e..a82ee4bab 100644
--- a/tradingagents/agents/trader/trader.py
+++ b/tradingagents/agents/trader/trader.py
@@ -10,6 +10,7 @@ from tradingagents.agents.schemas import TraderProposal, render_trader_proposal
from tradingagents.agents.utils.agent_utils import (
get_instrument_context_from_state,
get_language_instruction,
+ get_portfolio_context_from_state,
)
from tradingagents.agents.utils.structured import (
NO_EXTERNAL_TOOLS,
@@ -31,6 +32,7 @@ def create_trader(llm):
# report is empty when the user did not select the market analyst, so
# only offer it (and the grounding instruction) when it has content.
market_report = (state["market_report"] or "").strip()
+ portfolio_context = get_portfolio_context_from_state(state)
if market_report:
grounding = (
@@ -67,8 +69,17 @@ def create_trader(llm):
f"Here is the research team's investment plan for {company_name}. "
f"{instrument_context}\n\n"
f"{report_section}"
+ f"{portfolio_context}\n\n"
f"Proposed Investment Plan:\n{investment_plan}\n\n"
- f"Make an informed, strategic trading decision."
+ "Make an informed, strategic trading decision.\n\n"
+ "## Output\n\n"
+ "Write these sections, in this order, starting with the action "
+ "on its own line:\n\n"
+ "- **Action**: exactly one of Buy / Hold / Sell. A research "
+ "recommendation of Overweight is a Buy and Underweight is a Sell, "
+ "sized by how strong the case is; conflict alone is not a Hold.\n"
+ "- **Reasoning**: why, against the plan and the price structure\n"
+ "- **Entry Price**, **Stop Loss**, **Position Sizing**: when you can state them"
),
},
]
diff --git a/tradingagents/agents/utils/agent_states.py b/tradingagents/agents/utils/agent_states.py
index 82504ca03..0d6df58cc 100644
--- a/tradingagents/agents/utils/agent_states.py
+++ b/tradingagents/agents/utils/agent_states.py
@@ -74,3 +74,4 @@ class AgentState(MessagesState):
]
final_trade_decision: Annotated[str, "Final decision made by the Risk Analysts"]
past_context: Annotated[str, "Memory log context injected at run start (same-ticker decisions + cross-ticker lessons)"]
+ portfolio_context: Annotated[str, "Caller-supplied holdings and cash, rendered at run start; empty when not provided"]
diff --git a/tradingagents/agents/utils/agent_utils.py b/tradingagents/agents/utils/agent_utils.py
index cb1d3a3d2..3004d576f 100644
--- a/tradingagents/agents/utils/agent_utils.py
+++ b/tradingagents/agents/utils/agent_utils.py
@@ -48,6 +48,8 @@ __all__ = [
logger = logging.getLogger(__name__)
+from tradingagents.dataflows.utils import get_current_date # noqa: E402
+
def get_language_instruction() -> str:
"""Return a prompt instruction for the configured output language.
@@ -137,6 +139,7 @@ def build_instrument_context(
ticker: str,
asset_type: str = "stock",
identity: Mapping[str, str] | None = None,
+ curr_date: str | None = None,
) -> str:
"""Describe the exact instrument so agents preserve identity and ticker.
@@ -144,6 +147,11 @@ def build_instrument_context(
:func:`resolve_instrument_identity`), the company name and business
classification are injected so agents anchor to the real company rather
than pattern-matching the price chart to a wrong one (#814).
+
+ That profile carries no historical vintage: it describes the company today.
+ For a run dated earlier, the context says so, since a company that has since
+ renamed or been reclassified would otherwise anchor the whole graph to an
+ identity it did not have on the analysis date.
"""
is_crypto = asset_type == "crypto"
instrument_label = "asset" if is_crypto else "instrument"
@@ -174,6 +182,13 @@ def build_instrument_context(
"Do not substitute a different company or ticker unless a tool "
"result explicitly disproves this resolved identity."
)
+ today = get_current_date()
+ if curr_date and str(curr_date) < today:
+ context += (
+ f" This identity is how the vendor describes the instrument today "
+ f"({today}), not necessarily on {curr_date}: a name or "
+ f"classification changed since then would read as the current one."
+ )
if is_crypto:
context += (
@@ -201,6 +216,37 @@ def get_instrument_context_from_state(state: Mapping[str, Any]) -> str:
)
+def report_or_absent(text: str, source: str) -> str:
+ """An analyst's report, or a marker saying it was never produced.
+
+ A report is empty when its analyst was not selected, refused, or returned
+ nothing. Interpolating that into a labelled section presents an absence as a
+ blank finding, and the reading agent fills it in from nothing, the same way
+ an empty opponent argument used to invite an invented rebuttal (#1176).
+ """
+ text = (text or "").strip()
+ if text:
+ return text
+ return f"(No {source} report in this run: it is not available, not an empty finding.)"
+
+
+def get_portfolio_context_from_state(state: Mapping[str, Any]) -> str:
+ """Return the caller's portfolio block, or a notice that none was given.
+
+ A run without portfolio context must not read as a flat book: the agents
+ would otherwise size as if the caller held nothing, which is a claim about
+ an account we were never told about.
+ """
+ context = state.get("portfolio_context")
+ if isinstance(context, str) and context.strip():
+ return context
+ return (
+ "Portfolio context: not provided. You do not know the caller's current "
+ "holdings or cash, so do not assume a flat book; give direction and "
+ "sizing guidance in terms the caller can apply to their own position."
+ )
+
+
def create_msg_delete():
def delete_messages(state):
"""Clear messages and add a context-anchored placeholder.
diff --git a/tradingagents/agents/utils/core_stock_tools.py b/tradingagents/agents/utils/core_stock_tools.py
index bd5cabfad..eb97d982c 100644
--- a/tradingagents/agents/utils/core_stock_tools.py
+++ b/tradingagents/agents/utils/core_stock_tools.py
@@ -1,7 +1,9 @@
from typing import Annotated
from langchain_core.tools import tool
+from langgraph.prebuilt import InjectedState
+from tradingagents.dataflows.date_window import as_of_window
from tradingagents.dataflows.interface import route_to_vendor
@@ -10,6 +12,7 @@ def get_stock_data(
symbol: Annotated[str, "ticker symbol of the company"],
start_date: Annotated[str, "Start date in yyyy-mm-dd format"],
end_date: Annotated[str, "End date in yyyy-mm-dd format"],
+ trade_date: Annotated[str, InjectedState("trade_date")] = "",
) -> str:
"""
Retrieve stock price data (OHLCV) for a given ticker symbol.
@@ -21,4 +24,5 @@ def get_stock_data(
Returns:
str: A formatted dataframe containing the stock price data for the specified ticker symbol in the specified date range.
"""
+ start_date, end_date = as_of_window(start_date, end_date, trade_date)
return route_to_vendor("get_stock_data", symbol, start_date, end_date)
diff --git a/tradingagents/agents/utils/fundamental_data_tools.py b/tradingagents/agents/utils/fundamental_data_tools.py
index aefa0de7c..ffe76decc 100644
--- a/tradingagents/agents/utils/fundamental_data_tools.py
+++ b/tradingagents/agents/utils/fundamental_data_tools.py
@@ -1,7 +1,9 @@
from typing import Annotated
from langchain_core.tools import tool
+from langgraph.prebuilt import InjectedState
+from tradingagents.dataflows.date_window import as_of
from tradingagents.dataflows.interface import route_to_vendor
@@ -9,6 +11,7 @@ from tradingagents.dataflows.interface import route_to_vendor
def get_fundamentals(
ticker: Annotated[str, "ticker symbol"],
curr_date: Annotated[str, "current date you are trading at, yyyy-mm-dd"],
+ trade_date: Annotated[str, InjectedState("trade_date")] = "",
) -> str:
"""
Retrieve comprehensive fundamental data for a given ticker symbol.
@@ -19,7 +22,7 @@ def get_fundamentals(
Returns:
str: A formatted report containing comprehensive fundamental data
"""
- return route_to_vendor("get_fundamentals", ticker, curr_date)
+ return route_to_vendor("get_fundamentals", ticker, as_of(curr_date, trade_date))
@tool
@@ -27,6 +30,7 @@ def get_balance_sheet(
ticker: Annotated[str, "ticker symbol"],
freq: Annotated[str, "reporting frequency: annual/quarterly"] = "quarterly",
curr_date: Annotated[str, "current date you are trading at, yyyy-mm-dd"] = None,
+ trade_date: Annotated[str, InjectedState("trade_date")] = "",
) -> str:
"""
Retrieve balance sheet data for a given ticker symbol.
@@ -38,7 +42,7 @@ def get_balance_sheet(
Returns:
str: A formatted report containing balance sheet data
"""
- return route_to_vendor("get_balance_sheet", ticker, freq, curr_date)
+ return route_to_vendor("get_balance_sheet", ticker, freq, as_of(curr_date, trade_date))
@tool
@@ -46,6 +50,7 @@ def get_cashflow(
ticker: Annotated[str, "ticker symbol"],
freq: Annotated[str, "reporting frequency: annual/quarterly"] = "quarterly",
curr_date: Annotated[str, "current date you are trading at, yyyy-mm-dd"] = None,
+ trade_date: Annotated[str, InjectedState("trade_date")] = "",
) -> str:
"""
Retrieve cash flow statement data for a given ticker symbol.
@@ -57,7 +62,7 @@ def get_cashflow(
Returns:
str: A formatted report containing cash flow statement data
"""
- return route_to_vendor("get_cashflow", ticker, freq, curr_date)
+ return route_to_vendor("get_cashflow", ticker, freq, as_of(curr_date, trade_date))
@tool
@@ -65,6 +70,7 @@ def get_income_statement(
ticker: Annotated[str, "ticker symbol"],
freq: Annotated[str, "reporting frequency: annual/quarterly"] = "quarterly",
curr_date: Annotated[str, "current date you are trading at, yyyy-mm-dd"] = None,
+ trade_date: Annotated[str, InjectedState("trade_date")] = "",
) -> str:
"""
Retrieve income statement data for a given ticker symbol.
@@ -76,4 +82,4 @@ def get_income_statement(
Returns:
str: A formatted report containing income statement data
"""
- return route_to_vendor("get_income_statement", ticker, freq, curr_date)
+ return route_to_vendor("get_income_statement", ticker, freq, as_of(curr_date, trade_date))
diff --git a/tradingagents/agents/utils/macro_data_tools.py b/tradingagents/agents/utils/macro_data_tools.py
index 3d567549b..f44809e6c 100644
--- a/tradingagents/agents/utils/macro_data_tools.py
+++ b/tradingagents/agents/utils/macro_data_tools.py
@@ -1,7 +1,9 @@
from typing import Annotated
from langchain_core.tools import tool
+from langgraph.prebuilt import InjectedState
+from tradingagents.dataflows.date_window import as_of
from tradingagents.dataflows.interface import route_to_vendor
@@ -17,6 +19,7 @@ def get_macro_indicators(
look_back_days: Annotated[
int | None, "Trailing window length in days; omit for a 1-year window"
] = None,
+ trade_date: Annotated[str, InjectedState("trade_date")] = "",
) -> str:
"""
Retrieve a macroeconomic indicator time series from FRED (Federal Reserve
@@ -33,4 +36,4 @@ def get_macro_indicators(
Returns:
str: A formatted markdown report of the macro series
"""
- return route_to_vendor("get_macro_indicators", indicator, curr_date, look_back_days)
+ return route_to_vendor("get_macro_indicators", indicator, as_of(curr_date, trade_date), look_back_days)
diff --git a/tradingagents/agents/utils/market_data_validation_tools.py b/tradingagents/agents/utils/market_data_validation_tools.py
index 356a4ac49..853bda007 100644
--- a/tradingagents/agents/utils/market_data_validation_tools.py
+++ b/tradingagents/agents/utils/market_data_validation_tools.py
@@ -1,7 +1,9 @@
from typing import Annotated
from langchain_core.tools import tool
+from langgraph.prebuilt import InjectedState
+from tradingagents.dataflows.date_window import as_of
from tradingagents.dataflows.market_data_validator import build_verified_market_snapshot
@@ -12,6 +14,7 @@ def get_verified_market_snapshot(
look_back_days: Annotated[
int, "number of recent trading rows to include for sanity-checking"
] = 30,
+ trade_date: Annotated[str, InjectedState("trade_date")] = "",
) -> str:
"""Deterministic verification snapshot for exact market-data claims.
@@ -20,4 +23,4 @@ def get_verified_market_snapshot(
price levels, Bollinger bands, RSI, MACD, moving averages, support /
resistance, or historical comparisons, and treat it as the source of truth.
"""
- return build_verified_market_snapshot(symbol, curr_date, look_back_days)
+ return build_verified_market_snapshot(symbol, as_of(curr_date, trade_date), look_back_days)
diff --git a/tradingagents/agents/utils/memory.py b/tradingagents/agents/utils/memory.py
index 30b16339b..6abb5f631 100644
--- a/tradingagents/agents/utils/memory.py
+++ b/tradingagents/agents/utils/memory.py
@@ -36,11 +36,14 @@ class TradingMemoryLog:
"""Append pending entry at end of propagate(). No LLM call."""
if not self._log_path:
return
- # Idempotency guard: fast raw-text scan instead of full parse
+ # Idempotency guard: fast raw-text scan instead of full parse. Any entry
+ # for this ticker and date blocks another, pending or settled: a re-run
+ # after the outcome landed would otherwise count the same decision twice
+ # in past context and in every aggregate over the log.
if self._log_path.exists():
raw = self._log_path.read_text(encoding="utf-8")
for line in raw.splitlines():
- if line.startswith(f"[{trade_date} | {ticker} |") and line.endswith("| pending]"):
+ if line.startswith(f"[{trade_date} | {ticker} |") and line.endswith("]"):
return
rating = parse_rating(final_trade_decision)
tag = f"[{trade_date} | {ticker} | {rating} | pending]"
diff --git a/tradingagents/agents/utils/news_data_tools.py b/tradingagents/agents/utils/news_data_tools.py
index 6c6f5352a..122240a5a 100644
--- a/tradingagents/agents/utils/news_data_tools.py
+++ b/tradingagents/agents/utils/news_data_tools.py
@@ -1,7 +1,9 @@
from typing import Annotated
from langchain_core.tools import tool
+from langgraph.prebuilt import InjectedState
+from tradingagents.dataflows.date_window import as_of, as_of_window
from tradingagents.dataflows.interface import route_to_vendor
@@ -10,6 +12,7 @@ def get_news(
ticker: Annotated[str, "Ticker symbol"],
start_date: Annotated[str, "Start date in yyyy-mm-dd format"],
end_date: Annotated[str, "End date in yyyy-mm-dd format"],
+ trade_date: Annotated[str, InjectedState("trade_date")] = "",
) -> str:
"""
Retrieve news data for a given ticker symbol.
@@ -21,6 +24,7 @@ def get_news(
Returns:
str: A formatted string containing news data
"""
+ start_date, end_date = as_of_window(start_date, end_date, trade_date)
return route_to_vendor("get_news", ticker, start_date, end_date)
@tool
@@ -28,6 +32,7 @@ def get_global_news(
curr_date: Annotated[str, "Current date in yyyy-mm-dd format"],
look_back_days: Annotated[int | None, "Days to look back; omit to use the configured default"] = None,
limit: Annotated[int | None, "Max articles to return; omit to use the configured default"] = None,
+ trade_date: Annotated[str, InjectedState("trade_date")] = "",
) -> str:
"""
Retrieve global news data.
@@ -43,11 +48,12 @@ def get_global_news(
Returns:
str: A formatted string containing global news data
"""
- return route_to_vendor("get_global_news", curr_date, look_back_days, limit)
+ return route_to_vendor("get_global_news", as_of(curr_date, trade_date), look_back_days, limit)
@tool
def get_insider_transactions(
ticker: Annotated[str, "ticker symbol"],
+ trade_date: Annotated[str, InjectedState("trade_date")] = "",
) -> str:
"""
Retrieve insider transaction information about a company.
@@ -57,4 +63,4 @@ def get_insider_transactions(
Returns:
str: A report of insider transaction data
"""
- return route_to_vendor("get_insider_transactions", ticker)
+ return route_to_vendor("get_insider_transactions", ticker, trade_date or None)
diff --git a/tradingagents/agents/utils/prediction_markets_tools.py b/tradingagents/agents/utils/prediction_markets_tools.py
index 843c9a49c..dfa50f9b9 100644
--- a/tradingagents/agents/utils/prediction_markets_tools.py
+++ b/tradingagents/agents/utils/prediction_markets_tools.py
@@ -1,6 +1,7 @@
from typing import Annotated
from langchain_core.tools import tool
+from langgraph.prebuilt import InjectedState
from tradingagents.dataflows.interface import route_to_vendor
@@ -13,6 +14,7 @@ def get_prediction_markets(
"'US election', or a sector/company event.",
],
limit: Annotated[int | None, "Max markets to return; omit for a default of 6"] = None,
+ trade_date: Annotated[str, InjectedState("trade_date")] = "",
) -> str:
"""
Retrieve live, market-implied probabilities for forward-looking events from
@@ -28,4 +30,4 @@ def get_prediction_markets(
Returns:
str: A formatted markdown report of matching prediction markets
"""
- return route_to_vendor("get_prediction_markets", topic, limit)
+ return route_to_vendor("get_prediction_markets", topic, limit, trade_date or None)
diff --git a/tradingagents/agents/utils/rating.py b/tradingagents/agents/utils/rating.py
index 1a828ea21..daaa3a492 100644
--- a/tradingagents/agents/utils/rating.py
+++ b/tradingagents/agents/utils/rating.py
@@ -8,10 +8,10 @@ The same five-tier scale (Buy, Overweight, Hold, Underweight, Sell) is used by:
Centralising it here avoids drift between those call sites.
-``extract_rating`` returns ``None`` when no rating can be found, so the graph can
-surface an explicit ``REVIEW`` signal instead of a fabricated ``Hold`` (#1170).
-``parse_rating`` keeps the legacy silent-default behaviour for callers (e.g. the
-memory log) that need a rating string regardless.
+``extract_rating`` returns ``None`` when no rating can be found, and every
+caller turns that into ``REVIEW`` rather than a tradeable position: a decision
+nobody can read is not a Hold, and a Hold recorded in its place is quoted back to
+the next run as a call that was never made (#1170).
"""
from __future__ import annotations
@@ -32,9 +32,13 @@ RATING_REVIEW = "REVIEW"
_RATING_SET = {r.lower() for r in RATINGS_5_TIER}
-# Matches "Rating: X" / "rating - X" / "Rating: **X**" — tolerates markdown
-# bold wrappers and either a colon or hyphen separator.
-_RATING_LABEL_RE = re.compile(r"rating.*?[:\-][\s*]*(\w+)", re.IGNORECASE)
+# Matches "Rating: X" / "rating - X" / "Rating — **X**" — tolerates markdown
+# bold wrappers and any dash or colon a model writes as the separator.
+_RATING_LABEL_RE = re.compile(r"rating\b[^:\-\u2010-\u2015]*[:\-\u2010-\u2015][\s*]*(\w+)",
+ re.IGNORECASE)
+
+# A line presenting the scale rather than a decision ("Rating Scale: Buy, ...").
+_RATING_SCALE_RE = re.compile(r"rating\s*(scale|options|legend)", re.IGNORECASE)
# Standalone 5-tier word anywhere (word boundaries so "Buyer"/"Holding" don't match).
_RATING_WORD_RE = re.compile(
@@ -54,25 +58,31 @@ def extract_rating(text: str) -> str | None:
return None
norm = unicodedata.normalize("NFKC", text)
+ # The labelled rating, taking the last one written: a decision states its
+ # rating after discussing the alternatives. Lines presenting the scale
+ # itself are a legend the model echoed, not a call.
+ labelled = None
for line in norm.splitlines():
+ if _RATING_SCALE_RE.search(line):
+ continue
m = _RATING_LABEL_RE.search(line)
if m and m.group(1).lower() in _RATING_SET:
- return m.group(1).capitalize()
+ labelled = m.group(1).capitalize()
+ if labelled:
+ return labelled
- m = _RATING_WORD_RE.search(norm)
- if m:
- return m.group(1).capitalize()
-
- return None
+ # No label. A single rating word in the text is the call; several are an
+ # argument, and picking one of them reports a direction nobody decided --
+ # prose that rejects a Buy before concluding Underweight read as Buy.
+ named = {m.group(1).capitalize() for m in _RATING_WORD_RE.finditer(norm)}
+ return named.pop() if len(named) == 1 else None
-def parse_rating(text: str, default: str = "Hold") -> str:
- """Extract a 5-tier rating, falling back to ``default`` when none is found.
+def parse_rating(text: str, default: str = RATING_REVIEW) -> str:
+ """Extract a 5-tier rating, or ``REVIEW`` when the decision has none.
- Legacy convenience wrapper: it always returns a rating string, so an
- unparseable decision silently becomes ``default`` (``Hold``). Callers that
- must distinguish "no rating" from a real Hold should use
- :func:`extract_rating` (or the graph's REVIEW-surfacing signal) instead.
+ For callers that need a string for every decision, such as the memory log's
+ entry tag. The default is the review sentinel, never a tradeable rating.
"""
rating = extract_rating(text)
return rating if rating is not None else default
diff --git a/tradingagents/agents/utils/technical_indicators_tools.py b/tradingagents/agents/utils/technical_indicators_tools.py
index c1c5ad99f..c6baecf37 100644
--- a/tradingagents/agents/utils/technical_indicators_tools.py
+++ b/tradingagents/agents/utils/technical_indicators_tools.py
@@ -1,7 +1,9 @@
from typing import Annotated
from langchain_core.tools import tool
+from langgraph.prebuilt import InjectedState
+from tradingagents.dataflows.date_window import as_of
from tradingagents.dataflows.interface import route_to_vendor
@@ -11,6 +13,7 @@ def get_indicators(
indicator: Annotated[str, "technical indicator to get the analysis and report of"],
curr_date: Annotated[str, "The current trading date you are trading on, YYYY-mm-dd"],
look_back_days: Annotated[int, "how many days to look back"] = 30,
+ trade_date: Annotated[str, InjectedState("trade_date")] = "",
) -> str:
"""
Retrieve a single technical indicator for a given ticker symbol.
@@ -25,6 +28,7 @@ def get_indicators(
"""
# LLMs sometimes pass multiple indicators as a comma-separated string;
# split and process each individually.
+ curr_date = as_of(curr_date, trade_date)
indicators = [i.strip().lower() for i in indicator.split(",") if i.strip()]
results = []
for ind in indicators:
diff --git a/tradingagents/backtest.py b/tradingagents/backtest.py
new file mode 100644
index 000000000..99d6874a4
--- /dev/null
+++ b/tradingagents/backtest.py
@@ -0,0 +1,201 @@
+"""Run the graph over a grid of tickers and dates, and score what came back.
+
+One run yields one decision, so it cannot say whether the system decides well.
+This runs the same machinery over many (ticker, date) cells and reads the
+aggregate. The decision log is the results table: every run already records its
+rating and later settles it with realized and alpha return against the
+instrument's regional benchmark, so there is nothing to record separately.
+
+Scope: this evaluates decision quality. It is not a portfolio simulator, and
+must not grow one. Turning a rating into a filled order needs a quantity, a fill
+price and a cash ledger, none of which the system has; inventing them here would
+put an execution model behind an evaluation tool. Cells are therefore
+independent, and a portfolio, when given, is the same standing book for every
+cell rather than a position carried forward.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta
+from pathlib import Path
+
+from tradingagents.agents.utils.memory import TradingMemoryLog
+from tradingagents.agents.utils.rating import RATING_REVIEW
+from tradingagents.dataflows.utils import get_current_date, safe_ticker_component
+from tradingagents.graph.trading_graph import TradingAgentsGraph
+
+logger = logging.getLogger(__name__)
+
+
+def iter_grid(start_date: str, end_date: str, every_n_days: int = 1) -> list[str]:
+ """Analysis dates from ``start_date``, never past today.
+
+ A future date has no outcome to settle against, and the graph rejects one, so
+ the grid stops at the present rather than producing cells that cannot score.
+ """
+ start, end = _canonical(start_date), _canonical(end_date)
+ if every_n_days < 1:
+ raise ValueError("every_n_days must be at least 1")
+ if end < start:
+ raise ValueError(f"the grid ends before it starts: {end_date} is before {start_date}")
+
+ last = min(end, datetime.strptime(get_current_date(), "%Y-%m-%d"))
+ dates, cursor = [], start
+ while cursor <= last:
+ dates.append(cursor.strftime("%Y-%m-%d"))
+ cursor += timedelta(days=every_n_days)
+ return dates
+
+
+def _canonical(date: str) -> datetime:
+ """Parse a grid bound, rejecting anything the run date would also reject."""
+ try:
+ parsed = datetime.strptime(str(date), "%Y-%m-%d")
+ except (TypeError, ValueError) as exc:
+ raise ValueError(f"grid dates must be in YYYY-MM-DD format, got {date!r}") from exc
+ if parsed.strftime("%Y-%m-%d") != str(date):
+ raise ValueError(f"grid dates must be in YYYY-MM-DD format, got {date!r}")
+ return parsed
+
+
+def _alpha(entry: dict) -> float | None:
+ """Alpha return of a settled entry, or None when it has not settled.
+
+ The log stores it as a percentage rounded to one decimal, so aggregates here
+ are accurate to 0.1 of a percentage point, not to the raw quote.
+ """
+ text = (entry.get("alpha") or "").strip().rstrip("%")
+ try:
+ return float(text) / 100
+ except ValueError:
+ return None
+
+
+@dataclass
+class BacktestResult:
+ run_id: str
+ log_path: Path
+ cells_run: int = 0
+ skipped: int = 0
+ failures: list[tuple[str, str, str]] = field(default_factory=list)
+ settlement_failures: list[tuple[str, str]] = field(default_factory=list)
+
+
+# What each rating claims will happen, so an outcome can be scored against it.
+# Hold claims no direction, so nothing about alpha proves it right or wrong.
+_DIRECTION = {"Buy": 1, "Overweight": 1, "Hold": 0, "Underweight": -1, "Sell": -1}
+
+
+@dataclass
+class RatingScore:
+ count: int
+ hit_rate: float | None
+ mean_alpha: float
+
+
+@dataclass
+class BacktestSummary:
+ resolved: int
+ pending: int
+ by_rating: dict[str, RatingScore]
+ unscored: int = 0
+ holding: str = ""
+
+ def render(self) -> str:
+ lines = [f"Resolved cells: {self.resolved} · pending: {self.pending}"
+ + (f" · unscored: {self.unscored}" if self.unscored else "")]
+ for rating, score in self.by_rating.items():
+ called = (f"called the direction {score.hit_rate:.0%}"
+ if score.hit_rate is not None else "no direction claimed")
+ lines.append(
+ f"- {rating}: n={score.count}, {called}, "
+ f"mean alpha {score.mean_alpha:+.2%} vs the benchmark"
+ )
+ lines.append("")
+ if self.pending:
+ lines.append("Pending cells are not scored above; re-run to settle them.")
+ lines.append(
+ f"Alpha is measured over {self.holding} after each analysis date. "
+ "One model sampling per cell, and text feeds are not archived, so "
+ "these figures are indicative rather than repeatable."
+ )
+ return "\n".join(lines)
+
+
+def run_backtest(
+ tickers: list[str],
+ dates: list[str],
+ config: dict,
+ asset_type: str = "stock",
+ portfolio=None,
+ selected_analysts=("market", "social", "news", "fundamentals"),
+ run_id: str | None = None,
+) -> BacktestResult:
+ """Analyze every ticker on every date, into a decision log of this run's own.
+
+ The live log stays untouched: a sweep would otherwise flood the context that
+ real runs read back. Cells already in this run's log are skipped, so an
+ interrupted sweep resumes by being run again.
+ """
+ # run_id becomes a path segment, so it is validated like a ticker: an
+ # absolute or dotted value would otherwise place the run outside results_dir.
+ run_id = safe_ticker_component(run_id or datetime.now().strftime("%Y%m%d_%H%M%S"))
+ run_dir = Path(config["results_dir"]) / "backtest" / run_id
+ run_dir.mkdir(parents=True, exist_ok=True)
+ run_config = {**config, "results_dir": str(run_dir),
+ "memory_log_path": str(run_dir / "trading_memory.md")}
+
+ graph = TradingAgentsGraph(selected_analysts, config=run_config)
+ result = BacktestResult(run_id=run_id, log_path=Path(run_config["memory_log_path"]))
+ done = {(e["ticker"], e["date"]) for e in graph.memory_log.load_entries()}
+
+ for ticker in tickers:
+ for date in dates:
+ if (ticker, date) in done:
+ result.skipped += 1
+ continue
+ try:
+ graph.propagate(ticker, date, asset_type, portfolio=portfolio)
+ result.cells_run += 1
+ except Exception as exc: # one unreachable vendor must not end the sweep
+ logger.warning("Backtest cell %s %s failed: %s", ticker, date, exc)
+ result.failures.append((ticker, date, str(exc)))
+
+ # Settlement runs at the start of the next run for a ticker, so each ticker's
+ # last cell would stay pending without this pass.
+ for ticker in tickers:
+ try:
+ graph.settle_pending(ticker)
+ except Exception as exc: # reflection calls an LLM; one failure is not the sweep's
+ logger.warning("Settling %s failed: %s", ticker, exc)
+ result.settlement_failures.append((ticker, str(exc)))
+ return result
+
+
+def summarize(memory_log: TradingMemoryLog) -> BacktestSummary:
+ """Score the settled decisions in a log, by rating."""
+ entries = memory_log.load_entries()
+ # A decision with no readable rating has no direction, so it can neither
+ # count for nor against the system; it is reported as unscored instead.
+ resolved = [(e, _alpha(e)) for e in entries
+ if not e["pending"] and e["rating"] != RATING_REVIEW]
+ resolved = [(e, a) for e, a in resolved if a is not None]
+ by_rating: dict[str, RatingScore] = {}
+ for rating in dict.fromkeys(e["rating"] for e, _ in resolved):
+ alphas = [a for e, a in resolved if e["rating"] == rating]
+ direction = _DIRECTION.get(rating, 0)
+ by_rating[rating] = RatingScore(
+ count=len(alphas),
+ hit_rate=(sum(a * direction > 0 for a in alphas) / len(alphas)) if direction else None,
+ mean_alpha=sum(alphas) / len(alphas),
+ )
+ unscored = sum(1 for e in entries if e["rating"] == RATING_REVIEW)
+ # Report the window the outcomes were actually measured over, from the log.
+ windows = {f"{e['holding'][:-1]} trading days" for e, _ in resolved
+ if (e.get("holding") or "").endswith("d")}
+ return BacktestSummary(resolved=len(resolved),
+ pending=len(entries) - len(resolved) - unscored,
+ by_rating=by_rating, unscored=unscored,
+ holding=", ".join(sorted(windows)) or "the configured window")
diff --git a/tradingagents/dataflows/alpha_vantage_common.py b/tradingagents/dataflows/alpha_vantage_common.py
index ecbe4dcec..7f07af9b1 100644
--- a/tradingagents/dataflows/alpha_vantage_common.py
+++ b/tradingagents/dataflows/alpha_vantage_common.py
@@ -4,9 +4,9 @@ from datetime import datetime
from io import StringIO
import pandas as pd
-import requests
from .errors import VendorNotConfiguredError, VendorRateLimitError
+from .utils import get_scrubbed
API_BASE_URL = "https://www.alphavantage.co/query"
@@ -34,8 +34,13 @@ def get_api_key() -> str:
)
return api_key
-def format_datetime_for_api(date_input) -> str:
- """Convert various date formats to YYYYMMDDTHHMM format required by Alpha Vantage API."""
+def format_datetime_for_api(date_input, end_of_day: bool = False) -> str:
+ """Convert various date formats to the YYYYMMDDTHHMM Alpha Vantage expects.
+
+ A plain date means midnight, which is the start of that day. For the end of
+ a window pass ``end_of_day`` so the day itself is inside it, rather than
+ dropping everything published on the analysis date.
+ """
if isinstance(date_input, str):
# If already in correct format, return as-is
if len(date_input) == 13 and 'T' in date_input:
@@ -43,7 +48,7 @@ def format_datetime_for_api(date_input) -> str:
# Try to parse common date formats
try:
dt = datetime.strptime(date_input, "%Y-%m-%d")
- return dt.strftime("%Y%m%dT0000")
+ return dt.strftime("%Y%m%dT2359" if end_of_day else "%Y%m%dT0000")
except ValueError:
try:
dt = datetime.strptime(date_input, "%Y-%m-%d %H:%M")
@@ -66,10 +71,11 @@ def _make_api_request(function_name: str, params: dict) -> dict | str:
AlphaVantageRateLimitError: When API rate limit is exceeded
"""
# Create a copy of params to avoid modifying the original
+ api_key = get_api_key()
api_params = params.copy()
api_params.update({
"function": function_name,
- "apikey": get_api_key(),
+ "apikey": api_key,
"source": "trading_agents",
})
@@ -83,8 +89,9 @@ def _make_api_request(function_name: str, params: dict) -> dict | str:
# Remove entitlement if it's None or empty
api_params.pop("entitlement", None)
- response = requests.get(API_BASE_URL, params=api_params, timeout=REQUEST_TIMEOUT)
- response.raise_for_status()
+ response = get_scrubbed(
+ API_BASE_URL, params=api_params, timeout=REQUEST_TIMEOUT, secret=api_key
+ )
response_text = response.text
diff --git a/tradingagents/dataflows/alpha_vantage_indicator.py b/tradingagents/dataflows/alpha_vantage_indicator.py
index 5dd61f387..c53d91a5c 100644
--- a/tradingagents/dataflows/alpha_vantage_indicator.py
+++ b/tradingagents/dataflows/alpha_vantage_indicator.py
@@ -1,6 +1,7 @@
import logging
-from .alpha_vantage_common import AlphaVantageNotConfiguredError, _make_api_request
+from .alpha_vantage_common import _make_api_request
+from .errors import NoMarketDataError, VendorError
logger = logging.getLogger(__name__)
@@ -64,8 +65,11 @@ def get_indicator(
}
if indicator not in supported_indicators:
- raise ValueError(
- f"Indicator {indicator} is not supported. Please choose from: {list(supported_indicators.keys())}"
+ # A vendor error, not a caller error: another vendor may compute it, and
+ # the router decides. yfinance rejects a name nobody serves.
+ raise NoMarketDataError(
+ symbol, symbol,
+ f"Alpha Vantage does not serve {indicator}; it serves {list(supported_indicators)}"
)
curr_date_dt = datetime.strptime(curr_date, "%Y-%m-%d")
@@ -134,12 +138,13 @@ def get_indicator(
"time_period": str(time_period),
"datatype": "csv"
})
- elif indicator == "vwma":
- # Alpha Vantage doesn't have direct VWMA, so we'll return an informative message
- # In a real implementation, this would need to be calculated from OHLCV data
- return f"## VWMA (Volume Weighted Moving Average) for {symbol}:\n\nVWMA calculation requires OHLCV data and is not directly available from Alpha Vantage API.\nThis indicator would need to be calculated from the raw stock data using volume-weighted price averaging.\n\n{indicator_descriptions.get('vwma', 'No description available.')}"
else:
- return f"Error: Indicator {indicator} not implemented yet."
+ # This vendor has no endpoint for the indicator. Raising lets the
+ # router try the next vendor, which computes it; returning prose
+ # counted as a successful answer and ended the chain here.
+ raise NoMarketDataError(
+ symbol, symbol, f"Alpha Vantage does not serve the {indicator} indicator"
+ )
# Parse CSV data and extract values for the date range
lines = data.strip().split('\n')
@@ -209,11 +214,11 @@ def get_indicator(
return result_str
- except AlphaVantageNotConfiguredError:
- # Vendor unavailable (no API key). Let it propagate so the router can
- # fall back / emit the no-data sentinel instead of returning this as a
- # successful-looking error string.
+ except VendorError:
+ # Unavailable vendor, throttle, or an indicator this vendor does not
+ # serve. Let it propagate so the router falls back to a vendor that can,
+ # instead of returning the failure as a successful-looking string.
raise
except Exception as e:
logger.warning("Alpha Vantage indicator %s failed: %s", indicator, e)
- return f"Error retrieving {indicator} data: {str(e)}"
+ raise NoMarketDataError(symbol, symbol, f"{indicator} unavailable: {e}") from e
diff --git a/tradingagents/dataflows/alpha_vantage_news.py b/tradingagents/dataflows/alpha_vantage_news.py
index f9c7cfc99..e323e4900 100644
--- a/tradingagents/dataflows/alpha_vantage_news.py
+++ b/tradingagents/dataflows/alpha_vantage_news.py
@@ -1,4 +1,7 @@
+import json
+
from .alpha_vantage_common import _make_api_request, format_datetime_for_api
+from .config import get_config
def get_news(ticker, start_date, end_date) -> dict[str, str] | str:
@@ -15,30 +18,40 @@ def get_news(ticker, start_date, end_date) -> dict[str, str] | str:
Dictionary containing news sentiment data or JSON string.
"""
+ # Without a limit the endpoint returns 50 articles, each with per-ticker
+ # sentiment arrays, and all of it reaches the prompt.
params = {
"tickers": ticker,
"time_from": format_datetime_for_api(start_date),
- "time_to": format_datetime_for_api(end_date),
+ "time_to": format_datetime_for_api(end_date, end_of_day=True),
+ "limit": str(get_config()["news_article_limit"]),
}
return _make_api_request("NEWS_SENTIMENT", params)
-def get_global_news(curr_date, look_back_days: int = 7, limit: int = 50) -> dict[str, str] | str:
+def get_global_news(curr_date, look_back_days: int | None = None, limit: int | None = None) -> dict[str, str] | str:
"""Returns global market news & sentiment data without ticker-specific filtering.
Covers broad market topics like financial markets, economy, and more.
Args:
curr_date: Current date in yyyy-mm-dd format.
- look_back_days: Number of days to look back (default 7).
- limit: Maximum number of articles (default 50).
+ look_back_days: Number of days to look back; ``None`` uses
+ ``global_news_lookback_days`` from the active config.
+ limit: Maximum number of articles; ``None`` uses
+ ``global_news_article_limit`` from the active config.
Returns:
Dictionary containing global news sentiment data or JSON string.
"""
from datetime import datetime, timedelta
- # Calculate start date
+ config = get_config()
+ if look_back_days is None:
+ look_back_days = config["global_news_lookback_days"]
+ if limit is None:
+ limit = config["global_news_article_limit"]
+
curr_dt = datetime.strptime(curr_date, "%Y-%m-%d")
start_dt = curr_dt - timedelta(days=look_back_days)
start_date = start_dt.strftime("%Y-%m-%d")
@@ -46,20 +59,21 @@ def get_global_news(curr_date, look_back_days: int = 7, limit: int = 50) -> dict
params = {
"topics": "financial_markets,economy_macro,economy_monetary",
"time_from": format_datetime_for_api(start_date),
- "time_to": format_datetime_for_api(curr_date),
+ "time_to": format_datetime_for_api(curr_date, end_of_day=True),
"limit": str(limit),
}
return _make_api_request("NEWS_SENTIMENT", params)
-def get_insider_transactions(symbol: str) -> dict[str, str] | str:
+def get_insider_transactions(symbol: str, curr_date: str | None = None) -> dict[str, str] | str:
"""Returns latest and historical insider transactions by key stakeholders.
Covers transactions by founders, executives, board members, etc.
Args:
symbol: Ticker symbol. Example: "IBM".
+ curr_date: When given, only transactions on or before it (yyyy-mm-dd).
Returns:
Dictionary containing insider transaction data or JSON string.
@@ -69,4 +83,9 @@ def get_insider_transactions(symbol: str) -> dict[str, str] | str:
"symbol": symbol,
}
- return _make_api_request("INSIDER_TRANSACTIONS", params)
+ response = _make_api_request("INSIDER_TRANSACTIONS", params)
+ if not curr_date:
+ return response
+ payload = json.loads(response)
+ payload["data"] = [t for t in payload["data"] if t["transaction_date"] <= curr_date]
+ return json.dumps(payload)
diff --git a/tradingagents/dataflows/date_window.py b/tradingagents/dataflows/date_window.py
index 3a7dc0206..57ba38e1b 100644
--- a/tradingagents/dataflows/date_window.py
+++ b/tradingagents/dataflows/date_window.py
@@ -32,6 +32,66 @@ def in_window(pub_dt: datetime | None, start_dt: datetime, end_dt: datetime) ->
return end >= datetime.now(timezone.utc) - timedelta(days=1)
+def coverage_gap(
+ dates, start_date: str, end_date: str, source: str, subject: str
+) -> str | None:
+ """Placeholder for a window a feed did not fully observe, else None.
+
+ Yahoo news and the Reddit and StockTwits feeds return their latest items
+ whatever window is asked for, so "none found" over a window they never
+ observed would claim an absence nobody saw. A window is observed when
+ coverage reaches its first day and it ends by today; an empty result is then
+ a real absence and this returns None.
+
+ ``dates`` are the returned items' timestamps, plus the lookback start for a
+ feed with a fixed lookback. The oldest one bounds coverage only for a feed
+ returned newest-first and unbroken in time; a merged or relevance-ranked
+ result passes no dates, leaving only the present as the bound.
+ """
+ now = datetime.now(timezone.utc)
+ oldest = min((to_utc(d) for d in dates if d is not None), default=now)
+ if datetime.strptime(end_date, "%Y-%m-%d").date() > now.date():
+ reason = "the window extends past today"
+ elif oldest.date() > datetime.strptime(start_date, "%Y-%m-%d").date():
+ reason = f"it only serves recent items (coverage starts {oldest:%Y-%m-%d})"
+ else:
+ return None
+ return f"<{source} unavailable for {start_date}..{end_date}: {reason}, so this is not an absence of {subject}>"
+
+
+def _parse(date: str | None) -> datetime | None:
+ try:
+ return datetime.strptime(date, "%Y-%m-%d")
+ except (TypeError, ValueError):
+ return None
+
+
+def as_of(requested: str | None, trade_date: str) -> str | None:
+ """The date a tool serves: the model's date, but never later than the run's.
+
+ A model can omit the date or pass today's instead of the analysis date, which
+ would walk past every point-in-time guard behind the tool. An empty
+ ``trade_date`` (a direct call outside a graph run) passes the request through.
+ """
+ if not trade_date:
+ return requested
+ parsed = _parse(requested)
+ return requested if parsed is not None and parsed <= _parse(trade_date) else trade_date
+
+
+def as_of_window(start_date: str, end_date: str, trade_date: str) -> tuple[str, str]:
+ """``[start, end]`` with its end clamped to the run date.
+
+ A window wholly after the run date keeps its length and moves back to end there.
+ """
+ end = as_of(end_date, trade_date)
+ start, old_end = _parse(start_date), _parse(end_date)
+ if end == end_date or start is None or start <= _parse(end):
+ return start_date, end
+ span = (old_end - start) if old_end is not None and old_end >= start else timedelta(0)
+ return f"{_parse(end) - span:%Y-%m-%d}", end
+
+
def withhold_live_profile(curr_date: str | None, label: str) -> str | None:
"""Notice to serve instead of a live-only company profile, or None to serve it.
diff --git a/tradingagents/dataflows/fred.py b/tradingagents/dataflows/fred.py
index 98f1827b6..28312e434 100644
--- a/tradingagents/dataflows/fred.py
+++ b/tradingagents/dataflows/fred.py
@@ -13,9 +13,9 @@ import os
from datetime import datetime, timedelta
import pytz
-import requests
from .errors import VendorNotConfiguredError
+from .utils import get_scrubbed
logger = logging.getLogger(__name__)
@@ -134,9 +134,13 @@ def _fred_today() -> str:
def _request(path: str, params: dict) -> dict:
"""GET a FRED endpoint, surfacing FRED's JSON error body on a bad request."""
- api_params = {**params, "api_key": get_api_key(), "file_type": "json"}
- response = requests.get(
- f"{FRED_API_BASE}/{path}", params=api_params, timeout=REQUEST_TIMEOUT
+ api_key = get_api_key()
+ response = get_scrubbed(
+ f"{FRED_API_BASE}/{path}",
+ params={**params, "api_key": api_key, "file_type": "json"},
+ timeout=REQUEST_TIMEOUT,
+ secret=api_key,
+ passthrough=(400,),
)
# FRED returns 400 with a JSON {"error_message": ...} for unknown series IDs
# or malformed params; turn that into a clear, actionable error.
@@ -146,7 +150,6 @@ def _request(path: str, params: dict) -> dict:
except ValueError:
message = response.text
raise ValueError(f"FRED request failed: {message}")
- response.raise_for_status()
return response.json()
diff --git a/tradingagents/dataflows/interface.py b/tradingagents/dataflows/interface.py
index 281c83747..61fd74e1a 100644
--- a/tradingagents/dataflows/interface.py
+++ b/tradingagents/dataflows/interface.py
@@ -19,6 +19,11 @@ from .errors import (
)
from .fred import get_macro_data as get_fred_macro_data
from .polymarket import get_prediction_markets as get_polymarket_prediction_markets
+from .sec_edgar import (
+ get_balance_sheet as get_sec_edgar_balance_sheet,
+ get_cashflow as get_sec_edgar_cashflow,
+ get_income_statement as get_sec_edgar_income_statement,
+)
from .y_finance import (
get_balance_sheet as get_yfinance_balance_sheet,
get_cashflow as get_yfinance_cashflow,
@@ -79,6 +84,7 @@ TOOLS_CATEGORIES = {
VENDOR_LIST = [
"yfinance",
+ "sec_edgar",
"fred",
"polymarket",
"alpha_vantage",
@@ -110,14 +116,17 @@ VENDOR_METHODS = {
},
"get_balance_sheet": {
"alpha_vantage": get_alpha_vantage_balance_sheet,
+ "sec_edgar": get_sec_edgar_balance_sheet,
"yfinance": get_yfinance_balance_sheet,
},
"get_cashflow": {
"alpha_vantage": get_alpha_vantage_cashflow,
+ "sec_edgar": get_sec_edgar_cashflow,
"yfinance": get_yfinance_cashflow,
},
"get_income_statement": {
"alpha_vantage": get_alpha_vantage_income_statement,
+ "sec_edgar": get_sec_edgar_income_statement,
"yfinance": get_yfinance_income_statement,
},
# news_data
@@ -193,6 +202,7 @@ def route_to_vendor(method: str, *args, **kwargs):
vendor_chain = all_available_vendors
last_no_data: NoMarketDataError | None = None
+ last_unavailable: VendorRateLimitError | None = None
first_error: Exception | None = None
for vendor in vendor_chain:
vendor_impl = VENDOR_METHODS[method][vendor]
@@ -200,8 +210,11 @@ def route_to_vendor(method: str, *args, **kwargs):
try:
return impl_func(*args, **kwargs)
- except VendorRateLimitError:
- logger.warning("Vendor %r rate-limited for %s; trying next vendor.", vendor, method)
+ except VendorRateLimitError as e:
+ logger.warning("Vendor %r unavailable for %s: %s; trying next vendor.", vendor, method, e)
+ # Kept so an all-unavailable chain can say the vendor was the
+ # problem, rather than reporting nothing about the symbol.
+ last_unavailable = e
continue
except VendorNotConfiguredError as e:
logger.warning("Vendor %r not configured for %s; trying next vendor.", vendor, method)
@@ -250,6 +263,15 @@ def route_to_vendor(method: str, *args, **kwargs):
# first real error (e.g. the primary vendor's network failure). Optional
# enrichment categories degrade to a sentinel instead, so flavour data can't
# abort the run.
+ # Every vendor was throttled or unreachable: that is a fact about the
+ # vendors, not about the instrument, and it must not end the run.
+ if last_unavailable is not None:
+ return (
+ f"DATA_UNAVAILABLE: no configured vendor could serve {method} right now "
+ f"({last_unavailable}). This says nothing about the instrument; report the "
+ f"data as unavailable and do not estimate or fabricate values."
+ )
+
if first_error is not None:
if category in OPTIONAL_CATEGORIES:
logger.warning("Optional %s unavailable for %s: %s", category, method, first_error)
diff --git a/tradingagents/dataflows/market_data_validator.py b/tradingagents/dataflows/market_data_validator.py
index baa5efecf..05c062457 100644
--- a/tradingagents/dataflows/market_data_validator.py
+++ b/tradingagents/dataflows/market_data_validator.py
@@ -32,7 +32,9 @@ def _verified_rows(symbol: str, curr_date: str) -> pd.DataFrame:
look-ahead rows, but we re-apply the cutoff defensively — this is a
verification path, so it must not trust its input to be pre-filtered.
"""
- data = load_ohlcv(symbol, curr_date)
+ # As reported: this snapshot is quoted by the agents as exact prices, so a
+ # gap-filled cell would put the previous session's number under this date.
+ data = load_ohlcv(symbol, curr_date, fill_gaps=False)
if data is None or data.empty:
raise ValueError(f"No OHLCV data available for {symbol}.")
diff --git a/tradingagents/dataflows/polymarket.py b/tradingagents/dataflows/polymarket.py
index b76dfe7f0..3188ac034 100644
--- a/tradingagents/dataflows/polymarket.py
+++ b/tradingagents/dataflows/polymarket.py
@@ -15,6 +15,8 @@ from datetime import datetime, timezone
import requests
+from .utils import get_current_date
+
logger = logging.getLogger(__name__)
GAMMA_BASE = "https://gamma-api.polymarket.com"
@@ -65,7 +67,7 @@ def _is_forward_looking(market: dict, now: datetime) -> bool:
)
-def get_prediction_markets(topic: str, limit: int | None = None) -> str:
+def get_prediction_markets(topic: str, limit: int | None = None, curr_date: str | None = None) -> str:
"""Return live prediction-market probabilities for an event topic.
Args:
@@ -73,12 +75,20 @@ def get_prediction_markets(topic: str, limit: int | None = None) -> str:
"US election", or a sector/company event.
limit: Max markets to return (ranked by traded volume); ``None`` uses
DEFAULT_LIMIT.
+ curr_date: The analysis date. Polymarket serves only live odds, so a
+ date before today withholds them.
Returns:
A markdown report of the most-traded open markets matching the topic,
each with its implied probability, traded volume, resolution date, and
recent (1-week) move.
"""
+ if curr_date and curr_date < get_current_date():
+ return (
+ f"Prediction-market odds are withheld for {curr_date}. Polymarket serves "
+ f"only live odds on open markets, with no historical vintage, so serving "
+ f"them would put post-decision information into a {curr_date} analysis."
+ )
if limit is None:
limit = DEFAULT_LIMIT
diff --git a/tradingagents/dataflows/reddit.py b/tradingagents/dataflows/reddit.py
index 502c84d68..e01442853 100644
--- a/tradingagents/dataflows/reddit.py
+++ b/tradingagents/dataflows/reddit.py
@@ -1,14 +1,9 @@
"""Reddit search fetcher for ticker-specific discussion posts.
-Default path is Reddit's public Atom/RSS search feed
-(``reddit.com/r/{sub}/search.rss``). The richer JSON search endpoint
-(``/search.json``) is reliably WAF-blocked (``HTTP 403``) for public clients
-(issue #862), and probing it on every call only doubled our request volume
-against Reddit's per-IP rate limit — tripping ``429`` on the RSS fallback — so
-it is kept (``_fetch_subreddit_json``) but not used by default. On a 429 we back
-off once (honouring ``Retry-After``). RSS lacks score / comment counts, so those
-posts are marked and the formatter omits the metrics rather than printing fake
-zeros.
+Reads Reddit's public Atom/RSS search feed, searching all subreddits in one
+combined request. The JSON search endpoint is WAF-blocked (``HTTP 403``) for
+anonymous clients (#862), so RSS is the only path; it carries no score or comment
+counts. On a 429 we back off once, honouring ``Retry-After``.
A fetch that fails is reported as ````, never as "no posts found":
the two are different claims, and passing a rate-limited fetch off as silence
@@ -23,19 +18,18 @@ from __future__ import annotations
import html
import http.client
-import json
import logging
import random
import re
import time
import xml.etree.ElementTree as ET
from collections.abc import Iterable
-from datetime import datetime, timezone
+from datetime import datetime, timedelta, timezone
from urllib.error import HTTPError
from urllib.parse import urlencode
from urllib.request import Request, urlopen
-from .date_window import in_window
+from .date_window import coverage_gap, in_window
from .symbol_utils import crypto_base
logger = logging.getLogger(__name__)
@@ -51,15 +45,25 @@ def _within_window(posts, start_date, end_date):
return posts
start_dt = datetime.strptime(start_date, "%Y-%m-%d")
end_dt = datetime.strptime(end_date, "%Y-%m-%d")
- kept = []
- for p in posts:
- ts = p.get("created_utc")
- created = datetime.fromtimestamp(ts, tz=timezone.utc) if ts else None
- if in_window(created, start_dt, end_dt):
- kept.append(p)
- return kept
+ return [p for p in posts if in_window(_posted_at(p), start_dt, end_dt)]
+
+
+def _posted_at(post) -> datetime | None:
+ """A post's ``created_utc`` epoch as a UTC datetime, or None when missing."""
+ ts = post.get("created_utc")
+ return datetime.fromtimestamp(ts, tz=timezone.utc) if ts else None
+
+
+def _coverage_dates(posts) -> list:
+ """Dates that bound the feed's coverage. The search is limited to the last
+ week (``t=week``), so the lookback start bounds it even when nothing came
+ back; a full page may have cut older matches off, so then only the posts
+ themselves do."""
+ dates = [_posted_at(p) for p in posts]
+ if len(posts) < _FEED_PAGE:
+ dates.append(datetime.now(timezone.utc) - _SEARCH_LOOKBACK)
+ return dates
-_API = "https://www.reddit.com/r/{sub}/search.json?{qs}"
_RSS = "https://www.reddit.com/r/{sub}/search.rss?{qs}"
# A descriptive, identified User-Agent (per Reddit's API etiquette). Reddit
# blocks generic/anonymous tokens like bare "Mozilla/5.0" or "curl/…" but
@@ -73,6 +77,14 @@ _ATOM_NS = {"atom": "http://www.w3.org/2005/Atom"}
# investing trend more measured. Caller can override.
DEFAULT_SUBREDDITS = ("wallstreetbets", "stocks", "investing")
+# Reddit's maximum page size. A week of posts for a ticker across the default
+# subreddits fits well inside one page, which keeps a high-volume subreddit from
+# crowding the others out of a combined search.
+_FEED_PAGE = 100
+
+
+_SEARCH_LOOKBACK = timedelta(days=7) # matches t=week below
+
def _search_qs(ticker: str, limit: int) -> str:
return urlencode({
@@ -163,8 +175,7 @@ def _fetch_subreddit_rss(
) -> list[dict] | None:
"""Default path: parse the public Atom search feed for a subreddit.
- Carries no score / comment counts, so those fields are left None and the
- post is tagged ``source="rss"`` for honest display. On a 429 (Reddit's
+ ``sub`` may be one subreddit or several joined with ``+``. On a 429 (Reddit's
per-IP rate limit) we back off once — honouring ``Retry-After`` when
present — before giving up, so a transient burst doesn't blank the feed.
@@ -203,79 +214,37 @@ def _fetch_subreddit_rss(
title_el = entry.find("atom:title", _ATOM_NS)
published_el = entry.find("atom:published", _ATOM_NS)
content_el = entry.find("atom:content", _ATOM_NS)
+ category_el = entry.find("atom:category", _ATOM_NS)
posts.append({
"title": (title_el.text if title_el is not None else "") or "",
- "score": None,
- "num_comments": None,
"created_utc": _iso_to_timestamp(
published_el.text if published_el is not None else None
),
"selftext": _strip_html(content_el.text if content_el is not None else ""),
- "source": "rss",
+ # A combined feed names each entry's subreddit; a single-subreddit
+ # feed may omit it, and then it can only be that one.
+ "subreddit": category_el.get("term") if category_el is not None
+ else (sub if "+" not in sub else ""),
})
return posts
-def _fetch_subreddit_json(
- ticker: str,
- sub: str,
- limit: int,
- timeout: float,
-) -> list[dict]:
- """Richer JSON search path (carries score / comment counts).
-
- Reddit's WAF currently returns ``403 Blocked`` on this endpoint for
- non-OAuth clients (issue #862), so it is NOT used by default — calling it on
- every request only doubled our volume against the per-IP rate limit and
- triggered 429s on the RSS fallback. Kept for the day the WAF relaxes or an
- OAuth token is wired in; degrades to RSS on failure.
- """
- url = _API.format(sub=sub, qs=_search_qs(ticker, limit))
- req = Request(url, headers={"User-Agent": _UA, "Accept": "application/json"})
- try:
- with urlopen(req, timeout=timeout) as resp:
- payload = json.loads(_read_capped(resp))
- children = (payload.get("data") or {}).get("children") or []
- return [c.get("data", {}) for c in children if isinstance(c, dict)]
- except (OSError, http.client.HTTPException, json.JSONDecodeError) as exc:
- logger.warning(
- "Reddit JSON fetch failed for r/%s · %s: %s — falling back to RSS feed.",
- sub, ticker, exc,
- )
- return _fetch_subreddit_rss(ticker, sub, limit, timeout)
-
-
-def _fetch_subreddit(
- ticker: str,
- sub: str,
- limit: int,
- timeout: float,
- _retry: bool = True,
-) -> list[dict] | None:
- """Fetch one subreddit, RSS-first. ``None`` means the fetch failed.
-
- The JSON search endpoint is reliably WAF-blocked (403) for public clients,
- so we go straight to the RSS feed — which serves our identified User-Agent
- reliably — halving our request volume against Reddit's per-IP rate limit.
- """
- return _fetch_subreddit_rss(ticker, sub, limit, timeout, _retry=_retry)
-
-
def fetch_reddit_posts(
ticker: str,
subreddits: Iterable[str] = DEFAULT_SUBREDDITS,
+ *,
limit_per_sub: int = 5,
timeout: float = 10.0,
- inter_request_delay: float = 1.0,
start_date: str | None = None,
end_date: str | None = None,
) -> str:
"""Fetch recent Reddit posts mentioning ``ticker`` across finance
subreddits and return them as a formatted plaintext block.
- ``inter_request_delay`` paces the (now RSS-only) per-subreddit requests to
- stay under Reddit's public per-IP rate limit; combined with the RSS-first
- path it makes 429s rare even when several analyses run back-to-back.
+ All subreddits are searched in one combined feed (``r/a+b+c``): anonymous
+ RSS allows about one request per minute per IP, so a request per subreddit
+ spent a back-off on almost every run. Each entry names its subreddit, and
+ posts are grouped back by it.
When ``start_date``/``end_date`` (yyyy-mm-dd) are given, posts are trimmed to
that window so a historical run does not leak current discussion into a
@@ -285,74 +254,50 @@ def fetch_reddit_posts(
# ("BTC") so the query actually matches discussion instead of near-nothing.
ticker = crypto_base(ticker) or ticker
subreddits = list(subreddits)
- blocks = []
- total_posts = 0
- unavailable = []
- allow_retry = True
- for i, sub in enumerate(subreddits):
- if i > 0 and inter_request_delay:
- time.sleep(_jitter(inter_request_delay))
- fetched = _fetch_subreddit(ticker, sub, limit_per_sub, timeout, _retry=allow_retry)
- if fetched is None:
- # A failed fetch is not an absence of discussion, so it must not be
- # rendered as "no posts found" (#1295). One failure also means the
- # per-IP budget is likely gone, so skip the (now 60s) back-off on
- # the remaining subreddits rather than stalling the run on retries
- # that cannot succeed; #1286 tracks coordinating this properly.
- allow_retry = False
- unavailable.append(sub)
- blocks.append(f"r/{sub}: ")
- continue
- posts = _within_window(fetched, start_date, end_date)
- total_posts += len(posts)
- if not posts:
- blocks.append(f"r/{sub}: ")
- continue
+ label = ", ".join(f"r/{s}" for s in subreddits)
+ fetched = _fetch_subreddit_rss(ticker, "+".join(subreddits), _FEED_PAGE, timeout)
+ if fetched is None:
+ return f""
- via_rss = any(p.get("source") == "rss" for p in posts)
- header = f"r/{sub} — {len(posts)} recent posts mentioning {ticker.upper()}"
- header += " (via RSS feed; scores/comments unavailable):" if via_rss else ":"
- lines = [header]
- for p in posts:
- title = (p.get("title") or "").replace("\n", " ").strip()
- score = p.get("score")
- comments = p.get("num_comments")
- created = p.get("created_utc")
- created_str = (
- time.strftime("%Y-%m-%d", time.gmtime(created)) if created else "?"
+ window = bool(start_date and end_date)
+ posts = _within_window(fetched, start_date, end_date)
+ if not posts:
+ gap = window and coverage_gap(
+ _coverage_dates(fetched), start_date, end_date,
+ "Reddit search", f"discussion of {ticker.upper()}",
+ )
+ period = f"within {start_date}..{end_date}" if window else "in the past 7 days"
+ return gap or f""
+
+ # Group by the subreddit each entry names, in the requested order. Nothing
+ # is dropped: an unlabelled post from a one-subreddit request belongs to it,
+ # and any other name gets its own block.
+ by_sub = {s.lower(): (s, []) for s in subreddits}
+ for p in posts:
+ name = p.get("subreddit") or (subreddits[0] if len(subreddits) == 1 else "unknown")
+ by_sub.setdefault(name.lower(), (name, []))[1].append(p)
+
+ page_full = len(fetched) >= _FEED_PAGE
+ blocks = []
+ for sub, sub_posts in by_sub.values():
+ if not sub_posts:
+ blocks.append(
+ f"r/{sub}: "
+ if page_full else f"r/{sub}: "
)
- # Score / comment counts are absent on the RSS fallback path —
- # show them only when present rather than printing fake zeros.
- meta = created_str
- if score is not None and comments is not None:
- meta += f" · {score:>4}↑ · {comments:>3}c"
+ continue
+ sub_posts = sub_posts[:limit_per_sub] # the feed is newest-first
+ lines = [f"r/{sub} — {len(sub_posts)} recent posts mentioning {ticker.upper()}:"]
+ for p in sub_posts:
+ title = (p.get("title") or "").replace("\n", " ").strip()
+ created = p.get("created_utc")
+ created_str = time.strftime("%Y-%m-%d", time.gmtime(created)) if created else "?"
selftext = (p.get("selftext") or "").replace("\n", " ").strip()
if len(selftext) > 240:
selftext = selftext[:240] + "…"
lines.append(
- f" [{meta}] {title}"
+ f" [{created_str}] {title}"
+ (f"\n body excerpt: {selftext}" if selftext else "")
)
blocks.append("\n".join(lines))
-
- if total_posts == 0:
- searched = [s for s in subreddits if s not in unavailable]
- if not searched:
- # Every source failed: claiming "no posts" here would assert a
- # silence we never observed.
- return (
- f""
- )
- summary = (
- f""
- )
- if unavailable:
- summary += (
- f"\n"
- )
- return summary
return "\n\n".join(blocks)
diff --git a/tradingagents/dataflows/sec_edgar.py b/tradingagents/dataflows/sec_edgar.py
new file mode 100644
index 000000000..2999f815d
--- /dev/null
+++ b/tradingagents/dataflows/sec_edgar.py
@@ -0,0 +1,229 @@
+"""Company statements as they were filed, from SEC EDGAR.
+
+Every other fundamentals vendor serves a period's current value and cuts the
+statement at the fiscal period end. That is two claims a run should not make: a
+period that has ended is not public until the company files, weeks later, and a
+figure that was later restated is not what investors saw at the time.
+
+EDGAR reports every fact with the date it was filed, so a run dated ``curr_date``
+serves exactly what was on file by then, restatements included at the vintage
+that was current: Apple's 2008 total assets read 39.6B until the 2010 amendment
+restated them to 36.2B.
+
+Access needs no key or account, only a User-Agent identifying the caller, which
+SEC requires and refuses requests without. US filers only: anything absent from
+EDGAR's ticker map falls through to the next configured vendor.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import time
+from datetime import date, datetime
+from importlib import metadata
+from pathlib import Path
+
+import requests
+
+from .config import get_config
+from .errors import NoMarketDataError, VendorRateLimitError
+
+logger = logging.getLogger(__name__)
+
+_TICKERS_URL = "https://www.sec.gov/files/company_tickers.json"
+_FACTS_URL = "https://data.sec.gov/api/xbrl/companyfacts/CIK{cik}.json"
+
+# A filing history only changes when something new is filed, so one fetch per
+# company per day serves every date a run asks about.
+_CACHE_TTL_SECONDS = 24 * 60 * 60
+
+# Line items, each with the tags filers use for it, best first. First match wins
+# and values are never summed across tags: a company reporting revenue under two
+# tags would otherwise be counted twice.
+_STATEMENTS: dict[str, list[tuple[str, tuple[str, ...]]]] = {
+ "balance_sheet": [
+ ("Total Assets", ("Assets",)),
+ ("Current Assets", ("AssetsCurrent",)),
+ ("Cash and Equivalents", ("CashAndCashEquivalentsAtCarryingValue",)),
+ ("Total Liabilities", ("Liabilities",)),
+ ("Current Liabilities", ("LiabilitiesCurrent",)),
+ ("Stockholders Equity", ("StockholdersEquity",
+ "StockholdersEquityIncludingPortionAttributableToNoncontrollingInterest")),
+ ],
+ "income_statement": [
+ ("Revenue", ("RevenueFromContractWithCustomerExcludingAssessedTax", "Revenues",
+ "SalesRevenueNet")),
+ ("Cost of Revenue", ("CostOfRevenue", "CostOfGoodsAndServicesSold")),
+ ("Gross Profit", ("GrossProfit",)),
+ ("Operating Income", ("OperatingIncomeLoss",)),
+ ("Net Income", ("NetIncomeLoss",)),
+ ("Diluted EPS", ("EarningsPerShareDiluted",)),
+ ],
+ "cashflow": [
+ ("Operating Cash Flow", ("NetCashProvidedByUsedInOperatingActivities",
+ "NetCashProvidedByUsedInOperatingActivitiesContinuingOperations")),
+ ("Investing Cash Flow", ("NetCashProvidedByUsedInInvestingActivities",)),
+ ("Financing Cash Flow", ("NetCashProvidedByUsedInFinancingActivities",)),
+ ("Capital Expenditure", ("PaymentsToAcquirePropertyPlantAndEquipment",)),
+ ],
+}
+
+# A statement's figures cover a span: a quarter is about 90 days, a year about
+# 365. One filing reports both the quarter and the year to date under the same
+# end date, so a match on the end date alone can report half a year as a quarter.
+_SPANS = {"quarterly": (60, 115), "annual": (300, 400)}
+
+
+def _user_agent() -> str:
+ """Who SEC sees. No account or key exists; callers identify themselves.
+
+ www.sec.gov, which serves the ticker map, refuses a User-Agent carrying no
+ contact address: a client name alone or with a project URL gets 403, one
+ with an address gets 200. So the default carries a placeholder address and
+ the package version. Set SEC_EDGAR_USER_AGENT to your own name and address
+ so SEC can reach you about your traffic rather than the project.
+ """
+ configured = os.getenv("SEC_EDGAR_USER_AGENT", "").strip()
+ return configured or f"TradingAgents/{_version()} (contact@example.com)"
+
+
+def _version() -> str:
+ """The installed package version, so a release identifies itself correctly."""
+ try:
+ return metadata.version("tradingagents")
+ except metadata.PackageNotFoundError:
+ return "dev"
+
+
+def _fetch_json(url: str) -> dict:
+ """Read a public EDGAR document, respecting SEC's identification rule."""
+ try:
+ response = requests.get(url, headers={"User-Agent": _user_agent()}, timeout=30)
+ response.raise_for_status()
+ return response.json()
+ except requests.RequestException as exc:
+ status = getattr(getattr(exc, "response", None), "status_code", None)
+ # Every failure here is "this vendor cannot serve it now", so the router
+ # moves on instead of seeing a transport exception it has no rule for.
+ raise VendorRateLimitError(f"SEC EDGAR request failed ({status or type(exc).__name__})") from exc
+ except ValueError as exc:
+ raise VendorRateLimitError("SEC EDGAR returned an unreadable response") from exc
+
+
+def _cached_json(url: str, name: str) -> dict:
+ path = Path(get_config()["data_cache_dir"]) / "sec_edgar" / name
+ if path.exists() and time.time() - path.stat().st_mtime < _CACHE_TTL_SECONDS:
+ try:
+ return json.loads(path.read_text(encoding="utf-8"))
+ except ValueError:
+ pass # a truncated file is a miss, not a failure
+ data = _fetch_json(url)
+ path.parent.mkdir(parents=True, exist_ok=True)
+ temp = path.with_suffix(".tmp")
+ temp.write_text(json.dumps(data), encoding="utf-8")
+ os.replace(temp, path)
+ return data
+
+
+def cik_for(ticker: str) -> str | None:
+ """The filer's CIK, or None when the ticker is not a US filer."""
+ table = _cached_json(_TICKERS_URL, "company_tickers.json")
+ wanted = ticker.strip().upper()
+ for entry in table.values():
+ if entry.get("ticker", "").upper() == wanted:
+ return f"{int(entry['cik_str']):010d}"
+ return None
+
+
+def _as_of(facts: dict, tags: tuple[str, ...], curr_date: str, span: tuple[int, int]) -> tuple[dict, str]:
+ """({period end: value}, unit) for the first tag the filer reports, as known then.
+
+ A period reported more than once takes its latest filing on or before the
+ date, so an amendment counts from the day it was filed and not before. The
+ unit comes from the filing: most lines are USD, earnings per share are
+ USD/shares, and scaling those alike would print a real figure as zero.
+ """
+ low, high = span
+ values: dict[str, float] = {}
+ chosen_unit = "USD"
+ # Tags are tried in order and a period keeps the first one that reports it:
+ # filers renamed lines over the years, so one tag covers only part of the
+ # history. Values are never added across tags, which would double count.
+ for tag in tags:
+ for unit, unit_values in ((facts.get(tag) or {}).get("units", {})).items():
+ latest: dict[str, dict] = {}
+ for fact in unit_values:
+ if fact["filed"] > curr_date or fact["end"] in values:
+ continue
+ # A duration fact (revenue, cash flow) must cover the span asked
+ # for. An instant fact (a balance) has no span and serves both.
+ if "start" in fact:
+ days = (date.fromisoformat(fact["end"]) - date.fromisoformat(fact["start"])).days
+ if not low <= days <= high:
+ continue
+ seen = latest.get(fact["end"])
+ if seen is None or fact["filed"] >= seen["filed"]:
+ latest[fact["end"]] = fact
+ if latest:
+ chosen_unit = unit
+ values.update({end: fact["val"] for end, fact in latest.items()})
+ return dict(sorted(values.items())), chosen_unit
+
+
+def _statement(kind: str, ticker: str, freq: str, curr_date: str, title: str) -> str:
+ curr_date = curr_date or datetime.now().strftime("%Y-%m-%d")
+ cik = cik_for(ticker)
+ if cik is None:
+ raise NoMarketDataError(ticker, ticker, "not a US SEC filer")
+
+ facts = _cached_json(_FACTS_URL.format(cik=cik), f"CIK{cik}.json")
+ us_gaap = (facts.get("facts") or {}).get("us-gaap")
+ if not us_gaap:
+ raise NoMarketDataError(ticker, ticker, "US filer with no us-gaap facts")
+
+ span = _SPANS["quarterly" if freq.lower() == "quarterly" else "annual"]
+ lines = {label: _as_of(us_gaap, tags, curr_date, span) for label, tags in _STATEMENTS[kind]}
+ periods = sorted({end for values, _ in lines.values() for end in values})
+ if not periods:
+ raise NoMarketDataError(ticker, ticker, f"no {freq} {title.lower()} filed by {curr_date}")
+
+ header = (
+ f"# {title} for {ticker.upper()} ({freq}), USD in millions unless the row says otherwise\n"
+ f"# SEC EDGAR facts filed on or before {curr_date}, at the values filed then\n\n"
+ )
+ rows = [",".join([""] + periods)]
+ for label, (values, unit) in lines.items():
+ # Every row spans the same columns, or a reader lines the table up wrong.
+ if not values:
+ rows.append(",".join([label] + ["unavailable (not tagged by this filer)"] * len(periods)))
+ continue
+ name = label if unit == "USD" else f"{label} ({unit})"
+ # Plain numbers: a thousands separator would split the CSV field.
+ cells = [
+ (f"{values[p] / 1e6:.0f}" if unit == "USD" else f"{values[p]:.2f}")
+ if p in values else "" for p in periods
+ ]
+ rows.append(",".join([name] + cells))
+ return header + "\n".join(rows) + "\n"
+
+
+def get_balance_sheet(ticker: str, freq: str = "quarterly", curr_date: str | None = None) -> str:
+ """Balance sheet as filed on or before ``curr_date``."""
+ return _statement("balance_sheet", ticker, freq, curr_date, "Balance Sheet")
+
+
+def get_income_statement(ticker: str, freq: str = "quarterly", curr_date: str | None = None) -> str:
+ """Income statement as filed on or before ``curr_date``.
+
+ A fourth quarter is never derived: filers report it only inside the annual
+ figure, and subtracting three separately filed quarters would invent a number
+ with no filing date behind it.
+ """
+ return _statement("income_statement", ticker, freq, curr_date, "Income Statement")
+
+
+def get_cashflow(ticker: str, freq: str = "quarterly", curr_date: str | None = None) -> str:
+ """Cash flow statement as filed on or before ``curr_date``."""
+ return _statement("cashflow", ticker, freq, curr_date, "Cash Flow Statement")
diff --git a/tradingagents/dataflows/stockstats_utils.py b/tradingagents/dataflows/stockstats_utils.py
index 1bdd02ab8..5625f2e08 100644
--- a/tradingagents/dataflows/stockstats_utils.py
+++ b/tradingagents/dataflows/stockstats_utils.py
@@ -9,11 +9,14 @@ from stockstats import wrap
from yfinance.exceptions import YFRateLimitError
from .config import get_config
+from .errors import VendorRateLimitError
from .symbol_utils import NoMarketDataError, normalize_symbol
-from .utils import safe_ticker_component
+from .utils import safe_ticker_component, vendor_reachable
logger = logging.getLogger(__name__)
+_YAHOO_HOST = "https://query2.finance.yahoo.com"
+
# A vendor's latest OHLCV row this many calendar days before the requested date
# is treated as stale. Generous enough to span long holiday weekends, tight
# enough to catch the year-old frames yfinance occasionally returns (#1021).
@@ -26,6 +29,17 @@ MAX_OHLCV_STALE_DAYS = 10
OHLCV_CACHE_TTL_SECONDS = 900
+def raise_for_empty(symbol: str, canonical: str, what: str) -> None:
+ """Report an empty Yahoo result as an absence, or as an outage if it is one.
+
+ yfinance returns an empty frame for a failed request rather than raising, so
+ without this a Yahoo outage reads as "this symbol has no {what}".
+ """
+ if not vendor_reachable(_YAHOO_HOST):
+ raise VendorRateLimitError(f"Yahoo Finance is unreachable; no {what} was retrieved")
+ raise NoMarketDataError(symbol, canonical, f"no {what}")
+
+
def yf_retry(func, max_retries=3, base_delay=2.0):
"""Execute a yfinance call with exponential backoff on rate limits.
@@ -164,29 +178,31 @@ def _assert_ohlcv_not_stale(
)
-def _needs_same_day_refresh(data_file, curr_date_dt, today_date) -> bool:
- """Whether a cached frame must be refetched to reflect the requested day.
+def _cache_is_fresh(data_file, curr_date_dt, now) -> bool:
+ """Whether the symbol's cached download can serve this request.
- The cache file is keyed per day, so without this a run started before the
- day's bar was final keeps serving that snapshot to every later run (#1150).
- Two distinct staleness cases exist for a current-day request: the bar may be
- missing entirely, or present but still in progress — Yahoo publishes a
- partial daily candle during market hours, whose ``Close`` is not the closing
- price. Row inspection cannot tell a partial bar from a final one, so the TTL
- governs every current-day cache. Historical requests always reuse the cache,
- since those rows are immutable.
+ The file holds the download made on the day it was written, so it serves
+ only that day. A current-day request also refetches once the file is older
+ than the TTL: Yahoo publishes a partial daily candle during market hours,
+ whose ``Close`` is not the closing price, and row inspection cannot tell it
+ from a final one (#1150).
"""
- if curr_date_dt.date() < today_date.date():
+ written = pd.Timestamp.fromtimestamp(os.path.getmtime(data_file))
+ if written.date() != now.date():
return False
- return time.time() - os.path.getmtime(data_file) > OHLCV_CACHE_TTL_SECONDS
+ return curr_date_dt.date() < now.date() or (now - written).total_seconds() <= OHLCV_CACHE_TTL_SECONDS
-def load_ohlcv(symbol: str, curr_date: str) -> pd.DataFrame:
+def load_ohlcv(symbol: str, curr_date: str, fill_gaps: bool = True) -> pd.DataFrame:
"""Fetch OHLCV data with caching, filtered to prevent look-ahead bias.
Downloads 5 years of data up to today and caches per symbol. On
subsequent calls the cache is reused. Rows after curr_date are
filtered out so backtests never see future prices.
+
+ ``fill_gaps`` carries prices forward over gaps so indicators compute on a
+ continuous series. Pass ``False`` to read the values as the vendor reported
+ them, leaving a cell that was never reported empty.
"""
# Resolve broker/forex symbols (XAUUSD+ -> GC=F) to Yahoo's convention,
# then reject values that would escape the cache directory when
@@ -197,19 +213,19 @@ def load_ohlcv(symbol: str, curr_date: str) -> pd.DataFrame:
config = get_config()
curr_date_dt = pd.to_datetime(curr_date).normalize()
- # Cache uses a fixed window (5y to today) so one file per symbol.
- today_date = pd.Timestamp.today()
- start_date = today_date - pd.DateOffset(years=5)
+ # One cache file per symbol, holding the latest 5y-to-today download.
+ now = pd.Timestamp.today()
+ start_date = now - pd.DateOffset(years=5)
start_str = start_date.strftime("%Y-%m-%d")
# yfinance ``end`` is EXCLUSIVE; request tomorrow so today's row is included
# when curr_date is the current day (#986). Look-ahead is still prevented by
# the curr_date filter below.
- end_str = (today_date + pd.Timedelta(days=1)).strftime("%Y-%m-%d")
+ end_str = (now + pd.Timedelta(days=1)).strftime("%Y-%m-%d")
os.makedirs(config["data_cache_dir"], exist_ok=True)
data_file = os.path.join(
config["data_cache_dir"],
- f"{safe_symbol}-YFin-data-{start_str}-{end_str}.csv",
+ f"{safe_symbol}-YFin-data.csv",
)
# A cached file may be empty if a prior fetch failed (unknown symbol,
@@ -218,12 +234,10 @@ def load_ohlcv(symbol: str, curr_date: str) -> pd.DataFrame:
data = None
if os.path.exists(data_file):
cached = pd.read_csv(data_file, on_bad_lines="skip", encoding="utf-8")
- # Serve the cache only when it is usable and not a stale snapshot of the
- # day being requested (#1150); otherwise fall through and refetch.
if (
not cached.empty
and "Close" in cached.columns
- and not _needs_same_day_refresh(data_file, curr_date_dt, today_date)
+ and _cache_is_fresh(data_file, curr_date_dt, now)
):
data = cached
@@ -239,9 +253,7 @@ def load_ohlcv(symbol: str, curr_date: str) -> pd.DataFrame:
downloaded = _ensure_date_column(downloaded.reset_index())
# Only cache real data — never persist an empty frame.
if downloaded.empty or "Close" not in downloaded.columns:
- raise NoMarketDataError(
- symbol, canonical, "Yahoo Finance returned no rows"
- )
+ raise_for_empty(symbol, canonical, "price rows")
downloaded.to_csv(data_file, index=False, encoding="utf-8")
data = downloaded
@@ -266,7 +278,10 @@ def load_ohlcv(symbol: str, curr_date: str) -> pd.DataFrame:
data["Date"].iloc[-1].date(), data["Date"].iloc[settled[-1]].date(),
)
- data = _fill_price_gaps(data)
+ # Indicators need a continuous series, so gaps are carried forward. A caller
+ # that reports the numbers themselves asks for the frame as it was reported:
+ # a filled cell is the previous session's price under this session's date.
+ data = _fill_price_gaps(data) if fill_gaps else data.dropna(subset=["Close"]).copy()
# Reject a stale frame (latest row far older than curr_date) rather than
# feeding year-old prices into indicators (#1021).
diff --git a/tradingagents/dataflows/stocktwits.py b/tradingagents/dataflows/stocktwits.py
index dbf1457bd..49700c9ae 100644
--- a/tradingagents/dataflows/stocktwits.py
+++ b/tradingagents/dataflows/stocktwits.py
@@ -21,7 +21,7 @@ import logging
from datetime import datetime
from urllib.request import Request, urlopen
-from .date_window import in_window
+from .date_window import coverage_gap, in_window
from .symbol_utils import crypto_base
logger = logging.getLogger(__name__)
@@ -30,6 +30,16 @@ _API = "https://api.stocktwits.com/api/2/streams/symbol/{ticker}.json"
_UA = "tradingagents/0.2 (+https://github.com/TauricResearch/TradingAgents)"
+def _created_at(message) -> datetime | None:
+ """Parse a message's ISO 8601 ``created_at``; None when missing or malformed."""
+ raw = message.get("created_at")
+ if not raw:
+ return None
+ with contextlib.suppress(ValueError, TypeError):
+ return datetime.fromisoformat(str(raw).replace("Z", "+00:00"))
+ return None
+
+
def _within_window(messages, start_date, end_date):
"""Keep only messages published in [start_date, end_date] (look-ahead safe).
@@ -41,16 +51,7 @@ def _within_window(messages, start_date, end_date):
return messages
start_dt = datetime.strptime(start_date, "%Y-%m-%d")
end_dt = datetime.strptime(end_date, "%Y-%m-%d")
- kept = []
- for m in messages:
- created = None
- raw = m.get("created_at")
- if raw:
- with contextlib.suppress(ValueError, TypeError):
- created = datetime.fromisoformat(str(raw).replace("Z", "+00:00"))
- if in_window(created, start_dt, end_dt):
- kept.append(m)
- return kept
+ return [m for m in messages if in_window(_created_at(m), start_dt, end_dt)]
def _stocktwits_symbol(ticker: str) -> str:
@@ -75,9 +76,9 @@ def fetch_stocktwits_messages(
formatted plaintext block ready for prompt injection.
When ``start_date``/``end_date`` (yyyy-mm-dd) are given, messages are trimmed
- to that window. The StockTwits public stream only serves recent messages, so
- for a historical run they all fall after the window and a clear placeholder
- is returned rather than leaking today's chatter into a backtest (#1220).
+ to that window, so a historical run never sees today's chatter (#1220). The
+ public stream only serves recent messages, so a window it cannot reach is
+ reported as unavailable rather than as silence.
Returns a placeholder string when the endpoint is unreachable, the
symbol has no messages, or the response shape is unexpected — the
@@ -94,13 +95,17 @@ def fetch_stocktwits_messages(
logger.warning("StockTwits fetch failed for %s: %s", ticker, exc)
return f""
- messages = data.get("messages", []) if isinstance(data, dict) else []
- messages = _within_window(messages, start_date, end_date)
+ fetched = data.get("messages", []) if isinstance(data, dict) else []
+ messages = _within_window(fetched, start_date, end_date)
if not messages:
if start_date and end_date:
- return (
+ gap = coverage_gap(
+ (_created_at(m) for m in fetched), start_date, end_date,
+ "StockTwits", f"messages about ${ticker.upper()}",
+ )
+ return gap or (
f""
+ f"{start_date}..{end_date}>"
)
return f""
diff --git a/tradingagents/dataflows/symbol_utils.py b/tradingagents/dataflows/symbol_utils.py
index f91b4e149..647f50444 100644
--- a/tradingagents/dataflows/symbol_utils.py
+++ b/tradingagents/dataflows/symbol_utils.py
@@ -10,6 +10,8 @@ differ from the broker / TradingView / MT5 style symbols users often type:
EURUSD EURUSD=X spot forex pairs take a ``=X`` suffix
BTCUSD BTC-USD crypto pairs use a ``-`` separator
SPX500, US500 ^GSPC index CFDs map to Yahoo index symbols
+ 09992.HK, 700.HK 9992.HK, 0700.HK HK codes are zero-padded to 4 digits
+ 600519.SH 600519.SS Yahoo spells Shanghai ``.SS``
Passing the raw broker symbol to Yahoo returns an empty result, which the
agents previously received as free text and could hallucinate a price
@@ -72,6 +74,10 @@ _ALIASES = {
# Yahoo symbols may contain letters, digits, and these structural characters.
_YAHOO_SAFE = re.compile(r"^[A-Za-z0-9._\-\^=]+$")
+# HKEX codes as Yahoo spells them: the number zero-padded to 4 digits (#957).
+_HK_CODE = re.compile(r"^(\d{1,5})\.HK$")
+_SHANGHAI_SH = re.compile(r"^(\d{6})\.SH$")
+
# Crypto quote currencies that all map to Yahoo's USD pair. Yahoo lists only
# ``-USD`` (not the USDT/USDC stablecoin pairs), so a broker symbol quoted
@@ -109,7 +115,10 @@ def normalize_symbol(raw: str) -> str:
2. Crypto rule: a known crypto base quoted in USD/USDT/USDC (dashed or
not) -> ``BASE-USD``.
3. Forex rule: six letters that are two ISO currency codes -> ``PAIR=X``.
- 4. Otherwise the upper-cased symbol is returned unchanged (plain
+ 4. HK rule: a numeric ``.HK`` code -> Yahoo's 4-digit padding
+ (``09992.HK`` -> ``9992.HK``, ``700.HK`` -> ``0700.HK``).
+ 5. Shanghai rule: ``600519.SH`` -> ``600519.SS``.
+ 6. Otherwise the upper-cased symbol is returned unchanged (plain
equities, ETFs, Yahoo-native symbols like ``GC=F`` or ``^GSPC``).
A trailing ``+`` (broker CFD marker, e.g. ``XAUUSD+``) is stripped before
@@ -130,6 +139,10 @@ def normalize_symbol(raw: str) -> str:
canonical = crypto
elif len(s) == 6 and s[:3] in _FOREX_CURRENCIES and s[3:] in _FOREX_CURRENCIES:
canonical = f"{s}=X"
+ elif hk := _HK_CODE.match(s):
+ canonical = f"{int(hk.group(1)):04d}.HK"
+ elif sh := _SHANGHAI_SH.match(s):
+ canonical = f"{sh.group(1)}.SS"
else:
canonical = s
diff --git a/tradingagents/dataflows/utils.py b/tradingagents/dataflows/utils.py
index 71806b47f..1bff0273c 100644
--- a/tradingagents/dataflows/utils.py
+++ b/tradingagents/dataflows/utils.py
@@ -1,6 +1,8 @@
import re
from datetime import date
+import requests
+
# Tickers can contain letters, digits, dot, dash, underscore, caret
# (index symbols like ^GSPC), equals (futures like GC=F), and plus
# (forex/CFD symbols like XAUUSD+). None of these enable directory
@@ -39,3 +41,37 @@ def safe_ticker_component(value: str, *, max_len: int = 32) -> str:
def get_current_date():
return date.today().strftime("%Y-%m-%d")
+
+
+def get_scrubbed(url: str, *, params: dict, timeout: float, secret: str, passthrough=()):
+ """``requests.get`` plus ``raise_for_status``, with ``secret`` kept out of errors.
+
+ Vendors that authenticate with a query parameter put the key in the URL, and
+ requests quotes the full URL in HTTP, connection and timeout errors, so any
+ log or traceback that records one would carry the key (#1324). A requests
+ error is re-raised as the same class with the key replaced and nothing
+ attached: no request or response (both hold the URL) and no exception chain,
+ which is why this raises after the ``except`` block rather than inside it.
+ Statuses in ``passthrough`` are returned for the caller to handle.
+ """
+ try:
+ response = requests.get(url, params=params, timeout=timeout)
+ if response.status_code not in passthrough:
+ response.raise_for_status()
+ return response
+ except requests.RequestException as exc:
+ error = type(exc)(str(exc).replace(secret, "***")) if secret else exc
+ raise error
+
+
+def vendor_reachable(url: str, timeout: float = 5.0) -> bool:
+ """Whether the vendor answers at all, for telling silence from an outage.
+
+ A client that returns an empty result instead of raising leaves those two
+ cases indistinguishable. Called only when a result is empty.
+ """
+ try:
+ requests.head(url, timeout=timeout, allow_redirects=True)
+ return True
+ except requests.RequestException:
+ return False
diff --git a/tradingagents/dataflows/y_finance.py b/tradingagents/dataflows/y_finance.py
index 9e67ac591..c2f24f35d 100644
--- a/tradingagents/dataflows/y_finance.py
+++ b/tradingagents/dataflows/y_finance.py
@@ -7,14 +7,19 @@ import yfinance as yf
from dateutil.relativedelta import relativedelta
from .date_window import withhold_live_profile
+from .errors import VendorError, VendorRateLimitError
from .stockstats_utils import (
StockstatsUtils,
_assert_ohlcv_not_stale,
filter_financials_by_date,
load_ohlcv,
+ raise_for_empty,
yf_retry,
)
from .symbol_utils import NoMarketDataError, normalize_symbol
+from .utils import vendor_reachable
+
+_YAHOO_HOST = "https://query2.finance.yahoo.com"
logger = logging.getLogger(__name__)
@@ -42,9 +47,7 @@ def get_YFin_data_online(
# instead of returning prose: the routing layer turns it into a single
# unambiguous "no data" signal so the agent never fabricates a price.
if data.empty:
- raise NoMarketDataError(
- symbol, canonical, f"no rows between {start_date} and {end_date}"
- )
+ raise_for_empty(symbol, canonical, f"rows between {start_date} and {end_date}")
# Remove timezone info from index for cleaner output
if data.index.tz is not None:
@@ -189,7 +192,7 @@ def get_stock_stats_indicators_window(
for date_str, value in date_values:
ind_string += f"{date_str}: {value}\n"
- except NoMarketDataError:
+ except VendorError:
raise # Unknown/delisted symbol — let the router emit the sentinel
except Exception as e:
logger.warning("Bulk stockstats fetch failed, falling back per-day: %s", e)
@@ -264,11 +267,15 @@ def get_stockstats_indicator(
indicator,
curr_date,
)
- except NoMarketDataError:
+ except VendorError:
raise # Unknown/delisted symbol — let the router emit the sentinel
except Exception as e:
- logger.warning("Stockstats indicator %s failed on %s: %s", indicator, curr_date, e)
- return ""
+ # An empty string renders as "2026-05-08: " in the indicator table, which
+ # reads as no value that day rather than a read that failed. Raise so the
+ # router can try the next vendor or report the series unavailable.
+ raise NoMarketDataError(
+ symbol, symbol, f"{indicator} could not be read for {curr_date}: {e}"
+ ) from e
return str(indicator_value)
@@ -296,7 +303,7 @@ def get_fundamentals(
info = yf_retry(lambda: ticker_obj.info)
if not info:
- raise NoMarketDataError(ticker, canonical, "no fundamentals returned")
+ raise_for_empty(ticker, canonical, "fundamentals")
fields = [
("Name", info.get("longName")),
@@ -343,10 +350,10 @@ def get_fundamentals(
return header + "\n".join(lines)
- except NoMarketDataError:
+ except VendorError:
raise
except Exception as e:
- return f"Error retrieving fundamentals for {ticker}: {str(e)}"
+ raise NoMarketDataError(ticker, canonical, f"fundamentals unavailable: {e}") from e
def get_balance_sheet(
@@ -367,21 +374,22 @@ def get_balance_sheet(
data = filter_financials_by_date(data, curr_date)
if data.empty:
- raise NoMarketDataError(ticker, canonical, "no balance sheet data")
+ raise_for_empty(ticker, canonical, "balance sheet data")
# Convert to CSV string for consistency with other functions
csv_string = data.to_csv()
# Add header information
header = f"# Balance Sheet data for {canonical} ({freq})\n"
- header += f"# Data retrieved on: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n\n"
+ header += f"# Data retrieved on: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n"
+ header += _PERIOD_END_VINTAGE
return header + csv_string
- except NoMarketDataError:
+ except VendorError:
raise
except Exception as e:
- return f"Error retrieving balance sheet for {ticker}: {str(e)}"
+ raise NoMarketDataError(ticker, canonical, f"balance sheet unavailable: {e}") from e
def get_cashflow(
@@ -402,21 +410,22 @@ def get_cashflow(
data = filter_financials_by_date(data, curr_date)
if data.empty:
- raise NoMarketDataError(ticker, canonical, "no cash flow data")
+ raise_for_empty(ticker, canonical, "cash flow data")
# Convert to CSV string for consistency with other functions
csv_string = data.to_csv()
# Add header information
header = f"# Cash Flow data for {canonical} ({freq})\n"
- header += f"# Data retrieved on: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n\n"
+ header += f"# Data retrieved on: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n"
+ header += _PERIOD_END_VINTAGE
return header + csv_string
- except NoMarketDataError:
+ except VendorError:
raise
except Exception as e:
- return f"Error retrieving cash flow for {ticker}: {str(e)}"
+ raise NoMarketDataError(ticker, canonical, f"cash flow unavailable: {e}") from e
def get_income_statement(
@@ -437,25 +446,49 @@ def get_income_statement(
data = filter_financials_by_date(data, curr_date)
if data.empty:
- raise NoMarketDataError(ticker, canonical, "no income statement data")
+ raise_for_empty(ticker, canonical, "income statement data")
# Convert to CSV string for consistency with other functions
csv_string = data.to_csv()
# Add header information
header = f"# Income Statement data for {canonical} ({freq})\n"
- header += f"# Data retrieved on: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n\n"
+ header += f"# Data retrieved on: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n"
+ header += _PERIOD_END_VINTAGE
return header + csv_string
- except NoMarketDataError:
+ except VendorError:
raise
except Exception as e:
- return f"Error retrieving income statement for {ticker}: {str(e)}"
+ raise NoMarketDataError(ticker, canonical, f"income statement unavailable: {e}") from e
+
+
+# Rows are dated by the transaction, which is when the insider traded, not when
+# the market learned of it: a Form 4 is filed up to two business days later and
+# this vendor reports no filing date, so the most recent rows may not have been
+# public on the analysis date.
+_TRANSACTION_DATE_VINTAGE = (
+ "# Rows are dated by transaction date. A trade becomes public when its Form 4 "
+ "is filed, up to two business days later, so the newest rows may not have been "
+ "known on this date.\n\n"
+)
+
+
+# This vendor dates a statement by the period it covers, not by the day it was
+# filed, and carries no filing date to do better. A company files weeks after its
+# period ends, so a run dated in that gap can be served figures that were not yet
+# public. Say so rather than implying the stricter guarantee (SEC EDGAR, which
+# does carry filing dates, serves US filers as filed).
+_PERIOD_END_VINTAGE = (
+ "# Periods are cut at the fiscal period end; this vendor does not report "
+ "filing dates, so the most recent period may not have been published yet.\n\n"
+)
def get_insider_transactions(
- ticker: Annotated[str, "ticker symbol of the company"]
+ ticker: Annotated[str, "ticker symbol of the company"],
+ curr_date: Annotated[str | None, "only transactions on or before this date, yyyy-mm-dd"] = None,
):
"""Get insider transactions data from yfinance."""
canonical = normalize_symbol(ticker)
@@ -466,16 +499,29 @@ def get_insider_transactions(
# Empty is normal here (many valid symbols have no insider filings),
# so report it plainly rather than treating the symbol as invalid.
if data is None or data.empty:
+ if not vendor_reachable(_YAHOO_HOST):
+ raise VendorRateLimitError("Yahoo Finance is unreachable; insider filings were not retrieved")
return f"No insider transactions reported for symbol '{canonical}'"
+ if curr_date:
+ traded = data["Start Date"]
+ kept = data[traded <= pd.Timestamp(curr_date)]
+ if kept.empty:
+ return (
+ f""
+ )
+ data = kept
+
# Convert to CSV string for consistency with other functions
csv_string = data.to_csv()
# Add header information
header = f"# Insider Transactions data for {canonical}\n"
- header += f"# Data retrieved on: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n\n"
+ header += f"# Data retrieved on: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n"
+ header += _TRANSACTION_DATE_VINTAGE
return header + csv_string
except Exception as e:
- return f"Error retrieving insider transactions for {ticker}: {str(e)}"
+ raise NoMarketDataError(ticker, canonical, f"insider transactions unavailable: {e}") from e
diff --git a/tradingagents/dataflows/yfinance_news.py b/tradingagents/dataflows/yfinance_news.py
index 9891d7947..3b2efce51 100644
--- a/tradingagents/dataflows/yfinance_news.py
+++ b/tradingagents/dataflows/yfinance_news.py
@@ -7,7 +7,8 @@ import yfinance as yf
from dateutil.relativedelta import relativedelta
from .config import get_config
-from .date_window import in_window
+from .date_window import coverage_gap, in_window
+from .errors import NoMarketDataError
from .stockstats_utils import yf_retry
from .symbol_utils import normalize_symbol
@@ -84,10 +85,7 @@ def get_news_yfinance(
resolved = "" if canonical == ticker else f" (resolved to {canonical})"
try:
stock = yf.Ticker(canonical)
- news = yf_retry(lambda: stock.get_news(count=article_limit))
-
- if not news:
- return f"No news found for {ticker}{resolved}"
+ news = yf_retry(lambda: stock.get_news(count=article_limit)) or []
# Parse date range for filtering
start_dt = datetime.strptime(start_date, "%Y-%m-%d")
@@ -112,12 +110,16 @@ def get_news_yfinance(
filtered_count += 1
if filtered_count == 0:
- return f"No news found for {ticker}{resolved} between {start_date} and {end_date}"
+ gap = coverage_gap(
+ (_extract_article_data(a)["pub_date"] for a in news),
+ start_date, end_date, "Yahoo Finance news", f"news for {ticker}{resolved}",
+ )
+ return gap or f"No news found for {ticker}{resolved} between {start_date} and {end_date}"
return f"## {ticker}{resolved} News, from {start_date} to {end_date}:\n\n{news_str}"
except Exception as e:
- return f"Error fetching news for {ticker}: {str(e)}"
+ raise NoMarketDataError(ticker, ticker, f"news unavailable: {e}") from e
def get_global_news_yfinance(
@@ -145,7 +147,11 @@ def get_global_news_yfinance(
limit = config["global_news_article_limit"]
search_queries = config["global_news_queries"]
- all_news = []
+ curr_dt = datetime.strptime(curr_date, "%Y-%m-%d")
+ start_dt = curr_dt - relativedelta(days=look_back_days)
+ start_date = start_dt.strftime("%Y-%m-%d")
+
+ in_window_news = []
seen_titles = set()
try:
@@ -156,53 +162,39 @@ def get_global_news_yfinance(
enable_fuzzy_query=True,
))
- if search.news:
- for article in search.news:
- # Handle both flat and nested structures
- if "content" in article:
- data = _extract_article_data(article)
- title = data["title"]
- else:
- title = article.get("title", "")
+ for article in search.news or []:
+ # Window first: the limit counts what the run may read, so an
+ # out-of-window article must not spend the budget or cut the
+ # remaining searches short (#1356). Flat articles are filtered
+ # on the same rule, so none can leak future news (#1007).
+ data = _extract_article_data(article)
+ if not in_window(data["pub_date"], start_dt, curr_dt):
+ continue
+ if data["title"] and data["title"] not in seen_titles:
+ seen_titles.add(data["title"])
+ in_window_news.append(data)
- # Deduplicate by title
- if title and title not in seen_titles:
- seen_titles.add(title)
- all_news.append(article)
-
- if len(all_news) >= limit:
+ if len(in_window_news) >= limit:
break
- if not all_news:
- return f"No global news found for {curr_date}"
-
- # Calculate date range
- curr_dt = datetime.strptime(curr_date, "%Y-%m-%d")
- start_dt = curr_dt - relativedelta(days=look_back_days)
- start_date = start_dt.strftime("%Y-%m-%d")
-
news_str = ""
- kept = 0
- for article in all_news[:limit]:
- # Extract uniformly (flat + nested) and apply the same look-ahead-safe
- # window filter, so flat articles can't leak future news (#1007).
- data = _extract_article_data(article)
- if not in_window(data["pub_date"], start_dt, curr_dt):
- continue
+ for data in in_window_news[:limit]:
news_str += f"### {data['title']} (source: {data['publisher']})\n"
if data["summary"]:
news_str += f"{data['summary']}\n"
if data["link"]:
news_str += f"Link: {data['link']}\n"
news_str += "\n"
- kept += 1
- # All candidates fell outside the window -> say so rather than return an
+ # Nothing fell inside the window -> say so rather than return an
# empty-bodied report (#993).
- if kept == 0:
- return f"No global news found between {start_date} and {curr_date}"
+ if not news_str:
+ # Results merge several fuzzy searches, so their timestamps prove no
+ # continuous coverage; judge the window against the present only.
+ gap = coverage_gap((), start_date, curr_date, "Yahoo Finance global news", "market news")
+ return gap or f"No global news found between {start_date} and {curr_date}"
return f"## Global Market News, from {start_date} to {curr_date}:\n\n{news_str}"
except Exception as e:
- return f"Error fetching global news: {str(e)}"
+ raise NoMarketDataError("global news", "global news", f"unavailable: {e}") from e
diff --git a/tradingagents/default_config.py b/tradingagents/default_config.py
index 6a35f472e..8d6384b3b 100644
--- a/tradingagents/default_config.py
+++ b/tradingagents/default_config.py
@@ -154,6 +154,9 @@ DEFAULT_CONFIG = _apply_env_overrides({
# based on the ticker's exchange suffix. SPY remains the US default
# so the reflection label keeps reading "Alpha vs SPY" for US tickers
# while non-US tickers get their regional index automatically.
+ # Trading days after the analysis date over which a decision's outcome is
+ # measured, for reflection and for the backtest figures.
+ "holding_period_days": 5,
"benchmark_ticker": None,
"benchmark_map": {
".NS": "^NSEI", # NSE India (Nifty 50)
diff --git a/tradingagents/graph/checkpointer.py b/tradingagents/graph/checkpointer.py
index 750d8d12a..d40255fa4 100644
--- a/tradingagents/graph/checkpointer.py
+++ b/tradingagents/graph/checkpointer.py
@@ -71,13 +71,19 @@ def checkpoint_step(data_dir: str | Path, ticker: str, date: str, signature: str
def clear_all_checkpoints(data_dir: str | Path) -> int:
- """Remove all checkpoint DBs. Returns number of files deleted."""
+ """Remove all checkpoint databases. Returns the number of databases deleted.
+
+ SQLite keeps committed state in ``-wal`` and ``-shm`` files beside the
+ database, so deleting only the ``.db`` leaves a cleared checkpoint with data
+ still on disk.
+ """
cp_dir = Path(data_dir) / "checkpoints"
if not cp_dir.exists():
return 0
dbs = list(cp_dir.glob("*.db"))
for db in dbs:
- db.unlink()
+ for path in (db, *cp_dir.glob(f"{db.name}-*")):
+ path.unlink(missing_ok=True)
return len(dbs)
diff --git a/tradingagents/graph/propagation.py b/tradingagents/graph/propagation.py
index 2a6aeddb6..0bb2e461a 100644
--- a/tradingagents/graph/propagation.py
+++ b/tradingagents/graph/propagation.py
@@ -22,6 +22,7 @@ class Propagator:
asset_type: str = "stock",
past_context: str = "",
instrument_context: str = "",
+ portfolio_context: str = "",
) -> dict[str, Any]:
"""Create the initial state for the agent graph.
@@ -38,6 +39,7 @@ class Propagator:
"instrument_context": instrument_context,
"trade_date": str(trade_date),
"past_context": past_context,
+ "portfolio_context": portfolio_context,
"investment_debate_state": InvestDebateState(
{
"bull_history": "",
diff --git a/tradingagents/graph/reflection.py b/tradingagents/graph/reflection.py
index 0685941fe..094da1b51 100644
--- a/tradingagents/graph/reflection.py
+++ b/tradingagents/graph/reflection.py
@@ -9,20 +9,25 @@ class Reflector:
def __init__(self, quick_thinking_llm: Any):
"""Initialize the reflector with an LLM."""
self.quick_thinking_llm = quick_thinking_llm
- self.log_reflection_prompt = self._get_log_reflection_prompt()
- def _get_log_reflection_prompt(self) -> str:
+ def _system_prompt(self, holding_days: int) -> str:
"""Concise prompt for reflect_on_final_decision (Phase B log entries).
- Produces 2-4 sentences of plain prose — compact enough to be re-injected
- into future agent prompts without bloating the context window.
+ Produces 2-4 sentences of plain prose, compact enough to be re-injected
+ into future agent prompts without bloating the context window. The
+ window is named because it bounds what the outcome can show: a thesis
+ written for months is not disproved by a week, and a lesson that ignores
+ the difference is read by later runs as an established failure.
"""
return (
"You are a trading analyst reviewing your own past decision now that the outcome is known.\n"
+ f"The outcome covers {holding_days} trading days after the analysis date, "
+ "which may be shorter than the horizon the decision was written for.\n"
"Write exactly 2-4 sentences of plain prose (no bullets, no headers, no markdown).\n\n"
"Cover in order:\n"
- "1. Was the directional call correct? (cite the alpha figure)\n"
- "2. Which part of the investment thesis held or failed?\n"
+ f"1. What the {holding_days}-day alpha shows about the directional call (cite the figure), "
+ "and say so plainly if the window is too short to judge the thesis.\n"
+ "2. Which part of the investment thesis this window supports or undercuts.\n"
"3. One concrete lesson to apply to the next similar analysis.\n\n"
"Be specific and terse. Your output will be stored verbatim in a decision log "
"and re-read by future analysts, so every word must earn its place."
@@ -34,6 +39,7 @@ class Reflector:
raw_return: float,
alpha_return: float,
benchmark_name: str = "SPY",
+ holding_days: int = 5,
) -> str:
"""Single reflection call on the final trade decision with outcome context.
@@ -44,11 +50,11 @@ class Reflector:
callers that haven't been updated to thread the benchmark through.
"""
messages = [
- ("system", self.log_reflection_prompt),
+ ("system", self._system_prompt(holding_days)),
(
"human",
(
- f"Raw return: {raw_return:+.1%}\n"
+ f"Raw return over {holding_days} trading days: {raw_return:+.1%}\n"
f"Alpha vs {benchmark_name}: {alpha_return:+.1%}\n\n"
f"Final Decision:\n{final_decision}"
),
diff --git a/tradingagents/graph/trading_graph.py b/tradingagents/graph/trading_graph.py
index bf6c02827..a3510ddc2 100644
--- a/tradingagents/graph/trading_graph.py
+++ b/tradingagents/graph/trading_graph.py
@@ -30,7 +30,7 @@ from tradingagents.agents.utils.agent_utils import (
)
from tradingagents.agents.utils.memory import TradingMemoryLog
from tradingagents.dataflows.config import set_config
-from tradingagents.dataflows.utils import safe_ticker_component
+from tradingagents.dataflows.utils import get_current_date, safe_ticker_component
from tradingagents.default_config import DEFAULT_CONFIG
from tradingagents.llm_clients import create_llm_client
from tradingagents.reporting import write_report_tree
@@ -45,6 +45,20 @@ from .signal_processing import SignalProcessor
logger = logging.getLogger(__name__)
+def _validate_trade_date(trade_date) -> str:
+ """The run date as a canonical ``YYYY-MM-DD`` string no later than today."""
+ value = str(trade_date)
+ try:
+ canonical = datetime.strptime(value, "%Y-%m-%d").strftime("%Y-%m-%d") == value
+ except ValueError:
+ canonical = False
+ if not canonical:
+ raise ValueError(f"trade_date must be a date in YYYY-MM-DD format, got {trade_date!r}")
+ if value > get_current_date():
+ raise ValueError(f"trade_date cannot be in the future: {value}")
+ return value
+
+
def _coerce_max_retries(value):
"""Validate an ``llm_max_retries`` value to a non-negative int.
@@ -260,11 +274,15 @@ class TradingAgentsGraph:
entry, which is the right default because the alpha calculation works
in USD.
"""
+ from tradingagents.dataflows.symbol_utils import normalize_symbol
+
explicit = self.config.get("benchmark_ticker")
if explicit:
- return explicit
+ # Same alias mapping as the analyzed ticker; an unmapped alias finds
+ # no prices, and the decision would stay pending for good.
+ return normalize_symbol(explicit)
benchmark_map = self.config.get("benchmark_map", {})
- ticker_upper = ticker.upper()
+ ticker_upper = normalize_symbol(ticker)
for suffix, benchmark in benchmark_map.items():
if suffix and ticker_upper.endswith(suffix.upper()):
return benchmark
@@ -288,7 +306,9 @@ class TradingAgentsGraph:
try:
start = datetime.strptime(trade_date, "%Y-%m-%d")
- end = start + timedelta(days=holding_days + 7) # buffer for weekends/holidays
+ # holding_days counts trading days, so ask for the calendar span they
+ # occupy (about 7 for every 5) plus a week for holidays.
+ end = start + timedelta(days=round(holding_days * 7 / 5) + 7)
end_str = end.strftime("%Y-%m-%d")
# Normalize so the realized-return lookup hits the same instrument
@@ -341,16 +361,25 @@ class TradingAgentsGraph:
updates = []
for entry in pending:
raw, alpha, days, resolution_date = self._fetch_returns(
- ticker, entry["date"], benchmark=benchmark,
+ ticker, entry["date"], self.config.get("holding_period_days", 5),
+ benchmark=benchmark,
)
if raw is None:
continue # price not available yet — try again next run
- reflection = self.reflector.reflect_on_final_decision(
- final_decision=entry.get("decision", ""),
- raw_return=raw,
- alpha_return=alpha,
- benchmark_name=benchmark,
- )
+ try:
+ reflection = self.reflector.reflect_on_final_decision(
+ final_decision=entry.get("decision", ""),
+ raw_return=raw,
+ alpha_return=alpha,
+ benchmark_name=benchmark,
+ holding_days=days,
+ )
+ except Exception as exc:
+ # Reflection calls a provider, and this runs on the way into a
+ # new run: a transient failure leaves the entry pending for the
+ # next one rather than stopping the analysis that was asked for.
+ logger.warning("Reflection failed for %s on %s: %s", ticker, entry["date"], exc)
+ continue
updates.append({
"ticker": ticker,
"trade_date": entry["date"],
@@ -364,7 +393,8 @@ class TradingAgentsGraph:
if updates:
self.memory_log.batch_update_with_outcomes(updates)
- def resolve_instrument_context(self, ticker: str, asset_type: str = "stock") -> str:
+ def resolve_instrument_context(self, ticker: str, asset_type: str = "stock",
+ curr_date: str | None = None) -> str:
"""Resolve ticker identity once and return the full instrument context.
Deterministic yfinance lookup (cached, fail-open) injected into a
@@ -374,7 +404,7 @@ class TradingAgentsGraph:
graph regardless of entry point.
"""
identity = resolve_instrument_identity(ticker)
- return build_instrument_context(ticker, asset_type, identity)
+ return build_instrument_context(ticker, asset_type, identity, curr_date)
def _memory_as_of(self, trade_date) -> str | None:
"""Point-in-time cutoff for past-context lessons (#1251).
@@ -387,7 +417,7 @@ class TradingAgentsGraph:
td = str(trade_date)
return td if td < datetime.now().strftime("%Y-%m-%d") else None
- def _run_signature(self, asset_type: str) -> str:
+ def _run_signature(self, asset_type: str, portfolio=None) -> str:
"""Graph-shape inputs that must invalidate a checkpoint if changed.
Keyed into the checkpoint thread ID so a resume under a different analyst
@@ -399,9 +429,11 @@ class TradingAgentsGraph:
f"debate={self.config['max_debate_rounds']}",
f"risk={self.config['max_risk_discuss_rounds']}",
f"asset={asset_type}",
+ # None, an empty book and a changed book are three different runs.
+ f"portfolio={portfolio.fingerprint() if portfolio is not None else 'none'}",
])
- def propagate(self, company_name, trade_date, asset_type: str = "stock"):
+ def propagate(self, company_name, trade_date, asset_type: str = "stock", portfolio=None):
"""Run the trading agents graph for a company on a specific date.
``asset_type`` selects between the stock pipeline (default) and the
@@ -417,18 +449,16 @@ class TradingAgentsGraph:
``tradingagents.agents.utils.rating.is_review`` before mapping it to the
PortfolioRating enum.
"""
+ trade_date = _validate_trade_date(trade_date)
self.ticker = company_name
- # Resolve any pending memory-log entries for this ticker before the pipeline runs.
- self._resolve_pending_entries(company_name)
-
- with self.checkpoint_scope(company_name, trade_date, asset_type) as thread_id_value:
+ with self.checkpoint_scope(company_name, trade_date, asset_type, portfolio) as thread_id_value:
return self._run_graph(
company_name, trade_date, asset_type=asset_type,
- checkpoint_thread_id=thread_id_value,
+ checkpoint_thread_id=thread_id_value, portfolio=portfolio,
)
- def begin_checkpoint(self, company_name, trade_date, asset_type: str = "stock") -> str | None:
+ def begin_checkpoint(self, company_name, trade_date, asset_type: str = "stock", portfolio=None) -> str | None:
"""Recompile the graph with a per-ticker checkpointer and return the
``thread_id`` to inject into the stream/invoke ``config`` (or ``None``
when checkpointing is disabled).
@@ -442,7 +472,7 @@ class TradingAgentsGraph:
self._resuming = False
if not self.config.get("checkpoint_enabled"):
return None
- signature = self._run_signature(asset_type)
+ signature = self._run_signature(asset_type, portfolio)
self._checkpointer_ctx = get_checkpointer(self.config["data_cache_dir"], company_name)
saver = self._checkpointer_ctx.__enter__()
self.graph = self.workflow.compile(checkpointer=saver)
@@ -476,19 +506,19 @@ class TradingAgentsGraph:
self._resuming = False
@contextmanager
- def checkpoint_scope(self, company_name, trade_date, asset_type: str = "stock"):
+ def checkpoint_scope(self, company_name, trade_date, asset_type: str = "stock", portfolio=None):
"""Context-manager form of begin/end_checkpoint for the propagate path."""
try:
- yield self.begin_checkpoint(company_name, trade_date, asset_type)
+ yield self.begin_checkpoint(company_name, trade_date, asset_type, portfolio)
finally:
self.end_checkpoint()
- def clear_checkpoint_on_success(self, company_name, trade_date, asset_type: str = "stock"):
+ def clear_checkpoint_on_success(self, company_name, trade_date, asset_type: str = "stock", portfolio=None):
"""Drop a completed run's checkpoint so a later run starts fresh (#1249)."""
if self.config.get("checkpoint_enabled"):
clear_checkpoint(
self.config["data_cache_dir"], company_name, str(trade_date),
- self._run_signature(asset_type),
+ self._run_signature(asset_type, portfolio),
)
def save_reports(self, final_state, ticker, save_path=None) -> Path:
@@ -506,24 +536,50 @@ class TradingAgentsGraph:
)
return write_report_tree(final_state, ticker, save_path)
- def _run_graph(self, company_name, trade_date, asset_type: str = "stock",
- checkpoint_thread_id: str | None = None):
- """Execute the graph and write the resulting state to disk and memory log."""
- # Initialize state — inject memory log context for PM and the
- # deterministically resolved instrument identity for all agents. On a
- # historical run, gate lessons to those whose outcome was known by the
- # trade date so a backtest can't learn from the future (#1251).
- past_context = self.memory_log.get_past_context(
- company_name, as_of=self._memory_as_of(trade_date)
- )
- instrument_context = self.resolve_instrument_context(company_name, asset_type)
- init_agent_state = self.propagator.create_initial_state(
+ def create_run_state(self, company_name, trade_date, asset_type: str = "stock", portfolio=None):
+ """Build a run's initial state; propagate() and the CLI both start here.
+
+ Settles this ticker's pending decisions first, then injects the lessons
+ known by the trade date for the Portfolio Manager (#1251) and the
+ resolved instrument identity for every agent (#814). An entry point that
+ assembled the state itself would skip the decision log.
+ """
+ self._resolve_pending_entries(company_name)
+ return self.propagator.create_initial_state(
company_name,
trade_date,
asset_type=asset_type,
- past_context=past_context,
- instrument_context=instrument_context,
+ past_context=self.memory_log.get_past_context(
+ company_name, as_of=self._memory_as_of(trade_date)
+ ),
+ instrument_context=self.resolve_instrument_context(company_name, asset_type, trade_date),
+ portfolio_context=portfolio.render(company_name) if portfolio is not None else "",
)
+
+ def settle_pending(self, company_name):
+ """Settle this ticker's decisions whose holding window has now traded.
+
+ A run settles the ticker's earlier decisions on its way in, so the most
+ recent one stays pending until the next run for that ticker. A caller
+ that is done analyzing a ticker (a backtest sweep, a scheduled job) calls
+ this to settle it now.
+ """
+ self._resolve_pending_entries(company_name)
+
+ def record_decision(self, company_name, trade_date, final_state):
+ """Log a finished run's decision for reflection on the next same-ticker run."""
+ decision = final_state.get("final_trade_decision")
+ if not decision:
+ logger.warning("No final decision for %s on %s; nothing logged", company_name, trade_date)
+ return
+ self.memory_log.store_decision(
+ ticker=company_name, trade_date=trade_date, final_trade_decision=decision
+ )
+
+ def _run_graph(self, company_name, trade_date, asset_type: str = "stock",
+ checkpoint_thread_id: str | None = None, portfolio=None):
+ """Execute the graph and write the resulting state to disk and memory log."""
+ init_agent_state = self.create_run_state(company_name, trade_date, asset_type, portfolio)
args = self.propagator.get_graph_args()
# Inject the checkpoint thread_id (from checkpoint_scope) so the same
@@ -561,15 +617,10 @@ class TradingAgentsGraph:
# Log state to disk.
self._log_state(trade_date, final_state)
- # Store decision for deferred reflection on the next same-ticker run.
- self.memory_log.store_decision(
- ticker=company_name,
- trade_date=trade_date,
- final_trade_decision=final_state["final_trade_decision"],
- )
+ self.record_decision(company_name, trade_date, final_state)
# Clear checkpoint on successful completion to avoid stale state.
- self.clear_checkpoint_on_success(company_name, trade_date, asset_type)
+ self.clear_checkpoint_on_success(company_name, trade_date, asset_type, portfolio)
return final_state, self.process_signal(final_state["final_trade_decision"])
@@ -613,7 +664,8 @@ class TradingAgentsGraph:
log_path = directory / f"full_states_log_{trade_date}.json"
with open(log_path, "w", encoding="utf-8") as f:
- json.dump(self.log_states_dict[str(trade_date)], f, indent=4)
+ # Reports can be in any language and this file is read by a person.
+ json.dump(self.log_states_dict[str(trade_date)], f, indent=4, ensure_ascii=False)
def process_signal(self, full_signal):
"""Process a signal to extract the core decision."""
diff --git a/tradingagents/llm_clients/google_client.py b/tradingagents/llm_clients/google_client.py
index 19ae8a213..134baf556 100644
--- a/tradingagents/llm_clients/google_client.py
+++ b/tradingagents/llm_clients/google_client.py
@@ -1,3 +1,4 @@
+import re
from typing import Any
from langchain_google_genai import ChatGoogleGenerativeAI
@@ -5,6 +6,19 @@ from langchain_google_genai import ChatGoogleGenerativeAI
from .base_client import BaseLLMClient, normalize_content
from .validators import validate_model
+_GEMINI_VERSION = re.compile(r"^gemini-(\d+)\.(\d+)")
+
+
+def _accepts_minimal_thinking(model: str) -> bool:
+ """Whether ``thinking_level="minimal"`` is accepted: numbered Flash models
+ before 3.8. Pro, 3.8+ and version-less aliases (which move between
+ generations) are treated as rejecting it."""
+ model_lc = model.lower()
+ match = _GEMINI_VERSION.match(model_lc)
+ return bool(match) and "pro" not in model_lc and (
+ (int(match.group(1)), int(match.group(2))) < (3, 8)
+ )
+
class NormalizedChatGoogleGenerativeAI(ChatGoogleGenerativeAI):
"""ChatGoogleGenerativeAI with normalized content output.
@@ -42,12 +56,12 @@ class GoogleClient(BaseLLMClient):
llm_kwargs["google_api_key"] = google_api_key
# Gemini 3.x takes the string ``thinking_level`` (the integer
- # ``thinking_budget`` was for the now-retired 2.5 line). Pro accepts
- # low/high; Flash also accepts minimal/medium — so map an unsupported
- # "minimal" on Pro to the nearest level it does accept.
+ # ``thinking_budget`` was for the now-retired 2.5 line). Pro, Gemini
+ # 3.8+ and the -latest aliases reject "minimal" with a 400; "low" is
+ # accepted everywhere, so it is the fallback.
thinking_level = self.kwargs.get("thinking_level")
if thinking_level:
- if "pro" in self.model.lower() and thinking_level == "minimal":
+ if thinking_level == "minimal" and not _accepts_minimal_thinking(self.model):
thinking_level = "low"
llm_kwargs["thinking_level"] = thinking_level
diff --git a/tradingagents/llm_clients/model_catalog.py b/tradingagents/llm_clients/model_catalog.py
index 1d9ee802a..e60cc3476 100644
--- a/tradingagents/llm_clients/model_catalog.py
+++ b/tradingagents/llm_clients/model_catalog.py
@@ -45,14 +45,12 @@ _GLM_MODELS: dict[str, list[ModelOption]] = {
# "Custom model ID".
_QWEN_MODELS: dict[str, list[ModelOption]] = {
"quick": [
- ("Qwen 3.7 Plus - Latest, balanced speed/cost", "qwen3.7-plus"),
- ("Qwen 3.6 Plus - Previous-gen balanced", "qwen3.6-plus"),
+ ("Qwen 3.8 Flash - Latest fast model, 1M ctx", "qwen3.8-flash"),
("Custom model ID", "custom"),
],
"deep": [
- ("Qwen 3.7 Max - Latest flagship, most intelligent, 1M ctx", "qwen3.7-max"),
- ("Qwen 3.6 Max - Previous-gen flagship", "qwen3.6-max"),
- ("Qwen 3.7 Plus - Balanced alternative", "qwen3.7-plus"),
+ ("Qwen 3.8 Max - Latest flagship", "qwen3.8-max"),
+ ("Qwen 3.8 Flash - Fast alternative, 1M ctx", "qwen3.8-flash"),
("Custom model ID", "custom"),
],
}
@@ -101,46 +99,54 @@ MODEL_OPTIONS: ProviderModeOptions = {
("GPT-5.6 Luna - Fast, cost-efficient frontier", "gpt-5.6-luna"),
("GPT-5.6 Terra - Balances intelligence and cost", "gpt-5.6-terra"),
("GPT-5.4 Mini - Fast, strong coding and tool use", "gpt-5.4-mini"),
+ ("Custom model ID", "custom"),
],
"deep": [
- ("GPT-5.6 - Latest frontier reasoning (Sol)", "gpt-5.6"),
+ ("GPT-6 Astra - Latest frontier reasoning", "gpt-6-astra"),
+ ("GPT-5.6 - Frontier reasoning (Sol)", "gpt-5.6"),
("GPT-5.6 Terra - Balances intelligence and cost", "gpt-5.6-terra"),
("GPT-5.5 - Previous-gen frontier, 1M context", "gpt-5.5"),
- ("GPT-5.4 - Cost-effective, 1M context", "gpt-5.4"),
+ ("Custom model ID", "custom"),
],
},
"anthropic": {
"quick": [
("Claude Sonnet 5 - Best speed and intelligence balance", "claude-sonnet-5"),
("Claude Haiku 4.5 - Fastest with near-frontier intelligence", "claude-haiku-4-5"),
+ ("Custom model ID", "custom"),
],
"deep": [
- ("Claude Fable 5 - Most capable, long-running agents", "claude-fable-5"),
- ("Claude Opus 4.8 - Frontier agentic coding and reasoning", "claude-opus-4-8"),
+ ("Claude Opus 5 - Frontier agentic and enterprise work", "claude-opus-5"),
+ ("Claude Fable 5.1 - Most capable, demanding long-horizon reasoning", "claude-fable-5-1"),
("Claude Sonnet 5 - Near-frontier intelligence at Sonnet cost", "claude-sonnet-5"),
- ("Claude Opus 4.7 - Previous frontier, long-running agents", "claude-opus-4-7"),
+ ("Custom model ID", "custom"),
],
},
"google": {
"quick": [
- ("Gemini 3.5 Flash - Latest, frontier agentic + coding (GA)", "gemini-3.5-flash"),
+ ("Gemini 3.8 Flash - Most capable Flash", "gemini-3.8-flash"),
+ ("Gemini 3.5 Flash Lite - Fast and cost-efficient", "gemini-3.5-flash-lite"),
("Gemini 3.1 Flash Lite - Most cost-efficient", "gemini-3.1-flash-lite"),
+ ("Custom model ID", "custom"),
],
"deep": [
+ ("Gemini 3.8 Flash - Most capable Flash, 1M context", "gemini-3.8-flash"),
("Gemini 3.1 Pro - Reasoning-first, complex workflows (preview)", "gemini-3.1-pro-preview"),
- ("Gemini 3.5 Flash - Latest GA, strong agentic + coding", "gemini-3.5-flash"),
+ ("Gemini 3.5 Flash - Previous Flash, strong agentic + coding", "gemini-3.5-flash"),
+ ("Custom model ID", "custom"),
],
},
"xai": {
"quick": [
- ("Grok 4.3 - Latest flagship, fast with built-in reasoning", "grok-4.3"),
- ("Grok 4.20 (Non-Reasoning) - Speed-optimized", "grok-4.20-0309-non-reasoning"),
+ ("Grok 4.6 - Latest flagship, fastest, 500K ctx", "grok-4.6"),
("Grok Build 0.1 - Coding-specialized, 256K ctx", "grok-build-0.1"),
+ ("Custom model ID", "custom"),
],
"deep": [
- ("Grok 4.3 - Latest flagship, built-in reasoning, 1M ctx", "grok-4.3"),
- ("Grok 4.20 (Reasoning) - Previous-gen reasoning", "grok-4.20-0309-reasoning"),
- ("Grok 4.20 Multi-Agent - Multi-agent reasoning", "grok-4.20-multi-agent-0309"),
+ ("Grok 4.6 - Latest flagship, 500K ctx", "grok-4.6"),
+ ("Grok 4.5 - Previous flagship, coding and agentic", "grok-4.5"),
+ ("Grok 4.3 - Older generation, 1M ctx", "grok-4.3"),
+ ("Custom model ID", "custom"),
],
},
# DeepSeek: the deepseek-chat / deepseek-reasoner aliases are deprecated
@@ -149,12 +155,12 @@ MODEL_OPTIONS: ProviderModeOptions = {
# handles the reasoning_content round-trip).
"deepseek": {
"quick": [
- ("DeepSeek V4 Flash - Latest fast model, thinking + non-thinking", "deepseek-v4-flash"),
+ ("DeepSeek Flash - V4.1 Flash, fast, 1M ctx", "deepseek-flash"),
("Custom model ID", "custom"),
],
"deep": [
- ("DeepSeek V4 Pro - Latest flagship", "deepseek-v4-pro"),
- ("DeepSeek V4 Flash - Fast, supports thinking", "deepseek-v4-flash"),
+ ("DeepSeek V4 Pro - Flagship", "deepseek-v4-pro"),
+ ("DeepSeek Flash - V4.1 Flash, fast, 1M ctx", "deepseek-flash"),
("Custom model ID", "custom"),
],
},
@@ -200,7 +206,17 @@ MODEL_OPTIONS: ProviderModeOptions = {
# changing) models — offer "Custom model ID" rather than a list that goes
# stale. The endpoint + key are wired by the provider; the user picks the
# model their account has access to.
- "mistral": _CUSTOM_ONLY,
+ "mistral": {
+ "quick": [
+ ("Mistral Small 4 - Fast, 262K ctx", "mistral-small-2603"),
+ ("Custom model ID", "custom"),
+ ],
+ "deep": [
+ ("Mistral Medium 3.5 - 262K ctx", "mistral-medium-2604"),
+ ("Mistral Small 4 - Fast, 262K ctx", "mistral-small-2603"),
+ ("Custom model ID", "custom"),
+ ],
+ },
"groq": _CUSTOM_ONLY,
"nvidia": _CUSTOM_ONLY,
# Bedrock model IDs / cross-region inference profile IDs are user-specified.
@@ -213,8 +229,21 @@ def get_model_options(provider: str, mode: str) -> list[ModelOption]:
return MODEL_OPTIONS[provider.lower()][mode]
+# Served by the provider but not offered in the picker: models retired from the
+# menu, and the explicit ID of a model listed under a shorter name. Known to
+# validation so a config naming one runs without an unknown-model warning.
+LEGACY_MODELS: dict[str, list[str]] = {
+ "openai": ["gpt-5.4", "gpt-5.6-sol"],
+ "xai": ["grok-4.20-0309-reasoning", "grok-4.20-0309-non-reasoning",
+ "grok-4.20-multi-agent-0309"],
+ "deepseek": ["deepseek-v4-flash"],
+ "qwen": ["qwen3.7-max", "qwen3.7-plus", "qwen3.6-max", "qwen3.6-plus"],
+ "anthropic": ["claude-fable-5", "claude-opus-4-8", "claude-opus-4-7"],
+}
+
+
def get_known_models() -> dict[str, list[str]]:
- """Build known model names from the shared CLI catalog."""
+ """Build known model names from the shared CLI catalog plus legacy IDs."""
return {
provider: sorted(
{
@@ -222,6 +251,7 @@ def get_known_models() -> dict[str, list[str]]:
for options in mode_options.values()
for _, value in options
}
+ | set(LEGACY_MODELS.get(provider, []))
)
for provider, mode_options in MODEL_OPTIONS.items()
}
diff --git a/tradingagents/llm_clients/openai_client.py b/tradingagents/llm_clients/openai_client.py
index 5f78eb6e6..b1d7b65d6 100644
--- a/tradingagents/llm_clients/openai_client.py
+++ b/tradingagents/llm_clients/openai_client.py
@@ -168,11 +168,11 @@ _PASSTHROUGH_KWARGS = (
"api_key", "callbacks", "http_client", "http_async_client",
)
-# OpenAI's ``reasoning_effort`` is only accepted by reasoning models — the GPT-5
-# family and the o-series. Non-reasoning models (gpt-4.1, gpt-4o, ...) 400 with
+# OpenAI's ``reasoning_effort`` is only accepted by reasoning models — GPT-5 and
+# later, and the o-series. Non-reasoning models (gpt-4.1, gpt-4o, ...) 400 with
# "Unsupported parameter: 'reasoning.effort' is not supported with this model".
# Drop the kwarg for those rather than crash the run.
-_OPENAI_REASONING_MODEL = re.compile(r"^(gpt-5|o[1-9])")
+_OPENAI_REASONING_MODEL = re.compile(r"^(?:gpt-(?:[5-9]|[1-9]\d)|o[1-9])(?:[.-]|$)")
def _supports_reasoning_effort(model: str) -> bool:
@@ -225,7 +225,8 @@ OPENAI_COMPATIBLE_PROVIDERS: dict[str, ProviderSpec] = {
"groq": ProviderSpec(base_url="https://api.groq.com/openai/v1"),
"nvidia": ProviderSpec(base_url="https://integrate.api.nvidia.com/v1"),
"ollama": ProviderSpec(base_url="http://localhost:11434/v1", base_url_env="OLLAMA_BASE_URL",
- key_optional=True, placeholder_key="ollama"),
+ key_optional=True, placeholder_key="ollama",
+ chat_class=LocalCompatibleChatOpenAI),
# Generic endpoint: user supplies base_url; key optional (keyless local).
"openai_compatible": ProviderSpec(
require_base_url=True, key_optional=True, chat_class=LocalCompatibleChatOpenAI
diff --git a/tradingagents/portfolio.py b/tradingagents/portfolio.py
new file mode 100644
index 000000000..c4f42392e
--- /dev/null
+++ b/tradingagents/portfolio.py
@@ -0,0 +1,64 @@
+"""The caller's book, as the decision agents see it.
+
+Optional input to a run: what is held, at what average price, and how much cash
+is free. Without it the agents cannot tell adding to a full position from
+opening a new one. Three states are distinct and must stay so: a position, a
+flat book, and no context at all, since treating "not provided" as "flat" would
+invent a fact about the caller's account.
+
+Broker-neutral by construction: quantities are generic units and the currency is
+whatever label the caller passes, so nothing here implies a venue or an
+execution path.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+
+from pydantic import BaseModel, Field, ValidationError
+
+
+class Position(BaseModel):
+ ticker: str = Field(description="Instrument symbol, e.g. AAPL")
+ quantity: float = Field(description="Signed units held; negative is short")
+ average_price: float | None = Field(default=None, description="Average entry price per unit")
+
+
+class PortfolioContext(BaseModel):
+ cash: float | None = Field(default=None, description="Free cash available")
+ currency: str | None = Field(default=None, description="Currency label for cash and prices")
+ positions: list[Position] = Field(default_factory=list)
+
+ def position_in(self, ticker: str) -> Position | None:
+ return next((p for p in self.positions if p.ticker.upper() == ticker.strip().upper()), None)
+
+ def render(self, ticker: str) -> str:
+ """The portfolio block for the decision agents, led by the analyzed instrument."""
+ symbol = ticker.strip().upper()
+ held = self.position_in(symbol)
+ if held is None:
+ lines = [f"- No current position in {symbol}"]
+ else:
+ price = f", average price {held.average_price:,.2f}" if held.average_price is not None else ""
+ lines = [f"- Current position in {symbol}: {held.quantity:,.4g} units{price}"]
+ if self.cash is not None:
+ lines.append(f"- Cash available: {self.cash:,.2f}{' ' + self.currency if self.currency else ''}")
+ others = [p for p in self.positions if p is not held]
+ if others:
+ lines.append("- Other positions: " + ", ".join(f"{p.ticker.upper()} {p.quantity:,.4g}" for p in others))
+ return "Portfolio at the analysis date:\n" + "\n".join(lines)
+
+ def fingerprint(self) -> str:
+ """Stable digest of the book, so a changed one cannot resume a stale run."""
+ return hashlib.sha256(self.model_dump_json().encode()).hexdigest()[:12]
+
+
+def load_portfolio(path: str | Path) -> PortfolioContext:
+ """Read a portfolio JSON file, failing before the run rather than mid-graph."""
+ try:
+ data = json.loads(Path(path).read_text(encoding="utf-8"))
+ return PortfolioContext.model_validate(data)
+ except (OSError, json.JSONDecodeError, ValidationError) as exc:
+ raise ValueError(f"portfolio file {path} is not usable: {exc}") from exc