release: 0.5.0

- point-in-time integrity across every dated path, and a vendor failure reported as a vendor failure
- SEC EDGAR fundamentals served as filed
- backtesting over a ticker and date grid, and the caller's portfolio as run input
- current model lineups across every provider

.dockerignore

@@ -0,0 +1,15 @@
+.git
+.venv
+.env
+.claude
+.idea
+.vscode
+.DS_Store
+__pycache__
+*.egg-info
+build
+dist
+results
+eval_results
+Dockerfile
+docker-compose.yml

.env.enterprise.example

@@ -0,0 +1,5 @@
+# Azure OpenAI
+AZURE_OPENAI_API_KEY=
+AZURE_OPENAI_ENDPOINT=https://your-resource-name.openai.azure.com/
+AZURE_OPENAI_DEPLOYMENT_NAME=
+# OPENAI_API_VERSION=2024-10-21  # optional, required for non-v1 API

.env.example

@@ -3,4 +3,62 @@ OPENAI_API_KEY=
 GOOGLE_API_KEY=
 ANTHROPIC_API_KEY=
 XAI_API_KEY=
+DEEPSEEK_API_KEY=
+DASHSCOPE_API_KEY=
+DASHSCOPE_CN_API_KEY=
+ZHIPU_API_KEY=
+ZHIPU_CN_API_KEY=
+MINIMAX_API_KEY=
+MINIMAX_CN_API_KEY=
 OPENROUTER_API_KEY=
+MISTRAL_API_KEY=
+MOONSHOT_API_KEY=
+GROQ_API_KEY=
+NVIDIA_API_KEY=
+
+# 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=
+
+# Custom OpenAI-compatible endpoint (vLLM, LM Studio, llama.cpp). Local servers need no key.
+#OPENAI_COMPATIBLE_API_KEY=
+
+# 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=
+
+# Remote Ollama server. Unset uses http://localhost:11434/v1.
+#OLLAMA_BASE_URL=http://your-ollama-host:11434/v1
+
+# 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.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
+
+# 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
+
+# Retry budget for every LLM SDK. Raise it to ride out 429 throttling.
+#TRADINGAGENTS_LLM_MAX_RETRIES=6
+
+# Cap output tokens to bound a model that runs long and trips a timeout.
+#TRADINGAGENTS_MAX_TOKENS=8192
+
+# Reasoning depth per provider; setting one skips its prompt.
+#TRADINGAGENTS_OPENAI_REASONING_EFFORT=medium
+#TRADINGAGENTS_GOOGLE_THINKING_LEVEL=high
+#TRADINGAGENTS_ANTHROPIC_EFFORT=high

.github/workflows/ci.yml

@@ -0,0 +1,61 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: tests (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install (with dev extras)
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Run test suite
+        run: pytest -q
+
+  smoke-install:
+    name: clean-install smoke
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Fresh install (no dev extras) and import
+        run: |
+          python -m pip install --upgrade pip
+          pip install .
+          # Catches undeclared runtime deps (e.g. #994 python-dotenv): a bare
+          # install must import the package and the CLI module.
+          python -c "import tradingagents, cli.main; print('clean-install import OK')"
+
+  lint:
+    name: ruff (strict, full repo)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install ruff
+        run: pip install "ruff>=0.15"
+      - name: Lint the repository
+        # The repo is fully clean under the strict select, so we lint everything
+        # (generated results/ is excluded via pyproject extend-exclude).
+        run: ruff check .

.gitignore

@@ -217,3 +217,7 @@ __marimo__/
 
 # Cache
 **/data_cache/
+
+# Enterprise env file (secrets) and generated run reports
+.env.enterprise
+reports/

CHANGELOG.md

@@ -0,0 +1,565 @@
+# Changelog
+
+All notable changes to TradingAgents are documented here.
+
+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
+decision signals, working CLI checkpoint resume, and the GPT-5.6 / GLM-5.3 models.
+
+### Fixed
+
+- **FRED macro look-ahead.** Historical macro requests were served from today's
+  data vintage, leaking later revisions into a backtest; both the observations
+  and metadata requests now pin the vintage to the as-of date. (#1275)
+- **Social sentiment look-ahead.** StockTwits and Reddit were fetched with no
+  date, so a historical run showed today's chatter as if it were from the as-of
+  date; the social path is now trimmed to the analysis window, via one shared
+  UTC half-open window rule (`dataflows/date_window`) used by news too. (#1220)
+- **Memory point-in-time guard.** `get_past_context` returned every resolved
+  lesson regardless of the run date; each resolved entry now records the date
+  its outcome became known, and a historical run only sees lessons resolved by
+  the trade date. (#1251)
+- **Premature reflection.** A decision was settled on a partial return if a rerun
+  happened before its holding window fully traded; resolution now waits for the
+  full window. (#1169)
+- **Latest OHLCV bar dropped.** The newest bar with a NaN close was silently
+  dropped before the date cutoff, making the previous trading day look like the
+  latest; dates are normalized per element (DST- and non-US-market safe) and a
+  missing latest close raises rather than falling back. (#1201)
+- **Debate opening fabrication.** The first speaker in each debate round rebutted
+  an empty opponent response, fabricating the other side; all five debators now
+  open with their own case when no opponent has spoken. (#1176)
+- **Silent Hold.** An unparseable Portfolio Manager rating (including a fullwidth
+  colon) was coerced to a tradeable Hold; it now surfaces a `REVIEW` sentinel,
+  with `parse_rating` keeping its silent default for compatibility callers. (#1170)
+- **`--checkpoint` was a no-op on the CLI.** Checkpoint setup lived only in
+  `propagate()`; the CLI streamed the checkpointer-less graph. The lifecycle is
+  now shared, and a resume feeds `None` so LangGraph continues the interrupted
+  run instead of duplicating messages. (#1249)
+- **DeepSeek via OpenRouter.** `deepseek/<id>` fell through to default
+  capabilities and had object-form `tool_choice` forced on it; the official
+  namespace is stripped so it reuses the native DeepSeek quirks. (#1199)
+- **Trader price grounding.** The Trader saw only the digested plan; it now also
+  receives the technical market report so entry/stop levels anchor to real price
+  structure. (#1167)
+
+### Added
+
+- **Configurable output-token cap.** `max_tokens` / `TRADINGAGENTS_MAX_TOKENS`,
+  forwarded to every provider (Gemini as `max_output_tokens`), so a model that
+  emits unbounded reasoning can be bounded instead of hanging. (#1204)
+- **Latest models.** Added the GPT-5.6 family (`gpt-5.6` / `gpt-5.6-terra` /
+  `gpt-5.6-luna`) and GLM-5.3 (`glm-5.3`, `glm-5.3-flash`). The default models
+  are now `gpt-5.6` (deep) and `gpt-5.6-luna` (quick).
+
+### Contributors
+
+Thanks to everyone who reported these or sent a fix:
+
+[@PyriteResearch](https://github.com/PyriteResearch), [@yiran1268](https://github.com/yiran1268), [@fabiolenine](https://github.com/fabiolenine), [@lx7720](https://github.com/lx7720), [@taro0915](https://github.com/taro0915), [@Jaswanth-Sriram-Veturi](https://github.com/Jaswanth-Sriram-Veturi), [@ariesy](https://github.com/ariesy), [@liangzj1999](https://github.com/liangzj1999), [@zkwang616](https://github.com/zkwang616), [@aniketshukla1](https://github.com/aniketshukla1), [@loulanyue](https://github.com/loulanyue), [@hudsonwa](https://github.com/hudsonwa), [@daleselaji-dev](https://github.com/daleselaji-dev), [@wolfoswald777-crypto](https://github.com/wolfoswald777-crypto).
+
+## [0.3.1] — 2026-07-05
+
+Correctness and stability patch: data look-ahead, graph-router crash-safety,
+checkpoint identity, crypto sentiment sources, and configurable resilience.
+
+### Fixed
+
+- **Alpha Vantage look-ahead filter now runs.** The fundamentals payload is a
+  JSON string, so the dict-only guard skipped filtering and future-dated reports
+  leaked into historical runs; parse before filtering. (#1115, @zachthebird)
+- **News analyst prompt matches the tool.** The prompt advertised
+  `get_news(query, ...)` but the tool takes a ticker; aligned to stop
+  hallucinated free-text query calls. (#1116, @shcheuk)
+- **Shared debate/risk routers can't crash mid-run.** Both routers return more
+  targets than any one edge mapped; every edge now shares the complete path map,
+  so a fall-through under prompt/i18n/refactor drift stays routable.
+  (#1088, @Fr3ya, @sa7an7, @Sushanth012)
+- **Checkpoint resume respects graph shape.** The thread id folds in selected
+  analysts, debate/risk depth, and asset mode, so a resume under different
+  choices no longer continues the wrong graph. (#1089, @bossjoker1, @Ghraven)
+- **Crypto sentiment sources resolve.** StockTwits lists crypto as `<BASE>.X`
+  (Yahoo's `BTC-USD` 404s) and Reddit needs the base symbol to match; the social
+  path now maps crypto correctly for both. (#1113, @suremadoreai)
+
+### Added
+
+- **Configurable LLM retry budget.** `llm_max_retries` /
+  `TRADINGAGENTS_LLM_MAX_RETRIES` is forwarded to every provider, so a transient
+  429 burst no longer aborts a run. (#1091, @yanggaome)
+- **Bedrock API-key auth.** `AWS_BEARER_TOKEN_BEDROCK` authenticates Amazon
+  Bedrock without AWS access keys and takes precedence over an ambient
+  `AWS_PROFILE`. (#1103, @praxstack)
+- **Latest Claude models.** Added Claude Sonnet 5 (`claude-sonnet-5`) and
+  Fable 5 (`claude-fable-5`); effort control now covers the Claude 5 line.
+
+## [0.3.0] — 2026-06-22
+
+Stabilization and extensibility release: a CI gate, a unified verified
+data-access contract, a provider and data-vendor registry, and a maintenance
+sweep that hardened config precedence, the model catalog, data resilience, and
+structured output.
+
+### Added
+
+- **CI gate.** GitHub Actions runs the pytest suite across Python 3.10-3.13,
+  strict `ruff`, and a clean-install smoke that imports the package and CLI to
+  catch undeclared dependencies. (#994, #197)
+- **Provider registry.** OpenAI-compatible providers register as a single spec,
+  and a generic `openai_compatible` endpoint covers vLLM, LM Studio, and relays.
+  Adds NVIDIA NIM, Kimi, Groq, Mistral, and a native Amazon Bedrock client.
+- **Macro and prediction-market vendors.** FRED macro indicators and Polymarket
+  event probabilities, surfaced to the news and macro analysts.
+- **Programmatic report output.** `TradingAgentsGraph.save_reports()` writes the
+  same report tree the CLI produces, for headless and API runs. (#1037)
+- **Env-configurable reasoning depth** via `TRADINGAGENTS_OPENAI_REASONING_EFFORT`,
+  `TRADINGAGENTS_GOOGLE_THINKING_LEVEL`, and `TRADINGAGENTS_ANTHROPIC_EFFORT`,
+  each gated to the models that accept it.
+
+### Changed
+
+- **Verified data-access contract.** Symbol normalization on every vendor path
+  (identity, returns, CLI, news); the configured vendor list is the exact
+  resolution chain with no silent fallback to unselected vendors; a typed
+  `VendorError` taxonomy; look-ahead-safe news windows; stale-OHLCV rejection;
+  inclusive yfinance date ranges.
+- **Config precedence.** An explicit `TRADINGAGENTS_*` value or CLI flag now wins
+  over interactive defaults for debate and risk round counts,
+  `--checkpoint / --no-checkpoint`, and the Docker provider profile; invalid
+  boolean env values fail loudly. (#975, #976, #977)
+- **Current-generation model catalog.** Refreshed provider lineups; retired
+  `gpt-4.1`, Claude Sonnet 4.5, and the Gemini 2.5 line.
+- **Optional vendors degrade** instead of aborting a run: a failed macro or
+  prediction-market lookup returns a no-data sentinel.
+- **Analyst prompts lead with the current date** so tool-call date ranges anchor
+  to the run date rather than the model's training cutoff. (#836)
+
+### Fixed
+
+- **Instrument identity.** Deterministic ticker-to-company resolution prevents
+  wrong-company hallucination, and a verified market-data snapshot grounds price
+  and indicator claims. (#814, #830)
+- **Social and market data sources.** Reddit RSS-first with 429 backoff,
+  StockTwits transport hardening, and Alpha Vantage timeout plus
+  key-versus-rate-limit handling.
+- **Structured output.** Local OpenAI-compatible servers no longer reject
+  object-form `tool_choice`; a thinking model that returns no parsed result falls
+  back to free text; null-ish strings in optional price fields coerce to `None`.
+  (#1038, #1051, #1057)
+
+### Removed
+
+- The no-op `analyst_concurrency_limit` config knob; parallel analyst execution
+  is planned for a later release. (#979)
+- The unused committed `uv.lock`. (#1030)
+
+### Contributors
+
+Thanks to everyone who shaped this release through code, design, and reports:
+
+[@CadeYu](https://github.com/CadeYu), [@Zavianx](https://github.com/Zavianx), [@weijianz-opc](https://github.com/weijianz-opc), [@naltun](https://github.com/naltun), [@brahmasky](https://github.com/brahmasky), [@nik2208](https://github.com/nik2208), [@thieucong98](https://github.com/thieucong98), [@Derekko-web](https://github.com/Derekko-web), [@LukiPrince](https://github.com/LukiPrince), [@Eddieargenal](https://github.com/Eddieargenal), [@Ghraven](https://github.com/Ghraven), [@ms32035](https://github.com/ms32035), [@yting27](https://github.com/yting27), [@nyxst4ck](https://github.com/nyxst4ck), [@KenCheung-AIxFinance](https://github.com/KenCheung-AIxFinance), [@yangyusheng2n](https://github.com/yangyusheng2n), [@fareloj](https://github.com/fareloj), [@haosenwang1018](https://github.com/haosenwang1018), [@octo-patch](https://github.com/octo-patch), [@seifenk](https://github.com/seifenk), [@CaoYuhaoCarl](https://github.com/CaoYuhaoCarl), [@mihailnica10](https://github.com/mihailnica10), [@Dado-hash](https://github.com/Dado-hash), [@Handsomemikezzz](https://github.com/Handsomemikezzz), [@ydhawesome](https://github.com/ydhawesome), [@macd2](https://github.com/macd2), [@AyushKar2005](https://github.com/AyushKar2005), [@wildhuman](https://github.com/wildhuman), [@robert23kim](https://github.com/robert23kim), [@bngness](https://github.com/bngness), [@tedix-rodrigo](https://github.com/tedix-rodrigo), [@malaccan](https://github.com/malaccan), [@rfalken78](https://github.com/rfalken78), [@dengli1971-droid](https://github.com/dengli1971-droid), [@proofconcept39](https://github.com/proofconcept39), [@prasta1](https://github.com/prasta1), [@liximin](https://github.com/liximin), [@jeffhuen](https://github.com/jeffhuen), [@mazar](https://github.com/mazar), [@soyangelromero](https://github.com/soyangelromero), [@CNQQC](https://github.com/CNQQC), [@dovetaill](https://github.com/dovetaill), [@fperdigon](https://github.com/fperdigon), [@gyx09212214-prog](https://github.com/gyx09212214-prog), [@RSXLX](https://github.com/RSXLX).
+
+## [0.2.5] — 2026-05-11
+
+### Added
+
+- **Grounded Sentiment Analyst.** The renamed `sentiment_analyst` now reads
+  real Yahoo News, StockTwits, and Reddit data before generating its report,
+  replacing the prior flow that could fabricate social posts under prompt
+  pressure. (#557, #607)
+- **MiniMax provider** with the full M2.x catalog (M2.7 / M2.5 / M2.1 / M2
+  plus highspeed variants, 204K context). Dual-region: Global
+  (`MINIMAX_API_KEY`) and China (`MINIMAX_CN_API_KEY`).
+- **Dual-region Qwen and GLM** with separate keys per region — international
+  (`DASHSCOPE_API_KEY`, `ZHIPU_API_KEY`) and China (`DASHSCOPE_CN_API_KEY`,
+  `ZHIPU_CN_API_KEY`), selectable via a secondary region prompt. (#758)
+- **`TRADINGAGENTS_*` env-var configurability for `DEFAULT_CONFIG`.** Override
+  `llm_provider`, deep/quick model IDs, `backend_url`, `output_language`,
+  debate-round counts, checkpoint flag, and benchmark ticker via `.env` with
+  type-aware coercion (string / int / bool). (#602)
+- **Interactive API-key detection in the CLI.** When the selected provider's
+  key is missing, the CLI prompts for it and persists the value to `.env`
+  so the analysis run continues without restart.
+- **Remote Ollama support.** `OLLAMA_BASE_URL` points the CLI and the
+  programmatic client at a remote `ollama-serve`. The CLI surfaces the
+  resolved endpoint and warns on common malformed inputs. Adds a
+  `"Custom model ID"` option for models pulled via `ollama pull`. (#648, #768)
+- **Configurable news-fetch parameters** in `DEFAULT_CONFIG` — per-ticker
+  article limit, macro headline limit, lookback window, and macro search
+  queries. (#606, #683)
+- **Configurable alpha benchmark** for non-US tickers. Replaces hardcoded
+  SPY with regional indices for `.NS` (^NSEI), `.T` (^N225), `.HK` (^HSI),
+  `.L` (^FTSE), `.TO` (^GSPTSE), `.AX` (^AXJO), `.BO` (^BSESN); explicit
+  `benchmark_ticker` override available. Eliminates FX drift dominating
+  alpha for non-USD listings. (#628, #684)
+- **Multi-language output covers every user-facing agent** — researchers,
+  risk debators, research manager, and trader, ending the previous
+  partial-localization reports. (#575)
+- **Model catalog refresh.** OpenAI GPT-5.5 frontier, Anthropic Claude Opus
+  4.7, Gemini 3.1 Flash-Lite GA, xAI Grok 4.20, Qwen 3.6 line. Versioned IDs
+  only; auto-shifting aliases moved to the `"Custom model ID"` option.
+
+### Changed
+
+- **Sentiment Analyst** is now consistently named across the CLI dropdown,
+  status panel, and final reports (previously the backend was renamed but
+  the CLI still said "Social Analyst"). The `AnalystType.SOCIAL = "social"`
+  wire value is kept for saved-config back-compat.
+
+### Fixed
+
+- **Structured output works on DeepSeek V4 / reasoner and MiniMax M2.x.**
+  Those providers reject `tool_choice` per their tool-calling docs; the
+  binding flow now skips it automatically via a capability table.
+- **`pip install .` installations pick up the project `.env`** when running
+  the CLI as a console script. (#747)
+- **Reports save end-to-end** — streamed chunks were previously dropped from
+  `complete_report.md`. (#719, #736)
+- **Ticker prompt preserves exchange suffixes** (`.SH`, `.SZ`, `.SS`, `.HK`,
+  `.T`, etc.) for A-share, HK, Tokyo, and other non-US flows. (#770)
+- **Docker permission errors** no longer block first-run write to
+  `~/.tradingagents/`. (#519, #627, #672, #771)
+- **Config state no longer leaks between runs** when sub-dicts are mutated;
+  `set_config` partial updates preserve sibling defaults. (#788)
+- **`max_recur_limit` config actually applies** — previously read but not
+  forwarded to the propagator. (#764)
+- **Missing-API-key error** names the exact env var to set. (#680)
+- **Quieter startup** — suppressed the noisy upstream
+  `LangChainPendingDeprecationWarning` from langgraph-checkpoint; will be
+  removed once that package ships its fix.
+
+### Security
+
+- **Ticker path-traversal validation** at every filesystem-path site (cache,
+  checkpoint database, results) so a malicious ticker cannot escape its
+  intended directory. (#618)
+
+## [0.2.4] — 2026-04-25
+
+### Added
+
+- **Structured-output decision agents.** Research Manager, Trader, and Portfolio
+  Manager now use `llm.with_structured_output(Schema)` on their primary call
+  and return typed Pydantic instances. Each provider's native structured-output
+  mode is used (`json_schema` for OpenAI / xAI, `response_schema` for Gemini,
+  tool-use for Anthropic, function-calling for OpenAI-compatible providers).
+  Render helpers preserve the existing markdown shape so memory log, CLI
+  display, and saved reports keep working unchanged. (#434)
+- **LangGraph checkpoint resume** — opt-in via `--checkpoint`. State is saved
+  after each node so crashed or interrupted runs resume from the last
+  successful step. Per-ticker SQLite databases under
+  `~/.tradingagents/cache/checkpoints/`. `--clear-checkpoints` resets them. (#594)
+- **Persistent decision log** replacing the per-agent BM25 memory. Decisions
+  are stored automatically at the end of `propagate()`; the next same-ticker
+  run resolves prior pending entries with realised return, alpha vs SPY, and
+  a one-paragraph reflection. Override path with `TRADINGAGENTS_MEMORY_LOG_PATH`.
+  Optional `memory_log_max_entries` config caps resolved entries; pending
+  entries are never pruned. (#578, #563, #564, #579)
+- **DeepSeek, Qwen (Alibaba DashScope), GLM (Zhipu), and Azure OpenAI**
+  providers, plus dynamic OpenRouter model selection.
+- **Docker support** — multi-stage build with separate dev and runtime images.
+- **`scripts/smoke_structured_output.py`** — diagnostic that exercises the
+  three structured-output agents against any provider so contributors can
+  verify their setup with one command.
+- **5-tier rating scale** (Buy / Overweight / Hold / Underweight / Sell) used
+  consistently by Research Manager, Portfolio Manager, signal processor, and
+  the memory log; Trader keeps 3-tier (Buy / Hold / Sell) since transaction
+  direction is naturally ternary.
+- **Pytest fixtures** — lazy LLM client imports plus placeholder API keys so
+  the test suite runs cleanly without credentials. (#588)
+
+### Changed
+
+- **`backend_url` default is now `None`** rather than the OpenAI URL. Each
+  provider client falls back to its native default. The previous default
+  leaked the OpenAI URL into non-OpenAI clients (e.g. Gemini), producing
+  malformed request URLs for Python users who switched providers without
+  overriding `backend_url`. The CLI flow is unaffected.
+- All file I/O passes explicit `encoding="utf-8"` so Windows users no longer
+  hit `UnicodeEncodeError` with the cp1252 default. (#543, #550, #576)
+- Cache and log directories moved to `~/.tradingagents/` to resolve Docker
+  permission issues. (#519)
+- `SignalProcessor` reads the rating from the Portfolio Manager's rendered
+  markdown via a deterministic heuristic — no extra LLM call.
+- OpenAI structured-output calls default to `method="function_calling"` to
+  avoid noisy `PydanticSerializationUnexpectedValue` warnings emitted by
+  langchain-openai's Responses-API parse path. Same typed result, no warnings.
+
+### Fixed
+
+- Empty memory no longer triggers fabricated past-lessons in agent prompts;
+  the memory-log redesign makes this structurally impossible since only the
+  Portfolio Manager consults memory and only when entries exist. (#572)
+- Tool-call logging processes every chunk message, not just the last one, and
+  memory score normalization handles empty score arrays. (#534, #531)
+
+### Removed
+
+- `FinancialSituationMemory` (the per-agent BM25 system) and the dead
+  `reflect_and_remember()` plumbing; subsumed by the persistent decision log.
+- Hardcoded Google endpoint that caused 404 when `langchain-google-genai`
+  changed its API path. (#493, #496)
+
+### Contributors
+
+Thanks to everyone who shaped this release through code, design, and reports:
+
+- [@claytonbrown](https://github.com/claytonbrown) — checkpoint resume (#594), test fixtures (#588), design feedback on cost tracking (#582) and structured validation (#583)
+- [@Bcardo](https://github.com/Bcardo) — memory-log redesign (#579), empty-memory hallucination report (#572), encoding fix proposal (#570)
+- [@voidborne-d](https://github.com/voidborne-d) — memory persistence design (#564), portfolio manager state fix (#503)
+- [@mannubaveja007](https://github.com/mannubaveja007) — structured-output feature request (#434)
+- [@kelder66](https://github.com/kelder66) — RAM-only memory issue (#563)
+- [@Gujiassh](https://github.com/Gujiassh) — tool-call logging fix (#534), test stub PR (#533)
+- [@iuyup](https://github.com/iuyup) — memory score normalization fix (#531)
+- [@kaihg](https://github.com/kaihg) — Google base_url fix (#496)
+- [@32ryh98yfe](https://github.com/32ryh98yfe) — Gemini 404 report (#493)
+- [@uppb](https://github.com/uppb) — OpenRouter dynamic model selection (#482)
+- [@guoz14](https://github.com/guoz14) — OpenRouter limited-model report (#337)
+- [@samchenku](https://github.com/samchenku) — indicator name normalization (#490)
+- [@JasonOA888](https://github.com/JasonOA888) — y_finance pandas import fix (#488)
+- [@tiffanychum](https://github.com/tiffanychum) — stale import cleanup (#499)
+- [@zaizou](https://github.com/zaizou) — Docker permission issue (#519)
+- [@Stosman123](https://github.com/Stosman123), [@mauropuga](https://github.com/mauropuga), [@hotwind2015](https://github.com/hotwind2015) — Windows encoding bug reports (#543, #550, #576)
+- [@nnishad](https://github.com/nnishad), [@atharvajoshi01](https://github.com/atharvajoshi01) — encoding fix proposals (#568, #549)
+
+## [0.2.3] — 2026-03-29
+
+### Added
+
+- **Multi-language output** for analyst reports and final decisions, with a
+  CLI selector. Internal agent debate stays in English for reasoning quality. (#472)
+- **GPT-5.4 family models** in the default catalog, with deep/quick model split.
+- **Unified model catalog** as a single source of truth for CLI options and
+  provider validation.
+
+### Changed
+
+- `base_url` is forwarded to Google and Anthropic clients so corporate proxies
+  work consistently across providers. (#427)
+- Standardised the Google `api_key` parameter to the unified `api_key` form.
+
+### Fixed
+
+- Backtesting fetchers no longer leak look-ahead data when `curr_date` is in
+  the middle of a fetched window. (#475)
+- Invalid indicator names from the LLM are caught at the tool boundary instead
+  of crashing the run. (#429)
+- yfinance news fetchers respect the same exponential-backoff retry as price
+  fetchers. (#445)
+
+### Contributors
+
+- [@ahmedk20](https://github.com/ahmedk20) — multi-language output (#472)
+- [@CadeYu](https://github.com/CadeYu) — model catalog typing (#464)
+- [@javierdejesusda](https://github.com/javierdejesusda) — unified Google API key parameter (#453)
+- [@voidborne-d](https://github.com/voidborne-d) — yfinance news retry (#445)
+- [@kostakost2](https://github.com/kostakost2) — look-ahead bias report (#475)
+- [@lu-zhengda](https://github.com/lu-zhengda) — proxy/base_url support request (#427)
+- [@VamsiKrishna2021](https://github.com/VamsiKrishna2021) — invalid indicator crash report (#429)
+
+## [0.2.2] — 2026-03-22
+
+### Added
+
+- **Five-tier rating scale** (Buy / Overweight / Hold / Underweight / Sell)
+  introduced for the Portfolio Manager.
+- **Anthropic effort level** support for Claude models.
+- **OpenAI Responses API** path for native OpenAI models.
+
+### Changed
+
+- `risk_manager` renamed to `portfolio_manager` to match the role description
+  shown in the CLI display.
+- Exchange-qualified tickers (e.g. `7203.T`, `BRK.B`) preserved across all
+  agent prompts and tool calls.
+- Process-level UTF-8 default attempted for cross-platform consistency
+  (note: this approach did not actually take effect; replaced in v0.2.4 with
+  explicit per-call `encoding="utf-8"` arguments).
+
+### Fixed
+
+- yfinance rate-limit errors are retried with exponential backoff. (#426)
+- HTTP client SSL customisation is supported for environments that need
+  custom certificate bundles. (#379)
+- Report-section writes handle list-of-string content gracefully.
+
+### Contributors
+
+- [@CadeYu](https://github.com/CadeYu) — exchange-qualified ticker preservation (#413)
+- [@yang1002378395-cmyk](https://github.com/yang1002378395-cmyk) — HTTP client SSL customisation (#379)
+
+## [0.2.1] — 2026-03-15
+
+### Security
+
+- Patched `langchain-core` vulnerability (LangGrinch). (#335)
+- Removed `chainlit` dependency affected by CVE-2026-22218.
+
+### Added
+
+- `pyproject.toml` build-system configuration; the project now installs via
+  modern packaging tooling.
+
+### Removed
+
+- `setup.py` — dependencies consolidated to `pyproject.toml`.
+
+### Fixed
+
+- Risk manager reads the correct fundamental report source. (#341)
+- All `open()` calls receive an explicit UTF-8 encoding (initial pass).
+- `get_indicators` tool handles comma-separated indicator names from the LLM. (#368)
+- `Propagation` initialises every debate-state field so risk debaters never
+  see missing keys.
+- Stock data parsing tolerates malformed CSVs and NaN values.
+- Conditional debate logic respects the configured round count. (#361)
+
+### Contributors
+
+- [@RinZ27](https://github.com/RinZ27) — `langchain-core` security patch (#335)
+- [@Ljx-007](https://github.com/Ljx-007) — risk manager fundamental-report fix (#341)
+- [@makk9](https://github.com/makk9) — debate-rounds config issue (#361)
+
+## [0.2.0] — 2026-02-04
+
+This is the largest release since the initial public version. The framework
+moved from single-provider to a multi-provider architecture and grew several
+production-ready surfaces.
+
+### Added
+
+- **Multi-provider LLM support** (OpenAI, Google, Anthropic, xAI, OpenRouter,
+  Ollama) via a factory pattern, with provider-specific thinking configurations.
+- **Alpha Vantage** integration as a configurable primary data provider, with
+  yfinance as a community-stability fallback.
+- **Footer statistics** in the CLI: real-time tracking of LLM calls, tool
+  calls, and token usage via LangChain callbacks.
+- **Post-analysis report saving** — the framework writes per-section markdown
+  files (analyst reports, debate transcripts, final decision) when a run
+  completes.
+- **Announcements panel** — fetches updates from `api.tauric.ai/v1/announcements`
+  for the CLI welcome screen.
+- **Tool fallbacks** so a single vendor outage does not stop the pipeline.
+
+### Changed
+
+- Risky / Safe risk debaters renamed to **Aggressive / Conservative** for
+  consistency with the displayed agent labels.
+- Default data vendor switched to balance reliability and quota across
+  community deployments.
+- Ollama and OpenRouter model lists updated; default endpoints clarified.
+
+### Fixed
+
+- Analyst status tracking and message deduplication in the live display.
+- Infinite-loop guard in the agent loop; reflection and logging hardened.
+- Various data-vendor implementation bugs and tool-signature mismatches.
+
+### Contributors
+
+This release is the first with substantial outside contributions; many community
+PRs from late 2025 also landed here.
+
+- [@luohy15](https://github.com/luohy15) — Alpha Vantage data-vendor integration (#235)
+- [@EdwardoSunny](https://github.com/EdwardoSunny) — yfinance fetching optimisations (#245)
+- [@Mirza-Samad-Ahmed-Baig](https://github.com/Mirza-Samad-Ahmed-Baig) — infinite-loop guard, reflection, and logging fixes (#89)
+- [@ZeroAct](https://github.com/ZeroAct) — saved results path support (#29)
+- [@Zhongyi-Lu](https://github.com/Zhongyi-Lu) — `.env` gitignore (#49)
+- [@csoboy](https://github.com/csoboy) — local Ollama setup (#53)
+- [@chauhang](https://github.com/chauhang) — initial Docker support attempt (#47, later reverted; the merged Docker support shipped in v0.2.4)
+
+## [0.1.1] — 2025-06-07
+
+### Removed
+
+- Static site assets that had been bundled with v0.1.0; the public site now
+  lives separately.
+
+## [0.1.0] — 2025-06-05
+
+### Added
+
+- **Initial public release** of the TradingAgents multi-agent trading
+  framework: market / sentiment / news / fundamentals analysts; bull and bear
+  researchers; trader; aggressive, conservative, and neutral risk debaters;
+  portfolio manager. LangGraph orchestration, yfinance data, per-agent
+  BM25 memory, single-provider OpenAI integration, interactive CLI.
+
+[0.2.4]: https://github.com/TauricResearch/TradingAgents/compare/v0.2.3...v0.2.4
+[0.2.3]: https://github.com/TauricResearch/TradingAgents/compare/v0.2.2...v0.2.3
+[0.2.2]: https://github.com/TauricResearch/TradingAgents/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/TauricResearch/TradingAgents/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/TauricResearch/TradingAgents/compare/v0.1.1...v0.2.0
+[0.1.1]: https://github.com/TauricResearch/TradingAgents/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/TauricResearch/TradingAgents/releases/tag/v0.1.0

Dockerfile

@@ -0,0 +1,28 @@
+FROM python:3.12-slim AS builder
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1
+
+RUN python -m venv /opt/venv
+ENV PATH="/opt/venv/bin:$PATH"
+
+WORKDIR /build
+COPY . .
+RUN pip install --no-cache-dir .
+
+FROM python:3.12-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+
+COPY --from=builder /opt/venv /opt/venv
+ENV PATH="/opt/venv/bin:$PATH"
+
+RUN useradd --create-home appuser \
+ && install -d -m 0755 -o appuser -g appuser /home/appuser/.tradingagents
+USER appuser
+WORKDIR /home/appuser/app
+
+COPY --from=builder --chown=appuser:appuser /build .
+
+ENTRYPOINT ["tradingagents"]

README.md

@@ -5,12 +5,14 @@
 <div align="center" style="line-height: 1;">
   <a href="https://arxiv.org/abs/2412.20138" target="_blank"><img alt="arXiv" src="https://img.shields.io/badge/arXiv-2412.20138-B31B1B?logo=arxiv"/></a>
   <a href="https://discord.com/invite/hk9PGKShPK" target="_blank"><img alt="Discord" src="https://img.shields.io/badge/Discord-TradingResearch-7289da?logo=discord&logoColor=white&color=7289da"/></a>
-  <a href="./assets/wechat.png" target="_blank"><img alt="WeChat" src="https://img.shields.io/badge/WeChat-TauricResearch-brightgreen?logo=wechat&logoColor=white"/></a>
   <a href="https://x.com/TauricResearch" target="_blank"><img alt="X Follow" src="https://img.shields.io/badge/X-TauricResearch-white?logo=x&logoColor=white"/></a>
-  <br>
+  <a href="https://github.com/TauricResearch/" target="_blank"><img alt="Community" src="https://img.shields.io/badge/GitHub_Community-TauricResearch-14C290?logo=discourse"/></a>
-  <a href="https://github.com/TauricResearch/" target="_blank"><img alt="Community" src="https://img.shields.io/badge/Join_GitHub_Community-TauricResearch-14C290?logo=discourse"/></a>
 </div>
-
+<br>
+<div align="center">
+  <a href="https://github.com/TauricResearch" target="_blank"><img alt="TradingAgents #1 Repository of the Day" src="https://trendshift.io/api/badge/repositories/16192" width="250" height="55"/></a>
+</div>
+<br>
 <div align="center">
   <!-- Keep these links. Translations will automatically update with the README. -->
   <a href="https://www.readme-i18n.com/TauricResearch/TradingAgents?lang=de">Deutsch</a> | 
@@ -28,22 +30,22 @@
 # TradingAgents: Multi-Agents LLM Financial Trading Framework
 
 ## News
+- [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.
+
+<details>
+<summary>Earlier releases</summary>
+
+- [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.
+- [2026-03] **TradingAgents v0.2.3** released with multi-language support, GPT-5.4 family models, unified model catalog, backtesting date fidelity, and proxy support.
+- [2026-03] **TradingAgents v0.2.2** released with GPT-5.4/Gemini 3.1/Claude 4.6 model coverage, five-tier rating scale, OpenAI Responses API, Anthropic effort control, and cross-platform stability.
 - [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.
 
-<div align="center">
+</details>
-<a href="https://www.star-history.com/#TauricResearch/TradingAgents&Date">
- <picture>
-   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=TauricResearch/TradingAgents&type=Date&theme=dark" />
-   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=TauricResearch/TradingAgents&type=Date" />
-   <img alt="TradingAgents Star History" src="https://api.star-history.com/svg?repos=TauricResearch/TradingAgents&type=Date" style="width: 80%; height: auto;" />
- </picture>
-</a>
-</div>
-
-> 🎉 **TradingAgents** officially released! We have received numerous inquiries about the work, and we would like to express our thanks for the enthusiasm in our community.
->
-> So we decided to fully open-source the framework. Looking forward to building impactful projects with you!
 
 <div align="center">
 
@@ -51,6 +53,10 @@
 
 </div>
 
+> 🎉 **TradingAgents** officially released! We have received numerous inquiries about the work, and we would like to express our thanks for the enthusiasm in our community.
+>
+> So we decided to fully open-source the framework. Looking forward to building impactful projects with you!
+
 ## TradingAgents Framework
 
 TradingAgents is a multi-agent trading framework that mirrors the dynamics of real-world trading firms. By deploying specialized LLM-powered agents: from fundamental analysts, sentiment experts, and technical analysts, to trader, risk management team, the platform collaboratively evaluates market conditions and informs trading decisions. Moreover, these agents engage in dynamic discussions to pinpoint the optimal strategy.
@@ -61,11 +67,11 @@ TradingAgents is a multi-agent trading framework that mirrors the dynamics of re
 
 > TradingAgents framework is designed for research purposes. Trading performance may vary based on many factors, including the chosen backbone language models, model temperature, trading periods, the quality of data, and other non-deterministic factors. [It is not intended as financial, investment, or trading advice.](https://tauric.ai/disclaimer/)
 
-Our framework decomposes complex trading tasks into specialized roles. This ensures the system achieves a robust, scalable approach to market analysis and decision-making.
+Our framework decomposes complex trading tasks into specialized roles.
 
 ### Analyst Team
 - Fundamentals Analyst: Evaluates company financials and performance metrics, identifying intrinsic values and potential red flags.
-- Sentiment Analyst: Analyzes social media and public sentiment using sentiment scoring algorithms to gauge short-term market mood.
+- Sentiment Analyst: Aggregates news headlines, StockTwits, and Reddit chatter into a single sentiment read to gauge short-term market mood.
 - News Analyst: Monitors global news and macroeconomic indicators, interpreting the impact of events on market conditions.
 - Technical Analyst: Utilizes technical indicators (like MACD and RSI) to detect trading patterns and forecast price movements.
 
@@ -81,7 +87,7 @@ Our framework decomposes complex trading tasks into specialized roles. This ensu
 </p>
 
 ### Trader Agent
-- Composes reports from the analysts and researchers to make informed trading decisions. It determines the timing and magnitude of trades based on comprehensive market insights.
+- Composes reports from the analysts and researchers to make informed trading decisions, determining the timing and magnitude of trades.
 
 <p align="center">
   <img src="assets/trader.png" width="70%" style="display: inline-block; margin: 0 2%;">
@@ -107,13 +113,34 @@ cd TradingAgents
 
 Create a virtual environment in any of your favorite environment managers:
 ```bash
-conda create -n tradingagents python=3.13
+conda create -n tradingagents python=3.12
 conda activate tradingagents
 ```
 
-Install dependencies:
+Or with [uv](https://docs.astral.sh/uv/):
 ```bash
-pip install -r requirements.txt
+uv venv --python 3.12
+source .venv/bin/activate
+```
+
+Install the package and its dependencies (`uv pip install .` with uv):
+```bash
+pip install .
+```
+
+### Docker
+
+Alternatively, run with Docker:
+```bash
+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
 ```
 
 ### Required APIs
@@ -125,11 +152,29 @@ export OPENAI_API_KEY=...          # OpenAI (GPT)
 export GOOGLE_API_KEY=...          # Google (Gemini)
 export ANTHROPIC_API_KEY=...       # Anthropic (Claude)
 export XAI_API_KEY=...             # xAI (Grok)
+export DEEPSEEK_API_KEY=...        # DeepSeek
+export DASHSCOPE_API_KEY=...       # Qwen — International (dashscope-intl.aliyuncs.com)
+export DASHSCOPE_CN_API_KEY=...    # Qwen — China (dashscope.aliyuncs.com)
+export ZHIPU_API_KEY=...           # GLM via Z.AI (international)
+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
 ```
 
-For local models, configure Ollama with `llm_provider: "ollama"` in your config.
+For Azure OpenAI, copy `.env.enterprise.example` to `.env.enterprise` and fill in your credentials.
+
+For AWS Bedrock, install the extra with `pip install ".[bedrock]"`, set `llm_provider: "bedrock"`, configure AWS credentials (environment variables, `~/.aws/credentials`, or an IAM role) and `AWS_DEFAULT_REGION`, and use a Bedrock model ID, e.g. `us.anthropic.claude-opus-4-8-v1:0`.
+
+For local models, configure Ollama with `llm_provider: "ollama"`. The default endpoint is `http://localhost:11434/v1`; set `OLLAMA_BASE_URL` to point at a remote `ollama-serve`. Pull models with `ollama pull <name>`, and pick "Custom model ID" in the CLI for any model not listed by default.
+
+For any other OpenAI-compatible server (vLLM, LM Studio, llama.cpp, or a custom relay), use `llm_provider: "openai_compatible"` and set the endpoint via `backend_url` (or `TRADINGAGENTS_LLM_BACKEND_URL`), e.g. `http://localhost:8000/v1` for vLLM or `http://localhost:1234/v1` for LM Studio. The model is whatever your server serves. No key is needed for local servers; set `OPENAI_COMPATIBLE_API_KEY` when the endpoint requires one.
 
 Alternatively, copy `.env.example` to `.env` and fill in your keys:
 ```bash
@@ -138,11 +183,22 @@ cp .env.example .env
 
 ### CLI Usage
 
-You can also try out the CLI directly by running:
+Launch the interactive CLI:
 ```bash
-python -m cli.main
+tradingagents          # installed command
+python -m cli.main     # alternative: run directly from source
 ```
-You will see a screen where you can select your desired tickers, date, LLMs, research depth, etc.
+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
+
+TradingAgents works with any market Yahoo Finance covers, using the exchange-suffixed ticker. Company identity and the alpha benchmark resolve automatically per market.
+
+- US: `AAPL`, `SPY`
+- Hong Kong: `0700.HK` · Tokyo: `7203.T` · London: `AZN.L`
+- India: `RELIANCE.NS`, `.BO` · Canada: `.TO` · Australia: `.AX`
+- China A-shares: Shanghai `.SS`, Shenzhen `.SZ` (e.g. `600519.SS` for Kweichow Moutai)
+- Crypto: `BTC-USD`, `ETH-USD`
 
 <p align="center">
   <img src="assets/cli/cli_init.png" width="100%" style="display: inline-block; margin: 0 2%;">
@@ -162,7 +218,7 @@ An interface will appear showing results as they load, letting you track the age
 
 ### Implementation Details
 
-We built TradingAgents with LangGraph to ensure flexibility and modularity. The framework supports multiple LLM providers: OpenAI, Google, Anthropic, xAI, OpenRouter, and Ollama.
+We built TradingAgents with LangGraph to ensure flexibility and modularity. The framework supports multiple LLM providers: OpenAI, Google, Anthropic, xAI, DeepSeek, Qwen (Alibaba DashScope, international and China endpoints), GLM (Zhipu), MiniMax (global + China), OpenRouter, Ollama for local models, and Azure OpenAI for enterprise.
 
 ### Python Usage
 
@@ -175,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)
 ```
 
@@ -186,21 +242,129 @@ from tradingagents.graph.trading_graph import TradingAgentsGraph
 from tradingagents.default_config import DEFAULT_CONFIG
 
 config = DEFAULT_CONFIG.copy()
-config["llm_provider"] = "openai"        # openai, google, anthropic, xai, openrouter, ollama
+config["llm_provider"] = "openai"        # e.g. openai, google, anthropic, deepseek, groq, ollama; openai_compatible covers any OpenAI-compatible endpoint (vLLM, LM Studio, llama.cpp, ...)
-config["deep_think_llm"] = "gpt-5.2"     # Model for complex reasoning
+config["deep_think_llm"] = "gpt-5.6"      # Model for complex reasoning
-config["quick_think_llm"] = "gpt-5-mini" # Model for quick tasks
+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 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. 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/<TICKER>.db` (override the base with `TRADINGAGENTS_CACHE_DIR`). Use `--clear-checkpoints` to reset all of them before a run.
+
+```bash
+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-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.
+
+Language model sampling is non-deterministic. Even at a fixed temperature, providers do not guarantee byte-identical output across calls, and reasoning models (the default GPT-5.x family, and any thinking-mode model) vary the most because their internal reasoning is itself sampled.
+
+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 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, 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.
+
+Backtest results are not guaranteed to match any published figure. Returns depend on the model, the temperature, the date range, data quality, and the sampling above. Treat the framework as a research scaffold for studying multi-agent analysis, not as a strategy with a fixed, replicable return.
+
 ## Contributing
 
-We welcome contributions from the community! Whether it's fixing a bug, improving documentation, or suggesting a new feature, your input helps make this project better. If you are interested in this line of research, please consider joining our open-source financial AI research community [Tauric Research](https://tauric.ai/).
+Contributions are welcome: bug fixes, documentation, and feature ideas; past contributions are credited per release in [`CHANGELOG.md`](CHANGELOG.md).
 
 ## Citation
 

cli/announcements.py

@@ -1,4 +1,5 @@
 import getpass
+
 import requests
 from rich.console import Console
 from rich.panel import Panel

cli/models.py

@@ -1,10 +1,15 @@
 from enum import Enum
-from typing import List, Optional, Dict
-from pydantic import BaseModel
 
 
 class AnalystType(str, Enum):
     MARKET = "market"
+    # Wire value stays "social" for saved-config and string-keyed-caller
+    # back-compat; the user-facing label is "Sentiment Analyst".
     SOCIAL = "social"
     NEWS = "news"
     FUNDAMENTALS = "fundamentals"
+
+
+class AssetType(str, Enum):
+    STOCK = "stock"
+    CRYPTO = "crypto"

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

cli/stats_handler.py

@@ -1,9 +1,9 @@
 import threading
-from typing import Any, Dict, List, Union
+from typing import Any
 
 from langchain_core.callbacks import BaseCallbackHandler
-from langchain_core.outputs import LLMResult
 from langchain_core.messages import AIMessage
+from langchain_core.outputs import LLMResult
 
 
 class StatsCallbackHandler(BaseCallbackHandler):
@@ -19,8 +19,8 @@ class StatsCallbackHandler(BaseCallbackHandler):
 
     def on_llm_start(
         self,
-        serialized: Dict[str, Any],
+        serialized: dict[str, Any],
-        prompts: List[str],
+        prompts: list[str],
         **kwargs: Any,
     ) -> None:
         """Increment LLM call counter when an LLM starts."""
@@ -29,8 +29,8 @@ class StatsCallbackHandler(BaseCallbackHandler):
 
     def on_chat_model_start(
         self,
-        serialized: Dict[str, Any],
+        serialized: dict[str, Any],
-        messages: List[List[Any]],
+        messages: list[list[Any]],
         **kwargs: Any,
     ) -> None:
         """Increment LLM call counter when a chat model starts."""
@@ -57,7 +57,7 @@ class StatsCallbackHandler(BaseCallbackHandler):
 
     def on_tool_start(
         self,
-        serialized: Dict[str, Any],
+        serialized: dict[str, Any],
         input_str: str,
         **kwargs: Any,
     ) -> None:
@@ -65,7 +65,7 @@ class StatsCallbackHandler(BaseCallbackHandler):
         with self._lock:
             self.tool_calls += 1
 
-    def get_stats(self) -> Dict[str, Any]:
+    def get_stats(self) -> dict[str, Any]:
         """Return current statistics."""
         with self._lock:
             return {

cli/utils.py

@@ -1,25 +1,52 @@
-import questionary
+import os
-from typing import List, Optional, Tuple, Dict
+from pathlib import Path
 
+import questionary
+from dotenv import find_dotenv, set_key
 from rich.console import Console
 
-from cli.models import AnalystType
+from cli.models import AnalystType, AssetType
+from tradingagents.llm_clients.api_key_env import get_api_key_env
+from tradingagents.llm_clients.model_catalog import get_model_options
 
 console = Console()
 
+TICKER_INPUT_EXAMPLES = "SPY, 0700.HK, BTC-USD"
+
 ANALYST_ORDER = [
     ("Market Analyst", AnalystType.MARKET),
-    ("Social Media Analyst", AnalystType.SOCIAL),
+    ("Sentiment Analyst", AnalystType.SOCIAL),
     ("News Analyst", AnalystType.NEWS),
     ("Fundamentals Analyst", AnalystType.FUNDAMENTALS),
 ]
 
+CRYPTO_SUFFIXES = ("-USD", "-USDT", "-USDC", "-BTC", "-ETH")
+
+
+def is_valid_ticker_input(value: str) -> bool:
+    """Whether a ticker entry is acceptable (charset + length).
+
+    Allows the characters Yahoo symbols use, including ``=`` for futures/forex
+    like ``GC=F`` and ``EURUSD=X`` (#980), and ``^`` for indices. Empty input is
+    allowed (it defaults to SPY downstream).
+    """
+    v = value.strip()
+    return not v or (all(ch.isalnum() or ch in "._-^=" for ch in v) and len(v) <= 32)
+
 
 def get_ticker() -> str:
-    """Prompt the user to enter a ticker symbol."""
+    """Prompt the user to enter a ticker symbol, preserving exchange suffixes.
+
+    Uses questionary.text (not typer.prompt, which strips trailing dot-suffixes
+    like ``000404.SH`` on some shells) and validates the symbol charset so an
+    obvious typo is caught before the run starts.
+    """
     ticker = questionary.text(
-        "Enter the ticker symbol to analyze:",
+        f"Enter ticker symbol (e.g. {TICKER_INPUT_EXAMPLES}):",
-        validate=lambda x: len(x.strip()) > 0 or "Please enter a valid ticker symbol.",
+        validate=lambda x: (
+            is_valid_ticker_input(x)
+            or "Please enter a valid ticker symbol, e.g. AAPL, 000404.SZ, 0700.HK, GC=F."
+        ),
         style=questionary.Style(
             [
                 ("text", "fg:green"),
@@ -28,11 +55,48 @@ def get_ticker() -> str:
         ),
     ).ask()
 
-    if not ticker:
+    if ticker is None:
         console.print("\n[red]No ticker symbol provided. Exiting...[/red]")
         exit(1)
 
-    return ticker.strip().upper()
+    return normalize_ticker_symbol(ticker) if ticker.strip() else "SPY"
+
+
+def normalize_ticker_symbol(ticker: str) -> str:
+    """Resolve user input to its canonical Yahoo symbol (single source of truth).
+
+    Delegates to the data layer's ``normalize_symbol`` so the symbol the CLI
+    passes through the pipeline is exactly the one the data path will price
+    (e.g. ``BTCUSD`` -> ``BTC-USD``, ``XAUUSD`` -> ``GC=F``). Falls back to the
+    plain upper-case if the data layer is unavailable.
+    """
+    try:
+        from tradingagents.dataflows.symbol_utils import normalize_symbol
+
+        return normalize_symbol(ticker)
+    except Exception:
+        return ticker.strip().upper()
+
+
+def detect_asset_type(ticker: str) -> AssetType:
+    """Classify on the canonical symbol so e.g. BTCUSD and BTC-USDT both read as
+    crypto (#981/#982), matching what the data path will actually fetch."""
+    canonical = normalize_ticker_symbol(ticker)
+    if canonical.endswith(CRYPTO_SUFFIXES):
+        return AssetType.CRYPTO
+    return AssetType.STOCK
+
+
+def filter_analysts_for_asset_type(
+    analysts: list[AnalystType], asset_type: AssetType
+) -> list[AnalystType]:
+    if asset_type != AssetType.CRYPTO:
+        return analysts
+    return [
+        analyst
+        for analyst in analysts
+        if analyst != AnalystType.FUNDAMENTALS
+    ]
 
 
 def get_analysis_date() -> str:
@@ -68,12 +132,26 @@ def get_analysis_date() -> str:
     return date.strip()
 
 
-def select_analysts() -> List[AnalystType]:
+def _matching_choice(options, default):
-    """Select analysts using an interactive checkbox."""
+    """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,
+    )
     choices = questionary.checkbox(
         "Select Your [Analysts Team]:",
         choices=[
-            questionary.Choice(display, value=value) for display, value in ANALYST_ORDER
+            questionary.Choice(display, value=value, checked=value.value in (default or []))
+            for display, value in ANALYST_ORDER
+            if value in available_analysts
         ],
         instruction="\n- Press Space to select/unselect analysts\n- Press 'a' to select/unselect all\n- Press Enter when done",
         validate=lambda x: len(x) > 0 or "You must select at least one analyst.",
@@ -94,7 +172,7 @@ def select_analysts() -> 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
@@ -109,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(
             [
@@ -126,153 +205,233 @@ def select_research_depth() -> int:
     return choice
 
 
-def select_shallow_thinking_agent(provider) -> str:
+# Mainstream OpenRouter chat-LLM provider namespaces. We surface the newest
-    """Select shallow thinking llm engine using an interactive selection."""
+# models from these rather than the universal-newest, which is dominated by
+# niche/experimental releases. These are the general-purpose chat providers;
+# more enterprise/specialised namespaces (nvidia, cohere, amazon, ...) tend to
+# ship research/safety variants as their newest, so they're left out of the
+# shortlist. Provider names are stable (unlike model IDs), so this rarely needs
+# touching; anything not here is still reachable via Custom ID.
+_OPENROUTER_MAINSTREAM = {
+    "openai", "anthropic", "google", "deepseek", "qwen", "mistralai",
+    "meta-llama", "x-ai", "z-ai", "minimax", "moonshotai",
+}
 
-    # Define shallow thinking llm engine options with their corresponding model names
-    # Ordering: medium → light → heavy (balanced first for quick tasks)
-    # Within same tier, newer models first
-    SHALLOW_AGENT_OPTIONS = {
-        "openai": [
-            ("GPT-5 Mini - Balanced speed, cost, and capability", "gpt-5-mini"),
-            ("GPT-5 Nano - High-throughput, simple tasks", "gpt-5-nano"),
-            ("GPT-5.4 - Latest frontier, 1M context", "gpt-5.4"),
-            ("GPT-4.1 - Smartest non-reasoning model", "gpt-4.1"),
-        ],
-        "anthropic": [
-            ("Claude Sonnet 4.6 - Best speed and intelligence balance", "claude-sonnet-4-6"),
-            ("Claude Haiku 4.5 - Fast, near-instant responses", "claude-haiku-4-5"),
-            ("Claude Sonnet 4.5 - Agents and coding", "claude-sonnet-4-5"),
-        ],
-        "google": [
-            ("Gemini 3 Flash - Next-gen fast", "gemini-3-flash-preview"),
-            ("Gemini 2.5 Flash - Balanced, stable", "gemini-2.5-flash"),
-            ("Gemini 3.1 Flash Lite - Most cost-efficient", "gemini-3.1-flash-lite-preview"),
-            ("Gemini 2.5 Flash Lite - Fast, low-cost", "gemini-2.5-flash-lite"),
-        ],
-        "xai": [
-            ("Grok 4.1 Fast (Non-Reasoning) - Speed optimized, 2M ctx", "grok-4-1-fast-non-reasoning"),
-            ("Grok 4 Fast (Non-Reasoning) - Speed optimized", "grok-4-fast-non-reasoning"),
-            ("Grok 4.1 Fast (Reasoning) - High-performance, 2M ctx", "grok-4-1-fast-reasoning"),
-        ],
-        "openrouter": [
-            ("NVIDIA Nemotron 3 Nano 30B (free)", "nvidia/nemotron-3-nano-30b-a3b:free"),
-            ("Z.AI GLM 4.5 Air (free)", "z-ai/glm-4.5-air:free"),
-        ],
-        "ollama": [
-            ("Qwen3:latest (8B, local)", "qwen3:latest"),
-            ("GPT-OSS:latest (20B, local)", "gpt-oss:latest"),
-            ("GLM-4.7-Flash:latest (30B, local)", "glm-4.7-flash:latest"),
-        ],
-    }
 
-    choice = questionary.select(
+def _fetch_openrouter_models() -> list[tuple[str, str]]:
-        "Select Your [Quick-Thinking LLM Engine]:",
+    """Fetch available models from the OpenRouter API."""
-        choices=[
+    import requests
-            questionary.Choice(display, value=value)
+    try:
-            for display, value in SHALLOW_AGENT_OPTIONS[provider.lower()]
+        resp = requests.get("https://openrouter.ai/api/v1/models", timeout=10)
-        ],
+        resp.raise_for_status()
-        instruction="\n- Use arrow keys to navigate\n- Press Enter to select",
+        models = resp.json().get("data", [])
-        style=questionary.Style(
+        # Newest first so the top-N shown really is the latest available — the
-            [
+        # API currently returns this order, but sort explicitly so the prompt's
-                ("selected", "fg:magenta noinherit"),
+        # "latest available" label holds regardless of response ordering.
-                ("highlighted", "fg:magenta noinherit"),
+        models.sort(key=lambda m: m.get("created") or 0, reverse=True)
-                ("pointer", "fg:magenta noinherit"),
+        return [(m.get("name") or m["id"], m["id"]) for m in models]
-            ]
+    except Exception as e:
-        ),
+        console.print(f"\n[yellow]Could not fetch OpenRouter models: {e}[/yellow]")
+        return []
+
+
+def _require_text(message: str, hint: str) -> str:
+    """Prompt for a required value; exit cleanly if the user cancels.
+
+    ``questionary.text(...).ask()`` returns None on Ctrl-C/Esc; mirror the
+    exit-on-cancel behavior of the other required selections so a cancelled
+    prompt never returns an empty model/deployment that would fail downstream.
+    """
+    response = questionary.text(
+        message,
+        validate=lambda x: len(x.strip()) > 0 or hint,
     ).ask()
-
+    if response is None:
-    if choice is None:
+        console.print("\n[red]Cancelled. Exiting...[/red]")
-        console.print(
-            "\n[red]No shallow thinking llm engine selected. Exiting...[/red]"
-        )
         exit(1)
-
+    return response.strip()
-    return choice
 
 
-def select_deep_thinking_agent(provider) -> str:
+def select_openrouter_model(mode: str) -> str:
-    """Select deep thinking llm engine using an interactive selection."""
+    """Select an OpenRouter model from the newest available, or enter a custom ID.
 
-    # Define deep thinking llm engine options with their corresponding model names
+    ``mode`` ("quick"/"deep") labels the prompt so the two consecutive
-    # Ordering: heavy → medium → light (most capable first for deep tasks)
+    OpenRouter selections are distinguishable, like the other providers (#1000).
-    # Within same tier, newer models first
+    """
-    DEEP_AGENT_OPTIONS = {
+    models = _fetch_openrouter_models()  # newest first
-        "openai": [
+    # Prefer the newest from mainstream providers so the shortlist isn't crowded
-            ("GPT-5.4 - Latest frontier, 1M context", "gpt-5.4"),
+    # out by niche/experimental releases; fall back to all if none match.
-            ("GPT-5.2 - Strong reasoning, cost-effective", "gpt-5.2"),
+    mainstream = [
-            ("GPT-5 Mini - Balanced speed, cost, and capability", "gpt-5-mini"),
+        (name, mid) for name, mid in models
-            ("GPT-5.4 Pro - Most capable, expensive ($30/$180 per 1M tokens)", "gpt-5.4-pro"),
+        if not mid.startswith("~")  # skip variant/alias duplicate routes
-        ],
+        and mid.split("/", 1)[0] in _OPENROUTER_MAINSTREAM
-        "anthropic": [
-            ("Claude Opus 4.6 - Most intelligent, agents and coding", "claude-opus-4-6"),
-            ("Claude Opus 4.5 - Premium, max intelligence", "claude-opus-4-5"),
-            ("Claude Sonnet 4.6 - Best speed and intelligence balance", "claude-sonnet-4-6"),
-            ("Claude Sonnet 4.5 - Agents and coding", "claude-sonnet-4-5"),
-        ],
-        "google": [
-            ("Gemini 3.1 Pro - Reasoning-first, complex workflows", "gemini-3.1-pro-preview"),
-            ("Gemini 3 Flash - Next-gen fast", "gemini-3-flash-preview"),
-            ("Gemini 2.5 Pro - Stable pro model", "gemini-2.5-pro"),
-            ("Gemini 2.5 Flash - Balanced, stable", "gemini-2.5-flash"),
-        ],
-        "xai": [
-            ("Grok 4 - Flagship model", "grok-4-0709"),
-            ("Grok 4.1 Fast (Reasoning) - High-performance, 2M ctx", "grok-4-1-fast-reasoning"),
-            ("Grok 4 Fast (Reasoning) - High-performance", "grok-4-fast-reasoning"),
-            ("Grok 4.1 Fast (Non-Reasoning) - Speed optimized, 2M ctx", "grok-4-1-fast-non-reasoning"),
-        ],
-        "openrouter": [
-            ("Z.AI GLM 4.5 Air (free)", "z-ai/glm-4.5-air:free"),
-            ("NVIDIA Nemotron 3 Nano 30B (free)", "nvidia/nemotron-3-nano-30b-a3b:free"),
-        ],
-        "ollama": [
-            ("GLM-4.7-Flash:latest (30B, local)", "glm-4.7-flash:latest"),
-            ("GPT-OSS:latest (20B, local)", "gpt-oss:latest"),
-            ("Qwen3:latest (8B, local)", "qwen3:latest"),
-        ],
-    }
-
-    choice = questionary.select(
-        "Select Your [Deep-Thinking LLM Engine]:",
-        choices=[
-            questionary.Choice(display, value=value)
-            for display, value in DEEP_AGENT_OPTIONS[provider.lower()]
-        ],
-        instruction="\n- Use arrow keys to navigate\n- Press Enter to select",
-        style=questionary.Style(
-            [
-                ("selected", "fg:magenta noinherit"),
-                ("highlighted", "fg:magenta noinherit"),
-                ("pointer", "fg:magenta noinherit"),
-            ]
-        ),
-    ).ask()
-
-    if choice is None:
-        console.print("\n[red]No deep thinking llm engine selected. Exiting...[/red]")
-        exit(1)
-
-    return choice
-
-def select_llm_provider() -> tuple[str, str]:
-    """Select the OpenAI api url using interactive selection."""
-    # Define OpenAI api options with their corresponding endpoints
-    BASE_URLS = [
-        ("OpenAI", "https://api.openai.com/v1"),
-        ("Google", "https://generativelanguage.googleapis.com/v1"),
-        ("Anthropic", "https://api.anthropic.com/"),
-        ("xAI", "https://api.x.ai/v1"),
-        ("Openrouter", "https://openrouter.ai/api/v1"),
-        ("Ollama", "http://localhost:11434/v1"),
     ]
+    top = (mainstream or models)[:5]
+
+    choices = [questionary.Choice(name, value=mid) for name, mid in top]
+    choices.append(questionary.Choice("Custom model ID", value="custom"))
+
+    choice = questionary.select(
+        f"Select Your [{mode.title()}-Thinking] OpenRouter Model (latest available):",
+        choices=choices,
+        instruction="\n- Use arrow keys to navigate\n- Press Enter to select",
+        style=questionary.Style([
+            ("selected", "fg:magenta noinherit"),
+            ("highlighted", "fg:magenta noinherit"),
+            ("pointer", "fg:magenta noinherit"),
+        ]),
+    ).ask()
+
+    if choice is None:
+        console.print("\n[red]No model selected. Exiting...[/red]")
+        exit(1)
+    if choice == "custom":
+        return _require_text(
+            "Enter OpenRouter model ID (e.g. google/gemma-4-26b-a4b-it):",
+            "Please enter a model ID.",
+        )
+    return choice
+
+
+def _prompt_custom_model_id() -> str:
+    """Prompt user to type a custom model ID."""
+    return _require_text("Enter model ID:", "Please enter a model ID.")
+
+
+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)
+
+    if provider.lower() == "azure":
+        return _require_text(
+            f"Enter Azure deployment name ({mode}-thinking):",
+            "Please enter a deployment name.",
+        )
+
+    choice = questionary.select(
+        f"Select Your [{mode.title()}-Thinking LLM Engine]:",
+        choices=[
+            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(
+            [
+                ("selected", "fg:magenta noinherit"),
+                ("highlighted", "fg:magenta noinherit"),
+                ("pointer", "fg:magenta noinherit"),
+            ]
+        ),
+    ).ask()
+
+    if choice is None:
+        console.print(f"\n[red]No {mode} thinking llm engine selected. Exiting...[/red]")
+        exit(1)
+
+    if choice == "custom":
+        return _prompt_custom_model_id()
+
+    return choice
+
+
+def select_shallow_thinking_agent(provider, default=None) -> str:
+    """Select shallow thinking llm engine using an interactive selection."""
+    return _select_model(provider, "quick", default)
+
+
+def select_deep_thinking_agent(provider, default=None) -> str:
+    """Select deep thinking llm engine using an interactive selection."""
+    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.
+
+    Shared by the interactive picker and by env-driven configuration so an
+    env-set provider resolves to the same default endpoint the menu uses.
+    Ollama users can point at a remote ollama-serve via OLLAMA_BASE_URL
+    (convention from the broader Ollama ecosystem); falls back to the
+    localhost default when unset.
+    """
+    ollama_url = os.environ.get("OLLAMA_BASE_URL") or "http://localhost:11434/v1"
+    return [
+        ("OpenAI", "openai", "https://api.openai.com/v1"),
+        ("Google", "google", None),
+        ("Anthropic", "anthropic", "https://api.anthropic.com/"),
+        ("xAI", "xai", "https://api.x.ai/v1"),
+        ("DeepSeek", "deepseek", "https://api.deepseek.com"),
+        ("Qwen", "qwen", "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"),
+        # 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"),
+        ("Kimi (Moonshot)", "kimi", "https://api.moonshot.ai/v1"),
+        ("Groq", "groq", "https://api.groq.com/openai/v1"),
+        ("NVIDIA NIM", "nvidia", "https://integrate.api.nvidia.com/v1"),
+        ("Azure OpenAI", "azure", None),
+        ("Amazon Bedrock", "bedrock", None),
+        ("Ollama", "ollama", ollama_url),
+        ("OpenAI-compatible (vLLM, LM Studio, llama.cpp, custom relay)", "openai_compatible", None),
+    ]
+
+
+def provider_default_url(provider_key: str) -> str | None:
+    """Return the default backend URL for a provider key, or None if unknown."""
+    key = provider_key.lower()
+    for _, pk, url in _llm_provider_table():
+        if pk == key:
+            return url
+    return None
+
+
+def resolve_backend_url(
+    provider: str, menu_url: str | None = None, env_url: str | None = None
+) -> str | None:
+    """Resolve the backend URL with the correct precedence.
+
+    An explicit env override (``env_url``, from ``TRADINGAGENTS_LLM_BACKEND_URL``
+    via ``DEFAULT_CONFIG['backend_url']``) is honored regardless of how the
+    provider was chosen — interactively or from the environment (#978).
+    Otherwise the menu/region URL, then the provider's default.
+    """
+    return env_url or menu_url or provider_default_url(provider)
+
+
+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()
+    if not url:
+        console.print("\n[red]No endpoint URL provided. Exiting...[/red]")
+        exit(1)
+    return url.strip()
+
+
+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:",
         choices=[
-            questionary.Choice(display, value=(display, value))
+            questionary.Choice(display, value=(provider_key, url))
-            for display, value in BASE_URLS
+            for display, provider_key, url in PROVIDERS
         ],
+        default=preselected,
         instruction="\n- Use arrow keys to navigate\n- Press Enter to select",
         style=questionary.Style(
             [
@@ -284,13 +443,11 @@ def select_llm_provider() -> tuple[str, str]:
     ).ask()
 
     if choice is None:
-        console.print("\n[red]no OpenAI backend selected. Exiting...[/red]")
+        console.print("\n[red]No LLM provider selected. Exiting...[/red]")
         exit(1)
 
-    display_name, url = choice
+    provider, url = choice
-    print(f"You selected: {display_name}\tURL: {url}")
+    return provider, url
-
-    return display_name, url
 
 
 def ask_openai_reasoning_effort() -> str:
@@ -311,6 +468,28 @@ def ask_openai_reasoning_effort() -> str:
     ).ask()
 
 
+def ask_anthropic_effort() -> str | None:
+    """Ask for Anthropic effort level.
+
+    Controls token usage and response thoroughness on Claude 4.5 / 4.6 / 4.7
+    models. The API also accepts "max"; we expose low/medium/high as the
+    common selection range.
+    """
+    return questionary.select(
+        "Select Effort Level:",
+        choices=[
+        questionary.Choice("High (recommended)", "high"),
+        questionary.Choice("Medium (balanced)", "medium"),
+        questionary.Choice("Low (faster, cheaper)", "low"),
+        ],
+        style=questionary.Style([
+            ("selected", "fg:cyan noinherit"),
+            ("highlighted", "fg:cyan noinherit"),
+            ("pointer", "fg:cyan noinherit"),
+        ]),
+    ).ask()
+
+
 def ask_gemini_thinking_config() -> str | None:
     """Ask for Gemini thinking configuration.
 
@@ -320,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("Enable Thinking (recommended)", "high"),
-            questionary.Choice("Minimal/Disable Thinking", "minimal"),
+        questionary.Choice("Minimal/Disable Thinking", "minimal"),
         ],
         style=questionary.Style([
             ("selected", "fg:green noinherit"),
@@ -329,3 +508,211 @@ def ask_gemini_thinking_config() -> str | None:
             ("pointer", "fg:green noinherit"),
         ]),
     ).ask()
+
+
+def ask_glm_region() -> tuple[str, str]:
+    """Ask which GLM platform (Z.AI international vs BigModel China) to use.
+
+    Zhipu serves the same GLM models under two brands with separate
+    accounts; keys aren't interchangeable. Returns (provider_key, backend_url).
+    """
+    return questionary.select(
+        "Select GLM platform:",
+        choices=[
+            questionary.Choice(
+                "Z.AI — api.z.ai (international, uses ZHIPU_API_KEY)",
+                value=("glm", "https://api.z.ai/api/paas/v4/"),
+            ),
+            questionary.Choice(
+                "BigModel — open.bigmodel.cn (China, uses ZHIPU_CN_API_KEY)",
+                value=("glm-cn", "https://open.bigmodel.cn/api/paas/v4/"),
+            ),
+        ],
+        style=questionary.Style([
+            ("selected", "fg:cyan noinherit"),
+            ("highlighted", "fg:cyan noinherit"),
+            ("pointer", "fg:cyan noinherit"),
+        ]),
+    ).ask()
+
+
+def ask_qwen_region() -> tuple[str, str]:
+    """Ask which Qwen region (international vs China) to use.
+
+    Alibaba DashScope exposes two endpoints with separate accounts —
+    a key from one region does NOT authenticate against the other
+    (fixes #758). Returns (provider_key, backend_url).
+    """
+    return questionary.select(
+        "Select Qwen region:",
+        choices=[
+            questionary.Choice(
+                "International — dashscope-intl.aliyuncs.com (uses DASHSCOPE_API_KEY)",
+                value=("qwen", "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"),
+            ),
+            questionary.Choice(
+                "China — dashscope.aliyuncs.com (uses DASHSCOPE_CN_API_KEY)",
+                value=("qwen-cn", "https://dashscope.aliyuncs.com/compatible-mode/v1"),
+            ),
+        ],
+        style=questionary.Style([
+            ("selected", "fg:cyan noinherit"),
+            ("highlighted", "fg:cyan noinherit"),
+            ("pointer", "fg:cyan noinherit"),
+        ]),
+    ).ask()
+
+
+def ask_minimax_region() -> tuple[str, str]:
+    """Ask which MiniMax region (global vs China) to use.
+
+    MiniMax exposes two endpoints with separate accounts — a key from
+    one region does NOT authenticate against the other. Returns
+    (provider_key, backend_url).
+    """
+    return questionary.select(
+        "Select MiniMax region:",
+        choices=[
+            questionary.Choice(
+                "Global — api.minimax.io (uses MINIMAX_API_KEY)",
+                value=("minimax", "https://api.minimax.io/v1"),
+            ),
+            questionary.Choice(
+                "China — api.minimaxi.com (uses MINIMAX_CN_API_KEY)",
+                value=("minimax-cn", "https://api.minimaxi.com/v1"),
+            ),
+        ],
+        style=questionary.Style([
+            ("selected", "fg:cyan noinherit"),
+            ("highlighted", "fg:cyan noinherit"),
+            ("pointer", "fg:cyan noinherit"),
+        ]),
+    ).ask()
+
+
+def confirm_ollama_endpoint(url: str) -> None:
+    """Show the resolved Ollama endpoint after provider selection.
+
+    Surfaces three things the user benefits from seeing before model
+    selection: which URL we'll actually hit, where it came from
+    (`OLLAMA_BASE_URL` vs default), and a soft warning if the URL is
+    missing the scheme/port that ollama-serve expects. The warning is
+    advisory only — we don't reject malformed input, since the user may
+    be doing something deliberately unusual (e.g. a reverse-proxy path).
+    """
+    from_env = os.environ.get("OLLAMA_BASE_URL")
+    origin = " (from OLLAMA_BASE_URL)" if from_env and from_env == url else ""
+    console.print(f"[green]✓ Using Ollama at {url}{origin}[/green]")
+
+    if not url.startswith(("http://", "https://")):
+        console.print(
+            f"[yellow]Note: {url!r} is missing a scheme. "
+            f"Ollama-serve typically expects a URL like "
+            f"http://<host>:11434/v1.[/yellow]"
+        )
+    elif ":11434" not in url and "://localhost" not in url and "://127.0.0.1" not in url:
+        # Soft hint when the port differs from the ollama-serve default
+        # and the host isn't local (where users sometimes proxy on :80).
+        console.print(
+            f"[yellow]Note: {url!r} doesn't include port 11434. "
+            f"Make sure your remote ollama-serve listens on the port "
+            f"shown above.[/yellow]"
+        )
+
+
+def ensure_api_key(provider: str) -> str | None:
+    """Make sure the API key for `provider` is available in the environment.
+
+    If the env var is already set, returns its value untouched. Otherwise
+    interactively prompts the user, persists the value to the project's
+    .env file via python-dotenv's set_key (creating .env if needed), and
+    exports it into os.environ so the current process picks it up.
+
+    Returns None for providers that do not require a key (e.g. ollama)
+    and for providers not found in the canonical mapping.
+    """
+    env_var = get_api_key_env(provider)
+    if env_var is None:
+        return None  # ollama / unknown — no key check possible
+
+    # Key-optional providers (generic OpenAI-compatible / local servers) read the
+    # key when present but must never force an interactive prompt.
+    from tradingagents.llm_clients.openai_client import OPENAI_COMPATIBLE_PROVIDERS
+    spec = OPENAI_COMPATIBLE_PROVIDERS.get(provider.lower())
+    if spec is not None and spec.key_optional:
+        return os.environ.get(env_var)
+
+    existing = os.environ.get(env_var)
+    if existing:
+        return existing
+
+    console.print(
+        f"\n[yellow]{env_var} is not set in your environment.[/yellow]"
+    )
+    key = questionary.password(
+        f"Paste your {env_var} (will be saved to .env):",
+        style=questionary.Style([
+            ("text", "fg:cyan"),
+            ("highlighted", "noinherit"),
+        ]),
+    ).ask()
+    if not key:
+        console.print(
+            f"[red]Skipped. API calls will fail until {env_var} is set.[/red]"
+        )
+        return None
+
+    env_path = find_dotenv(usecwd=True) or str(Path.cwd() / ".env")
+    # 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(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=choices,
+        default=_matching_choice([(c.title, c.value) for c in choices], default),
+        style=questionary.Style([
+            ("selected", "fg:yellow noinherit"),
+            ("highlighted", "fg:yellow noinherit"),
+            ("pointer", "fg:yellow noinherit"),
+        ]),
+    ).ask()
+
+    # Output language has a sensible default, so a cancel falls back to English
+    # rather than exiting the run (unlike the required model/provider prompts).
+    if choice is None:
+        return "English"
+    if choice == "custom":
+        return (questionary.text(
+            "Enter language name (e.g. Turkish, Vietnamese, Thai, Indonesian):",
+            validate=lambda x: len(x.strip()) > 0 or "Please enter a language name.",
+        ).ask() or "").strip() or "English"
+
+    return choice

docker-compose.yml

@@ -0,0 +1,36 @@
+services:
+  tradingagents:
+    build: .
+    env_file:
+      - .env
+    volumes:
+      - tradingagents_data:/home/appuser/.tradingagents
+    tty: true
+    stdin_open: true
+
+  ollama:
+    image: ollama/ollama:latest
+    volumes:
+      - ollama_data:/root/.ollama
+    profiles:
+      - ollama
+
+  tradingagents-ollama:
+    build: .
+    env_file:
+      - .env
+    environment:
+      - TRADINGAGENTS_LLM_PROVIDER=ollama
+      - OLLAMA_BASE_URL=http://ollama:11434/v1
+    volumes:
+      - tradingagents_data:/home/appuser/.tradingagents
+    depends_on:
+      - ollama
+    tty: true
+    stdin_open: true
+    profiles:
+      - ollama
+
+volumes:
+  tradingagents_data:
+  ollama_data:

main.py

@@ -1,31 +1,18 @@
-from tradingagents.graph.trading_graph import TradingAgentsGraph
 from tradingagents.default_config import DEFAULT_CONFIG
+from tradingagents.graph.trading_graph import TradingAgentsGraph
 
-from dotenv import load_dotenv
+# DEFAULT_CONFIG already applies TRADINGAGENTS_* env-var overrides
-
+# (llm_provider, deep_think_llm, quick_think_llm, backend_url, etc.),
-# Load environment variables from .env file
+# so users can switch models or endpoints purely via .env without
-load_dotenv()
+# editing this script. Override individual keys here only when you
-
+# want a hard-coded value that should ignore the environment.
-# Create a custom config
 config = DEFAULT_CONFIG.copy()
-config["deep_think_llm"] = "gpt-5-mini"  # Use a different model
-config["quick_think_llm"] = "gpt-5-mini"  # Use a different model
-config["max_debate_rounds"] = 1  # Increase debate rounds
-
-# Configure data vendors (default uses yfinance, no extra API keys needed)
-config["data_vendors"] = {
-    "core_stock_apis": "yfinance",           # Options: alpha_vantage, yfinance
-    "technical_indicators": "yfinance",      # Options: alpha_vantage, yfinance
-    "fundamental_data": "yfinance",          # Options: alpha_vantage, yfinance
-    "news_data": "yfinance",                 # Options: alpha_vantage, yfinance
-}
 
 # Initialize with custom config
 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

pyproject.toml

@@ -4,32 +4,39 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tradingagents"
-version = "0.2.1"
+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-google-genai>=2.1.5",
     "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",
-    "rank-bm25>=0.2.2",
-    "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>=0.2.63",
+    "yfinance>=1.4.1",
+]
+
+[project.optional-dependencies]
+dev = [
+    "ruff>=0.15",
+    "pytest>=8.0",
+    "pytest-subtests>=0.13",
+]
+# Amazon Bedrock support (AWS SigV4 auth + boto3). Optional so the core install
+# stays lean: pip install "tradingagents[bedrock]".
+bedrock = [
+    "langchain-aws>=1.5.0",
 ]
 
 [project.scripts]
@@ -37,3 +44,39 @@ tradingagents = "cli.main:app"
 
 [tool.setuptools.packages.find]
 include = ["tradingagents*", "cli*"]
+
+[tool.setuptools.package-data]
+cli = ["static/*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra --strict-markers"
+markers = [
+    "unit: fast isolated unit tests",
+    "integration: tests requiring external services",
+    "smoke: quick sanity-check tests",
+]
+filterwarnings = [
+    "ignore::DeprecationWarning",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+extend-exclude = ["results"]
+
+[tool.ruff.lint]
+# Standard "good defaults" rule set (pyflakes + pycodestyle + isort + bugbear +
+# pyupgrade + comprehensions/simplify). Line length (E501) and layout are owned
+# by the formatter; whole-repo `ruff format` adoption is deferred until the
+# open-PR backlog clears, to avoid mass merge conflicts.
+select = ["E", "W", "F", "I", "B", "UP", "C4", "SIM"]
+ignore = ["E501"]
+
+[tool.ruff.lint.per-file-ignores]
+"**/__init__.py" = ["F401"]   # intentional re-exports
+
+[tool.ruff.lint.isort]
+# Keep multiple aliased names from one module in a single combined import block
+# (e.g. the vendor re-exports in interface.py) instead of one statement per name.
+combine-as-imports = true

requirements.txt

@@ -1,21 +1 @@
-typing-extensions
+.
-langchain-core
-langchain-openai
-langchain-experimental
-pandas
-yfinance
-stockstats
-langgraph
-rank-bm25
-setuptools
-backtrader
-parsel
-requests
-tqdm
-pytz
-redis
-rich
-typer
-questionary
-langchain_anthropic
-langchain-google-genai

test.py

@@ -1,11 +0,0 @@
-import time
-from tradingagents.dataflows.y_finance import get_YFin_data_online, get_stock_stats_indicators_window, get_balance_sheet as get_yfinance_balance_sheet, get_cashflow as get_yfinance_cashflow, get_income_statement as get_yfinance_income_statement, get_insider_transactions as get_yfinance_insider_transactions
-
-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)

tests/__init__.py

@@ -0,0 +1 @@
+

tests/conftest.py

@@ -0,0 +1,67 @@
+"""Shared pytest fixtures that prevent CI hangs when API keys are absent."""
+
+import os
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+
+def pytest_configure(config):
+    for marker in ("unit", "integration", "smoke"):
+        config.addinivalue_line("markers", f"{marker}: {marker}-level tests")
+
+
+_API_KEY_ENV_VARS = (
+    "OPENAI_API_KEY",
+    "GOOGLE_API_KEY",
+    "ANTHROPIC_API_KEY",
+    "XAI_API_KEY",
+    "DEEPSEEK_API_KEY",
+    "DASHSCOPE_API_KEY",
+    "DASHSCOPE_CN_API_KEY",
+    "ZHIPU_API_KEY",
+    "ZHIPU_CN_API_KEY",
+    "MINIMAX_API_KEY",
+    "MINIMAX_CN_API_KEY",
+    "OPENROUTER_API_KEY",
+    "AZURE_OPENAI_API_KEY",
+    "ALPHA_VANTAGE_API_KEY",
+)
+
+
+@pytest.fixture(autouse=True)
+def _dummy_api_keys(monkeypatch):
+    for env_var in _API_KEY_ENV_VARS:
+        # `or` not a .get default: an env var present but empty (e.g. a key left
+        # blank in a .env copied from .env.example) must still get the placeholder.
+        monkeypatch.setenv(env_var, os.environ.get(env_var) or "placeholder")
+
+
+@pytest.fixture(autouse=True)
+def _isolate_config():
+    """Reset the global dataflows config before and after each test.
+
+    ``set_config`` merges (it never clears keys absent from the override), so a
+    test that sets e.g. ``tool_vendors`` would otherwise leak into later tests
+    and make routing behavior order-dependent. Replace the global outright so
+    every test starts from a clean DEFAULT_CONFIG.
+    """
+    import copy
+
+    import tradingagents.dataflows.config as config_module
+    import tradingagents.default_config as default_config
+
+    config_module._config = copy.deepcopy(default_config.DEFAULT_CONFIG)
+    yield
+    config_module._config = copy.deepcopy(default_config.DEFAULT_CONFIG)
+
+
+@pytest.fixture()
+def mock_llm_client():
+    client = MagicMock()
+    client.get_llm.return_value = MagicMock()
+    with patch(
+        "tradingagents.llm_clients.factory.create_llm_client",
+        return_value=client,
+    ):
+        yield client

tests/test_alpha_vantage_hardening.py

@@ -0,0 +1,213 @@
+"""Alpha Vantage request hardening.
+
+Regressions for #990 (no request timeout -> can hang), #991 (invalid-key
+responses mislabeled as rate limits and silently treated as transient), and
+#1115 (fundamentals look-ahead filter never ran because the payload is a JSON
+string, not a dict), and the date trim that keeps post-end_date bars out of a
+historical run.
+"""
+import json
+
+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
+
+    def raise_for_status(self):
+        pass
+
+
+def _patched_get(body, capture=None):
+    def fake_get(url, params=None, **kwargs):
+        if capture is not None:
+            capture.update(kwargs)
+        return _FakeResponse(body)
+    return fake_get
+
+
+@pytest.mark.unit
+def test_request_passes_timeout(monkeypatch):
+    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
+
+
+@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(utils.requests, "get", _patched_get(body))
+    with pytest.raises(av.AlphaVantageRateLimitError):
+        av._make_api_request("TIME_SERIES_DAILY", {"symbol": "AAPL"})
+
+
+@pytest.mark.unit
+def test_invalid_key_not_mislabeled_as_rate_limit(monkeypatch):
+    # AV's invalid-key notice mentions "API key"; it must NOT be treated as a
+    # (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(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(utils.requests, "get", _patched_get('{"Note": "API call frequency is 5 calls per minute."}'))
+        av._make_api_request("TIME_SERIES_DAILY", {"symbol": "AAPL"})
+
+
+_FUNDAMENTALS_JSON = json.dumps({
+    "symbol": "AAPL",
+    "annualReports": [
+        {"fiscalDateEnding": "2025-12-31", "totalAssets": "1"},   # future -> must drop
+        {"fiscalDateEnding": "2023-12-31", "totalAssets": "2"},   # past   -> must keep
+    ],
+    "quarterlyReports": [
+        {"fiscalDateEnding": "2024-06-30", "totalAssets": "3"},   # future -> must drop
+        {"fiscalDateEnding": "2023-09-30", "totalAssets": "4"},   # past   -> must keep
+    ],
+})
+
+
+@pytest.mark.unit
+def test_fundamentals_look_ahead_filter_runs_on_json_string(monkeypatch):
+    # #1115: the payload arrives as a JSON *string*; the old dict-only guard let
+    # future-dated fiscal periods leak into historical runs.
+    monkeypatch.setattr(avf, "_make_api_request", lambda fn, params: _FUNDAMENTALS_JSON)
+    out = avf.get_balance_sheet("AAPL", curr_date="2024-01-01")
+    assert isinstance(out, str)  # callers still receive a str
+    parsed = json.loads(out)
+    assert [r["fiscalDateEnding"] for r in parsed["annualReports"]] == ["2023-12-31"]
+    assert [r["fiscalDateEnding"] for r in parsed["quarterlyReports"]] == ["2023-09-30"]
+
+
+@pytest.mark.unit
+def test_fundamentals_no_curr_date_passes_through(monkeypatch):
+    monkeypatch.setattr(avf, "_make_api_request", lambda fn, params: _FUNDAMENTALS_JSON)
+    assert avf.get_income_statement("AAPL") == _FUNDAMENTALS_JSON
+
+
+@pytest.mark.unit
+def test_fundamentals_non_json_body_unchanged(monkeypatch):
+    monkeypatch.setattr(avf, "_make_api_request", lambda fn, params: "not-json")
+    assert avf.get_cashflow("AAPL", curr_date="2024-01-01") == "not-json"
+
+
+# ---------------------------------------------------------------------------
+# Date trim (see the rationale on the unguarded trim in alpha_vantage_common)
+# ---------------------------------------------------------------------------
+
+_DAILY_CSV = (
+    "timestamp,open,high,low,close,volume\n"
+    "2024-05-13,1,1,1,1,10\n"   # after end_date -> must never be served
+    "2024-05-10,1,1,1,1,10\n"
+    "2024-05-09,1,1,1,1,10\n"
+)
+
+
+@pytest.mark.unit
+def test_stock_data_is_trimmed_to_the_requested_window(monkeypatch):
+    monkeypatch.setattr(avs, "_make_api_request", lambda *a, **k: _DAILY_CSV)
+    out = avs.get_stock("IBM", "2024-05-09", "2024-05-10")
+    assert "2024-05-10" in out and "2024-05-09" in out
+    assert "2024-05-13" not in out, "bar after end_date leaked into the window"
+
+
+@pytest.mark.unit
+def test_unparseable_body_is_never_served_untrimmed(monkeypatch):
+    """The trim used to swallow the failure and return the whole body, putting
+    bars after end_date into a backtest. It must raise instead."""
+    monkeypatch.setattr(avs, "_make_api_request",
+                        lambda *a, **k: "timestamp,close\nnot-a-date,1\n")
+
+    with pytest.raises(ValueError):
+        avs.get_stock("IBM", "2024-05-09", "2024-05-10")
+
+
+@pytest.mark.unit
+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"

tests/test_analyst_execution.py

@@ -0,0 +1,90 @@
+import unittest
+
+from tradingagents.graph.analyst_execution import (
+    AnalystWallTimeTracker,
+    build_analyst_execution_plan,
+    get_initial_analyst_node,
+    sync_analyst_tracker_from_chunk,
+)
+
+
+class AnalystExecutionPlanTests(unittest.TestCase):
+    def test_build_plan_preserves_selected_order(self):
+        plan = build_analyst_execution_plan(["news", "market"])
+
+        self.assertEqual([spec.key for spec in plan.specs], ["news", "market"])
+        self.assertEqual(plan.specs[0].agent_node, "News Analyst")
+        self.assertEqual(plan.specs[0].tool_node, "tools_news")
+        self.assertEqual(plan.specs[0].clear_node, "Msg Clear News")
+
+    def test_rejects_unknown_analyst_keys(self):
+        with self.assertRaises(ValueError):
+            build_analyst_execution_plan(["market", "macro"])
+
+    def test_get_initial_analyst_node_uses_plan_metadata(self):
+        plan = build_analyst_execution_plan(["fundamentals", "news"])
+
+        self.assertEqual(
+            get_initial_analyst_node(plan),
+            "Fundamentals Analyst",
+        )
+
+    def test_social_key_displays_as_sentiment_analyst(self):
+        # The wire key stays "social" for saved-config back-compat, but the
+        # user-visible agent_node label must match the v0.2.5 rename so the
+        # wall-time summary and any future consumer of agent_node says
+        # "Sentiment Analyst" rather than the legacy "Social Analyst".
+        plan = build_analyst_execution_plan(["social"])
+        spec = plan.specs[0]
+        self.assertEqual(spec.key, "social")
+        self.assertEqual(spec.agent_node, "Sentiment Analyst")
+        self.assertEqual(spec.report_key, "sentiment_report")
+
+
+class AnalystWallTimeTrackerTests(unittest.TestCase):
+    def test_records_wall_time_when_analyst_completes(self):
+        plan = build_analyst_execution_plan(["market", "news"])
+        tracker = AnalystWallTimeTracker(plan)
+
+        tracker.mark_started("market", started_at=10.0)
+        tracker.mark_completed("market", completed_at=13.5)
+
+        self.assertEqual(tracker.get_wall_times(), {"market": 3.5})
+
+    def test_formats_summary_in_plan_order(self):
+        plan = build_analyst_execution_plan(["news", "market"])
+        tracker = AnalystWallTimeTracker(plan)
+
+        tracker.mark_started("market", started_at=20.0)
+        tracker.mark_completed("market", completed_at=22.25)
+        tracker.mark_started("news", started_at=10.0)
+        tracker.mark_completed("news", completed_at=14.0)
+
+        self.assertEqual(
+            tracker.format_summary(),
+            "Analyst wall time: News 4.00s | Market 2.25s",
+        )
+
+    def test_syncs_wall_time_from_sequential_chunks(self):
+        plan = build_analyst_execution_plan(["market", "news"])
+        tracker = AnalystWallTimeTracker(plan)
+
+        sync_analyst_tracker_from_chunk(tracker, {}, now=10.0)
+        self.assertEqual(tracker.get_wall_times(), {})
+
+        sync_analyst_tracker_from_chunk(
+            tracker,
+            {"market_report": "done"},
+            now=13.0,
+        )
+        self.assertEqual(tracker.get_wall_times(), {"market": 3.0})
+
+        sync_analyst_tracker_from_chunk(
+            tracker,
+            {"market_report": "done", "news_report": "done"},
+            now=18.0,
+        )
+        self.assertEqual(
+            tracker.get_wall_times(),
+            {"market": 3.0, "news": 5.0},
+        )

tests/test_anthropic_effort.py

@@ -0,0 +1,98 @@
+"""Tests for Anthropic effort-parameter gating (#831).
+
+Haiku (any version) and Sonnet 4.5 reject the ``effort`` parameter with a
+400. Only Opus 4.5+ and Sonnet 4.6+ accept it. The gate uses a per-family
+minimum version so future ``claude-{opus,sonnet}-X-Y`` releases inherit
+support automatically.
+"""
+
+import pytest
+
+from tradingagents.llm_clients import anthropic_client as mod
+
+
+def _capture_kwargs(monkeypatch):
+    captured: dict = {}
+    monkeypatch.setattr(
+        mod, "NormalizedChatAnthropic",
+        lambda **kwargs: captured.setdefault("kwargs", kwargs),
+    )
+    return captured
+
+
+@pytest.mark.unit
+class TestEffortGate:
+    @pytest.mark.parametrize(
+        "model",
+        [
+            "claude-haiku-4-5", "claude-haiku-5-0", "claude-haiku-4-7-preview",
+            # Sonnet 4.5 (and earlier) 400 on effort — only Sonnet 4.6+ supports it.
+            "claude-sonnet-4-5", "claude-sonnet-4-0",
+        ],
+    )
+    def test_unsupported_models_do_not_receive_effort(self, monkeypatch, model):
+        captured = _capture_kwargs(monkeypatch)
+        mod.AnthropicClient(model=model, effort="medium", api_key="x").get_llm()
+        assert "effort" not in captured["kwargs"]
+
+    @pytest.mark.parametrize(
+        "model",
+        [
+            "claude-opus-4-5", "claude-opus-4-6", "claude-opus-4-7",
+            "claude-sonnet-4-6",
+        ],
+    )
+    def test_current_opus_and_sonnet_receive_effort(self, monkeypatch, model):
+        captured = _capture_kwargs(monkeypatch)
+        mod.AnthropicClient(model=model, effort="high", api_key="x").get_llm()
+        assert captured["kwargs"]["effort"] == "high"
+
+    @pytest.mark.parametrize(
+        "model",
+        ["claude-opus-5-0", "claude-opus-4-8", "claude-sonnet-5-0"],
+    )
+    def test_future_opus_sonnet_inherit_effort_via_pattern(self, monkeypatch, model):
+        """Forward-compat: new Opus/Sonnet versions don't need a code change."""
+        captured = _capture_kwargs(monkeypatch)
+        mod.AnthropicClient(model=model, effort="low", api_key="x").get_llm()
+        assert captured["kwargs"]["effort"] == "low"
+
+    @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-opus-5", "claude-fable-5-1"],
+    )
+    def test_claude_5_family_receives_effort(self, monkeypatch, model):
+        captured = _capture_kwargs(monkeypatch)
+        mod.AnthropicClient(model=model, effort="high", api_key="x").get_llm()
+        assert captured["kwargs"]["effort"] == "high"
+
+    def test_mythos_preview_receives_effort(self, monkeypatch):
+        captured = _capture_kwargs(monkeypatch)
+        mod.AnthropicClient(
+            model="claude-mythos-preview", effort="medium", api_key="x"
+        ).get_llm()
+        assert captured["kwargs"]["effort"] == "medium"
+
+    def test_unknown_anthropic_model_does_not_receive_effort(self, monkeypatch):
+        """Default is conservative — unknown models don't get effort to avoid 400s."""
+        captured = _capture_kwargs(monkeypatch)
+        mod.AnthropicClient(
+            model="claude-experimental-x", effort="medium", api_key="x"
+        ).get_llm()
+        assert "effort" not in captured["kwargs"]
+
+    def test_other_kwargs_still_forwarded_when_effort_skipped(self, monkeypatch):
+        """Skipping effort must not break other passthrough kwargs."""
+        captured = _capture_kwargs(monkeypatch)
+        mod.AnthropicClient(
+            model="claude-haiku-4-5",
+            effort="medium",
+            api_key="placeholder",
+            max_tokens=1024,
+            timeout=30,
+        ).get_llm()
+        assert captured["kwargs"]["api_key"] == "placeholder"
+        assert captured["kwargs"]["max_tokens"] == 1024
+        assert captured["kwargs"]["timeout"] == 30
+        assert "effort" not in captured["kwargs"]

tests/test_api_key_env.py

@@ -0,0 +1,193 @@
+"""Tests for the canonical provider->env-var mapping and the CLI key-prompt helper."""
+
+from __future__ import annotations
+
+import os
+import stat
+from unittest.mock import patch
+
+import pytest
+
+from tradingagents.llm_clients.api_key_env import PROVIDER_API_KEY_ENV, get_api_key_env
+
+# ---- Mapping coverage -----------------------------------------------------
+
+
+def test_every_select_llm_provider_choice_has_an_entry():
+    """select_llm_provider() must not present a provider the mapping doesn't know about."""
+    # Mirrors the dropdown order in cli/utils.select_llm_provider so the two
+    # stay in lockstep. Region-specific keys (qwen-cn / minimax-cn / glm-cn)
+    # are reached via the secondary region prompt, so they must also be present.
+    expected = {
+        "openai", "google", "anthropic", "xai", "deepseek",
+        "qwen", "qwen-cn",
+        "glm", "glm-cn",
+        "minimax", "minimax-cn",
+        "openrouter", "azure", "ollama",
+    }
+    assert expected.issubset(PROVIDER_API_KEY_ENV.keys())
+
+
+@pytest.mark.parametrize(
+    "provider,env_var",
+    [
+        ("openai",     "OPENAI_API_KEY"),
+        ("anthropic",  "ANTHROPIC_API_KEY"),
+        ("google",     "GOOGLE_API_KEY"),
+        ("azure",      "AZURE_OPENAI_API_KEY"),
+        ("xai",        "XAI_API_KEY"),
+        ("deepseek",   "DEEPSEEK_API_KEY"),
+        ("qwen",       "DASHSCOPE_API_KEY"),
+        ("qwen-cn",    "DASHSCOPE_CN_API_KEY"),
+        ("glm",        "ZHIPU_API_KEY"),
+        ("glm-cn",     "ZHIPU_CN_API_KEY"),
+        ("minimax",    "MINIMAX_API_KEY"),
+        ("minimax-cn", "MINIMAX_CN_API_KEY"),
+        ("openrouter", "OPENROUTER_API_KEY"),
+    ],
+)
+def test_known_providers_resolve(provider, env_var):
+    assert get_api_key_env(provider) == env_var
+
+
+def test_ollama_has_no_key():
+    assert get_api_key_env("ollama") is None
+
+
+def test_unknown_provider_returns_none():
+    assert get_api_key_env("not-a-real-provider") is None
+
+
+def test_case_insensitive_lookup():
+    assert get_api_key_env("OpenAI") == "OPENAI_API_KEY"
+    assert get_api_key_env("QWEN-CN") == "DASHSCOPE_CN_API_KEY"
+
+
+# ---- ensure_api_key behavior ---------------------------------------------
+
+
+@pytest.fixture
+def cli_utils(monkeypatch):
+    """Import cli.utils with a fresh environment so module-level state is consistent."""
+    import importlib
+
+    import cli.utils as cli_utils_module
+    return importlib.reload(cli_utils_module)
+
+
+def test_ensure_api_key_returns_existing(monkeypatch, cli_utils):
+    monkeypatch.setenv("OPENAI_API_KEY", "sk-already-set")
+    result = cli_utils.ensure_api_key("openai")
+    assert result == "sk-already-set"
+
+
+def test_ensure_api_key_no_op_for_ollama(monkeypatch, cli_utils):
+    # Even with no env var set, ollama should not prompt and should return None.
+    monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+    with patch.object(cli_utils, "questionary") as mock_q:
+        result = cli_utils.ensure_api_key("ollama")
+    assert result is None
+    mock_q.password.assert_not_called()
+
+
+def test_ensure_api_key_unknown_provider_no_prompt(monkeypatch, cli_utils):
+    with patch.object(cli_utils, "questionary") as mock_q:
+        result = cli_utils.ensure_api_key("totally-fake-provider")
+    assert result is None
+    mock_q.password.assert_not_called()
+
+
+def test_ensure_api_key_prompts_and_writes_to_env(monkeypatch, tmp_path, cli_utils):
+    """When key is missing, user-pasted value must be written to .env AND os.environ."""
+    monkeypatch.delenv("DEEPSEEK_API_KEY", raising=False)
+    monkeypatch.chdir(tmp_path)
+
+    fake_prompt = type("P", (), {"ask": staticmethod(lambda: "sk-deepseek-test")})()
+    with patch.object(cli_utils.questionary, "password", return_value=fake_prompt):
+        result = cli_utils.ensure_api_key("deepseek")
+
+    assert result == "sk-deepseek-test"
+    assert os.environ["DEEPSEEK_API_KEY"] == "sk-deepseek-test"
+    env_file = tmp_path / ".env"
+    assert env_file.exists()
+    assert "DEEPSEEK_API_KEY" in env_file.read_text()
+    assert "sk-deepseek-test" in env_file.read_text()
+
+
+def test_ensure_api_key_user_cancels_returns_none(monkeypatch, tmp_path, cli_utils):
+    """Empty prompt response (user cancelled) must not write to .env."""
+    monkeypatch.delenv("XAI_API_KEY", raising=False)
+    monkeypatch.chdir(tmp_path)
+
+    fake_prompt = type("P", (), {"ask": staticmethod(lambda: None)})()
+    with patch.object(cli_utils.questionary, "password", return_value=fake_prompt):
+        result = cli_utils.ensure_api_key("xai")
+
+    assert result is None
+    assert "XAI_API_KEY" not in os.environ
+    # .env may or may not exist depending on find_dotenv's walk, but if it
+    # does it must not contain the key.
+    env_file = tmp_path / ".env"
+    if env_file.exists():
+        assert "XAI_API_KEY" not in env_file.read_text()
+
+
+def test_ensure_api_key_updates_existing_env_file(monkeypatch, tmp_path, cli_utils):
+    """An existing .env with other keys must be preserved on writeback."""
+    monkeypatch.delenv("OPENROUTER_API_KEY", raising=False)
+    monkeypatch.chdir(tmp_path)
+    env_file = tmp_path / ".env"
+    env_file.write_text("OPENAI_API_KEY=sk-existing\nOTHER=value\n")
+
+    fake_prompt = type("P", (), {"ask": staticmethod(lambda: "sk-openrouter-new")})()
+    with patch.object(cli_utils.questionary, "password", return_value=fake_prompt):
+        cli_utils.ensure_api_key("openrouter")
+
+    content = env_file.read_text()
+    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

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()

tests/test_bedrock_provider.py

@@ -0,0 +1,80 @@
+"""Amazon Bedrock — first-class native client via the optional langchain-aws extra.
+
+Auth uses the AWS credential chain (no single key env); the model is a Bedrock
+model ID / inference profile ID; langchain-aws is imported lazily with a clear
+install hint when the [bedrock] extra is absent.
+"""
+import sys
+
+import pytest
+
+from tradingagents.llm_clients.api_key_env import get_api_key_env
+from tradingagents.llm_clients.factory import create_llm_client
+from tradingagents.llm_clients.validators import validate_model
+
+
+@pytest.mark.unit
+def test_factory_routes_bedrock():
+    client = create_llm_client("bedrock", "us.anthropic.claude-opus-4-8-v1:0")
+    assert type(client).__name__ == "BedrockClient"
+
+
+@pytest.mark.unit
+def test_bedrock_any_model_and_no_key_env():
+    assert validate_model("bedrock", "any.model-id:0") is True
+    # Bedrock uses the AWS credential chain, so there is no single key env.
+    assert get_api_key_env("bedrock") is None
+
+
+@pytest.mark.unit
+def test_helpful_error_when_langchain_aws_absent(monkeypatch):
+    import tradingagents.llm_clients.bedrock_client as bc
+    monkeypatch.setattr(bc, "_BEDROCK_CLASS", None)
+    monkeypatch.setitem(sys.modules, "langchain_aws", None)  # force ImportError on import
+    with pytest.raises(ImportError, match=r"bedrock"):
+        create_llm_client("bedrock", "m").get_llm()
+
+
+def _capture_kwargs(monkeypatch):
+    """Stub _bedrock_class so the constructor kwargs are testable without the
+    optional langchain-aws extra installed."""
+    import tradingagents.llm_clients.bedrock_client as bc
+    captured = {}
+
+    class _FakeChat:
+        def __init__(self, **kwargs):
+            captured.update(kwargs)
+
+    monkeypatch.setattr(bc, "_bedrock_class", lambda: _FakeChat)
+    return captured
+
+
+@pytest.mark.unit
+def test_bearer_token_passed_as_api_key(monkeypatch):
+    # #1103: a Bedrock API key authenticates without AWS access keys.
+    captured = _capture_kwargs(monkeypatch)
+    monkeypatch.setenv("AWS_BEARER_TOKEN_BEDROCK", "bt-secret")
+    monkeypatch.setenv("AWS_DEFAULT_REGION", "us-east-1")
+    create_llm_client("bedrock", "us.anthropic.claude-opus-4-8-v1:0").get_llm()
+    assert captured["api_key"] == "bt-secret"
+    assert captured["region_name"] == "us-east-1"
+
+
+@pytest.mark.unit
+def test_no_bearer_token_omits_api_key(monkeypatch):
+    # Without a token, fall back to the AWS credential chain (no api_key kwarg).
+    captured = _capture_kwargs(monkeypatch)
+    monkeypatch.delenv("AWS_BEARER_TOKEN_BEDROCK", raising=False)
+    create_llm_client("bedrock", "us.anthropic.claude-opus-4-8-v1:0").get_llm()
+    assert "api_key" not in captured
+
+
+@pytest.mark.unit
+def test_construction_when_extra_installed(monkeypatch):
+    pytest.importorskip("langchain_aws")
+    import tradingagents.llm_clients.bedrock_client as bc
+    monkeypatch.setattr(bc, "_BEDROCK_CLASS", None)
+    monkeypatch.setenv("AWS_DEFAULT_REGION", "eu-west-1")
+    llm = create_llm_client("bedrock", "us.anthropic.claude-sonnet-5").get_llm()
+    assert type(llm).__name__ == "NormalizedChatBedrockConverse"
+    assert llm.region_name == "eu-west-1"

tests/test_capabilities.py

@@ -0,0 +1,155 @@
+"""Unit tests for the LLM capability table."""
+
+from dataclasses import FrozenInstanceError
+
+import pytest
+
+from tradingagents.llm_clients.capabilities import (
+    get_capabilities,
+)
+
+
+@pytest.mark.unit
+class TestExactIdMatches:
+    def test_deepseek_chat_supports_tool_choice(self):
+        caps = get_capabilities("deepseek-chat")
+        assert caps.supports_tool_choice is True
+
+    def test_deepseek_reasoner_rejects_tool_choice(self):
+        caps = get_capabilities("deepseek-reasoner")
+        assert caps.supports_tool_choice is False
+        assert caps.requires_reasoning_content_roundtrip is True
+
+    def test_deepseek_v4_flash_rejects_tool_choice(self):
+        caps = get_capabilities("deepseek-v4-flash")
+        assert caps.supports_tool_choice is False
+        assert caps.requires_reasoning_content_roundtrip is True
+
+    def test_deepseek_v4_pro_rejects_tool_choice(self):
+        caps = get_capabilities("deepseek-v4-pro")
+        assert caps.supports_tool_choice is False
+        assert caps.requires_reasoning_content_roundtrip is True
+
+
+@pytest.mark.unit
+class TestPatternMatches:
+    """Forward-compat regex patterns catch unknown DeepSeek and MiniMax variants."""
+
+    def test_future_deepseek_v5_inherits_thinking_quirks(self):
+        caps = get_capabilities("deepseek-v5-flash")
+        assert caps.supports_tool_choice is False
+        assert caps.requires_reasoning_content_roundtrip is True
+
+    def test_future_deepseek_v9_inherits_thinking_quirks(self):
+        caps = get_capabilities("deepseek-v9-anything")
+        assert caps.supports_tool_choice is False
+
+    def test_reasoner_variant_inherits_thinking_quirks(self):
+        caps = get_capabilities("deepseek-reasoner-pro")
+        assert caps.supports_tool_choice is False
+
+    def test_minimax_m3_inherits_thinking_quirks(self):
+        caps = get_capabilities("MiniMax-M3")
+        assert caps.supports_tool_choice is False
+
+    def test_future_minimax_m4_highspeed_inherits_thinking_quirks(self):
+        caps = get_capabilities("MiniMax-M4-highspeed")
+        assert caps.supports_tool_choice is False
+
+
+@pytest.mark.unit
+class TestMinimaxExactMatches:
+    """MiniMax M2.x models reject langchain's function-spec dict tool_choice
+    (official API enum: none/auto only)."""
+
+    def test_m2_7_rejects_tool_choice(self):
+        caps = get_capabilities("MiniMax-M2.7")
+        assert caps.supports_tool_choice is False
+        assert caps.supports_json_mode is False  # only MiniMax-Text-01 supports json_object
+
+    def test_m2_7_highspeed_rejects_tool_choice(self):
+        assert get_capabilities("MiniMax-M2.7-highspeed").supports_tool_choice is False
+
+    def test_m2_1_rejects_tool_choice(self):
+        assert get_capabilities("MiniMax-M2.1").supports_tool_choice is False
+
+    def test_m2_base_rejects_tool_choice(self):
+        assert get_capabilities("MiniMax-M2").supports_tool_choice is False
+
+    def test_m2_x_requires_reasoning_split(self):
+        # M2.x reasoning models need reasoning_split=True so <think> blocks
+        # land in reasoning_details instead of content (#826).
+        for model in ("MiniMax-M2.7", "MiniMax-M2.5-highspeed", "MiniMax-M2"):
+            assert get_capabilities(model).requires_reasoning_split is True
+
+    def test_future_m3_inherits_reasoning_split(self):
+        assert get_capabilities("MiniMax-M3-highspeed").requires_reasoning_split is True
+
+    def test_non_reasoning_minimax_does_not_get_reasoning_split(self):
+        # Coding Plan, MiniMax-Text-01, and any non-M2-prefixed MiniMax model
+        # reject the reasoning_split kwarg via the openai SDK's strict
+        # validation (#826). Default capability has it disabled.
+        for model in ("minimax-text-01", "MiniMax-Coding-Plan", "abab6.5-chat"):
+            assert get_capabilities(model).requires_reasoning_split is False
+
+
+@pytest.mark.unit
+class TestDefault:
+    """Unknown / non-DeepSeek models get the permissive default."""
+
+    def test_gpt_default(self):
+        caps = get_capabilities("gpt-4.1")
+        assert caps.supports_tool_choice is True
+        assert caps.preferred_structured_method == "function_calling"
+
+    def test_grok_default(self):
+        caps = get_capabilities("grok-4-0709")
+        assert caps.supports_tool_choice is True
+
+    def test_unknown_model_default(self):
+        caps = get_capabilities("totally-made-up-model-id")
+        assert caps.supports_tool_choice is True
+
+    def test_exact_match_precedes_pattern(self):
+        """deepseek-chat must NOT match the v\\d regex."""
+        caps = get_capabilities("deepseek-chat")
+        assert caps.supports_tool_choice is True
+
+
+@pytest.mark.unit
+class TestOpenRouterDeepSeekNamespace:
+    """OpenRouter namespaces DeepSeek as ``deepseek/<id>``; strip it so the
+    same quirks apply as the native provider (#1199)."""
+
+    def test_prefixed_v4_flash_suppresses_tool_choice(self):
+        # Was falling through to _DEFAULT (tool_choice on) -> slow object-form call.
+        assert get_capabilities("deepseek/deepseek-v4-flash").supports_tool_choice is False
+
+    def test_prefixed_reasoner_suppresses_tool_choice(self):
+        assert get_capabilities("deepseek/deepseek-reasoner").supports_tool_choice is False
+
+    def test_prefixed_chat_selects_deepseek_chat_not_default(self):
+        # Must resolve to _DEEPSEEK_CHAT, not _DEFAULT: supports_json_schema=False
+        # is what distinguishes them (both keep tool_choice).
+        caps = get_capabilities("deepseek/deepseek-chat")
+        assert caps.supports_tool_choice is True
+        assert caps.supports_json_schema is False  # _DEEPSEEK_CHAT, not _DEFAULT
+
+    def test_only_official_namespace_is_stripped(self):
+        # A third-party publisher whose model name WOULD match a deepseek pattern
+        # must stay _DEFAULT: proves we strip only "deepseek/", not any "*/".
+        caps = get_capabilities("tngtech/deepseek-v4-flash")
+        assert caps.supports_tool_choice is True         # not thinking
+        assert caps.supports_json_schema is True          # _DEFAULT
+
+    def test_native_ids_unchanged(self):
+        assert get_capabilities("deepseek-v4-flash").supports_tool_choice is False
+        assert get_capabilities("deepseek-chat").supports_tool_choice is True
+
+
+@pytest.mark.unit
+def test_capabilities_dataclass_is_frozen():
+    """Capability rows are immutable so they can be safely shared."""
+    caps = get_capabilities("deepseek-chat")
+    with pytest.raises(FrozenInstanceError):
+        caps.supports_tool_choice = False  # type: ignore[misc]

tests/test_checkpoint_lifecycle.py

@@ -0,0 +1,172 @@
+"""The checkpoint lifecycle is reusable so --checkpoint works on the CLI path (#1249).
+
+Checkpoint setup previously lived only inside ``propagate``; the CLI streamed the
+checkpointer-less graph, so ``--checkpoint`` neither saved nor resumed. The
+lifecycle is now ``begin_checkpoint`` / ``end_checkpoint`` /
+``clear_checkpoint_on_success`` on TradingAgentsGraph, used by both paths. These
+tests drive that lifecycle exactly as the CLI does (begin -> stream self.graph ->
+clear/end) and prove state is saved and resumed.
+"""
+from __future__ import annotations
+
+import tempfile
+from typing import TypedDict
+
+import pytest
+from langgraph.graph import END, StateGraph
+
+from tradingagents.graph.checkpointer import checkpoint_step
+from tradingagents.graph.trading_graph import TradingAgentsGraph
+
+_should_crash = False
+
+
+class _State(TypedDict):
+    count: int
+
+
+def _node_a(state: _State) -> dict:
+    return {"count": state["count"] + 1}
+
+
+def _node_b(state: _State) -> dict:
+    if _should_crash:
+        raise RuntimeError("simulated mid-stream crash")
+    return {"count": state["count"] + 10}
+
+
+def _workflow() -> StateGraph:
+    b = StateGraph(_State)
+    b.add_node("analyst", _node_a)
+    b.add_node("trader", _node_b)
+    b.set_entry_point("analyst")
+    b.add_edge("analyst", "trader")
+    b.add_edge("trader", END)
+    return b
+
+
+def _bare_graph(tmpdir, *, enabled=True):
+    g = object.__new__(TradingAgentsGraph)
+    g.config = {
+        "checkpoint_enabled": enabled, "data_cache_dir": tmpdir,
+        "max_debate_rounds": 1, "max_risk_discuss_rounds": 1,
+    }
+    g.selected_analysts = ("market",)
+    g.workflow = _workflow()
+    g.graph = g.workflow.compile()
+    g._checkpointer_ctx = None
+    return g
+
+
+
+
+@pytest.mark.unit
+def test_disabled_is_a_noop():
+    with tempfile.TemporaryDirectory() as tmp:
+        g = _bare_graph(tmp, enabled=False)
+        plain = g.graph
+        assert g.begin_checkpoint("AAPL", "2026-05-08", "stock") is None
+        assert g.graph is plain  # graph not recompiled
+        g.end_checkpoint()  # safe no-op
+
+
+@pytest.mark.unit
+def test_begin_returns_thread_id_and_recompiles():
+    with tempfile.TemporaryDirectory() as tmp:
+        g = _bare_graph(tmp)
+        plain = g.graph
+        tid = g.begin_checkpoint("AAPL", "2026-05-08", "stock")
+        try:
+            assert tid  # a real thread_id
+            assert g.graph is not plain  # recompiled with a checkpointer
+        finally:
+            g.end_checkpoint()
+        assert g._checkpointer_ctx is None  # restored
+
+
+@pytest.mark.unit
+def test_checkpoint_input_is_none_only_when_resuming():
+    global _should_crash
+    with tempfile.TemporaryDirectory() as tmp:
+        init = {"count": 0}
+        args = ("AAPL", "2026-05-08", "stock")
+        # Fresh run: no checkpoint yet -> stream the initial state, then crash.
+        g1 = _bare_graph(tmp)
+        tid = g1.begin_checkpoint(*args)
+        try:
+            assert g1._resuming is False
+            assert g1.checkpoint_input(init) is init  # not resuming -> initial state
+            _should_crash = True
+            with pytest.raises(RuntimeError):
+                for _ in g1.graph.stream(init, config={"configurable": {"thread_id": tid}}):
+                    pass
+        finally:
+            g1.end_checkpoint()
+        assert g1.checkpoint_input(init) is init  # reset after teardown
+
+        # A later run finds the checkpoint -> resume by feeding None, not the
+        # initial state (re-passing it would duplicate messages, #1249).
+        _should_crash = False
+        g2 = _bare_graph(tmp)
+        g2.begin_checkpoint(*args)
+        try:
+            assert g2._resuming is True
+            assert g2.checkpoint_input(init) is None
+        finally:
+            g2.end_checkpoint()
+
+
+@pytest.mark.unit
+def test_cli_style_usage_saves_then_resumes():
+    global _should_crash
+    with tempfile.TemporaryDirectory() as tmp:
+        cfg_args = ("AAPL", "2026-05-08", "stock")
+
+        # Run 1 (the CLI path): begin -> stream self.graph -> crash at 'trader'.
+        _should_crash = True
+        g1 = _bare_graph(tmp)
+        tid = g1.begin_checkpoint(*cfg_args)
+        args = {"config": {"configurable": {"thread_id": tid}}}
+        try:
+            with pytest.raises(RuntimeError):
+                for _ in g1.graph.stream({"count": 0}, **args):
+                    pass
+        finally:
+            g1.end_checkpoint()
+
+        # A checkpoint was saved for this run signature (so --checkpoint works).
+
+        sig = g1._run_signature("stock")
+        assert checkpoint_step(tmp, "AAPL", "2026-05-08", sig) is not None
+
+        # Run 2 (fresh graph, as a new CLI invocation): resume and finish.
+        _should_crash = False
+        g2 = _bare_graph(tmp)
+        tid2 = g2.begin_checkpoint(*cfg_args)
+        assert tid2 == tid  # stable id -> same thread resumes
+        try:
+            result = g2.graph.invoke(None, config={"configurable": {"thread_id": tid2}})
+            assert result["count"] == 11  # analyst(+1) resumed into trader(+10)
+            g2.clear_checkpoint_on_success(*cfg_args)
+        finally:
+            g2.end_checkpoint()
+
+        # 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()) == []

tests/test_checkpoint_resume.py

@@ -0,0 +1,218 @@
+"""Test checkpoint resume: crash mid-analysis, re-run resumes from last node."""
+
+import tempfile
+import unittest
+from typing import TypedDict
+
+from langgraph.graph import END, StateGraph
+
+from tradingagents.graph.checkpointer import (
+    checkpoint_step,
+    clear_checkpoint,
+    get_checkpointer,
+    has_checkpoint,
+    thread_id,
+)
+
+# Mutable flag to simulate crash on first run
+_should_crash = False
+
+
+class _SimpleState(TypedDict):
+    count: int
+
+
+def _node_a(state: _SimpleState) -> dict:
+    return {"count": state["count"] + 1}
+
+
+def _node_b(state: _SimpleState) -> dict:
+    if _should_crash:
+        raise RuntimeError("simulated mid-analysis crash")
+    return {"count": state["count"] + 10}
+
+
+def _build_graph() -> StateGraph:
+    builder = StateGraph(_SimpleState)
+    builder.add_node("analyst", _node_a)
+    builder.add_node("trader", _node_b)
+    builder.set_entry_point("analyst")
+    builder.add_edge("analyst", "trader")
+    builder.add_edge("trader", END)
+    return builder
+
+
+class TestCheckpointResume(unittest.TestCase):
+    def setUp(self):
+        self.tmpdir = tempfile.mkdtemp()
+        self.ticker = "TEST"
+        self.date = "2026-04-20"
+
+    def test_crash_and_resume(self):
+        """Crash at 'trader' node, then resume from checkpoint."""
+        global _should_crash
+        builder = _build_graph()
+        tid = thread_id(self.ticker, self.date)
+        cfg = {"configurable": {"thread_id": tid}}
+
+        # Run 1: crash at trader node
+        _should_crash = True
+        with get_checkpointer(self.tmpdir, self.ticker) as saver:
+            graph = builder.compile(checkpointer=saver)
+            with self.assertRaises(RuntimeError):
+                graph.invoke({"count": 0}, config=cfg)
+
+        # Checkpoint should exist at step 1 (analyst completed)
+        self.assertTrue(has_checkpoint(self.tmpdir, self.ticker, self.date))
+        step = checkpoint_step(self.tmpdir, self.ticker, self.date)
+        self.assertEqual(step, 1)
+
+        # Run 2: resume — trader succeeds this time
+        _should_crash = False
+        with get_checkpointer(self.tmpdir, self.ticker) as saver:
+            graph = builder.compile(checkpointer=saver)
+            result = graph.invoke(None, config=cfg)
+
+        # analyst added 1, trader added 10 → 11
+        self.assertEqual(result["count"], 11)
+
+    def test_clear_checkpoint_allows_fresh_start(self):
+        """After clearing, the graph starts from scratch."""
+        global _should_crash
+        builder = _build_graph()
+        tid = thread_id(self.ticker, self.date)
+        cfg = {"configurable": {"thread_id": tid}}
+
+        # Create a checkpoint by crashing
+        _should_crash = True
+        with get_checkpointer(self.tmpdir, self.ticker) as saver:
+            graph = builder.compile(checkpointer=saver)
+            with self.assertRaises(RuntimeError):
+                graph.invoke({"count": 0}, config=cfg)
+
+        self.assertTrue(has_checkpoint(self.tmpdir, self.ticker, self.date))
+
+        # Clear it
+        clear_checkpoint(self.tmpdir, self.ticker, self.date)
+        self.assertFalse(has_checkpoint(self.tmpdir, self.ticker, self.date))
+
+        # Fresh run succeeds from scratch
+        _should_crash = False
+        with get_checkpointer(self.tmpdir, self.ticker) as saver:
+            graph = builder.compile(checkpointer=saver)
+            result = graph.invoke({"count": 0}, config=cfg)
+
+        self.assertEqual(result["count"], 11)
+
+
+    def test_different_date_starts_fresh(self):
+        """A different date must NOT resume from an existing checkpoint."""
+        global _should_crash
+        builder = _build_graph()
+        date2 = "2026-04-21"
+
+        # Run with date1 — crash to leave a checkpoint
+        _should_crash = True
+        tid1 = thread_id(self.ticker, self.date)
+        with get_checkpointer(self.tmpdir, self.ticker) as saver:
+            graph = builder.compile(checkpointer=saver)
+            with self.assertRaises(RuntimeError):
+                graph.invoke({"count": 0}, config={"configurable": {"thread_id": tid1}})
+
+        self.assertTrue(has_checkpoint(self.tmpdir, self.ticker, self.date))
+
+        # date2 should have no checkpoint
+        self.assertFalse(has_checkpoint(self.tmpdir, self.ticker, date2))
+
+        # Run with date2 — should start fresh and succeed
+        _should_crash = False
+        tid2 = thread_id(self.ticker, date2)
+        self.assertNotEqual(tid1, tid2)
+
+        with get_checkpointer(self.tmpdir, self.ticker) as saver:
+            graph = builder.compile(checkpointer=saver)
+            result = graph.invoke({"count": 0}, config={"configurable": {"thread_id": tid2}})
+
+        # Fresh run: analyst +1, trader +10 = 11
+        self.assertEqual(result["count"], 11)
+
+        # Original date checkpoint still exists (untouched)
+        self.assertTrue(has_checkpoint(self.tmpdir, self.ticker, self.date))
+
+
+class TestCheckpointSignature(unittest.TestCase):
+    """A different graph shape (analyst selection / depth / asset mode) must not
+    resume the previous run's checkpoint (#1089)."""
+
+    def setUp(self):
+        self.tmpdir = tempfile.mkdtemp()
+        self.ticker = "TEST"
+        self.date = "2026-04-20"
+
+    def test_empty_signature_is_legacy_id(self):
+        self.assertEqual(
+            thread_id(self.ticker, self.date),
+            thread_id(self.ticker, self.date, ""),
+        )
+
+    def test_signature_changes_thread_id(self):
+        legacy = thread_id(self.ticker, self.date)
+        sig_a = thread_id(self.ticker, self.date, "analysts=market,news|asset=stock")
+        sig_b = thread_id(self.ticker, self.date, "analysts=market|asset=stock")
+        self.assertNotEqual(sig_a, sig_b)          # different graph shapes differ
+        self.assertNotEqual(legacy, sig_a)         # signature-keyed differs from legacy
+        self.assertEqual(                          # same inputs are stable
+            sig_a, thread_id(self.ticker, self.date, "analysts=market,news|asset=stock")
+        )
+
+    def test_different_signature_starts_fresh(self):
+        global _should_crash
+        builder = _build_graph()
+        sig1 = "analysts=market,news,fundamentals|asset=stock"
+        sig2 = "analysts=market|asset=stock"       # dropped analysts -> different graph
+
+        _should_crash = True
+        tid1 = thread_id(self.ticker, self.date, sig1)
+        with get_checkpointer(self.tmpdir, self.ticker) as saver:
+            graph = builder.compile(checkpointer=saver)
+            with self.assertRaises(RuntimeError):
+                graph.invoke({"count": 0}, config={"configurable": {"thread_id": tid1}})
+
+        self.assertTrue(has_checkpoint(self.tmpdir, self.ticker, self.date, sig1))
+        # A different graph shape has no checkpoint to resume from.
+        self.assertFalse(has_checkpoint(self.tmpdir, self.ticker, self.date, sig2))
+
+        _should_crash = False
+        tid2 = thread_id(self.ticker, self.date, sig2)
+        self.assertNotEqual(tid1, tid2)
+        with get_checkpointer(self.tmpdir, self.ticker) as saver:
+            graph = builder.compile(checkpointer=saver)
+            result = graph.invoke({"count": 0}, config={"configurable": {"thread_id": tid2}})
+        self.assertEqual(result["count"], 11)
+        # sig1's checkpoint remains untouched.
+        self.assertTrue(has_checkpoint(self.tmpdir, self.ticker, self.date, sig1))
+
+    def test_run_signature_captures_graph_shape(self):
+        from tradingagents.graph.trading_graph import TradingAgentsGraph
+
+        # Build a bare instance to exercise the pure helper without heavy __init__.
+        g = object.__new__(TradingAgentsGraph)
+        g.selected_analysts = ("market", "news")
+        g.config = {"max_debate_rounds": 1, "max_risk_discuss_rounds": 1}
+        base = g._run_signature("stock")
+
+        self.assertNotEqual(base, g._run_signature("crypto"))     # asset mode
+        g.selected_analysts = ("market",)
+        self.assertNotEqual(base, g._run_signature("stock"))      # analyst selection
+        g.selected_analysts = ("market", "news")
+        g.config = {"max_debate_rounds": 3, "max_risk_discuss_rounds": 1}
+        self.assertNotEqual(base, g._run_signature("stock"))      # debate depth
+        g.config = {"max_debate_rounds": 1, "max_risk_discuss_rounds": 5}
+        self.assertNotEqual(base, g._run_signature("stock"))      # risk depth
+        # Stable for identical inputs.
+        g.config = {"max_debate_rounds": 1, "max_risk_discuss_rounds": 1}
+        self.assertEqual(base, g._run_signature("stock"))
+
+
+if __name__ == "__main__":
+    unittest.main()

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

tests/test_cli_config_precedence.py

@@ -0,0 +1,107 @@
+"""CLI config precedence (#976, #977).
+
+An explicit environment override for the debate/risk round counts, or the
+checkpoint flag, must win over the interactive research-depth selection — the CLI
+must not clobber an env-configured value back to a prompt/flag default.
+"""
+
+from unittest import mock
+
+import pytest
+
+import cli.main as m
+
+# Minimal selections dict shaped like get_user_selections()'s return value.
+SELECTIONS = {
+    "research_depth": 5,
+    "quick_think_llm": "gpt-5.4-mini",
+    "deep_think_llm": "gpt-5.5",
+    "backend_url": None,
+    "llm_provider": "openai",
+    "google_thinking_level": None,
+    "openai_reasoning_effort": None,
+    "anthropic_effort": None,
+    "output_language": "English",
+}
+
+
+def test_research_depth_sets_both_rounds_without_env(monkeypatch):
+    for var in ("TRADINGAGENTS_MAX_DEBATE_ROUNDS", "TRADINGAGENTS_MAX_RISK_ROUNDS"):
+        monkeypatch.delenv(var, raising=False)
+    cfg = m._build_run_config(SELECTIONS, checkpoint=None)
+    assert cfg["max_debate_rounds"] == 5
+    assert cfg["max_risk_discuss_rounds"] == 5
+
+
+def test_env_round_counts_win_over_selection(monkeypatch):
+    monkeypatch.setenv("TRADINGAGENTS_MAX_DEBATE_ROUNDS", "2")
+    monkeypatch.setenv("TRADINGAGENTS_MAX_RISK_ROUNDS", "4")
+    # DEFAULT_CONFIG already reflects the env (applied at import); emulate that.
+    patched = dict(m.DEFAULT_CONFIG, max_debate_rounds=2, max_risk_discuss_rounds=4)
+    with mock.patch.object(m, "DEFAULT_CONFIG", patched):
+        cfg = m._build_run_config(SELECTIONS, checkpoint=None)
+    assert cfg["max_debate_rounds"] == 2  # env value, not research_depth=5
+    assert cfg["max_risk_discuss_rounds"] == 4
+
+
+def test_partial_env_only_overrides_that_count(monkeypatch):
+    monkeypatch.setenv("TRADINGAGENTS_MAX_DEBATE_ROUNDS", "2")
+    monkeypatch.delenv("TRADINGAGENTS_MAX_RISK_ROUNDS", raising=False)
+    patched = dict(m.DEFAULT_CONFIG, max_debate_rounds=2)
+    with mock.patch.object(m, "DEFAULT_CONFIG", patched):
+        cfg = m._build_run_config(SELECTIONS, checkpoint=None)
+    assert cfg["max_debate_rounds"] == 2  # env wins
+    assert cfg["max_risk_discuss_rounds"] == 5  # falls through to research_depth
+
+
+def test_checkpoint_none_preserves_env_default():
+    patched = dict(m.DEFAULT_CONFIG, checkpoint_enabled=True)  # e.g. env-enabled
+    with mock.patch.object(m, "DEFAULT_CONFIG", patched):
+        cfg = m._build_run_config(SELECTIONS, checkpoint=None)
+    assert cfg["checkpoint_enabled"] is True  # not clobbered back to False
+
+
+@pytest.mark.parametrize("flag", [True, False])
+def test_checkpoint_flag_overrides_env(flag):
+    patched = dict(m.DEFAULT_CONFIG, checkpoint_enabled=not 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

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",),
+    ]

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)

tests/test_cli_env_skip.py

@@ -0,0 +1,149 @@
+"""Tests for env-driven CLI behavior (#897, #873).
+
+The config-layer override (TRADINGAGENTS_* -> DEFAULT_CONFIG) is covered by
+test_env_overrides.py. These tests cover the CLI layer: an env-configured
+provider/model/language must skip its interactive prompt and use the value.
+"""
+
+import os
+import unittest
+from unittest import mock
+
+import pytest
+
+
+@pytest.mark.unit
+class TestProviderDefaultUrl(unittest.TestCase):
+    def test_known_providers_resolve(self):
+        from cli.utils import provider_default_url
+        self.assertEqual(provider_default_url("openai"), "https://api.openai.com/v1")
+        self.assertEqual(provider_default_url("DeepSeek"), "https://api.deepseek.com")
+        self.assertIsNone(provider_default_url("google"))  # uses SDK default
+
+    def test_unknown_provider_returns_none(self):
+        from cli.utils import provider_default_url
+        self.assertIsNone(provider_default_url("not-a-provider"))
+
+    def test_ollama_honors_base_url_env(self):
+        from cli.utils import provider_default_url
+        with mock.patch.dict(os.environ, {"OLLAMA_BASE_URL": "http://host:1234/v1"}):
+            self.assertEqual(provider_default_url("ollama"), "http://host:1234/v1")
+
+
+@pytest.mark.unit
+class TestCliSkipsPromptsFromEnv(unittest.TestCase):
+    def test_env_config_skips_llm_prompts(self):
+        import cli.main as m
+
+        env = {
+            "TRADINGAGENTS_LLM_PROVIDER": "openai",
+            "TRADINGAGENTS_DEEP_THINK_LLM": "kimi-k2.5",
+            "TRADINGAGENTS_QUICK_THINK_LLM": "deepseek-v4-pro",
+            "TRADINGAGENTS_LLM_BACKEND_URL": "https://opencode.ai/zen/go/v1",
+            "TRADINGAGENTS_OUTPUT_LANGUAGE": "Japanese",
+        }
+        fake_cfg = dict(m.DEFAULT_CONFIG)
+        fake_cfg.update({
+            "llm_provider": "openai",
+            "backend_url": "https://opencode.ai/zen/go/v1",
+            "quick_think_llm": "deepseek-v4-pro",
+            "deep_think_llm": "kimi-k2.5",
+            "output_language": "Japanese",
+        })
+
+        with mock.patch.dict(os.environ, env, clear=False), \
+             mock.patch.object(m, "DEFAULT_CONFIG", fake_cfg), \
+             mock.patch.object(m, "fetch_announcements", return_value=None), \
+             mock.patch.object(m, "display_announcements"), \
+             mock.patch.object(m, "get_ticker", return_value="AAPL"), \
+             mock.patch.object(m, "get_analysis_date", return_value="2026-05-29"), \
+             mock.patch.object(m, "select_analysts", return_value=[]), \
+             mock.patch.object(m, "select_research_depth", return_value=1), \
+             mock.patch.object(m, "ensure_api_key") as ensure_key, \
+             mock.patch.object(m, "select_llm_provider") as prompt_provider, \
+             mock.patch.object(m, "ask_output_language") as prompt_lang, \
+             mock.patch.object(m, "select_shallow_thinking_agent") as prompt_quick, \
+             mock.patch.object(m, "select_deep_thinking_agent") as prompt_deep:
+            sel = m.get_user_selections()
+
+        # None of the LLM selection prompts should have been shown.
+        prompt_provider.assert_not_called()
+        prompt_lang.assert_not_called()
+        prompt_quick.assert_not_called()
+        prompt_deep.assert_not_called()
+        # API key is still verified for the env-configured provider.
+        ensure_key.assert_called_once()
+
+        # 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["quick_think_llm"], "deepseek-v4-pro")
+        self.assertEqual(sel["deep_think_llm"], "kimi-k2.5")
+        self.assertEqual(sel["output_language"], "Japanese")
+
+
+@pytest.mark.unit
+class TestResearchDepthSkippedFromEnv(unittest.TestCase):
+    def test_both_round_envs_skip_depth_prompt(self):
+        import cli.main as m
+
+        env = {
+            "TRADINGAGENTS_MAX_DEBATE_ROUNDS": "2",
+            "TRADINGAGENTS_MAX_RISK_ROUNDS": "4",
+        }
+        fake_cfg = dict(m.DEFAULT_CONFIG)
+        fake_cfg.update({"max_debate_rounds": 2, "max_risk_discuss_rounds": 4})
+
+        with mock.patch.dict(os.environ, env, clear=False), \
+             mock.patch.object(m, "DEFAULT_CONFIG", fake_cfg), \
+             mock.patch.object(m, "fetch_announcements", return_value=None), \
+             mock.patch.object(m, "display_announcements"), \
+             mock.patch.object(m, "get_ticker", return_value="AAPL"), \
+             mock.patch.object(m, "get_analysis_date", return_value="2026-05-29"), \
+             mock.patch.object(m, "select_analysts", return_value=[]), \
+             mock.patch.object(m, "select_research_depth") as prompt_depth, \
+             mock.patch.object(m, "ensure_api_key"), \
+             mock.patch.object(m, "select_llm_provider", return_value=("openai", None)), \
+             mock.patch.object(m, "ask_output_language", return_value="English"), \
+             mock.patch.object(m, "select_shallow_thinking_agent", return_value="gpt-5.4-mini"), \
+             mock.patch.object(m, "select_deep_thinking_agent", return_value="gpt-5.5"), \
+             mock.patch.object(m, "ask_openai_reasoning_effort", return_value=None):
+            sel = m.get_user_selections()
+
+        # The research-depth prompt is skipped; the value comes from the env config.
+        prompt_depth.assert_not_called()
+        self.assertEqual(sel["research_depth"], 2)
+
+
+@pytest.mark.unit
+class TestReasoningEffortSkippedFromEnv(unittest.TestCase):
+    def test_effort_env_skips_step8_prompt(self):
+        import cli.main as m
+
+        env = {"TRADINGAGENTS_OPENAI_REASONING_EFFORT": "high"}
+        fake_cfg = dict(m.DEFAULT_CONFIG)
+        fake_cfg.update({"openai_reasoning_effort": "high"})
+
+        with mock.patch.dict(os.environ, env, clear=False), \
+             mock.patch.object(m, "DEFAULT_CONFIG", fake_cfg), \
+             mock.patch.object(m, "fetch_announcements", return_value=None), \
+             mock.patch.object(m, "display_announcements"), \
+             mock.patch.object(m, "get_ticker", return_value="AAPL"), \
+             mock.patch.object(m, "get_analysis_date", return_value="2026-05-29"), \
+             mock.patch.object(m, "select_analysts", return_value=[]), \
+             mock.patch.object(m, "select_research_depth", return_value=1), \
+             mock.patch.object(m, "ensure_api_key"), \
+             mock.patch.object(m, "select_llm_provider", return_value=("openai", None)), \
+             mock.patch.object(m, "ask_output_language", return_value="English"), \
+             mock.patch.object(m, "select_shallow_thinking_agent", return_value="gpt-5.4-mini"), \
+             mock.patch.object(m, "select_deep_thinking_agent", return_value="gpt-5.5"), \
+             mock.patch.object(m, "ask_openai_reasoning_effort") as prompt_effort:
+            sel = m.get_user_selections()
+
+        # The reasoning-effort prompt is skipped; the value comes from env config.
+        prompt_effort.assert_not_called()
+        self.assertEqual(sel["openai_reasoning_effort"], "high")
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_cli_no_console.py

@@ -0,0 +1,57 @@
+"""A terminal without a console buffer must fail with one actionable line (#1138).
+
+prompt_toolkit raises NoConsoleScreenBufferError before the first prompt in
+non-interactive Windows terminals; the CLI should not surface that traceback.
+The Windows-only exception import must also stay inert on other platforms.
+"""
+from __future__ import annotations
+
+import sys
+
+from typer.testing import CliRunner
+
+import cli.main as m
+
+
+def test_no_console_error_tuple_matches_platform():
+    # Off Windows the win32 module is never imported (it asserts the platform),
+    # so the tuple is empty — which `except` accepts and never matches. On
+    # Windows it holds the real exception type, and a broken prompt_toolkit
+    # would raise at import rather than silently disabling the handler.
+    assert isinstance(m._NO_CONSOLE_ERRORS, tuple)
+    assert all(issubclass(e, BaseException) for e in m._NO_CONSOLE_ERRORS)
+    if sys.platform == "win32":
+        assert m._NO_CONSOLE_ERRORS, "Windows must resolve the console error type"
+    else:
+        assert m._NO_CONSOLE_ERRORS == ()
+
+
+def test_missing_console_prints_actionable_message(monkeypatch):
+    class _NoConsole(Exception):
+        pass
+
+    # Simulate the Windows failure on any platform by registering a stand-in.
+    monkeypatch.setattr(m, "_NO_CONSOLE_ERRORS", (_NoConsole,))
+
+    def _boom(*a, **k):
+        raise _NoConsole("No Windows console found. Are you running cmd.exe?")
+
+    monkeypatch.setattr(m, "run_analysis", _boom)
+
+    result = CliRunner().invoke(m.app, [])
+    assert result.exit_code == 1
+    assert "no Windows console available" in result.output
+    # The raw prompt_toolkit traceback must not reach the user.
+    assert "Traceback" not in result.output
+
+
+def test_unrelated_errors_still_propagate(monkeypatch):
+    # The handler must stay narrow: only the console error is translated.
+    monkeypatch.setattr(m, "_NO_CONSOLE_ERRORS", (RuntimeError,))
+
+    def _boom(*a, **k):
+        raise ValueError("unrelated")
+
+    monkeypatch.setattr(m, "run_analysis", _boom)
+    result = CliRunner().invoke(m.app, [])
+    assert isinstance(result.exception, ValueError)

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"

tests/test_cli_symbol_handling.py

@@ -0,0 +1,75 @@
+"""CLI symbol validation/classification must agree with the data path.
+
+Regressions for #980 (validation rejected GC=F), #981 (BTCUSD misclassified as
+stock), #982 (BTC-USDT accepted but unpriceable on Yahoo).
+"""
+import pytest
+
+from cli.models import AssetType
+from cli.utils import detect_asset_type, is_valid_ticker_input, normalize_ticker_symbol
+from tradingagents.dataflows.symbol_utils import normalize_symbol
+
+
+# --- #982: stablecoin-quoted crypto normalizes to Yahoo's -USD pair ---
+@pytest.mark.parametrize("raw,expected", [
+    ("BTCUSD", "BTC-USD"),
+    ("BTCUSDT", "BTC-USD"),
+    ("BTC-USDT", "BTC-USD"),
+    ("BTC-USDC", "BTC-USD"),
+    ("ethusdt", "ETH-USD"),
+    # non-crypto must be untouched
+    ("AAPL", "AAPL"),
+    ("GC=F", "GC=F"),
+    ("600519.SS", "600519.SS"),
+    ("EURUSD", "EURUSD=X"),
+])
+def test_normalize_symbol_crypto_and_passthrough(raw, expected):
+    assert normalize_symbol(raw) == expected
+
+
+# --- #980: validation accepts Yahoo futures/forex symbols ---
+@pytest.mark.parametrize("value,ok", [
+    ("GC=F", True),
+    ("EURUSD=X", True),
+    ("AAPL", True),
+    ("0700.HK", True),
+    ("^GSPC", True),
+    ("", True),                 # empty -> defaults to SPY downstream
+    ("bad symbol!", False),     # space + '!' rejected
+    ("A" * 40, False),          # too long
+])
+def test_ticker_input_validation(value, ok):
+    assert is_valid_ticker_input(value) is ok
+
+
+# --- #981/#982: asset-type classified on the canonical symbol ---
+@pytest.mark.parametrize("raw,expected", [
+    ("BTCUSD", AssetType.CRYPTO),
+    ("BTC-USDT", AssetType.CRYPTO),
+    ("BTC-USD", AssetType.CRYPTO),
+    ("ETHUSD", AssetType.CRYPTO),
+    ("AAPL", AssetType.STOCK),
+    ("GC=F", AssetType.STOCK),
+    ("600519.SS", AssetType.STOCK),
+])
+def test_detect_asset_type(raw, expected):
+    assert detect_asset_type(raw) == expected
+
+
+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))

tests/test_crypto_asset_mode.py

@@ -0,0 +1,56 @@
+import unittest
+
+from cli.models import AnalystType, AssetType
+from cli.utils import detect_asset_type, filter_analysts_for_asset_type
+from tradingagents.graph.propagation import Propagator
+
+
+class CryptoAssetModeTests(unittest.TestCase):
+    def test_detects_crypto_pair_symbols(self):
+        self.assertEqual(detect_asset_type("BTC-USD"), AssetType.CRYPTO)
+        self.assertEqual(detect_asset_type("eth-usd"), AssetType.CRYPTO)
+
+    def test_defaults_non_crypto_symbols_to_stock(self):
+        self.assertEqual(detect_asset_type("AAPL"), AssetType.STOCK)
+        self.assertEqual(detect_asset_type("SPY"), AssetType.STOCK)
+
+    def test_filters_out_fundamentals_analyst_for_crypto(self):
+        analysts = [
+            AnalystType.MARKET,
+            AnalystType.SOCIAL,
+            AnalystType.NEWS,
+            AnalystType.FUNDAMENTALS,
+        ]
+
+        self.assertEqual(
+            filter_analysts_for_asset_type(analysts, AssetType.CRYPTO),
+            [
+                AnalystType.MARKET,
+                AnalystType.SOCIAL,
+                AnalystType.NEWS,
+            ],
+        )
+
+    def test_keeps_all_analysts_for_stock(self):
+        analysts = [
+            AnalystType.MARKET,
+            AnalystType.SOCIAL,
+            AnalystType.NEWS,
+            AnalystType.FUNDAMENTALS,
+        ]
+
+        self.assertEqual(
+            filter_analysts_for_asset_type(analysts, AssetType.STOCK),
+            analysts,
+        )
+
+    def test_propagator_includes_asset_type_in_initial_state(self):
+        state = Propagator().create_initial_state(
+            "BTC-USD", "2026-04-18", asset_type=AssetType.CRYPTO.value
+        )
+
+        self.assertEqual(state["asset_type"], AssetType.CRYPTO.value)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_dataflows_config.py

@@ -0,0 +1,61 @@
+"""Config isolation: get/set must not leak nested-dict references."""
+
+import copy
+import unittest
+
+import pytest
+
+import tradingagents.default_config as default_config
+from tradingagents.dataflows.config import get_config, set_config
+
+
+@pytest.mark.unit
+class DataflowsConfigIsolationTests(unittest.TestCase):
+    def setUp(self):
+        set_config(copy.deepcopy(default_config.DEFAULT_CONFIG))
+
+    def test_get_config_returns_deep_copy(self):
+        cfg = get_config()
+        cfg["data_vendors"]["core_stock_apis"] = "alpha_vantage"
+        cfg["tool_vendors"]["get_stock_data"] = "alpha_vantage"
+
+        fresh = get_config()
+        self.assertEqual(fresh["data_vendors"]["core_stock_apis"], "yfinance")
+        self.assertNotIn("get_stock_data", fresh["tool_vendors"])
+
+    def test_set_config_does_not_alias_caller_nested_dicts(self):
+        custom = copy.deepcopy(default_config.DEFAULT_CONFIG)
+        custom["data_vendors"]["core_stock_apis"] = "alpha_vantage"
+        custom["tool_vendors"]["get_stock_data"] = "alpha_vantage"
+
+        set_config(custom)
+
+        custom["data_vendors"]["core_stock_apis"] = "yfinance"
+        custom["tool_vendors"]["get_stock_data"] = "yfinance"
+
+        fresh = get_config()
+        self.assertEqual(fresh["data_vendors"]["core_stock_apis"], "alpha_vantage")
+        self.assertEqual(fresh["tool_vendors"]["get_stock_data"], "alpha_vantage")
+
+    def test_partial_nested_update_preserves_existing_defaults(self):
+        set_config(
+            {
+                "data_vendors": {
+                    "core_stock_apis": "alpha_vantage",
+                }
+            }
+        )
+
+        fresh = get_config()
+        self.assertEqual(fresh["data_vendors"]["core_stock_apis"], "alpha_vantage")
+        self.assertEqual(fresh["data_vendors"]["technical_indicators"], "yfinance")
+        self.assertEqual(fresh["data_vendors"]["fundamental_data"], "yfinance")
+        self.assertEqual(fresh["data_vendors"]["news_data"], "yfinance")
+
+    def test_nested_dict_updates_merge_one_level_deep(self):
+        set_config({"tool_vendors": {"get_stock_data": "alpha_vantage"}})
+        set_config({"tool_vendors": {"get_news": "alpha_vantage"}})
+
+        fresh = get_config()
+        self.assertEqual(fresh["tool_vendors"]["get_stock_data"], "alpha_vantage")
+        self.assertEqual(fresh["tool_vendors"]["get_news"], "alpha_vantage")

tests/test_date_boundaries.py

@@ -0,0 +1,61 @@
+"""yfinance treats ``end`` as exclusive; we must request one extra day so the
+requested end_date (and the current day) is actually included.
+
+Regressions for #986 (current-day OHLCV excluded) and #987 (requested end_date
+row omitted).
+"""
+import pandas as pd
+import pytest
+
+import tradingagents.dataflows.stockstats_utils as su
+import tradingagents.dataflows.y_finance as yfin
+from tradingagents.dataflows.config import set_config
+
+
+@pytest.mark.unit
+def test_get_yfin_requests_inclusive_end(monkeypatch):
+    captured = {}
+
+    class FakeTicker:
+        def __init__(self, symbol):
+            pass
+
+        def history(self, start, end):
+            captured["start"] = start
+            captured["end"] = end
+            idx = pd.to_datetime(["2025-05-08", "2025-05-09"])
+            return pd.DataFrame(
+                {"Open": [1.0, 2.0], "High": [1.0, 2.0], "Low": [1.0, 2.0],
+                 "Close": [1.0, 2.0], "Volume": [1, 2]},
+                index=idx,
+            )
+
+    monkeypatch.setattr(yfin.yf, "Ticker", FakeTicker)
+    out = yfin.get_YFin_data_online("AAPL", "2025-05-01", "2025-05-09")
+
+    # end is requested one day past end_date so 2025-05-09 is included (#987).
+    assert captured["end"] == "2025-05-10"
+    # Header still reflects the requested range, not the internal +1 day.
+    assert "to 2025-05-09" in out
+
+
+@pytest.mark.unit
+def test_load_ohlcv_requests_inclusive_end(monkeypatch, tmp_path):
+    set_config({"data_cache_dir": str(tmp_path)})
+    captured = {}
+
+    def fake_download(symbol, start, end, **kwargs):
+        captured["end"] = end
+        idx = pd.to_datetime([pd.Timestamp.today().normalize()])
+        return pd.DataFrame(
+            {"Open": [100.0], "High": [100.0], "Low": [100.0],
+             "Close": [100.0], "Volume": [1]},
+            index=idx,
+        )
+
+    monkeypatch.setattr(su.yf, "download", fake_download)
+    today = pd.Timestamp.today().strftime("%Y-%m-%d")
+    su.load_ohlcv("AAPL", today)
+
+    expected_end = (pd.Timestamp.today() + pd.Timedelta(days=1)).strftime("%Y-%m-%d")
+    assert captured["end"] == expected_end  # tomorrow -> today's row included (#986)

tests/test_debate_opening.py

@@ -0,0 +1,111 @@
+"""The first speaker in each debate must not rebut a nonexistent argument (#1176).
+
+Each debate round's opening speaker receives an empty opponent response; the
+prompt used to interpolate it into a "refute the opponent" instruction, so models
+fabricated the other side's position. All five debators (bull, bear, and the
+three risk analysts) now substitute an explicit opening marker when the opponent
+has not spoken, and pass a real argument through unchanged.
+"""
+from __future__ import annotations
+
+from unittest.mock import MagicMock
+
+import pytest
+
+from tradingagents.agents.researchers.bear_researcher import create_bear_researcher
+from tradingagents.agents.researchers.bull_researcher import create_bull_researcher
+from tradingagents.agents.risk_mgmt.aggressive_debator import create_aggressive_debator
+from tradingagents.agents.risk_mgmt.conservative_debator import create_conservative_debator
+from tradingagents.agents.risk_mgmt.neutral_debator import create_neutral_debator
+from tradingagents.agents.utils.agent_utils import opponent_argument_or_opening
+
+_REPORTS = {
+    "company_of_interest": "AAPL", "asset_type": "stock",
+    "market_report": "m", "sentiment_report": "s",
+    "news_report": "n", "fundamentals_report": "f",
+}
+
+
+def _capturing_llm(captured: dict):
+    llm = MagicMock()
+    llm.invoke.side_effect = lambda prompt: (
+        captured.__setitem__("prompt", prompt) or MagicMock(content="argument")
+    )
+    return llm
+
+
+def _investment_state(current_response):
+    return {
+        **_REPORTS,
+        "count": 0,
+        "investment_debate_state": {
+            "history": "", "bull_history": "", "bear_history": "",
+            "current_response": current_response, "count": 0,
+        },
+    }
+
+
+def _risk_state(**responses):
+    base = {
+        "current_aggressive_response": "", "current_conservative_response": "",
+        "current_neutral_response": "", "history": "", "aggressive_history": "",
+        "conservative_history": "", "neutral_history": "", "count": 0,
+    }
+    base.update(responses)
+    return {**_REPORTS, "trader_investment_plan": "plan", "risk_debate_state": base}
+
+
+# --- shared helper ----------------------------------------------------------
+
+@pytest.mark.unit
+def test_helper_marks_empty_and_passes_through():
+    assert "has not spoken yet" in opponent_argument_or_opening("", "bear analyst")
+    assert opponent_argument_or_opening("  real point ", "bear") == "real point"
+
+
+# --- researchers ------------------------------------------------------------
+
+@pytest.mark.unit
+@pytest.mark.parametrize(
+    "factory,opponent",
+    [(create_bull_researcher, "bear"), (create_bear_researcher, "bull")],
+)
+def test_researcher_opening_has_no_phantom_opponent(factory, opponent):
+    captured = {}
+    factory(_capturing_llm(captured))(_investment_state(""))
+    assert "has not spoken yet" in captured["prompt"]
+
+
+@pytest.mark.unit
+def test_researcher_passes_real_opponent_argument():
+    captured = {}
+    state = _investment_state("Bear Analyst: valuation is stretched")
+    create_bull_researcher(_capturing_llm(captured))(state)
+    assert "valuation is stretched" in captured["prompt"]
+    assert "has not spoken yet" not in captured["prompt"]
+
+
+# --- risk debators ----------------------------------------------------------
+
+@pytest.mark.unit
+@pytest.mark.parametrize(
+    "factory", [create_aggressive_debator, create_conservative_debator, create_neutral_debator]
+)
+def test_risk_opening_has_no_phantom_opponent(factory):
+    captured = {}
+    factory(_capturing_llm(captured))(_risk_state())
+    # Both opponent slots were empty -> two opening markers, no fabricated args.
+    assert captured["prompt"].count("has not spoken yet") == 2
+
+
+@pytest.mark.unit
+def test_risk_passes_real_opponent_arguments():
+    captured = {}
+    state = _risk_state(
+        current_conservative_response="Conservative Analyst: trim risk",
+        current_neutral_response="Neutral Analyst: hold steady",
+    )
+    create_aggressive_debator(_capturing_llm(captured))(state)
+    assert "trim risk" in captured["prompt"]
+    assert "hold steady" in captured["prompt"]
+    assert "has not spoken yet" not in captured["prompt"]

tests/test_deepseek_reasoning.py

@@ -0,0 +1,239 @@
+"""Tests for DeepSeekChatOpenAI thinking-mode behaviour.
+
+Two pieces verified:
+
+1. ``reasoning_content`` is captured on receive into the AIMessage's
+   ``additional_kwargs`` and re-attached on send so DeepSeek's API
+   sees the same value across turns.
+2. ``with_structured_output`` consults the capability table and
+   suppresses ``tool_choice`` for models that reject it (V4 + reasoner),
+   matching DeepSeek's official tool-calling pattern at
+   https://api-docs.deepseek.com/guides/tool_calls.
+"""
+
+import os
+
+import pytest
+from langchain_core.messages import AIMessage, HumanMessage
+from langchain_core.prompt_values import ChatPromptValue
+from pydantic import BaseModel
+
+from tradingagents.llm_clients.openai_client import (
+    DeepSeekChatOpenAI,
+    NormalizedChatOpenAI,
+    _input_to_messages,
+)
+
+# ---------------------------------------------------------------------------
+# _input_to_messages — the helper that handles list / ChatPromptValue / other
+# (Gemini bot review note: non-list inputs must also work)
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.unit
+class TestInputToMessages:
+    def test_list_input_returned_as_is(self):
+        msgs = [HumanMessage(content="hi")]
+        assert _input_to_messages(msgs) is msgs
+
+    def test_chat_prompt_value_unwrapped(self):
+        msgs = [HumanMessage(content="hi")]
+        prompt_value = ChatPromptValue(messages=msgs)
+        assert _input_to_messages(prompt_value) == msgs
+
+    def test_string_input_yields_empty_list(self):
+        # A bare string isn't a message-bearing input; the caller's normal
+        # langchain conversion happens upstream of _get_request_payload.
+        assert _input_to_messages("hello") == []
+
+
+# ---------------------------------------------------------------------------
+# Reasoning content propagation across turns
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.unit
+class TestDeepSeekReasoningContent:
+    def _client(self):
+        os.environ.setdefault("DEEPSEEK_API_KEY", "placeholder")
+        return DeepSeekChatOpenAI(
+            model="deepseek-v4-flash",
+            api_key="placeholder",
+            base_url="https://api.deepseek.com",
+        )
+
+    def test_capture_on_receive(self):
+        """When the response carries reasoning_content, it lands on the
+        AIMessage's additional_kwargs so the next turn can echo it back."""
+        client = self._client()
+        result = client._create_chat_result(
+            {
+                "model": "deepseek-v4-flash",
+                "choices": [
+                    {
+                        "index": 0,
+                        "message": {
+                            "role": "assistant",
+                            "content": "Plan: buy NVDA.",
+                            "reasoning_content": "Step 1: trend is up. Step 2: ...",
+                        },
+                        "finish_reason": "stop",
+                    }
+                ],
+                "usage": {"prompt_tokens": 10, "completion_tokens": 5, "total_tokens": 15},
+            }
+        )
+        ai = result.generations[0].message
+        assert ai.additional_kwargs["reasoning_content"] == "Step 1: trend is up. Step 2: ..."
+
+    def test_propagate_on_send(self):
+        """When an outgoing AIMessage carries reasoning_content, the request
+        payload echoes it on the corresponding message dict."""
+        client = self._client()
+        prior = AIMessage(
+            content="Plan",
+            additional_kwargs={"reasoning_content": "weighed bull case"},
+        )
+        new_user = HumanMessage(content="Refine.")
+        payload = client._get_request_payload([prior, new_user])
+        # Find the assistant message in the payload
+        assistant_dicts = [m for m in payload["messages"] if m.get("role") == "assistant"]
+        assert assistant_dicts, "assistant message missing from outgoing payload"
+        assert assistant_dicts[0]["reasoning_content"] == "weighed bull case"
+
+    def test_propagate_through_chat_prompt_value(self):
+        """Gemini bot review note: non-list inputs (ChatPromptValue) must
+        also propagate reasoning_content."""
+        client = self._client()
+        prior = AIMessage(
+            content="Plan",
+            additional_kwargs={"reasoning_content": "weighed bull case"},
+        )
+        prompt_value = ChatPromptValue(messages=[prior, HumanMessage(content="Refine.")])
+        payload = client._get_request_payload(prompt_value)
+        assistant_dicts = [m for m in payload["messages"] if m.get("role") == "assistant"]
+        assert assistant_dicts[0]["reasoning_content"] == "weighed bull case"
+
+
+# ---------------------------------------------------------------------------
+# Capability-driven structured output: tool_choice suppressed for V4 + reasoner
+# ---------------------------------------------------------------------------
+
+
+def _bound_kwargs(runnable):
+    """Extract bind() kwargs from a with_structured_output result."""
+    first = runnable.steps[0] if hasattr(runnable, "steps") else runnable
+    return getattr(first, "kwargs", {})
+
+
+@pytest.mark.unit
+class TestStructuredOutputCapabilityDispatch:
+    """DeepSeek V4 and reasoner reject the tool_choice parameter
+    (official guide: api-docs.deepseek.com/guides/tool_calls passes
+    tools=[...] without tool_choice). Verify the capability dispatch
+    suppresses tool_choice for those models and sends it for chat."""
+
+    class _Sample(BaseModel):
+        answer: str
+
+    def _client(self, model):
+        return DeepSeekChatOpenAI(
+            model=model, api_key="placeholder", base_url="https://api.deepseek.com",
+        )
+
+    def test_chat_sends_tool_choice(self):
+        bound = self._client("deepseek-chat").with_structured_output(self._Sample)
+        assert _bound_kwargs(bound).get("tool_choice") is not None
+
+    def test_reasoner_suppresses_tool_choice(self):
+        bound = self._client("deepseek-reasoner").with_structured_output(self._Sample)
+        # tool_choice is either absent or explicitly None — both are valid
+        # signals that langchain's bind_tools will skip the parameter.
+        assert _bound_kwargs(bound).get("tool_choice") in (None, ...) or \
+            "tool_choice" not in _bound_kwargs(bound)
+
+    def test_v4_flash_suppresses_tool_choice(self):
+        bound = self._client("deepseek-v4-flash").with_structured_output(self._Sample)
+        assert _bound_kwargs(bound).get("tool_choice") is None or \
+            "tool_choice" not in _bound_kwargs(bound)
+
+    def test_v4_pro_suppresses_tool_choice(self):
+        bound = self._client("deepseek-v4-pro").with_structured_output(self._Sample)
+        assert _bound_kwargs(bound).get("tool_choice") is None or \
+            "tool_choice" not in _bound_kwargs(bound)
+
+    def test_future_v_variant_via_regex(self):
+        """Forward-compat: unknown deepseek-v\\d-* IDs inherit V4 quirks."""
+        bound = self._client("deepseek-v5-hypothetical").with_structured_output(self._Sample)
+        assert _bound_kwargs(bound).get("tool_choice") is None or \
+            "tool_choice" not in _bound_kwargs(bound)
+
+    def test_schema_is_still_bound_as_tool(self):
+        """tool_choice is suppressed, but the schema is still bound as a tool —
+        exactly matching DeepSeek's official tool-calling examples."""
+        bound = self._client("deepseek-reasoner").with_structured_output(self._Sample)
+        kwargs = _bound_kwargs(bound)
+        tools = kwargs.get("tools", [])
+        assert any(
+            t.get("function", {}).get("name") == "_Sample" for t in tools
+        ), f"schema not bound as a tool: {tools}"
+
+
+# ---------------------------------------------------------------------------
+# Live API: structured output round-trips against the real DeepSeek backend
+# ---------------------------------------------------------------------------
+
+
+def _has_real_deepseek_key():
+    key = os.environ.get("DEEPSEEK_API_KEY", "")
+    return bool(key) and key != "placeholder"
+
+
+@pytest.mark.integration
+@pytest.mark.skipif(
+    not _has_real_deepseek_key(),
+    reason="DEEPSEEK_API_KEY not set (or placeholder); skipping live API call",
+)
+class TestDeepSeekLiveStructuredOutput:
+    """End-to-end: a real DeepSeek V4-flash call returns a typed instance.
+
+    Verifies the no-tool_choice path doesn't trigger the 400 reported in
+    issue #678 and that the structured-output binding still parses to a
+    Pydantic instance.
+    """
+
+    class _Pick(BaseModel):
+        action: str
+        confidence: float
+
+    def test_v4_flash_returns_structured_output(self):
+        client = DeepSeekChatOpenAI(
+            model="deepseek-v4-flash",
+            api_key=os.environ["DEEPSEEK_API_KEY"],
+            base_url="https://api.deepseek.com",
+            timeout=60,
+        )
+        bound = client.with_structured_output(self._Pick)
+        result = bound.invoke(
+            "Pick BUY or SELL or HOLD for a tech stock with strong earnings. "
+            "Confidence is a float between 0 and 1."
+        )
+        assert isinstance(result, self._Pick)
+        assert result.action in {"BUY", "SELL", "HOLD"}
+        assert 0.0 <= result.confidence <= 1.0
+
+
+# ---------------------------------------------------------------------------
+# Base class isolation: NormalizedChatOpenAI does NOT have DeepSeek behaviour
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.unit
+class TestBaseClassIsolation:
+    def test_normalized_does_not_propagate_reasoning_content(self):
+        """The general-purpose NormalizedChatOpenAI must not carry
+        DeepSeek-specific behaviour. Only the subclass does."""
+        assert not hasattr(NormalizedChatOpenAI, "_get_request_payload") or (
+            NormalizedChatOpenAI._get_request_payload
+            is NormalizedChatOpenAI.__bases__[0]._get_request_payload
+        )

tests/test_env_overrides.py

@@ -0,0 +1,129 @@
+"""Tests for TRADINGAGENTS_* env-var overlay onto DEFAULT_CONFIG."""
+
+from __future__ import annotations
+
+import importlib
+
+import pytest
+
+import tradingagents.default_config as default_config_module
+
+
+def _reload_with_env(monkeypatch, **overrides):
+    """Set/clear env vars then reload default_config to re-evaluate DEFAULT_CONFIG."""
+    for key in list(default_config_module._ENV_OVERRIDES):
+        monkeypatch.delenv(key, raising=False)
+    for key, val in overrides.items():
+        monkeypatch.setenv(key, val)
+    return importlib.reload(default_config_module)
+
+
+def test_no_env_uses_built_in_defaults(monkeypatch):
+    dc = _reload_with_env(monkeypatch)
+    assert dc.DEFAULT_CONFIG["llm_provider"] == "openai"
+    assert dc.DEFAULT_CONFIG["deep_think_llm"] == "gpt-5.6"
+    assert dc.DEFAULT_CONFIG["quick_think_llm"] == "gpt-5.6-luna"
+    assert dc.DEFAULT_CONFIG["backend_url"] is None
+    assert dc.DEFAULT_CONFIG["max_debate_rounds"] == 1
+    assert dc.DEFAULT_CONFIG["checkpoint_enabled"] is False
+
+
+def test_string_overrides(monkeypatch):
+    dc = _reload_with_env(
+        monkeypatch,
+        TRADINGAGENTS_LLM_PROVIDER="google",
+        TRADINGAGENTS_DEEP_THINK_LLM="gemini-3-pro-preview",
+        TRADINGAGENTS_QUICK_THINK_LLM="gemini-3-flash-preview",
+        TRADINGAGENTS_LLM_BACKEND_URL="https://example.invalid/v1",
+        TRADINGAGENTS_OUTPUT_LANGUAGE="Chinese",
+    )
+    assert dc.DEFAULT_CONFIG["llm_provider"] == "google"
+    assert dc.DEFAULT_CONFIG["deep_think_llm"] == "gemini-3-pro-preview"
+    assert dc.DEFAULT_CONFIG["quick_think_llm"] == "gemini-3-flash-preview"
+    assert dc.DEFAULT_CONFIG["backend_url"] == "https://example.invalid/v1"
+    assert dc.DEFAULT_CONFIG["output_language"] == "Chinese"
+
+
+def test_int_coercion(monkeypatch):
+    dc = _reload_with_env(
+        monkeypatch,
+        TRADINGAGENTS_MAX_DEBATE_ROUNDS="3",
+        TRADINGAGENTS_MAX_RISK_ROUNDS="2",
+    )
+    assert dc.DEFAULT_CONFIG["max_debate_rounds"] == 3
+    assert isinstance(dc.DEFAULT_CONFIG["max_debate_rounds"], int)
+    assert dc.DEFAULT_CONFIG["max_risk_discuss_rounds"] == 2
+    assert isinstance(dc.DEFAULT_CONFIG["max_risk_discuss_rounds"], int)
+
+
+@pytest.mark.parametrize(
+    "raw,expected",
+    [
+        ("true", True), ("True", True), ("1", True), ("yes", True), ("on", True),
+        ("false", False), ("False", False), ("0", False), ("no", False), ("off", False),
+    ],
+)
+def test_bool_coercion(monkeypatch, raw, expected):
+    dc = _reload_with_env(monkeypatch, TRADINGAGENTS_CHECKPOINT_ENABLED=raw)
+    assert dc.DEFAULT_CONFIG["checkpoint_enabled"] is expected
+
+
+def test_reasoning_thinking_overrides(monkeypatch):
+    """The provider reasoning/thinking knobs are env-configurable (non-interactive runs)."""
+    dc = _reload_with_env(
+        monkeypatch,
+        TRADINGAGENTS_OPENAI_REASONING_EFFORT="high",
+        TRADINGAGENTS_GOOGLE_THINKING_LEVEL="minimal",
+        TRADINGAGENTS_ANTHROPIC_EFFORT="low",
+    )
+    assert dc.DEFAULT_CONFIG["openai_reasoning_effort"] == "high"
+    assert dc.DEFAULT_CONFIG["google_thinking_level"] == "minimal"
+    assert dc.DEFAULT_CONFIG["anthropic_effort"] == "low"
+
+
+def test_reasoning_effort_defaults_to_none(monkeypatch):
+    """Unset reasoning/thinking knobs stay None so each provider uses its own default."""
+    dc = _reload_with_env(monkeypatch)
+    assert dc.DEFAULT_CONFIG["openai_reasoning_effort"] is None
+    assert dc.DEFAULT_CONFIG["google_thinking_level"] is None
+    assert dc.DEFAULT_CONFIG["anthropic_effort"] is None
+
+
+def test_empty_env_value_is_passthrough(monkeypatch):
+    """Empty TRADINGAGENTS_* values must not clobber the built-in default."""
+    dc = _reload_with_env(
+        monkeypatch,
+        TRADINGAGENTS_LLM_PROVIDER="",
+        TRADINGAGENTS_MAX_DEBATE_ROUNDS="",
+    )
+    assert dc.DEFAULT_CONFIG["llm_provider"] == "openai"
+    assert dc.DEFAULT_CONFIG["max_debate_rounds"] == 1
+
+
+def test_invalid_int_raises(monkeypatch):
+    """Garbage int values should surface a ValueError at import, not silently misconfigure."""
+    monkeypatch.setenv("TRADINGAGENTS_MAX_DEBATE_ROUNDS", "not-a-number")
+    with pytest.raises(ValueError, match="TRADINGAGENTS_MAX_DEBATE_ROUNDS"):
+        importlib.reload(default_config_module)
+    # Restore module state for subsequent tests in this process
+    monkeypatch.delenv("TRADINGAGENTS_MAX_DEBATE_ROUNDS", raising=False)
+    importlib.reload(default_config_module)
+
+
+@pytest.mark.parametrize("bad", ["treu", "flase", "maybe", "2", "enabled"])
+def test_invalid_bool_raises(monkeypatch, bad):
+    """A misspelled boolean must fail loudly (like ints) instead of silently False."""
+    monkeypatch.setenv("TRADINGAGENTS_CHECKPOINT_ENABLED", bad)
+    with pytest.raises(ValueError, match="TRADINGAGENTS_CHECKPOINT_ENABLED"):
+        importlib.reload(default_config_module)
+    monkeypatch.delenv("TRADINGAGENTS_CHECKPOINT_ENABLED", raising=False)
+    importlib.reload(default_config_module)
+
+
+def test_unknown_env_var_is_ignored(monkeypatch):
+    """Env vars outside _ENV_OVERRIDES must not bleed into DEFAULT_CONFIG."""
+    dc = _reload_with_env(
+        monkeypatch,
+        TRADINGAGENTS_NONEXISTENT_KEY="oops",
+    )
+    assert "nonexistent_key" not in dc.DEFAULT_CONFIG

tests/test_fred.py

@@ -0,0 +1,286 @@
+"""FRED macro vendor: alias resolution, configuration errors, output formatting,
+missing-value handling, lookahead-safe windowing, and router integration.
+
+All API access is mocked, so these run without a network connection or a key.
+"""
+import copy
+import unittest
+from unittest import mock
+
+import pytest
+import requests
+
+import tradingagents.dataflows.config as config_module
+import tradingagents.default_config as default_config
+from tradingagents.dataflows import fred, interface
+from tradingagents.dataflows.config import set_config
+
+# A small, stable set of observations to format against.
+_META = {
+    "seriess": [
+        {
+            "title": "Unemployment Rate",
+            "units_short": "%",
+            "frequency": "Monthly",
+            "seasonal_adjustment_short": "SA",
+        }
+    ]
+}
+_OBS = {
+    "observations": [
+        {"date": "2025-06-01", "value": "4.1"},
+        {"date": "2025-07-01", "value": "4.3"},
+        {"date": "2025-08-01", "value": "."},   # missing -> skipped
+        {"date": "2025-09-01", "value": "4.4"},
+    ]
+}
+
+
+def _request_stub(meta=_META, obs=_OBS):
+    """Build a _request replacement that dispatches on the endpoint path."""
+    def _impl(path, params):
+        if path == "series":
+            return meta
+        if path == "series/observations":
+            return obs
+        raise AssertionError(f"unexpected FRED path: {path}")
+    return _impl
+
+
+@pytest.mark.unit
+class FredResolutionTests(unittest.TestCase):
+    def test_alias_maps_to_series_id(self):
+        self.assertEqual(fred._resolve_series_id("cpi"), "CPIAUCSL")
+        self.assertEqual(fred._resolve_series_id("unemployment"), "UNRATE")
+
+    def test_alias_is_case_and_separator_insensitive(self):
+        self.assertEqual(fred._resolve_series_id("Fed Funds Rate"), "FEDFUNDS")
+        self.assertEqual(fred._resolve_series_id("10y-treasury"), "DGS10")
+
+    def test_unknown_alias_is_treated_as_raw_series_id(self):
+        # Power users can pass any FRED series ID; we uppercase by convention.
+        self.assertEqual(fred._resolve_series_id("dgs30"), "DGS30")
+        self.assertEqual(fred._resolve_series_id("MyCustomSeries"), "MYCUSTOMSERIES")
+
+    def test_descriptive_phrase_is_rejected(self):
+        # An LLM phrase (spaces / too long) is not a series ID — reject up front
+        # with guidance rather than 400ing the API.
+        for bad in ("bank of japan rate", "the unemployment number", "X" * 31):
+            with self.assertRaises(ValueError):
+                fred._resolve_series_id(bad)
+
+    def test_get_macro_data_returns_guidance_on_bad_indicator(self):
+        # Invalid indicator -> actionable message, not a crash (no API call).
+        out = fred.get_macro_data("bank of japan rate", "2026-01-01")
+        self.assertIn("FRED", out)
+        self.assertIn("not a known macro alias", out)
+
+
+@pytest.mark.unit
+class FredConfigTests(unittest.TestCase):
+    def test_missing_key_raises_not_configured(self):
+        with mock.patch.dict("os.environ", {}, clear=True), \
+                self.assertRaises(fred.FredNotConfiguredError):
+            fred.get_api_key()
+
+    def test_not_configured_is_a_value_error(self):
+        # Routing relies on this subclassing for "vendor unavailable" handling.
+        self.assertTrue(issubclass(fred.FredNotConfiguredError, ValueError))
+
+
+@pytest.mark.unit
+class FredFormattingTests(unittest.TestCase):
+    def test_report_has_header_latest_change_and_table(self):
+        with mock.patch.object(fred, "_request", side_effect=_request_stub()):
+            out = fred.get_macro_data("unemployment", "2025-09-30", 365)
+        self.assertIn("## FRED: Unemployment Rate (UNRATE)", out)
+        self.assertIn("Units: %", out)
+        self.assertIn("Frequency: Monthly (SA)", out)
+        self.assertIn("**Latest:** 4.4 (2025-09-01)", out)
+        # change over the window: 4.4 - 4.1 = +0.30
+        self.assertIn("+0.30", out)
+        self.assertIn("| 2025-06-01 | 4.1 |", out)
+
+    def test_missing_value_is_skipped(self):
+        with mock.patch.object(fred, "_request", side_effect=_request_stub()):
+            out = fred.get_macro_data("unemployment", "2025-09-30", 365)
+        # the "." observation must not appear as a row
+        self.assertNotIn("2025-08-01", out)
+
+    def test_empty_window_reports_no_observations(self):
+        empty = {"observations": []}
+        with mock.patch.object(fred, "_request", side_effect=_request_stub(obs=empty)):
+            out = fred.get_macro_data("unemployment", "2025-09-30", 30)
+        self.assertIn("No observations", out)
+
+    def test_unknown_series_returns_not_found_message(self):
+        # A well-formed but unknown series ID returns guidance, not a crash, so
+        # the run is not aborted over an optional macro lookup.
+        no_series = {"seriess": []}
+        with mock.patch.object(fred, "_request", side_effect=_request_stub(meta=no_series)):
+            out = fred.get_macro_data("totally_unknown_xyz", "2025-09-30", 30)
+        self.assertIn("not found", out)
+
+    def test_long_series_is_truncated_but_change_uses_full_range(self):
+        # Build > MAX_ROWS observations deterministically.
+        obs = {
+            "observations": [
+                {"date": f"2025-01-{(i % 28) + 1:02d}", "value": str(i)}
+                for i in range(fred.MAX_ROWS + 10)
+            ]
+        }
+        with mock.patch.object(fred, "_request", side_effect=_request_stub(obs=obs)):
+            out = fred.get_macro_data("unemployment", "2025-12-31", 365)
+        self.assertIn(f"most recent {fred.MAX_ROWS}", out)
+        # change-over-window must reference the true first (0) and last value
+        self.assertIn("from 0 ", out)
+        body_rows = [ln for ln in out.splitlines() if ln.startswith("| 2025")]
+        self.assertEqual(len(body_rows), fred.MAX_ROWS)
+
+    def test_window_is_lookahead_safe(self):
+        # observation_end must equal curr_date so a past date never pulls future data.
+        captured = {}
+
+        def _capture(path, params):
+            captured[path] = params
+            return _META if path == "series" else _OBS
+
+        with mock.patch.object(fred, "_request", side_effect=_capture):
+            fred.get_macro_data("unemployment", "2025-09-30", 90)
+        obs_params = captured["series/observations"]
+        self.assertEqual(obs_params["observation_end"], "2025-09-30")
+        self.assertEqual(obs_params["observation_start"], "2025-07-02")  # 90d back
+
+    def test_requests_pin_the_data_vintage(self):
+        # #1275: both the metadata and observations requests must pin the vintage
+        # to curr_date (clamped to FRED's today), or FRED serves the latest
+        # revision and revision-prone series leak future information. A past
+        # curr_date sits below FRED's today, so it pins through unchanged.
+        captured = {}
+
+        def _capture(path, params):
+            captured[path] = params
+            return _META if path == "series" else _OBS
+
+        with mock.patch.object(fred, "_fred_today", return_value="2026-01-01"), \
+                mock.patch.object(fred, "_request", side_effect=_capture):
+            fred.get_macro_data("cpi", "2025-09-30", 90)
+
+        for path in ("series", "series/observations"):
+            self.assertEqual(captured[path]["realtime_start"], "2025-09-30", path)
+            self.assertEqual(captured[path]["realtime_end"], "2025-09-30", path)
+
+    def test_future_curr_date_clamps_vintage_to_fred_today(self):
+        # #1275 regression: on a live run curr_date is the caller's LOCAL date,
+        # which can be a day ahead of FRED's US-Central clock. Pinning the vintage
+        # to that future date 400s, and the routing layer then drops macro data
+        # silently. The pin must clamp to FRED's today; the observation window
+        # (future bars can't exist yet) stays at curr_date.
+        captured = {}
+
+        def _capture(path, params):
+            captured[path] = params
+            return _META if path == "series" else _OBS
+
+        with mock.patch.object(fred, "_fred_today", return_value="2026-08-31"), \
+                mock.patch.object(fred, "_request", side_effect=_capture):
+            fred.get_macro_data("cpi", "2026-09-01", 90)  # local a day ahead of Chicago
+
+        for path in ("series", "series/observations"):
+            self.assertEqual(captured[path]["realtime_start"], "2026-08-31", path)
+            self.assertEqual(captured[path]["realtime_end"], "2026-08-31", path)
+        # the observation window still tracks curr_date, not the clamped vintage
+        self.assertEqual(captured["series/observations"]["observation_end"], "2026-09-01")
+
+
+@pytest.mark.unit
+class FredRoutingTests(unittest.TestCase):
+    def setUp(self):
+        config_module._config = copy.deepcopy(default_config.DEFAULT_CONFIG)
+
+    def tearDown(self):
+        config_module._config = copy.deepcopy(default_config.DEFAULT_CONFIG)
+
+    def test_macro_category_routes_to_fred(self):
+        self.assertEqual(
+            interface.get_category_for_method("get_macro_indicators"), "macro_data"
+        )
+        set_config({"data_vendors": {"macro_data": "fred"}})
+        with mock.patch.dict(
+            interface.VENDOR_METHODS,
+            {"get_macro_indicators": {"fred": lambda *a, **k: "MACRO_OK"}},
+            clear=False,
+        ):
+            out = interface.route_to_vendor("get_macro_indicators", "cpi", "2026-06-01", 365)
+        self.assertEqual(out, "MACRO_OK")
+
+    def test_not_configured_degrades_gracefully(self):
+        # macro_data is optional: with only fred and no key, the router degrades
+        # to a sentinel instead of aborting the run — a missing optional key must
+        # not crash an analysis.
+        set_config({"data_vendors": {"macro_data": "fred"}})
+
+        def _unconfigured(*a, **k):
+            raise fred.FredNotConfiguredError("FRED_API_KEY not set")
+
+        with mock.patch.dict(
+            interface.VENDOR_METHODS,
+            {"get_macro_indicators": {"fred": _unconfigured}},
+            clear=False,
+        ):
+            out = interface.route_to_vendor("get_macro_indicators", "cpi", "2026-06-01", 365)
+        self.assertIn("DATA_UNAVAILABLE", out)
+
+
+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

tests/test_fundamentals_lookahead.py

@@ -0,0 +1,130 @@
+"""Historical fundamentals must not leak a live company profile (#1300).
+
+Vendor "company overview" endpoints (yfinance ``Ticker.info``, Alpha Vantage
+``OVERVIEW``) serve only present-day values: market cap, valuation multiples,
+the 52-week range and TTM income all move with today's quote, and even name,
+sector and industry shift when a company renames or is reclassified. None of it
+carries a historical vintage, so emitting it into a run dated in the past puts
+post-decision information into the analyst's context, in the same family as the
+FRED (#1275), social (#1220) and memory (#1251) leaks.
+
+Both vendors withhold on one shared rule (``date_window.withhold_live_profile``)
+so switching ``fundamental_data`` between them cannot reintroduce the leak. The
+statement tools stay point-in-time by filtering on ``curr_date``, and a live run
+is unchanged. All API access is mocked.
+"""
+from __future__ import annotations
+
+from unittest import mock
+
+import pytest
+
+from tradingagents.dataflows import alpha_vantage_fundamentals as av, date_window, y_finance
+
+_TODAY = "2026-09-07"
+_PAST = "2024-05-10"
+
+# A profile payload mixing stable-looking identity fields with market-dependent ones.
+_INFO = {
+    "longName": "Apple Inc.",
+    "sector": "Technology",
+    "industry": "Consumer Electronics",
+    "marketCap": 3_500_000_000_000,
+    "trailingPE": 34.2,
+    "fiftyTwoWeekHigh": 260.1,
+    "totalRevenue": 391_000_000_000,
+}
+
+# Values that must never reach a historical run.
+_LEAKY = ("3500000000000", "34.2", "260.1", "391000000000",
+          "Apple Inc.", "Technology", "Consumer Electronics")
+
+
+def _yf(curr_date, info=_INFO, today=_TODAY):
+    with mock.patch.object(date_window, "get_current_date", return_value=today), \
+         mock.patch.object(y_finance, "yf_retry", lambda fn: info), \
+         mock.patch.object(y_finance.yf, "Ticker"):
+        return y_finance.get_fundamentals("AAPL", curr_date)
+
+
+def _av(curr_date, today=_TODAY):
+    """Alpha Vantage path; the API call is mocked so a leak would be visible."""
+    with mock.patch.object(date_window, "get_current_date", return_value=today), \
+         mock.patch.object(av, "_make_api_request",
+                           return_value="MarketCapitalization: 3500000000000") as req:
+        return av.get_fundamentals("AAPL", curr_date), req
+
+
+@pytest.mark.unit
+class TestYFinanceHistoricalRun:
+    def test_no_profile_value_survives(self):
+        out = _yf(_PAST)
+        for leaked in _LEAKY:
+            assert leaked not in out, f"leaked live-profile value {leaked!r}"
+
+    def test_states_the_as_of_date_and_explains_itself(self):
+        # The analyst must be told why the figures are absent, so it does not
+        # read the gap as a real signal or fabricate around it.
+        out = _yf(_PAST)
+        assert f"Point-in-time as of: {_PAST}" in out
+        assert "withheld" in out
+        assert _PAST in out and _TODAY in out
+
+    def test_no_wall_clock_retrieval_stamp(self):
+        # The old header stamped datetime.now(), which is what surfaced the leak.
+        assert "Data retrieved on:" not in _yf(_PAST)
+
+    def test_the_request_is_not_even_made(self):
+        # The response would only be discarded; skipping it also avoids burning
+        # vendor quota on a call whose result cannot be used.
+        with mock.patch.object(date_window, "get_current_date", return_value=_TODAY), \
+             mock.patch.object(y_finance.yf, "Ticker") as tk:
+            y_finance.get_fundamentals("AAPL", _PAST)
+        tk.assert_not_called()
+
+
+@pytest.mark.unit
+class TestAlphaVantageHistoricalRun:
+    """The same rule must hold for the other fundamentals vendor, or switching
+    data_vendors["fundamental_data"] would silently reintroduce the leak."""
+
+    def test_overview_is_withheld(self):
+        out, _ = _av(_PAST)
+        assert "3500000000000" not in out
+        assert "withheld" in out
+        assert f"Point-in-time as of: {_PAST}" in out
+
+    def test_the_api_call_is_not_made(self):
+        _, req = _av(_PAST)
+        req.assert_not_called()
+
+    def test_live_run_still_calls_the_api(self):
+        out, req = _av(_TODAY)
+        req.assert_called_once()
+        assert "3500000000000" in out
+
+
+@pytest.mark.unit
+class TestLiveRunUnchanged:
+    def test_yfinance_current_date_returns_the_full_profile(self):
+        out = _yf(_TODAY)
+        for value in _LEAKY:
+            assert value in out
+        assert "Data retrieved on:" in out
+        assert "withheld" not in out
+
+    def test_yfinance_absent_curr_date_returns_the_full_profile(self):
+        out = _yf(None)
+        assert "Market Cap: 3500000000000" in out
+        assert "withheld" not in out
+
+
+@pytest.mark.unit
+class TestNoUsableFieldsStillRaises:
+    def test_stub_payload_raises_no_market_data(self):
+        # yfinance returns {"trailingPegRatio": None} for unknown symbols; on a
+        # live run that must stay a hard "no data", not a bare header.
+        from tradingagents.dataflows.symbol_utils import NoMarketDataError
+
+        with pytest.raises(NoMarketDataError):
+            _yf(_TODAY, info={"trailingPegRatio": None})

tests/test_google_api_key.py

@@ -0,0 +1,31 @@
+import unittest
+from unittest.mock import patch
+
+import pytest
+
+from tradingagents.llm_clients.google_client import GoogleClient
+
+
+@pytest.mark.unit
+class TestGoogleApiKeyStandardization(unittest.TestCase):
+    """Verify GoogleClient accepts unified api_key parameter."""
+
+    @patch("tradingagents.llm_clients.google_client.NormalizedChatGoogleGenerativeAI")
+    def test_api_key_handling(self, mock_chat):
+        test_cases = [
+            ("unified api_key is mapped", {"api_key": "test-key-123"}, "test-key-123"),
+            ("legacy google_api_key still works", {"google_api_key": "legacy-key-456"}, "legacy-key-456"),
+            ("unified api_key takes precedence", {"api_key": "unified", "google_api_key": "legacy"}, "unified"),
+        ]
+
+        for msg, kwargs, expected_key in test_cases:
+            with self.subTest(msg=msg):
+                mock_chat.reset_mock()
+                client = GoogleClient("gemini-3.5-flash", **kwargs)
+                client.get_llm()
+                call_kwargs = mock_chat.call_args[1]
+                self.assertEqual(call_kwargs.get("google_api_key"), expected_key)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_google_thinking_level.py

@@ -0,0 +1,62 @@
+"""Gemini thinking_level forwarding (Gemini 3.x).
+
+The catalog is Gemini 3.x only, which takes the string ``thinking_level``
+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
+
+import pytest
+
+from tradingagents.llm_clients.google_client import GoogleClient
+
+
+def _captured_kwargs(model, **kwargs):
+    captured = {}
+    with mock.patch.object(
+        __import__("tradingagents.llm_clients.google_client", fromlist=["x"]),
+        "NormalizedChatGoogleGenerativeAI",
+        lambda **kw: captured.setdefault("kw", kw),
+    ):
+        GoogleClient(model, api_key="x", **kwargs).get_llm()
+    return captured["kw"]
+
+
+@pytest.mark.parametrize("level", ["minimal", "low", "medium", "high"])
+def test_flash_passes_thinking_level_through(level):
+    kw = _captured_kwargs("gemini-3.5-flash", thinking_level=level)
+    assert kw["thinking_level"] == level
+    assert "thinking_budget" not in kw  # the 2.5-era param is gone
+
+
+def test_pro_remaps_minimal_to_low():
+    kw = _captured_kwargs("gemini-3.1-pro-preview", thinking_level="minimal")
+    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"
+
+
+def test_no_thinking_level_is_omitted():
+    kw = _captured_kwargs("gemini-3.5-flash")
+    assert "thinking_level" not in kw
+    assert "thinking_budget" not in kw

tests/test_i18n_coverage.py

@@ -0,0 +1,59 @@
+"""Every report-producing agent must apply the configured output language
+(#740/#801).
+
+A non-English run should produce a fully localized report, not a mix of
+languages. The bug originally happened because several agents silently omitted
+the instruction (fixed in 6b384f7); this test codifies the invariant so a future
+refactor can't quietly drop it again.
+"""
+from pathlib import Path
+
+import pytest
+
+from tradingagents.agents.utils.agent_utils import get_language_instruction
+
+_AGENTS_DIR = Path(__file__).resolve().parents[1] / "tradingagents" / "agents"
+
+# Every node whose text reaches the saved report. If you add a report-producing
+# agent, add it here — and make it call get_language_instruction().
+REPORT_AGENTS = [
+    "analysts/market_analyst.py",
+    "analysts/news_analyst.py",
+    "analysts/fundamentals_analyst.py",
+    "analysts/sentiment_analyst.py",
+    "researchers/bull_researcher.py",
+    "researchers/bear_researcher.py",
+    "managers/research_manager.py",
+    "managers/portfolio_manager.py",
+    "risk_mgmt/aggressive_debator.py",
+    "risk_mgmt/conservative_debator.py",
+    "risk_mgmt/neutral_debator.py",
+    "trader/trader.py",
+]
+
+
+@pytest.mark.unit
+class TestLanguageInstruction:
+    def test_english_adds_no_tokens(self, monkeypatch):
+        from tradingagents.dataflows.config import set_config
+        set_config({"output_language": "English"})
+        assert get_language_instruction() == ""
+
+    def test_non_english_emits_directive(self):
+        from tradingagents.dataflows.config import set_config
+        set_config({"output_language": "中文"})
+        out = get_language_instruction()
+        assert "中文" in out
+        assert "entire response" in out
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("rel", REPORT_AGENTS)
+def test_report_agent_applies_language_instruction(rel):
+    path = _AGENTS_DIR / rel
+    assert path.exists(), f"missing agent module: {rel}"
+    src = path.read_text(encoding="utf-8")
+    assert "get_language_instruction()" in src, (
+        f"{rel} does not apply get_language_instruction(); its output would "
+        f"ignore the configured output_language (#740/#801)."
+    )

tests/test_instrument_identity.py

@@ -0,0 +1,170 @@
+"""Tests for deterministic instrument-identity resolution (#814) and the
+context-anchored message placeholder (#888)."""
+
+import unittest
+from unittest.mock import patch
+
+import pytest
+from langchain_core.messages import AIMessage, HumanMessage, RemoveMessage
+
+from tradingagents.agents.utils.agent_utils import (
+    build_instrument_context,
+    create_msg_delete,
+    get_instrument_context_from_state,
+    resolve_instrument_identity,
+)
+
+
+@pytest.mark.unit
+class ResolveInstrumentIdentityTests(unittest.TestCase):
+    def setUp(self):
+        resolve_instrument_identity.cache_clear()
+
+    def test_resolves_company_metadata_from_yfinance(self):
+        with patch("tradingagents.agents.utils.agent_utils.yf.Ticker") as mock:
+            mock.return_value.info = {
+                "longName": "TOTO LTD.",
+                "shortName": "TOTO",
+                "sector": "Industrials",
+                "industry": "Building Products & Equipment",
+                "exchange": "PNK",
+                "quoteType": "EQUITY",
+            }
+            identity = resolve_instrument_identity("totdy")
+        mock.assert_called_once_with("TOTDY")
+        self.assertEqual(identity["company_name"], "TOTO LTD.")
+        self.assertEqual(identity["sector"], "Industrials")
+        self.assertEqual(identity["industry"], "Building Products & Equipment")
+        self.assertEqual(identity["exchange"], "PNK")
+
+    def test_falls_back_to_short_name(self):
+        with patch("tradingagents.agents.utils.agent_utils.yf.Ticker") as mock:
+            mock.return_value.info = {"shortName": "TOTO", "sector": "Industrials"}
+            identity = resolve_instrument_identity("TOTDY")
+        self.assertEqual(identity["company_name"], "TOTO")
+
+    def test_skips_placeholder_values(self):
+        with patch("tradingagents.agents.utils.agent_utils.yf.Ticker") as mock:
+            mock.return_value.info = {"longName": "  ", "sector": "None", "industry": "n/a"}
+            identity = resolve_instrument_identity("TOTDY")
+        self.assertEqual(identity, {})
+
+    def test_fails_open_on_exception(self):
+        with patch(
+            "tradingagents.agents.utils.agent_utils.yf.Ticker",
+            side_effect=RuntimeError("rate limited"),
+        ):
+            self.assertEqual(resolve_instrument_identity("TOTDY"), {})
+
+    def test_result_is_cached(self):
+        with patch("tradingagents.agents.utils.agent_utils.yf.Ticker") as mock:
+            mock.return_value.info = {"longName": "TOTO LTD."}
+            first = resolve_instrument_identity("TOTDY")
+            second = resolve_instrument_identity("TOTDY")
+        mock.assert_called_once()  # second call served from cache
+        self.assertEqual(first, second)
+
+
+@pytest.mark.unit
+class BuildInstrumentContextTests(unittest.TestCase):
+    def test_mentions_exact_symbol_without_identity(self):
+        context = build_instrument_context("7203.T")
+        self.assertIn("7203.T", context)
+        self.assertIn("exchange suffix", context)
+        self.assertNotIn("Resolved identity", context)
+
+    def test_injects_resolved_identity(self):
+        context = build_instrument_context(
+            "TOTDY", "stock",
+            {
+                "company_name": "TOTO LTD.",
+                "sector": "Industrials",
+                "industry": "Building Products & Equipment",
+                "exchange": "PNK",
+            },
+        )
+        self.assertIn("Company: TOTO LTD.", context)
+        self.assertIn("Industrials / Building Products & Equipment", context)
+        self.assertIn("Exchange: PNK", context)
+        self.assertIn("Do not substitute a different company", context)
+
+    def test_crypto_uses_name_label_and_keeps_hint(self):
+        context = build_instrument_context(
+            "BTC-USD", "crypto", {"company_name": "Bitcoin USD"}
+        )
+        self.assertIn("Name: Bitcoin USD", context)
+        self.assertIn("crypto asset rather than a company", context)
+
+
+@pytest.mark.unit
+class GetInstrumentContextFromStateTests(unittest.TestCase):
+    def test_prefers_precomputed_context(self):
+        state = {"company_of_interest": "TOTDY", "instrument_context": "PRECOMPUTED"}
+        self.assertEqual(get_instrument_context_from_state(state), "PRECOMPUTED")
+
+    def test_fallback_is_network_free_ticker_only(self):
+        # No instrument_context and no yfinance call — must not hit the network.
+        with patch("tradingagents.agents.utils.agent_utils.yf.Ticker") as mock:
+            context = get_instrument_context_from_state(
+                {"company_of_interest": "NVDA", "asset_type": "stock"}
+            )
+        mock.assert_not_called()
+        self.assertIn("NVDA", context)
+
+    def test_fallback_respects_asset_type(self):
+        context = get_instrument_context_from_state(
+            {"company_of_interest": "BTC-USD", "asset_type": "crypto"}
+        )
+        self.assertIn("crypto asset", context)
+
+
+@pytest.mark.unit
+class ContextAnchoredPlaceholderTests(unittest.TestCase):
+    """#888 — the message-clear placeholder must not be a bare 'Continue'."""
+
+    def _run(self, state_extra):
+        state = {
+            "messages": [
+                HumanMessage(content="old", id="h1"),
+                AIMessage(content="reply", id="a1"),
+            ],
+            **state_extra,
+        }
+        return create_msg_delete()(state)
+
+    def test_placeholder_is_not_bare_continue(self):
+        result = self._run(
+            {"company_of_interest": "EC", "asset_type": "stock", "trade_date": "2026-05-28"}
+        )
+        placeholder = result["messages"][-1]
+        self.assertIsInstance(placeholder, HumanMessage)
+        self.assertNotEqual(placeholder.content.strip(), "Continue")
+
+    def test_placeholder_carries_resolved_identity(self):
+        result = self._run(
+            {
+                "company_of_interest": "EC",
+                "instrument_context": "The instrument to analyze is `EC`. Resolved identity: Company: Ecopetrol.",
+                "trade_date": "2026-05-28",
+            }
+        )
+        content = result["messages"][-1].content
+        self.assertIn("Ecopetrol", content)
+        self.assertIn("2026-05-28", content)
+
+    def test_old_messages_are_removed(self):
+        result = self._run({"company_of_interest": "EC", "trade_date": "2026-05-28"})
+        removals = [m for m in result["messages"] if isinstance(m, RemoveMessage)]
+        humans = [m for m in result["messages"] if isinstance(m, HumanMessage)]
+        self.assertEqual(len(removals), 2)
+        self.assertEqual(len(humans), 1)
+
+    def test_safe_defaults_when_state_minimal(self):
+        result = create_msg_delete()({"messages": [], "company_of_interest": "EC"})
+        placeholder = result["messages"][-1]
+        self.assertNotEqual(placeholder.content.strip(), "Continue")
+        self.assertIn("EC", placeholder.content)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_llm_max_retries.py

@@ -0,0 +1,100 @@
+"""Configurable LLM SDK retry budget (#1090/#1091).
+
+A single transient 429 burst used to kill an otherwise-healthy multi-agent run
+because each provider SDK's max_retries (default 2) was not exposed. This adds an
+opt-in llm_max_retries knob forwarded to every provider chat client.
+"""
+from __future__ import annotations
+
+import importlib
+
+import pytest
+
+import tradingagents.default_config as default_config_module
+from tradingagents.graph.trading_graph import TradingAgentsGraph, _coerce_max_retries
+
+# --- coercion / validation -------------------------------------------------
+
+@pytest.mark.unit
+@pytest.mark.parametrize("value,expected", [(0, 0), (2, 2), (10, 10), ("6", 6)])
+def test_coerce_accepts_non_negative_ints_and_numeric_strings(value, expected):
+    assert _coerce_max_retries(value) == expected
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("bad", [-1, "-3"])
+def test_coerce_rejects_negative(bad):
+    with pytest.raises(ValueError, match=">= 0"):
+        _coerce_max_retries(bad)
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("bad", [True, False])
+def test_coerce_rejects_booleans(bad):
+    with pytest.raises(ValueError, match="boolean"):
+        _coerce_max_retries(bad)
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("bad", ["abc", "1.5", None])
+def test_coerce_rejects_non_integers(bad):
+    with pytest.raises(ValueError, match="integer"):
+        _coerce_max_retries(bad)
+
+
+# --- forwarding into provider kwargs --------------------------------------
+
+def _bare_graph(config):
+    g = object.__new__(TradingAgentsGraph)
+    g.config = config
+    return g
+
+
+@pytest.mark.unit
+def test_not_forwarded_when_unset():
+    kwargs = _bare_graph({"llm_provider": "openai", "llm_max_retries": None})._get_provider_kwargs()
+    assert "max_retries" not in kwargs
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("provider", ["openai", "anthropic", "google"])
+def test_forwarded_across_providers(provider):
+    kwargs = _bare_graph({"llm_provider": provider, "llm_max_retries": 6})._get_provider_kwargs()
+    assert kwargs["max_retries"] == 6
+
+
+@pytest.mark.unit
+def test_forwarded_env_string_is_coerced():
+    # env vars arrive as strings; the consumer coerces (like temperature)
+    kwargs = _bare_graph({"llm_provider": "openai", "llm_max_retries": "4"})._get_provider_kwargs()
+    assert kwargs["max_retries"] == 4
+
+
+@pytest.mark.unit
+def test_invalid_config_value_fails_loudly():
+    with pytest.raises(ValueError):
+        _bare_graph({"llm_provider": "openai", "llm_max_retries": -1})._get_provider_kwargs()
+
+
+# --- env overlay -----------------------------------------------------------
+
+def _reload_with_env(monkeypatch, **overrides):
+    for key in list(default_config_module._ENV_OVERRIDES):
+        monkeypatch.delenv(key, raising=False)
+    for key, val in overrides.items():
+        monkeypatch.setenv(key, val)
+    return importlib.reload(default_config_module)
+
+
+@pytest.mark.unit
+def test_default_is_none(monkeypatch):
+    dc = _reload_with_env(monkeypatch)
+    assert dc.DEFAULT_CONFIG["llm_max_retries"] is None
+
+
+@pytest.mark.unit
+def test_env_override_sets_config(monkeypatch):
+    dc = _reload_with_env(monkeypatch, TRADINGAGENTS_LLM_MAX_RETRIES="8")
+    # None-default key: env value arrives as a string and is coerced downstream.
+    assert dc.DEFAULT_CONFIG["llm_max_retries"] == "8"
+    assert _coerce_max_retries(dc.DEFAULT_CONFIG["llm_max_retries"]) == 8

tests/test_llm_max_tokens.py

@@ -0,0 +1,122 @@
+"""Configurable output-token cap (#1204).
+
+Some model/gateway combinations (e.g. deepseek-v4-flash deployments) emit
+unbounded reasoning/output and hang or trip an idle timeout. An opt-in
+``max_tokens`` config knob is forwarded to every provider so a run can bound it;
+Gemini names the parameter ``max_output_tokens``, so it is forwarded under the
+right key per provider.
+"""
+from __future__ import annotations
+
+import importlib
+
+import pytest
+
+import tradingagents.default_config as default_config_module
+from tradingagents.graph.trading_graph import TradingAgentsGraph, _coerce_max_tokens
+
+# --- coercion / validation -------------------------------------------------
+
+@pytest.mark.unit
+@pytest.mark.parametrize("value,expected", [(1, 1), (8192, 8192), ("4096", 4096)])
+def test_coerce_accepts_positive_ints_and_numeric_strings(value, expected):
+    assert _coerce_max_tokens(value) == expected
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("bad", [0, -1, "0", "-5"])
+def test_coerce_rejects_non_positive(bad):
+    with pytest.raises(ValueError, match="> 0"):
+        _coerce_max_tokens(bad)
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("bad", [True, False])
+def test_coerce_rejects_booleans(bad):
+    with pytest.raises(ValueError, match="boolean"):
+        _coerce_max_tokens(bad)
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("bad", ["abc", "1.5", None])
+def test_coerce_rejects_non_integers(bad):
+    with pytest.raises(ValueError, match="integer"):
+        _coerce_max_tokens(bad)
+
+
+# --- forwarding into provider kwargs (right key per provider) --------------
+
+def _bare_graph(config):
+    g = object.__new__(TradingAgentsGraph)
+    g.config = config
+    return g
+
+
+@pytest.mark.unit
+def test_not_forwarded_when_unset():
+    kwargs = _bare_graph({"llm_provider": "openai", "max_tokens": None})._get_provider_kwargs()
+    assert "max_tokens" not in kwargs
+    assert "max_output_tokens" not in kwargs
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("provider", ["openai", "anthropic", "deepseek", "openai_compatible"])
+def test_forwarded_as_max_tokens_for_non_google(provider):
+    kwargs = _bare_graph({"llm_provider": provider, "max_tokens": 8192})._get_provider_kwargs()
+    assert kwargs["max_tokens"] == 8192
+    assert "max_output_tokens" not in kwargs
+
+
+@pytest.mark.unit
+def test_forwarded_as_max_output_tokens_for_google():
+    # Gemini's kwarg name differs; forwarding plain max_tokens would be rejected.
+    kwargs = _bare_graph({"llm_provider": "google", "max_tokens": 8192})._get_provider_kwargs()
+    assert kwargs["max_output_tokens"] == 8192
+    assert "max_tokens" not in kwargs
+
+
+@pytest.mark.unit
+def test_env_string_is_coerced():
+    kwargs = _bare_graph({"llm_provider": "openai", "max_tokens": "4096"})._get_provider_kwargs()
+    assert kwargs["max_tokens"] == 4096
+
+
+@pytest.mark.unit
+def test_invalid_value_fails_loudly():
+    with pytest.raises(ValueError):
+        _bare_graph({"llm_provider": "openai", "max_tokens": 0})._get_provider_kwargs()
+
+
+# --- client-side allowlists carry the kwarg --------------------------------
+
+@pytest.mark.unit
+def test_openai_and_google_clients_accept_the_kwarg():
+    from tradingagents.llm_clients import openai_client
+    from tradingagents.llm_clients.google_client import GoogleClient  # noqa: F401
+    assert "max_tokens" in openai_client._PASSTHROUGH_KWARGS
+    # Google client forwards max_output_tokens through construction.
+    llm = GoogleClient("gemini-3.5-flash", api_key="x", max_output_tokens=8192).get_llm()
+    assert getattr(llm, "max_output_tokens", None) == 8192
+
+
+# --- env overlay -----------------------------------------------------------
+
+def _reload_with_env(monkeypatch, **overrides):
+    for key in list(default_config_module._ENV_OVERRIDES):
+        monkeypatch.delenv(key, raising=False)
+    for key, val in overrides.items():
+        monkeypatch.setenv(key, val)
+    return importlib.reload(default_config_module)
+
+
+@pytest.mark.unit
+def test_default_is_none(monkeypatch):
+    dc = _reload_with_env(monkeypatch)
+    assert dc.DEFAULT_CONFIG["max_tokens"] is None
+
+
+@pytest.mark.unit
+def test_env_override_sets_config(monkeypatch):
+    dc = _reload_with_env(monkeypatch, TRADINGAGENTS_MAX_TOKENS="8192")
+    assert dc.DEFAULT_CONFIG["max_tokens"] == "8192"
+    assert _coerce_max_tokens(dc.DEFAULT_CONFIG["max_tokens"]) == 8192

tests/test_market_data_validator.py

@@ -0,0 +1,76 @@
+"""Tests for the deterministic market-data verification snapshot (#830/#881)."""
+
+from __future__ import annotations
+
+import pandas as pd
+import pytest
+
+import tradingagents.dataflows.market_data_validator as validator
+
+
+def _sample_ohlcv() -> pd.DataFrame:
+    dates = pd.bdate_range("2026-04-01", "2026-05-20")
+    closes = [100 + i for i in range(len(dates))]
+    return pd.DataFrame({
+        "Date": dates,
+        "Open": [c - 0.5 for c in closes],
+        "High": [c + 1.0 for c in closes],
+        "Low": [c - 1.0 for c in closes],
+        "Close": closes,
+        "Volume": [1_000_000 + i for i in range(len(dates))],
+    })
+
+
+@pytest.mark.unit
+class TestVerifiedSnapshot:
+    def test_excludes_future_rows(self, monkeypatch):
+        data = pd.concat([
+            _sample_ohlcv(),
+            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, fill_gaps=True: data)
+
+        snap = validator.build_verified_market_snapshot("COF", "2026-05-13")
+        assert "Verified market data snapshot for COF" in snap
+        assert "Requested analysis date: 2026-05-13" in snap
+        assert "Latest trading row used: 2026-05-13" in snap
+        assert "999.00" not in snap          # future row excluded
+        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, 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, 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, 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, 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-")]
+        assert 0 < len(close_rows) <= 30
+
+
+@pytest.mark.unit
+class TestTool:
+    def test_tool_delegates_to_builder(self, monkeypatch):
+        from tradingagents.agents.utils.market_data_validation_tools import (
+            get_verified_market_snapshot,
+        )
+        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"}
+        )
+        assert "Verified market data snapshot for COF" in out

tests/test_market_toolnode.py

@@ -0,0 +1,23 @@
+"""The market analyst is bound (and prompt-instructed) to call
+get_verified_market_snapshot; if the executor ToolNode doesn't register it, the
+call fails and the model reports the tool "unavailable" and skips verification.
+
+Regression guard for that wiring gap (snapshot bound to the LLM but missing from
+the market ToolNode).
+"""
+import pytest
+
+from tradingagents.graph.trading_graph import TradingAgentsGraph
+
+
+@pytest.mark.unit
+def test_market_toolnode_can_execute_verified_snapshot():
+    # _create_tool_nodes does not use self -> call unbound (avoids building LLMs).
+    nodes = TradingAgentsGraph._create_tool_nodes(None)
+    market_tools = set(nodes["market"].tools_by_name)
+    assert "get_verified_market_snapshot" in market_tools, (
+        "get_verified_market_snapshot is bound to the market analyst but not "
+        "registered in the market ToolNode, so the model's call fails."
+    )
+    # the other core market tools must remain too
+    assert {"get_stock_data", "get_indicators"} <= market_tools

tests/test_memory_pointintime.py

@@ -0,0 +1,95 @@
+"""Memory-log lessons must be point-in-time safe in a backtest (#1251).
+
+get_past_context previously returned every resolved lesson regardless of the run
+date, so a historical run could learn from an outcome that had not happened yet.
+Resolved entries now record the date their outcome became known (``resolved:``),
+and get_past_context(as_of=...) filters on it. Legacy entries without a
+resolution date are excluded from a point-in-time query (conservative migration).
+"""
+from __future__ import annotations
+
+import pytest
+
+from tradingagents.agents.utils.memory import TradingMemoryLog
+
+
+def _log(tmp_path):
+    return TradingMemoryLog({"memory_log_path": str(tmp_path / "mem.md")})
+
+
+def _resolve(log, ticker, date, resolution_date, reflection):
+    log.store_decision(ticker, date, f"Rating: Buy\n{reflection}")
+    log.update_with_outcome(
+        ticker, date, 0.05, 0.02, 5, reflection, resolution_date=resolution_date,
+    )
+
+
+@pytest.mark.unit
+def test_resolution_date_is_stored_and_parsed(tmp_path):
+    log = _log(tmp_path)
+    _resolve(log, "NVDA", "2026-01-05", "2026-01-10", "outcome known 01-10")
+    entry = log.load_entries()[0]
+    assert entry["resolved"] == "2026-01-10"
+    assert "resolved:2026-01-10" in (tmp_path / "mem.md").read_text()
+
+
+@pytest.mark.unit
+def test_as_of_excludes_lessons_resolved_after_the_run_date(tmp_path):
+    log = _log(tmp_path)
+    # Decision on 01-05, outcome only known on 01-10.
+    _resolve(log, "NVDA", "2026-01-05", "2026-01-10", "great trade")
+
+    # A run as-of 01-07 must NOT see it (the outcome was still in the future).
+    assert log.get_past_context("NVDA", as_of="2026-01-07") == ""
+    # A run as-of 01-10 (and later) sees it.
+    assert "great trade" in log.get_past_context("NVDA", as_of="2026-01-10")
+    assert "great trade" in log.get_past_context("NVDA", as_of="2026-02-01")
+
+
+@pytest.mark.unit
+def test_no_as_of_is_unfiltered_live_behavior(tmp_path):
+    log = _log(tmp_path)
+    _resolve(log, "NVDA", "2026-01-05", "2026-01-10", "great trade")
+    # Live run (no as_of): unchanged behavior, lesson is shown.
+    assert "great trade" in log.get_past_context("NVDA")
+
+
+@pytest.mark.unit
+def test_legacy_entry_without_resolution_date_excluded_in_backtest(tmp_path):
+    log = _log(tmp_path)
+    # Simulate a pre-migration resolved entry: no resolution_date recorded.
+    log.store_decision("NVDA", "2026-01-05", "Rating: Buy\nlegacy lesson")
+    log.update_with_outcome("NVDA", "2026-01-05", 0.05, 0.02, 5, "legacy lesson")
+    entry = log.load_entries()[0]
+    assert entry["resolved"] is None
+
+    # Conservative: excluded from a point-in-time query (can't prove it was known)...
+    assert log.get_past_context("NVDA", as_of="2026-06-01") == ""
+    # ...but still available on a live (unfiltered) run.
+    assert "legacy lesson" in log.get_past_context("NVDA")
+
+
+@pytest.mark.unit
+def test_cross_ticker_lessons_are_also_gated(tmp_path):
+    log = _log(tmp_path)
+    _resolve(log, "AAPL", "2026-01-05", "2026-01-10", "cross lesson")
+    # Querying a different ticker as-of before resolution: no cross lesson leaks.
+    assert log.get_past_context("NVDA", as_of="2026-01-07") == ""
+    assert "cross lesson" in log.get_past_context("NVDA", as_of="2026-01-10")
+
+
+@pytest.mark.unit
+def test_memory_as_of_gates_historical_but_not_live():
+    # The graph filters only for a past trade date; a current-date run passes
+    # None so live behavior and legacy entries are unaffected (#1251).
+    from datetime import datetime, timedelta
+
+    from tradingagents.graph.trading_graph import TradingAgentsGraph
+
+    g = object.__new__(TradingAgentsGraph)
+    past = "2024-01-01"
+    today = datetime.now().strftime("%Y-%m-%d")
+    future = (datetime.now() + timedelta(days=30)).strftime("%Y-%m-%d")
+    assert g._memory_as_of(past) == past       # backtest -> filter on the trade date
+    assert g._memory_as_of(today) is None      # live -> no filter
+    assert g._memory_as_of(future) is None     # future-dated run -> no filter

tests/test_minimax.py

@@ -0,0 +1,73 @@
+"""Tests for MinimaxChatOpenAI quirks.
+
+Verifies the subclass injects ``reasoning_split=True`` into outgoing
+requests so M2.x reasoning models put their <think> block into
+``reasoning_details`` instead of polluting ``message.content``.
+"""
+
+import os
+
+import pytest
+from langchain_core.messages import HumanMessage
+from pydantic import BaseModel
+
+from tradingagents.llm_clients.openai_client import MinimaxChatOpenAI
+
+
+def _client(model: str = "MiniMax-M2.7"):
+    os.environ.setdefault("MINIMAX_API_KEY", "placeholder")
+    return MinimaxChatOpenAI(
+        model=model,
+        api_key="placeholder",
+        base_url="https://api.minimax.io/v1",
+    )
+
+
+@pytest.mark.unit
+class TestMinimaxReasoningSplit:
+    def test_reasoning_split_sent_via_extra_body_not_top_level(self):
+        # Must be in extra_body, not top-level: the openai SDK validates
+        # top-level params and rejects unknown ones like reasoning_split (#826).
+        payload = _client()._get_request_payload([HumanMessage(content="hi")])
+        assert payload.get("extra_body", {}).get("reasoning_split") is True
+        assert "reasoning_split" not in payload  # never top-level
+
+    def test_non_reasoning_minimax_does_not_inject_reasoning_split(self):
+        """Coding Plan / MiniMax-Text-01 / any non-M2-prefixed model must NOT
+        receive reasoning_split at all (top-level or extra_body) (#826)."""
+        for model in ("minimax-text-01", "MiniMax-Coding-Plan"):
+            payload = _client(model)._get_request_payload(
+                [HumanMessage(content="hi")]
+            )
+            assert "reasoning_split" not in payload
+            assert "reasoning_split" not in payload.get("extra_body", {})
+
+
+@pytest.mark.unit
+class TestMinimaxStructuredOutputDispatch:
+    """M2.x models route through the capability table — tool_choice is
+    suppressed but the schema is still bound as a tool."""
+
+    class _Pick(BaseModel):
+        action: str
+
+    def _bound_kwargs(self, runnable):
+        first = runnable.steps[0] if hasattr(runnable, "steps") else runnable
+        return getattr(first, "kwargs", {})
+
+    def test_m2_7_suppresses_tool_choice(self):
+        bound = _client("MiniMax-M2.7").with_structured_output(self._Pick)
+        kwargs = self._bound_kwargs(bound)
+        assert kwargs.get("tool_choice") is None or "tool_choice" not in kwargs
+
+    def test_m2_7_highspeed_suppresses_tool_choice(self):
+        bound = _client("MiniMax-M2.7-highspeed").with_structured_output(self._Pick)
+        kwargs = self._bound_kwargs(bound)
+        assert kwargs.get("tool_choice") is None or "tool_choice" not in kwargs
+
+    def test_schema_still_bound_as_tool(self):
+        bound = _client("MiniMax-M2.7").with_structured_output(self._Pick)
+        tools = self._bound_kwargs(bound).get("tools", [])
+        assert any(
+            t.get("function", {}).get("name") == "_Pick" for t in tools
+        ), f"schema not bound: {tools}"

tests/test_model_validation.py

@@ -0,0 +1,100 @@
+import unittest
+import warnings
+
+import pytest
+
+from tradingagents.llm_clients.base_client import BaseLLMClient
+from tradingagents.llm_clients.model_catalog import get_known_models
+from tradingagents.llm_clients.validators import validate_model
+
+
+class DummyLLMClient(BaseLLMClient):
+    def __init__(self, provider: str, model: str):
+        self.provider = provider
+        super().__init__(model)
+
+    def get_llm(self):
+        self.warn_if_unknown_model()
+        return object()
+
+    def validate_model(self) -> bool:
+        return validate_model(self.provider, self.model)
+
+
+@pytest.mark.unit
+class ModelValidationTests(unittest.TestCase):
+    def test_cli_catalog_models_are_all_validator_approved(self):
+        for provider, models in get_known_models().items():
+            if provider in ("ollama", "openrouter"):
+                continue
+
+            for model in models:
+                with self.subTest(provider=provider, model=model):
+                    self.assertTrue(validate_model(provider, model))
+
+    def test_unknown_model_emits_warning_for_strict_provider(self):
+        client = DummyLLMClient("openai", "not-a-real-openai-model")
+
+        with warnings.catch_warnings(record=True) as caught:
+            warnings.simplefilter("always")
+            client.get_llm()
+
+        self.assertEqual(len(caught), 1)
+        self.assertIn("not-a-real-openai-model", str(caught[0].message))
+        self.assertIn("openai", str(caught[0].message))
+
+    def test_openrouter_and_ollama_accept_custom_models_without_warning(self):
+        for provider in ("openrouter", "ollama"):
+            client = DummyLLMClient(provider, "custom-model-name")
+
+            with self.subTest(provider=provider):
+                with warnings.catch_warnings(record=True) as caught:
+                    warnings.simplefilter("always")
+                    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)

tests/test_news_analyst_prompt.py

@@ -0,0 +1,25 @@
+"""Guard the news analyst prompt against tool-signature drift (#1116).
+
+The prompt used to advertise ``get_news(query, ...)`` while the tool takes a
+``ticker``, tricking the LLM into hallucinating free-text query calls.
+"""
+import inspect
+
+import pytest
+
+import tradingagents.agents.analysts.news_analyst as na
+from tradingagents.agents.utils.news_data_tools import get_news
+
+
+@pytest.mark.unit
+def test_get_news_takes_ticker_not_query():
+    arg_names = set(get_news.args.keys())
+    assert "ticker" in arg_names
+    assert "query" not in arg_names
+
+
+@pytest.mark.unit
+def test_news_prompt_matches_get_news_signature():
+    src = inspect.getsource(na)
+    assert "get_news(ticker, start_date, end_date)" in src
+    assert "get_news(query" not in src

tests/test_news_lookahead.py

@@ -0,0 +1,259 @@
+"""yfinance news must not leak future-dated (or undated, in a backtest) articles
+into a historical window.
+
+Regressions for #992 (flat articles bypassed the date filter), #1007 (global
+news injected future articles), #993 (empty-after-filter returned a blank body),
+and #1126 (inclusive upper bound leaked the midnight-after article; host-local
+timestamp parsing made filtering machine-dependent).
+"""
+from datetime import datetime, timezone
+
+import pytest
+
+import tradingagents.dataflows.yfinance_news as ynews
+from tradingagents.dataflows.date_window import in_window
+
+
+def _epoch(date_str):
+    """Epoch seconds for UTC midnight of ``date_str`` (host-timezone independent)."""
+    return int(datetime.strptime(date_str, "%Y-%m-%d").replace(tzinfo=timezone.utc).timestamp())
+
+
+@pytest.mark.unit
+def test_flat_article_publish_time_is_parsed():
+    # #992: flat articles now carry a pub_date (was always None -> unfilterable).
+    # #1126: parsed as UTC-aware, so the date can't shift with the host timezone.
+    data = ynews._extract_article_data(
+        {"title": "X", "publisher": "P", "link": "l", "providerPublishTime": _epoch("2025-05-09")}
+    )
+    assert data["pub_date"] is not None
+    assert data["pub_date"].tzinfo is not None
+    assert data["pub_date"] == datetime(2025, 5, 9, tzinfo=timezone.utc)
+
+
+@pytest.mark.unit
+def test_window_excludes_future_and_undated_in_backtest():
+    start = datetime(2025, 5, 1)
+    end = datetime(2025, 5, 9)  # historical window (well in the past)
+    inside = datetime(2025, 5, 5)
+    future = datetime(2025, 6, 1)
+    assert in_window(inside, start, end) is True
+    assert in_window(future, start, end) is False     # look-ahead blocked
+    assert in_window(None, start, end) is False        # undated -> excluded in backtest
+
+
+@pytest.mark.unit
+def test_window_keeps_undated_in_live_window():
+    # Live window (reaches today): undated articles can't be "future", so keep them.
+    now = datetime.now(timezone.utc)
+    assert in_window(None, now, now) is True
+
+
+@pytest.mark.unit
+def test_upper_bound_is_exclusive():
+    # #1126: an article stamped exactly midnight AFTER end_date leaked in under
+    # the old inclusive bound; the whole of end_date itself must still be kept.
+    start = datetime(2025, 5, 1)
+    end = datetime(2025, 5, 9)
+    midnight_after = datetime(2025, 5, 10, 0, 0, 0, tzinfo=timezone.utc)
+    last_moment = datetime(2025, 5, 9, 23, 59, 59, tzinfo=timezone.utc)
+    assert in_window(midnight_after, start, end) is False
+    assert in_window(last_moment, start, end) is True
+
+
+@pytest.mark.unit
+def test_offset_aware_timestamp_is_converted_not_truncated():
+    # #1126: 2025-05-10T01:00+05:00 is really 2025-05-09T20:00Z -> inside the
+    # window. Stripping tzinfo (old behavior) misread it as 05-10 and dropped it.
+    start = datetime(2025, 5, 1)
+    end = datetime(2025, 5, 9)
+    aware = datetime.fromisoformat("2025-05-10T01:00:00+05:00")
+    assert in_window(aware, start, end) is True
+
+
+@pytest.mark.unit
+def test_global_news_future_flat_article_excluded(monkeypatch):
+    # #1007: a flat, future-dated global article must not appear in a historical run.
+    future_article = {"title": "FUTURE EVENT", "publisher": "P", "link": "l",
+                      "providerPublishTime": _epoch("2025-06-01")}
+    past_article = {"title": "PAST EVENT", "publisher": "P", "link": "l",
+                    "providerPublishTime": _epoch("2025-05-05")}
+
+    class FakeSearch:
+        def __init__(self, *a, **k):
+            self.news = [future_article, past_article]
+
+    monkeypatch.setattr(ynews.yf, "Search", FakeSearch)
+    out = ynews.get_global_news_yfinance("2025-05-09", look_back_days=7, limit=10)
+    assert "PAST EVENT" in out
+    assert "FUTURE EVENT" not in out  # #1007
+
+
+@pytest.mark.unit
+def test_global_news_empty_after_filter_is_informative(monkeypatch):
+    # #993: everything filtered out -> a clear message, not a blank-bodied report.
+    only_future = {"title": "FUTURE", "publisher": "P", "link": "l",
+                   "providerPublishTime": _epoch("2025-06-01")}
+
+    class FakeSearch:
+        def __init__(self, *a, **k):
+            self.news = [only_future]
+
+    monkeypatch.setattr(ynews.yf, "Search", FakeSearch)
+    out = ynews.get_global_news_yfinance("2025-05-09", look_back_days=7, limit=10)
+    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

tests/test_no_data_handling.py

@@ -0,0 +1,88 @@
+"""Tests that empty vendor results never become fabricated data.
+
+Covers two systematic fixes:
+  - load_ohlcv must not cache an empty download (cache poisoning), and must
+    raise NoMarketDataError instead of returning an empty frame.
+  - route_to_vendor must convert NoMarketDataError into a single explicit
+    "NO_DATA_AVAILABLE" sentinel after all vendors are exhausted.
+"""
+
+import os
+import unittest
+from unittest import mock
+
+import pandas as pd
+import pytest
+
+from tradingagents.dataflows import interface, stockstats_utils
+from tradingagents.dataflows.config import set_config
+from tradingagents.dataflows.symbol_utils import NoMarketDataError
+
+
+@pytest.mark.unit
+class TestLoadOhlcvNoPoison(unittest.TestCase):
+    def setUp(self):
+        self._tmp = os.path.join(os.path.dirname(__file__), "_tmp_cache")
+        os.makedirs(self._tmp, exist_ok=True)
+        set_config({"data_cache_dir": self._tmp})
+
+    def tearDown(self):
+        for f in os.listdir(self._tmp):
+            os.remove(os.path.join(self._tmp, f))
+        os.rmdir(self._tmp)
+
+    def test_empty_download_raises_and_does_not_cache(self):
+        empty = pd.DataFrame()
+        with mock.patch.object(stockstats_utils.yf, "download", return_value=empty), \
+                self.assertRaises(NoMarketDataError):
+            stockstats_utils.load_ohlcv("FAKE", "2026-01-01")
+        # Nothing should have been written to the cache.
+        self.assertEqual(os.listdir(self._tmp), [])
+
+        # A second call must re-attempt the fetch (no poisoned cache served).
+        with mock.patch.object(stockstats_utils.yf, "download", return_value=empty) as dl2:
+            with self.assertRaises(NoMarketDataError):
+                stockstats_utils.load_ohlcv("FAKE", "2026-01-01")
+            self.assertTrue(dl2.called)
+
+
+@pytest.mark.unit
+class TestRouteToVendorSentinel(unittest.TestCase):
+    def test_no_data_from_all_vendors_returns_sentinel(self):
+        def raises_no_data(symbol, *a, **k):
+            raise NoMarketDataError(symbol, "GC=F", "no rows")
+
+        patched = {"yfinance": raises_no_data, "alpha_vantage": raises_no_data}
+        with mock.patch.dict(
+            interface.VENDOR_METHODS, {"get_stock_data": patched}, clear=False
+        ):
+            result = interface.route_to_vendor(
+                "get_stock_data", "XAUUSD+", "2026-01-01", "2026-01-10"
+            )
+        self.assertIn("NO_DATA_AVAILABLE", result)
+        self.assertIn("XAUUSD+", result)
+        self.assertIn("GC=F", result)
+        self.assertIn("Do not estimate", result)
+
+    def test_unconfigured_fallback_does_not_mask_no_data(self):
+        # When the primary vendor reports no data and the fallback is simply
+        # unavailable (e.g. missing API key -> raises), the no-data sentinel
+        # must win rather than the fallback's incidental error crashing out.
+        def raises_no_data(symbol, *a, **k):
+            raise NoMarketDataError(symbol, symbol, "no rows")
+
+        def raises_unavailable(symbol, *a, **k):
+            raise ValueError("ALPHA_VANTAGE_API_KEY environment variable is not set.")
+
+        patched = {"yfinance": raises_no_data, "alpha_vantage": raises_unavailable}
+        with mock.patch.dict(
+            interface.VENDOR_METHODS, {"get_stock_data": patched}, clear=False
+        ):
+            result = interface.route_to_vendor(
+                "get_stock_data", "FAKE", "2026-01-01", "2026-01-10"
+            )
+        self.assertIn("NO_DATA_AVAILABLE", result)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_ohlcv_cache_freshness.py

@@ -0,0 +1,105 @@
+"""The OHLCV cache: one file per symbol, fresh only on the day it was written.
+
+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 pandas as pd
+import pytest
+
+import tradingagents.dataflows.stockstats_utils as su
+
+NOW = pd.Timestamp("2026-07-18 12:00")
+STALE = su.OHLCV_CACHE_TTL_SECONDS + 60
+
+
+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": [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_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._cache_is_fresh(f, NOW.normalize(), NOW) is False
+
+
+@pytest.mark.unit
+def test_recent_cache_is_fresh(tmp_path):
+    # Written moments ago: don't hammer the vendor (weekend/holiday guard).
+    assert su._cache_is_fresh(_write(tmp_path), NOW.normalize(), NOW) is True
+
+
+@pytest.mark.unit
+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._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 freshness check is wired into load_ohlcv's cache branch."""
+    _write(tmp_path, age_seconds=STALE)
+    calls = []
+
+    def _fake_download(*a, **k):
+        calls.append(1)
+        return pd.DataFrame(
+            {"Date": pd.to_datetime(["2026-07-17", "2026-07-18"]), "Close": [100.0, 222.0]}
+        ).set_index("Date")
+
+    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):
+    _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)})
+    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"))
+
+    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()))
+
+    assert len(downloads) == 3, "each new day refetches"
+    assert [p.name for p in tmp_path.iterdir()] == ["AAPL-YFin-data.csv"]

tests/test_ohlcv_latest_bar.py

@@ -0,0 +1,200 @@
+"""The latest trading day's bar must not silently vanish (#1201).
+
+yfinance can return the newest in-range bar with a NaN close (an unsettled or
+glitched session). The old path parsed dates without normalizing timezone and
+dropped every NaN-close row before applying the curr_date cutoff, so the latest
+bar disappeared and the previous trading day looked like the latest. Now dates
+are normalized before the cutoff, so the frame ends at the last settled bar
+instead of carrying a fabricated close.
+
+Refusing the whole frame instead (the first attempt at #1201) reported a
+tradable symbol as invalid or delisted (#1289), so only a range with no close
+anywhere counts as no data and the staleness check judges the rest.
+"""
+from __future__ import annotations
+
+import os
+
+import pandas as pd
+import pytest
+
+from tradingagents.dataflows import stockstats_utils as su
+from tradingagents.dataflows.symbol_utils import NoMarketDataError
+
+# --- date normalization -----------------------------------------------------
+
+@pytest.mark.unit
+def test_normalize_dates_strips_tz_and_normalizes_to_midnight():
+    aware = pd.Series(pd.to_datetime(
+        ["2026-05-08 09:30:00-04:00", "2026-05-09 16:00:00-04:00"]
+    ))
+    out = su._normalize_dates(aware)
+    assert out.dt.tz is None
+    assert list(out) == [pd.Timestamp("2026-05-08"), pd.Timestamp("2026-05-09")]
+
+
+@pytest.mark.unit
+def test_normalize_dates_leaves_naive_dates_at_midnight():
+    naive = pd.Series(pd.to_datetime(["2026-05-08 14:30:00", "2026-05-09 00:00:00"]))
+    out = su._normalize_dates(naive)
+    assert out.dt.tz is None
+    assert list(out) == [pd.Timestamp("2026-05-08"), pd.Timestamp("2026-05-09")]
+
+
+@pytest.mark.unit
+def test_normalize_dates_handles_mixed_dst_offsets():
+    # 5y of US bars span DST; via a cache CSV they arrive as mixed-offset
+    # strings, which pd.to_datetime can't unify. Each keeps its own local date.
+    mixed = pd.Series([
+        "2026-01-08 00:00:00-05:00",  # EST
+        "2026-06-08 00:00:00-04:00",  # EDT
+        "not-a-date",                 # -> NaT
+    ])
+    out = su._normalize_dates(mixed)
+    assert out.iloc[0] == pd.Timestamp("2026-01-08")
+    assert out.iloc[1] == pd.Timestamp("2026-06-08")
+    assert pd.isna(out.iloc[2])
+
+
+@pytest.mark.unit
+def test_normalize_dates_keeps_positive_offset_local_date():
+    # A Tokyo bar at local midnight (+09:00) must stay on its own calendar day,
+    # not shift to the previous UTC day (which utc=True parsing would cause).
+    jst = pd.Series(["2026-05-08 00:00:00+09:00"])
+    assert su._normalize_dates(jst).iloc[0] == pd.Timestamp("2026-05-08")
+
+
+# --- fill vs guard responsibilities ----------------------------------------
+
+@pytest.mark.unit
+def test_clean_dataframe_keeps_nan_close_for_the_caller_to_inspect():
+    # _clean_dataframe normalizes but no longer drops the NaN close itself.
+    df = pd.DataFrame({"Date": ["2026-05-08", "2026-05-09"], "Close": [100.0, float("nan")]})
+    cleaned = su._clean_dataframe(df)
+    assert len(cleaned) == 2
+    assert pd.isna(cleaned["Close"].iloc[-1])
+
+
+@pytest.mark.unit
+def test_fill_price_gaps_drops_nan_close_rows():
+    df = pd.DataFrame({"Date": pd.to_datetime(["2026-05-07", "2026-05-08"]),
+                       "Close": [float("nan"), 100.0]})
+    filled = su._fill_price_gaps(df)
+    assert len(filled) == 1
+    assert filled["Close"].iloc[0] == 100.0
+
+
+# --- load_ohlcv end-to-end (with a mocked cache read) -----------------------
+
+def _run_load(monkeypatch, tmp_path, frame, curr_date):
+    """Drive load_ohlcv against a pre-seeded cache frame (no network)."""
+    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))
+    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")
+    monkeypatch.setattr(su.yf, "download", _fail_download)
+    return su.load_ohlcv("AAPL", curr_date)
+
+
+@pytest.mark.unit
+def test_unsettled_latest_bar_is_served_as_the_last_settled_bar(monkeypatch, tmp_path):
+    # Newest bar (the curr_date) has no close: serve the last settled bar rather
+    # than reporting the whole symbol as unavailable (#1289).
+    frame = pd.DataFrame({
+        "Date": ["2026-05-07", "2026-05-08"],
+        "Open": [100.0, 101.0], "High": [101.0, 102.0], "Low": [99.0, 100.0],
+        "Close": [100.5, float("nan")], "Volume": [1_000_000, 1_000_000],
+    })
+    out = _run_load(monkeypatch, tmp_path, frame, "2026-05-08")
+    assert out["Date"].iloc[-1] == pd.Timestamp("2026-05-07")
+    assert out["Close"].iloc[-1] == 100.5
+
+
+@pytest.mark.unit
+def test_no_settled_bar_at_all_is_still_no_data(monkeypatch, tmp_path):
+    frame = pd.DataFrame({
+        "Date": ["2026-05-07", "2026-05-08"],
+        "Open": [100.0, 101.0], "High": [101.0, 102.0], "Low": [99.0, 100.0],
+        "Close": [float("nan"), float("nan")], "Volume": [1_000_000, 1_000_000],
+    })
+    with pytest.raises(NoMarketDataError, match="no bar in range has a closing price"):
+        _run_load(monkeypatch, tmp_path, frame, "2026-05-08")
+
+
+@pytest.mark.unit
+def test_serving_the_last_settled_bar_does_not_bypass_the_staleness_check(
+    monkeypatch, tmp_path
+):
+    # Falling back must not resurrect a long-dead series: once the closeless
+    # tail is gone, the remaining bar is judged on its age like any other.
+    frame = pd.DataFrame({
+        "Date": ["2026-01-05", "2026-05-08"],
+        "Open": [100.0, 101.0], "High": [101.0, 102.0], "Low": [99.0, 100.0],
+        "Close": [100.5, float("nan")], "Volume": [1_000_000, 1_000_000],
+    })
+    with pytest.raises(NoMarketDataError, match="stale"):
+        _run_load(monkeypatch, tmp_path, frame, "2026-05-08")
+
+
+@pytest.mark.unit
+def test_older_nan_close_row_is_still_dropped(monkeypatch, tmp_path):
+    # A stale gap mid-series is dropped; the valid latest bar is served.
+    frame = pd.DataFrame({
+        "Date": ["2026-05-06", "2026-05-07", "2026-05-08"],
+        "Open": [100.0, 101.0, 102.0], "High": [101.0, 102.0, 103.0],
+        "Low": [99.0, 100.0, 101.0],
+        "Close": [100.5, float("nan"), 102.5], "Volume": [1_000_000, 1_000_000, 1_000_000],
+    })
+    out = _run_load(monkeypatch, tmp_path, frame, "2026-05-08")
+    assert out["Close"].iloc[-1] == 102.5
+    assert (out["Date"] == pd.Timestamp("2026-05-07")).sum() == 0  # the NaN row is gone
+
+
+@pytest.mark.unit
+def test_tz_aware_latest_bar_is_kept_at_the_cutoff(monkeypatch, tmp_path):
+    # A tz-aware/intraday latest bar on the cutoff day must not be filtered out
+    # by a naive-vs-aware comparison.
+    frame = pd.DataFrame({
+        "Date": ["2026-05-07 09:30:00-04:00", "2026-05-08 09:30:00-04:00"],
+        "Open": [100.0, 101.0], "High": [101.0, 102.0], "Low": [99.0, 100.0],
+        "Close": [100.5, 101.5], "Volume": [1_000_000, 1_000_000],
+    })
+    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

tests/test_ollama_base_url.py

@@ -0,0 +1,224 @@
+"""Tests for OLLAMA_BASE_URL env-var override across CLI and client paths."""
+
+from __future__ import annotations
+
+import importlib
+import re
+
+import pytest
+
+# Rich colorizes console output and highlights numbers and URLs, which splits
+# asserted substrings with escape codes ("port \x1b[1;33m11434"). Whether it
+# does so depends on the ambient terminal, so strip the codes to keep these
+# assertions independent of where the suite runs.
+_ANSI = re.compile(r"\x1b\[[0-9;]*m")
+
+
+def _console_out(capsys) -> str:
+    return _ANSI.sub("", capsys.readouterr().out)
+
+
+@pytest.fixture(scope="module", autouse=True)
+def _resync_reloaded_modules():
+    """Restore module state after this file's importlib.reload() calls.
+
+    Several tests below reload ``cli.utils`` to re-evaluate OLLAMA_BASE_URL.
+    That leaves ``cli.main``'s star-imported names (e.g. get_ticker) bound to
+    the pre-reload module objects, which breaks identity checks in unrelated
+    tests that happen to run afterward. Re-sync once on teardown so the reload
+    doesn't leak across test modules.
+    """
+    yield
+    import cli.main
+    import cli.utils
+    importlib.reload(cli.utils)
+    importlib.reload(cli.main)
+
+
+# ---- openai_client side: registry-driven base_url resolution --------------
+
+
+def _reload_client():
+    import tradingagents.llm_clients.openai_client as mod
+    return importlib.reload(mod)
+
+
+def _base_url(mod, provider, **kwargs):
+    return str(mod.OpenAIClient(model="m", provider=provider, **kwargs).get_llm().openai_api_base)
+
+
+def test_resolver_returns_default_when_env_unset(monkeypatch):
+    monkeypatch.delenv("OLLAMA_BASE_URL", raising=False)
+    mod = _reload_client()
+    assert _base_url(mod, "ollama") == "http://localhost:11434/v1"
+
+
+def test_resolver_returns_env_when_set(monkeypatch):
+    monkeypatch.setenv("OLLAMA_BASE_URL", "http://remote-ollama:11434/v1")
+    mod = _reload_client()
+    assert _base_url(mod, "ollama") == "http://remote-ollama:11434/v1"
+
+
+def test_resolver_evaluation_is_call_time(monkeypatch):
+    """Setting the env AFTER module import must still take effect."""
+    monkeypatch.delenv("OLLAMA_BASE_URL", raising=False)
+    mod = _reload_client()
+    monkeypatch.setenv("OLLAMA_BASE_URL", "http://late-set:11434/v1")
+    assert _base_url(mod, "ollama") == "http://late-set:11434/v1"
+
+
+def test_resolver_does_not_affect_other_providers(monkeypatch):
+    """OLLAMA_BASE_URL should NOT leak into xai/deepseek/etc."""
+    monkeypatch.setenv("OLLAMA_BASE_URL", "http://elsewhere/v1")
+    mod = _reload_client()
+    assert _base_url(mod, "xai") == "https://api.x.ai/v1"
+    assert _base_url(mod, "deepseek") == "https://api.deepseek.com"
+
+
+def test_client_get_llm_picks_up_env(monkeypatch):
+    """End-to-end: OllamaClient.get_llm() respects OLLAMA_BASE_URL."""
+    monkeypatch.setenv("OLLAMA_BASE_URL", "http://my-ollama:11434/v1")
+    mod = _reload_client()
+    client = mod.OpenAIClient(model="llama3.1", provider="ollama")
+    llm = client.get_llm()
+    assert "my-ollama" in str(llm.openai_api_base)
+
+
+def test_explicit_base_url_overrides_env(monkeypatch):
+    """An explicit base_url passed to the client wins over the env var."""
+    monkeypatch.setenv("OLLAMA_BASE_URL", "http://env-set:11434/v1")
+    mod = _reload_client()
+    client = mod.OpenAIClient(
+        model="llama3.1",
+        provider="ollama",
+        base_url="http://explicit:11434/v1",
+    )
+    llm = client.get_llm()
+    assert "explicit" in str(llm.openai_api_base)
+    assert "env-set" not in str(llm.openai_api_base)
+
+
+# ---- cli.utils side: select_llm_provider dropdown -------------------------
+
+
+def test_cli_dropdown_uses_env(monkeypatch):
+    """The Ollama entry in the CLI dropdown must reflect OLLAMA_BASE_URL."""
+    monkeypatch.setenv("OLLAMA_BASE_URL", "http://cli-remote:11434/v1")
+    import cli.utils as cli_utils
+    importlib.reload(cli_utils)
+    # Reach inside the function via the same env-read it does at call time
+    ollama_url = (
+        __import__("os").environ.get("OLLAMA_BASE_URL")
+        or "http://localhost:11434/v1"
+    )
+    assert ollama_url == "http://cli-remote:11434/v1"
+
+
+def test_cli_dropdown_default_when_unset(monkeypatch):
+    monkeypatch.delenv("OLLAMA_BASE_URL", raising=False)
+    import cli.utils as cli_utils
+    importlib.reload(cli_utils)
+    ollama_url = (
+        __import__("os").environ.get("OLLAMA_BASE_URL")
+        or "http://localhost:11434/v1"
+    )
+    assert ollama_url == "http://localhost:11434/v1"
+
+
+# ---- confirm_ollama_endpoint UX -------------------------------------------
+
+
+def test_confirm_endpoint_shows_default(monkeypatch, capsys):
+    monkeypatch.delenv("OLLAMA_BASE_URL", raising=False)
+    import cli.utils as cli_utils
+    importlib.reload(cli_utils)
+    cli_utils.confirm_ollama_endpoint("http://localhost:11434/v1")
+    out = _console_out(capsys)
+    assert "http://localhost:11434/v1" in out
+    assert "OLLAMA_BASE_URL" not in out  # not from env
+    assert "Note" not in out  # no warnings for the canonical default
+
+
+def test_confirm_endpoint_marks_env_origin(monkeypatch, capsys):
+    monkeypatch.setenv("OLLAMA_BASE_URL", "http://remote-host:11434/v1")
+    import cli.utils as cli_utils
+    importlib.reload(cli_utils)
+    cli_utils.confirm_ollama_endpoint("http://remote-host:11434/v1")
+    out = _console_out(capsys)
+    assert "http://remote-host:11434/v1" in out
+    assert "OLLAMA_BASE_URL" in out
+
+
+def test_confirm_endpoint_warns_on_missing_scheme(monkeypatch, capsys):
+    """If user sets OLLAMA_BASE_URL=0.0.0.128, advise on the expected shape."""
+    monkeypatch.setenv("OLLAMA_BASE_URL", "0.0.0.128")
+    import cli.utils as cli_utils
+    importlib.reload(cli_utils)
+    cli_utils.confirm_ollama_endpoint("0.0.0.128")
+    out = _console_out(capsys)
+    assert "missing a scheme" in out
+    assert "http://<host>:11434/v1" in out
+
+
+def test_confirm_endpoint_warns_on_non_default_port_remote(monkeypatch, capsys):
+    """A remote host with no :11434 gets a soft hint about port mismatch."""
+    monkeypatch.setenv("OLLAMA_BASE_URL", "http://remote-host/v1")
+    import cli.utils as cli_utils
+    importlib.reload(cli_utils)
+    cli_utils.confirm_ollama_endpoint("http://remote-host/v1")
+    out = _console_out(capsys)
+    assert "port 11434" in out
+
+
+def test_confirm_endpoint_quiet_on_local_no_port(monkeypatch, capsys):
+    """Local host without port shouldn't trigger the remote-port hint."""
+    monkeypatch.setenv("OLLAMA_BASE_URL", "http://localhost/v1")
+    import cli.utils as cli_utils
+    importlib.reload(cli_utils)
+    cli_utils.confirm_ollama_endpoint("http://localhost/v1")
+    out = _console_out(capsys)
+    assert "Note" not in out  # localhost is fine without explicit port
+
+
+def test_ollama_model_labels_no_local_suffix():
+    """Labels should no longer claim '(local)' since the endpoint is dynamic."""
+    from tradingagents.llm_clients.model_catalog import get_model_options
+    for mode in ("quick", "deep"):
+        labels = [label for label, _ in get_model_options("ollama", mode)]
+        assert all("local" not in label for label in labels), labels
+
+
+def test_ollama_offers_custom_model_id():
+    """Ollama users with custom-pulled models can pick 'Custom model ID'."""
+    from tradingagents.llm_clients.model_catalog import get_model_options
+    for mode in ("quick", "deep"):
+        entries = get_model_options("ollama", mode)
+        values = [v for _, v in entries]
+        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

tests/test_openai_compatible_provider.py

@@ -0,0 +1,100 @@
+"""Generic OpenAI-compatible provider (vLLM / LM Studio / llama.cpp / relays).
+
+Verifies the user-supplied base_url is required and honored, the key is optional
+(keyless local default), Chat Completions (not the Responses API) is used, any
+model name is accepted, and the env backend URL precedence (#978).
+"""
+
+import pytest
+
+from tradingagents.llm_clients.api_key_env import get_api_key_env
+from tradingagents.llm_clients.factory import create_llm_client
+from tradingagents.llm_clients.validators import validate_model
+
+# Note: assert by class NAME, not isinstance — other tests reload the
+# openai_client module, which would otherwise create a second class identity.
+
+
+@pytest.mark.unit
+def test_factory_routes_to_openai_client():
+    client = create_llm_client(
+        provider="openai_compatible", model="my-model", base_url="http://localhost:8000/v1"
+    )
+    assert type(client).__name__ == "OpenAIClient"
+
+
+@pytest.mark.unit
+def test_base_url_required(monkeypatch):
+    monkeypatch.delenv("OPENAI_COMPATIBLE_API_KEY", raising=False)
+    with pytest.raises(ValueError, match="requires a base_url"):
+        create_llm_client(provider="openai_compatible", model="m").get_llm()
+
+
+@pytest.mark.unit
+def test_keyless_local_uses_placeholder_and_chat_completions(monkeypatch):
+    monkeypatch.delenv("OPENAI_COMPATIBLE_API_KEY", raising=False)
+    llm = create_llm_client(
+        provider="openai_compatible", model="qwen2.5", base_url="http://localhost:8000/v1"
+    ).get_llm()
+    assert type(llm).__name__ == "LocalCompatibleChatOpenAI"
+    assert str(llm.openai_api_base) == "http://localhost:8000/v1"
+    # keyless local servers: a placeholder key is sent
+    key = llm.openai_api_key.get_secret_value() if hasattr(llm.openai_api_key, "get_secret_value") else llm.openai_api_key
+    assert key == "EMPTY"
+    # must use Chat Completions, not OpenAI's Responses API
+    assert getattr(llm, "use_responses_api", False) in (False, None)
+
+
+@pytest.mark.unit
+def test_optional_key_from_env(monkeypatch):
+    monkeypatch.setenv("OPENAI_COMPATIBLE_API_KEY", "sk-relay-123")
+    llm = create_llm_client(
+        provider="openai_compatible", model="m", base_url="https://relay.example/v1"
+    ).get_llm()
+    key = llm.openai_api_key.get_secret_value() if hasattr(llm.openai_api_key, "get_secret_value") else llm.openai_api_key
+    assert key == "sk-relay-123"
+
+
+@pytest.mark.unit
+def test_any_model_accepted_no_forced_key():
+    assert validate_model("openai_compatible", "literally-anything") is True
+    # The key env exists (read for keyed relays) but the provider is marked
+    # key-optional, so the CLI never forces a prompt and keyless servers work.
+    assert get_api_key_env("openai_compatible") == "OPENAI_COMPATIBLE_API_KEY"
+    from tradingagents.llm_clients.openai_client import OPENAI_COMPATIBLE_PROVIDERS
+    assert OPENAI_COMPATIBLE_PROVIDERS["openai_compatible"].key_optional is True
+
+
+@pytest.mark.unit
+def test_env_backend_url_precedence():
+    # #978: explicit env URL wins over the menu/default regardless of provider source.
+    from cli.utils import resolve_backend_url
+    assert resolve_backend_url("openai", "https://api.openai.com/v1", env_url="http://proxy/v1") == "http://proxy/v1"
+    assert resolve_backend_url("openai", "https://api.openai.com/v1", env_url=None) == "https://api.openai.com/v1"
+    assert resolve_backend_url("deepseek", None, None) == "https://api.deepseek.com"
+
+
+@pytest.mark.unit
+def test_structured_output_suppresses_object_tool_choice(monkeypatch):
+    # LM Studio / vLLM reject the object-form tool_choice langchain sends for
+    # function-calling structured output (#1057). The generic provider binds the
+    # schema as a tool but must not force tool_choice.
+    from langchain_openai import ChatOpenAI
+    from pydantic import BaseModel
+
+    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",
+    )
+    llm = create_llm_client(
+        provider="openai_compatible", model="local-llm-30b", base_url="http://localhost:1234/v1"
+    ).get_llm()
+    out = llm.with_structured_output(Schema)
+    assert out == "BOUND"
+    assert captured["method"] == "function_calling"
+    assert captured["tool_choice"] is None  # not the object form

tests/test_openai_reasoning_effort.py

@@ -0,0 +1,43 @@
+"""OpenAI ``reasoning_effort`` is gated to reasoning models.
+
+Non-reasoning OpenAI models (gpt-4.1, gpt-4o, ...) 400 with "Unsupported
+parameter: 'reasoning.effort'". The client must drop the kwarg for those rather
+than forward it and crash the run. The GPT-5 family and the o-series accept it.
+"""
+
+import pytest
+
+from tradingagents.llm_clients.openai_client import (
+    OpenAIClient,
+    _supports_reasoning_effort,
+)
+
+
+@pytest.mark.parametrize(
+    "model,expected",
+    [
+        ("gpt-5.5", True), ("gpt-5.4", True), ("gpt-5.4-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-10", True),
+        ("gpt-5foo", False), ("gpt-60x", False), ("o3rd-party", False),
+    ],
+)
+def test_supports_reasoning_effort(model, expected):
+    assert _supports_reasoning_effort(model) is expected
+
+
+def _effort_on(model, monkeypatch):
+    # A fake key lets get_llm() construct the client without a network call.
+    monkeypatch.setenv("OPENAI_API_KEY", "test-key")
+    llm = OpenAIClient(model, provider="openai", reasoning_effort="low").get_llm()
+    return getattr(llm, "reasoning_effort", None)
+
+
+def test_reasoning_model_receives_effort(monkeypatch):
+    assert _effort_on("gpt-5.4-mini", monkeypatch) == "low"
+
+
+def test_non_reasoning_model_drops_effort(monkeypatch):
+    # gpt-4.1 would 400 with reasoning_effort — it must be dropped.
+    assert _effort_on("gpt-4.1", monkeypatch) is None

tests/test_openai_responses_base_url.py

@@ -0,0 +1,43 @@
+"""The Responses API only exists on native OpenAI; a custom base_url on the
+openai provider must fall back to Chat Completions (#1024)."""
+
+from __future__ import annotations
+
+import pytest
+
+from tradingagents.llm_clients.openai_client import (
+    OpenAIClient,
+    _is_native_openai_base_url,
+)
+
+
+@pytest.mark.unit
+class NativeBaseUrlTests:
+    def test_unset_is_native(self):
+        assert _is_native_openai_base_url(None) is True
+        assert _is_native_openai_base_url("") is True
+
+    def test_openai_hosts_are_native(self):
+        assert _is_native_openai_base_url("https://api.openai.com/v1") is True
+        assert _is_native_openai_base_url("api.openai.com/v1") is True
+
+    def test_custom_endpoints_are_not_native(self):
+        assert _is_native_openai_base_url("http://localhost:1234/v1") is False
+        assert _is_native_openai_base_url("https://my-gateway.example.com/v1") is False
+        assert _is_native_openai_base_url("https://api.openai.com.evil.com/v1") is False
+
+
+@pytest.mark.unit
+class ResponsesApiSelectionTests:
+    def test_native_openai_enables_responses_api(self, monkeypatch):
+        monkeypatch.setenv("OPENAI_API_KEY", "sk-test")
+        llm = OpenAIClient("gpt-5.5", provider="openai").get_llm()
+        assert getattr(llm, "use_responses_api", False) is True
+
+    def test_custom_base_url_disables_responses_api(self, monkeypatch):
+        monkeypatch.setenv("OPENAI_API_KEY", "sk-test")
+        llm = OpenAIClient(
+            "gpt-5.5", base_url="http://localhost:1234/v1", provider="openai"
+        ).get_llm()
+        # use_responses_api should be absent/False so the client speaks Chat Completions.
+        assert getattr(llm, "use_responses_api", False) is False

tests/test_openrouter_model_select.py

@@ -0,0 +1,122 @@
+"""OpenRouter model selection: prompts are labeled by mode (#1000); required
+prompts exit cleanly on cancel; the output-language prompt defaults to English
+on cancel; and the OpenRouter list is newest-first."""
+
+from unittest import mock
+
+import pytest
+
+from cli import utils
+
+
+def _asks(value):
+    return mock.Mock(ask=mock.Mock(return_value=value))
+
+
+@pytest.mark.unit
+class TestOpenRouterPromptLabel:
+    @pytest.mark.parametrize("mode,label", [("quick", "Quick-Thinking"), ("deep", "Deep-Thinking")])
+    def test_prompt_states_the_mode(self, mode, label):
+        captured = {}
+
+        def fake_select(message, **kwargs):
+            captured["message"] = message
+            return _asks("openrouter/some-model")
+
+        with mock.patch.object(utils, "_fetch_openrouter_models",
+                               return_value=[("Some Model", "openrouter/some-model")]), \
+             mock.patch.object(utils.questionary, "select", side_effect=fake_select):
+            out = utils.select_openrouter_model(mode)
+
+        assert label in captured["message"]
+        assert out == "openrouter/some-model"
+
+
+@pytest.mark.unit
+class TestOpenRouterLatestFirst:
+    def test_models_sorted_newest_first(self):
+        payload = {"data": [
+            {"id": "old/model", "name": "Old", "created": 1000},
+            {"id": "new/model", "name": "New", "created": 3000},
+            {"id": "mid/model", "name": "Mid", "created": 2000},
+        ]}
+        resp = mock.Mock()
+        resp.json.return_value = payload
+        resp.raise_for_status = mock.Mock()
+        with mock.patch("requests.get", return_value=resp):
+            out = utils._fetch_openrouter_models()
+        assert [mid for _, mid in out] == ["new/model", "mid/model", "old/model"]
+
+
+@pytest.mark.unit
+class TestMainstreamFilter:
+    def test_dropdown_prefers_mainstream_over_niche(self):
+        # _fetch returns newest-first; the shortlist should drop niche namespaces.
+        models = [
+            ("Fusion", "openrouter/fusion"),
+            ("Niche", "nex-agi/nex-n2-pro:free"),
+            ("Claude", "anthropic/claude-x"),
+            ("GPT", "openai/gpt-x"),
+        ]
+        captured = {}
+
+        def fake_select(message, **kwargs):
+            captured["values"] = [c.value for c in kwargs["choices"]]
+            return _asks("anthropic/claude-x")
+
+        with mock.patch.object(utils, "_fetch_openrouter_models", return_value=models), \
+             mock.patch.object(utils.questionary, "select", side_effect=fake_select):
+            utils.select_openrouter_model("quick")
+
+        assert "anthropic/claude-x" in captured["values"]
+        assert "openai/gpt-x" in captured["values"]
+        assert "openrouter/fusion" not in captured["values"]
+        assert "nex-agi/nex-n2-pro:free" not in captured["values"]
+        assert "custom" in captured["values"]  # escape hatch preserved
+
+    def test_falls_back_to_all_when_no_mainstream(self):
+        models = [("Niche", "nex-agi/x"), ("Other", "thedrummer/y")]
+        captured = {}
+
+        def fake_select(message, **kwargs):
+            captured["values"] = [c.value for c in kwargs["choices"]]
+            return _asks("nex-agi/x")
+
+        with mock.patch.object(utils, "_fetch_openrouter_models", return_value=models), \
+             mock.patch.object(utils.questionary, "select", side_effect=fake_select):
+            utils.select_openrouter_model("deep")
+
+        assert "nex-agi/x" in captured["values"]  # fallback keeps the list usable
+
+
+@pytest.mark.unit
+class TestCancelExitsCleanly:
+    def test_dropdown_cancel_exits(self):
+        with mock.patch.object(utils, "_fetch_openrouter_models", return_value=[]), \
+             mock.patch.object(utils.questionary, "select", return_value=_asks(None)), \
+             pytest.raises(SystemExit):
+            utils.select_openrouter_model("quick")
+
+    def test_custom_id_cancel_exits(self):
+        with mock.patch.object(utils, "_fetch_openrouter_models", return_value=[]), \
+             mock.patch.object(utils.questionary, "select", return_value=_asks("custom")), \
+             mock.patch.object(utils.questionary, "text", return_value=_asks(None)), \
+             pytest.raises(SystemExit):
+            utils.select_openrouter_model("deep")
+
+    def test_prompt_custom_model_id_cancel_exits(self):
+        with mock.patch.object(utils.questionary, "text", return_value=_asks(None)), \
+             pytest.raises(SystemExit):
+            utils._prompt_custom_model_id()
+
+
+@pytest.mark.unit
+class TestLanguageDefaultsToEnglish:
+    def test_select_cancel_defaults_english(self):
+        with mock.patch.object(utils.questionary, "select", return_value=_asks(None)):
+            assert utils.ask_output_language() == "English"
+
+    def test_custom_language_cancel_defaults_english(self):
+        with mock.patch.object(utils.questionary, "select", return_value=_asks("custom")), \
+             mock.patch.object(utils.questionary, "text", return_value=_asks(None)):
+            assert utils.ask_output_language() == "English"

tests/test_polymarket.py

@@ -0,0 +1,129 @@
+"""Polymarket prediction-market vendor: forward-looking filtering, volume
+ranking, formatting, graceful degradation, and router integration.
+
+All API access is mocked, so these run without a network connection.
+"""
+import copy
+import unittest
+from unittest import mock
+
+import pytest
+import requests
+
+import tradingagents.dataflows.config as config_module
+import tradingagents.default_config as default_config
+from tradingagents.dataflows import interface, polymarket
+from tradingagents.dataflows.config import set_config
+
+
+def _market(question, prob, *, volume, end_date, closed=False, wk=None):
+    return {
+        "question": question,
+        "outcomes": '["Yes", "No"]',
+        "outcomePrices": f'["{prob}", "{round(1 - prob, 4)}"]',
+        "volumeNum": volume,
+        "endDate": end_date,
+        "closed": closed,
+        "oneWeekPriceChange": wk,
+    }
+
+
+# One event with a mix: a high-volume open market, a closed one, a past-dated
+# one, and a lower-volume open one. Far-future / far-past dates keep the test
+# independent of the real clock.
+_SEARCH = {
+    "events": [
+        {
+            "markets": [
+                _market("Open big?", 0.76, volume=5_000_000, end_date="2030-12-31T00:00:00Z", wk=-0.045),
+                _market("Resolved already?", 1.0, volume=9_000_000, end_date="2030-12-31T00:00:00Z", closed=True),
+                _market("Past event?", 0.5, volume=8_000_000, end_date="2020-01-01T00:00:00Z"),
+                _market("Open small?", 0.30, volume=1_000, end_date="2030-06-30T00:00:00Z"),
+            ]
+        }
+    ]
+}
+
+
+@pytest.mark.unit
+class PolymarketFilterTests(unittest.TestCase):
+    def test_closed_and_past_markets_are_excluded(self):
+        with mock.patch.object(polymarket, "_request", return_value=_SEARCH):
+            out = polymarket.get_prediction_markets("anything", limit=10)
+        self.assertIn("Open big?", out)
+        self.assertIn("Open small?", out)
+        self.assertNotIn("Resolved already?", out)  # closed
+        self.assertNotIn("Past event?", out)         # endDate in the past
+
+    def test_ranked_by_volume(self):
+        with mock.patch.object(polymarket, "_request", return_value=_SEARCH):
+            out = polymarket.get_prediction_markets("anything", limit=10)
+        self.assertLess(out.index("Open big?"), out.index("Open small?"))
+
+    def test_limit_caps_results(self):
+        with mock.patch.object(polymarket, "_request", return_value=_SEARCH):
+            out = polymarket.get_prediction_markets("anything", limit=1)
+        self.assertIn("Open big?", out)
+        self.assertNotIn("Open small?", out)
+
+
+@pytest.mark.unit
+class PolymarketFormatTests(unittest.TestCase):
+    def test_probability_volume_and_weekly_change_render(self):
+        with mock.patch.object(polymarket, "_request", return_value=_SEARCH):
+            out = polymarket.get_prediction_markets("anything", limit=10)
+        self.assertIn("Yes 76%", out)
+        self.assertIn("$5,000,000 volume", out)
+        self.assertIn("resolves 2030-12-31", out)
+        self.assertIn("1-week -4.5pp", out)  # -0.045 -> -4.5pp
+
+    def test_weekly_change_omitted_when_absent(self):
+        # "Open small?" has wk=None -> no 1-week clause on its line.
+        with mock.patch.object(polymarket, "_request", return_value=_SEARCH):
+            out = polymarket.get_prediction_markets("anything", limit=10)
+        small_line = next(ln for ln in out.splitlines() if "Open small?" in ln)
+        self.assertNotIn("1-week", small_line)
+
+    def test_no_matches_reports_clearly(self):
+        with mock.patch.object(polymarket, "_request", return_value={"events": []}):
+            out = polymarket.get_prediction_markets("obscure ticker", limit=6)
+        self.assertIn("No open prediction markets", out)
+
+
+@pytest.mark.unit
+class PolymarketResilienceTests(unittest.TestCase):
+    def test_network_error_degrades_gracefully(self):
+        # An external-service hiccup must not raise into the analyst.
+        with mock.patch.object(
+            polymarket, "_request", side_effect=requests.RequestException("boom")
+        ):
+            out = polymarket.get_prediction_markets("Fed rate cut")
+        self.assertIn("unavailable", out.lower())
+        self.assertIn("Fed rate cut", out)
+
+
+@pytest.mark.unit
+class PolymarketRoutingTests(unittest.TestCase):
+    def setUp(self):
+        config_module._config = copy.deepcopy(default_config.DEFAULT_CONFIG)
+
+    def tearDown(self):
+        config_module._config = copy.deepcopy(default_config.DEFAULT_CONFIG)
+
+    def test_category_routes_to_polymarket(self):
+        self.assertEqual(
+            interface.get_category_for_method("get_prediction_markets"),
+            "prediction_markets",
+        )
+        set_config({"data_vendors": {"prediction_markets": "polymarket"}})
+        with mock.patch.dict(
+            interface.VENDOR_METHODS,
+            {"get_prediction_markets": {"polymarket": lambda *a, **k: "POLY_OK"}},
+            clear=False,
+        ):
+            out = interface.route_to_vendor("get_prediction_markets", "fed", 5)
+        self.assertEqual(out, "POLY_OK")
+
+
+if __name__ == "__main__":
+    unittest.main()

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

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

tests/test_provider_registry.py

@@ -0,0 +1,60 @@
+"""The OpenAI-compatible provider registry is the single source of truth for the
+family; this guards each provider's resolved config (base URL, subclass, auth,
+Responses API) so a future edit can't silently break one.
+"""
+import pytest
+
+from tradingagents.llm_clients.openai_client import (
+    OPENAI_COMPATIBLE_PROVIDERS,
+    DeepSeekChatOpenAI,
+    LocalCompatibleChatOpenAI,
+    MinimaxChatOpenAI,
+    NormalizedChatOpenAI,
+    is_openai_compatible,
+)
+
+
+@pytest.mark.unit
+def test_registry_membership():
+    assert is_openai_compatible("openai")
+    assert is_openai_compatible("openai_compatible")  # the generic endpoint
+    # native (different API) clients are intentionally NOT in the registry
+    assert not is_openai_compatible("anthropic")
+    assert not is_openai_compatible("google")
+    assert not is_openai_compatible("azure")
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("provider,base_url,chat_class,responses", [
+    ("openai", None, NormalizedChatOpenAI, True),
+    ("xai", "https://api.x.ai/v1", NormalizedChatOpenAI, False),
+    ("deepseek", "https://api.deepseek.com", DeepSeekChatOpenAI, False),
+    ("qwen", "https://dashscope-intl.aliyuncs.com/compatible-mode/v1", NormalizedChatOpenAI, False),
+    ("qwen-cn", "https://dashscope.aliyuncs.com/compatible-mode/v1", NormalizedChatOpenAI, False),
+    ("glm", "https://api.z.ai/api/paas/v4/", NormalizedChatOpenAI, False),
+    ("glm-cn", "https://open.bigmodel.cn/api/paas/v4/", NormalizedChatOpenAI, False),
+    ("minimax", "https://api.minimax.io/v1", MinimaxChatOpenAI, False),
+    ("minimax-cn", "https://api.minimaxi.com/v1", MinimaxChatOpenAI, False),
+    ("openrouter", "https://openrouter.ai/api/v1", NormalizedChatOpenAI, False),
+    ("mistral", "https://api.mistral.ai/v1", NormalizedChatOpenAI, False),
+    ("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", LocalCompatibleChatOpenAI, False),
+])
+def test_registry_spec(provider, base_url, chat_class, responses):
+    spec = OPENAI_COMPATIBLE_PROVIDERS[provider]
+    assert spec.base_url == base_url
+    assert spec.chat_class is chat_class
+    assert spec.use_responses_api is responses
+
+
+@pytest.mark.unit
+def test_key_optionality():
+    # Local/generic endpoints are key-optional; hosted APIs require a key.
+    assert OPENAI_COMPATIBLE_PROVIDERS["ollama"].key_optional is True
+    assert OPENAI_COMPATIBLE_PROVIDERS["openai_compatible"].key_optional is True
+    assert OPENAI_COMPATIBLE_PROVIDERS["openai_compatible"].require_base_url is True
+    assert OPENAI_COMPATIBLE_PROVIDERS["xai"].key_optional is False
+    # OLLAMA_BASE_URL is the only base-URL env override.
+    assert OPENAI_COMPATIBLE_PROVIDERS["ollama"].base_url_env == "OLLAMA_BASE_URL"

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]

tests/test_reddit_fallback.py

@@ -0,0 +1,274 @@
+"""Tests for the Reddit RSS fetcher: one combined request, its 429 backoff, and
+chunked-transfer error handling (#1024)."""
+
+from __future__ import annotations
+
+import http.client
+from unittest.mock import patch
+from urllib.error import HTTPError
+
+import pytest
+
+from tradingagents.dataflows import reddit
+
+_SAMPLE_ATOM = """<?xml version="1.0" encoding="UTF-8"?>
+<feed xmlns="http://www.w3.org/2005/Atom">
+  <entry>
+    <title>NVDA earnings beat, stock pops</title>
+    <published>2026-05-20T14:30:00+00:00</published>
+    <content type="html">&lt;!-- SC_OFF --&gt;&lt;div class="md"&gt;&lt;p&gt;Great &lt;b&gt;quarter&lt;/b&gt; for NVDA&amp;#39;s datacenter unit.&lt;/p&gt;&lt;/div&gt;&lt;!-- SC_ON --&gt;</content>
+  </entry>
+  <entry>
+    <title>Is NVDA overvalued?</title>
+    <published>2026-05-19T09:00:00Z</published>
+    <content type="html">&lt;p&gt;Forward P/E discussion&lt;/p&gt;</content>
+  </entry>
+</feed>
+"""
+
+
+def _resp(read_fn):
+    """A minimal context-manager response whose read() runs ``read_fn``."""
+    class _Resp:
+        def __enter__(self_inner):
+            return self_inner
+
+        def __exit__(self_inner, *a):
+            return False
+
+        def read(self_inner, size=-1):
+            data = read_fn()
+            return data if size is None or size < 0 else data[:size]
+    return _Resp()
+
+
+def _atom_resp():
+    return _resp(lambda: _SAMPLE_ATOM.encode("utf-8"))
+
+
+def _raise(exc):
+    def _r():
+        raise exc
+    return _resp(_r)
+
+
+@pytest.mark.unit
+class TestIsoToTimestamp:
+    def test_parses_offset_and_z(self):
+        assert reddit._iso_to_timestamp("2026-05-20T14:30:00+00:00") > 0
+        assert reddit._iso_to_timestamp("2026-05-19T09:00:00Z") > 0
+
+    def test_none_and_garbage_return_none(self):
+        assert reddit._iso_to_timestamp(None) is None
+        assert reddit._iso_to_timestamp("not-a-date") is None
+
+
+@pytest.mark.unit
+class TestStripHtml:
+    def test_extracts_between_sc_markers_and_unescapes(self):
+        raw = "<!-- SC_OFF --><div class=\"md\"><p>Great <b>quarter</b> &amp; more</p></div><!-- SC_ON -->"
+        assert reddit._strip_html(raw) == "Great quarter & more"
+
+    def test_empty(self):
+        assert reddit._strip_html("") == ""
+
+
+@pytest.mark.unit
+class TestRssParsing:
+    def test_parses_atom_entries(self):
+        with patch.object(reddit, "urlopen", return_value=_atom_resp()):
+            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]["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"<<not xml>>")):
+            assert reddit._fetch_subreddit_rss("NVDA", "stocks", 5, 5.0) is None
+
+
+@pytest.mark.unit
+class TestRss429Backoff:
+    def test_429_then_success_retries_once(self):
+        err = HTTPError("url", 429, "Too Many Requests", {}, None)
+        with patch.object(reddit, "urlopen", side_effect=[err, _atom_resp()]) as op, \
+             patch.object(reddit.time, "sleep") as slept:
+            posts = reddit._fetch_subreddit_rss("NVDA", "stocks", 5, 5.0)
+        assert op.call_count == 2          # original + exactly one retry
+        slept.assert_called_once()         # backed off before retrying
+        assert len(posts) == 2
+
+    def test_429_twice_gives_up_after_one_retry(self):
+        err = HTTPError("url", 429, "Too Many Requests", {}, None)
+        with patch.object(reddit, "urlopen", side_effect=[err, err]) as op, \
+             patch.object(reddit.time, "sleep"):
+            posts = reddit._fetch_subreddit_rss("NVDA", "stocks", 5, 5.0)
+        assert op.call_count == 2          # one retry, then gives up cleanly
+        assert posts is None
+
+    def test_retry_after_header_is_honoured(self):
+        err = HTTPError("url", 429, "Too Many Requests", {"Retry-After": "12"}, None)
+        with patch.object(reddit, "urlopen", side_effect=[err, _atom_resp()]), \
+             patch.object(reddit.time, "sleep") as slept:
+            reddit._fetch_subreddit_rss("NVDA", "stocks", 5, 5.0)
+        slept.assert_called_once_with(12.0)
+
+    def test_retry_after_zero_is_honoured_not_treated_as_absent(self):
+        # A valid "Retry-After: 0" means retry at once; it must not fall through
+        # to the fallback wait (the earlier `or 5.0` bug turned 0 into 5s).
+        err = HTTPError("url", 429, "Too Many Requests", {"Retry-After": "0"}, None)
+        with patch.object(reddit, "urlopen", side_effect=[err, _atom_resp()]), \
+             patch.object(reddit.time, "sleep") as slept:
+            reddit._fetch_subreddit_rss("NVDA", "stocks", 5, 5.0)
+        slept.assert_called_once_with(0.0)
+
+    def test_headerless_429_fallback_is_jittered(self):
+        # No Retry-After -> our own ~5s fallback, jittered so concurrent runs
+        # don't retry in lockstep (kept within a tight band).
+        err = HTTPError("url", 429, "Too Many Requests", {}, None)
+        with patch.object(reddit, "urlopen", side_effect=[err, _atom_resp()]), \
+             patch.object(reddit.time, "sleep") as slept:
+            reddit._fetch_subreddit_rss("NVDA", "stocks", 5, 5.0)
+        slept.assert_called_once()
+        (wait,), _ = slept.call_args
+        assert 48.0 <= wait <= 72.0  # 60s +/-20% jitter
+
+
+@pytest.mark.unit
+class TestChunkedTransferErrorsHandled:
+    """IncompleteRead/RemoteDisconnected come from http.client and are NOT
+    OSErrors, so they were previously uncaught and crashed the pipeline (#1024)."""
+
+    def test_rss_incomplete_read_reports_unavailable(self):
+        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_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.
+        big = _resp(lambda: b"x" * 100)
+        with patch.object(reddit, "_MAX_FEED_BYTES", 10), \
+             patch.object(reddit, "urlopen", return_value=big):
+            assert reddit._fetch_subreddit_rss("NVDA", "stocks", 5, 5.0) is None
+
+
+@pytest.mark.unit
+class TestFormatterHandlesRssPosts:
+    def test_rss_posts_omit_fake_counts_and_note_source(self):
+        rss_posts = [{
+            "title": "NVDA pops", "score": None, "num_comments": None,
+            "created_utc": reddit._iso_to_timestamp("2026-05-20T14:30:00Z"),
+            "selftext": "great quarter", "source": "rss",
+        }]
+        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
+
+
+@pytest.mark.unit
+class TestCryptoSearchTerm:
+    """A crypto pair (BTC-USD) barely matches Reddit text; search the base (#1113)."""
+
+    def _captured_ticker(self, ticker):
+        seen = {}
+
+        def fake_fetch(t, subs, limit, timeout, **kwargs):
+            seen["ticker"] = t
+            return []
+
+        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):
+        assert self._captured_ticker("BTC-USD") == "BTC"
+
+    def test_equity_passes_through(self):
+        assert self._captured_ticker("NVDA") == "NVDA"
+
+
+@pytest.mark.unit
+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."""
+
+    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}
+
+    def test_all_subreddits_share_one_request(self):
+        calls = []
+
+        def record(t, subs, limit, timeout):
+            calls.append((subs, limit))
+            return []
+
+        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_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_genuine_empty_still_reports_no_posts(self):
+        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_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: <no posts found" in out
+
+
+@pytest.mark.unit
+def test_posts_from_an_unrequested_or_unnamed_subreddit_are_not_dropped():
+    posts = [
+        {"title": "ELSEWHERE", "created_utc": None, "selftext": "", "subreddit": "options"},
+        {"title": "NO LABEL", "created_utc": None, "selftext": "", "subreddit": ""},
+    ]
+    with patch.object(reddit, "_fetch_subreddit_rss", return_value=posts):
+        out = reddit.fetch_reddit_posts("NVDA", subreddits=("a", "b"))
+    assert "ELSEWHERE" in out and "r/options" in out
+    assert "NO LABEL" in out
+
+
+
+@pytest.mark.unit
+def test_each_subreddit_keeps_its_own_quota():
+    busy = [{"title": f"A{i}", "created_utc": None, "selftext": "", "subreddit": "a"} for i in range(9)]
+    quiet = [{"title": "B0", "created_utc": None, "selftext": "", "subreddit": "b"}]
+    with patch.object(reddit, "_fetch_subreddit_rss", return_value=busy + quiet):
+        out = reddit.fetch_reddit_posts("NVDA", subreddits=("a", "b"), limit_per_sub=3)
+    assert "A0" in out and "A2" in out and "A3" not in out  # capped per subreddit
+    assert "B0" in out                                        # not crowded out
+
+
+@pytest.mark.unit
+def test_empty_subreddit_on_a_full_page_is_not_called_empty():
+    # A full page may have cut a quieter subreddit's posts off, so its absence
+    # from the page is not evidence of no posts.
+    full = [{"title": f"A{i}", "created_utc": None, "selftext": "", "subreddit": "a"}
+            for i in range(reddit._FEED_PAGE)]
+    with patch.object(reddit, "_fetch_subreddit_rss", return_value=full):
+        out = reddit.fetch_reddit_posts("NVDA", subreddits=("a", "b"))
+    assert "r/b: <no posts found" not in out
+    assert f"newest {reddit._FEED_PAGE}" in out

tests/test_reporting.py

@@ -0,0 +1,50 @@
+"""Report parity: the shared writer produces the report tree for the CLI and the
+programmatic API alike (#1037)."""
+
+from types import SimpleNamespace
+
+import pytest
+
+from tradingagents.graph.trading_graph import TradingAgentsGraph
+from tradingagents.reporting import write_report_tree
+
+
+def _state():
+    return {
+        "market_report": "MKT",
+        "news_report": "NEWS",
+        "investment_debate_state": {"judge_decision": "RM PLAN"},
+        "trader_investment_plan": "TRADE",
+        "risk_debate_state": {"judge_decision": "PM DECISION"},
+    }
+
+
+@pytest.mark.unit
+def test_write_report_tree_creates_files(tmp_path):
+    out = write_report_tree(_state(), "AAPL", tmp_path)
+    assert out.name == "complete_report.md"
+    assert (tmp_path / "1_analysts" / "market.md").read_text() == "MKT"
+    assert (tmp_path / "1_analysts" / "news.md").read_text() == "NEWS"
+    assert (tmp_path / "2_research" / "manager.md").read_text() == "RM PLAN"
+    assert (tmp_path / "3_trading" / "trader.md").read_text() == "TRADE"
+    assert (tmp_path / "5_portfolio" / "decision.md").read_text() == "PM DECISION"
+    complete = out.read_text()
+    assert "Trading Analysis Report: AAPL" in complete
+    assert "MKT" in complete and "PM DECISION" in complete
+
+
+@pytest.mark.unit
+def test_save_reports_explicit_path(tmp_path):
+    # Unbound: with an explicit save_path, the method doesn't touch self/config.
+    out = TradingAgentsGraph.save_reports(None, _state(), "AAPL", save_path=tmp_path)
+    assert (tmp_path / "complete_report.md").exists()
+    assert out == tmp_path / "complete_report.md"
+
+
+@pytest.mark.unit
+def test_save_reports_defaults_under_results_dir(tmp_path):
+    mock_self = SimpleNamespace(config={"results_dir": str(tmp_path)})
+    out = TradingAgentsGraph.save_reports(mock_self, _state(), "AAPL")
+    assert out.exists()
+    assert out.parent.parent.name == "reports"  # results_dir/reports/AAPL_<stamp>/...
+    assert out.parent.name.startswith("AAPL_")

tests/test_risk_router_path_map.py

@@ -0,0 +1,81 @@
+"""Shared-router / path_map completeness (#1088).
+
+Both `should_continue_risk_analysis` (three risk edges) and
+`should_continue_debate` (two research-debate edges) are single routers whose
+return set is larger than any one edge previously mapped. Each edge now shares a
+complete path map (`RISK_ANALYSIS_PATH_MAP` / `DEBATE_PATH_MAP`), so a
+fall-through return can never hit a missing entry -- which would crash LangGraph
+mid-run on prompt/i18n/refactor drift in the speaker labels.
+"""
+import pytest
+
+from tradingagents.graph.conditional_logic import ConditionalLogic
+from tradingagents.graph.setup import DEBATE_PATH_MAP, RISK_ANALYSIS_PATH_MAP
+
+
+def _state(latest_speaker, count=0):
+    return {"risk_debate_state": {"latest_speaker": latest_speaker, "count": count}}
+
+
+def _debate_state(current_response, count=0):
+    return {"investment_debate_state": {"current_response": current_response, "count": count}}
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("latest_speaker", [
+    "Aggressive", "Aggressive Analyst",
+    "Conservative", "Conservative Analyst",
+    "Neutral", "Neutral Analyst",
+    "",                          # drift: empty label
+    "Aggressive Risk Analyst",   # drift: node renamed
+    "Agresivo",                  # drift: i18n / translated label
+])
+def test_router_return_always_routable(latest_speaker):
+    logic = ConditionalLogic(max_risk_discuss_rounds=1)
+    target = logic.should_continue_risk_analysis(_state(latest_speaker))
+    assert target in RISK_ANALYSIS_PATH_MAP
+
+
+@pytest.mark.unit
+def test_router_terminates_at_round_limit():
+    logic = ConditionalLogic(max_risk_discuss_rounds=1)
+    # count >= 3 * rounds routes to the Portfolio Manager (debate ends)
+    assert logic.should_continue_risk_analysis(_state("Neutral", count=3)) == "Portfolio Manager"
+
+
+@pytest.mark.unit
+def test_path_map_covers_full_router_range():
+    logic = ConditionalLogic(max_risk_discuss_rounds=1)
+    returns = {
+        logic.should_continue_risk_analysis(_state(s, c))
+        for s in ("Aggressive", "Conservative", "Neutral", "drift")
+        for c in (0, 99)
+    }
+    # Every value the router can emit is a key in the shared map...
+    assert returns <= set(RISK_ANALYSIS_PATH_MAP)
+    # ...and the terminal target is reachable.
+    assert "Portfolio Manager" in returns
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("current_response", [
+    "Bull", "Bull Researcher", "Bear", "Bear Researcher",
+    "",                       # drift: empty label
+    "Optimista",              # drift: i18n / translated label
+])
+def test_debate_router_return_always_routable(current_response):
+    logic = ConditionalLogic(max_debate_rounds=1)
+    target = logic.should_continue_debate(_debate_state(current_response))
+    assert target in DEBATE_PATH_MAP
+
+
+@pytest.mark.unit
+def test_debate_path_map_covers_full_router_range():
+    logic = ConditionalLogic(max_debate_rounds=1)
+    returns = {
+        logic.should_continue_debate(_debate_state(s, c))
+        for s in ("Bull", "Bear", "drift")
+        for c in (0, 99)
+    }
+    assert returns <= set(DEBATE_PATH_MAP)
+    assert "Research Manager" in returns  # terminal reachable

tests/test_safe_ticker_component.py

@@ -0,0 +1,57 @@
+"""Tests for the ticker path-component validator that blocks directory traversal."""
+
+import os
+import unittest
+
+import pytest
+
+from tradingagents.dataflows.utils import safe_ticker_component
+
+
+@pytest.mark.unit
+class TestSafeTickerComponent(unittest.TestCase):
+    def test_accepts_common_ticker_formats(self):
+        for ticker in ("AAPL", "BRK-B", "BRK.A", "0700.HK", "7203.T", "BHP.AX", "^GSPC"):
+            self.assertEqual(safe_ticker_component(ticker), ticker)
+
+    def test_accepts_futures_and_forex_formats(self):
+        # Futures use '=' (GC=F gold, CL=F crude), forex/CFD symbols use '+'.
+        for ticker in ("GC=F", "CL=F", "ES=F", "XAUUSD+", "EURUSD+"):
+            self.assertEqual(safe_ticker_component(ticker), ticker)
+
+    def test_rejects_path_separators(self):
+        for bad in (".", "..", "../etc", "a/b", "a\\b", "/abs", "..\\..\\x"):
+            with self.assertRaises(ValueError):
+                safe_ticker_component(bad)
+
+    def test_rejects_null_byte_and_whitespace(self):
+        for bad in ("AAP L", "AAPL\x00", "AAPL\n", "\tAAPL"):
+            with self.assertRaises(ValueError):
+                safe_ticker_component(bad)
+
+    def test_rejects_empty_or_non_string(self):
+        for bad in ("", None, 123, b"AAPL"):
+            with self.assertRaises(ValueError):
+                safe_ticker_component(bad)
+
+    def test_rejects_overlong_input(self):
+        with self.assertRaises(ValueError):
+            safe_ticker_component("A" * 33)
+
+    def test_rejects_dot_only_values(self):
+        # '.' and '..' pass the regex but traverse when used as a path
+        # component (e.g. ``Path(results_dir) / ticker / "logs"``).
+        for bad in (".", "..", "...", "...."):
+            with self.assertRaises(ValueError):
+                safe_ticker_component(bad)
+
+    def test_traversal_string_does_not_escape_join(self):
+        """Sanity: sanitized values stay within base when joined."""
+        base = os.path.realpath("/tmp/cache")
+        ticker = safe_ticker_component("AAPL")
+        joined = os.path.realpath(os.path.join(base, f"{ticker}.csv"))
+        self.assertTrue(joined.startswith(base + os.sep))
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_sec_edgar.py

@@ -0,0 +1,239 @@
+"""SEC EDGAR fundamentals: statements as they were filed, not as they read today.
+
+Every other fundamentals vendor serves the current value of a past period and
+cuts on the fiscal period end, so a run sees figures the company had not yet
+filed, and later restatements replace what was actually published. EDGAR carries
+the filing date of every fact, so a run can be limited to what was on file by its
+own date.
+"""
+
+from __future__ import annotations
+
+from unittest import mock
+
+import pytest
+
+from tradingagents.dataflows import sec_edgar
+from tradingagents.dataflows.errors import NoMarketDataError
+
+_REAL_FETCH = sec_edgar._fetch_json
+
+TICKER_MAP = {"0": {"cik_str": 320193, "ticker": "AAPL", "title": "Apple Inc."}}
+
+
+def _fact(end, val, filed, form="10-K", fp="FY", start=None):
+    fact = {"end": end, "val": val, "filed": filed, "form": form, "fy": int(end[:4]), "fp": fp}
+    if start:
+        fact["start"] = start
+    return fact
+
+
+FACTS = {
+    "cik": 320193,
+    "entityName": "Apple Inc.",
+    "facts": {"us-gaap": {
+        "Assets": {"units": {"USD": [
+            _fact("2008-09-27", 39_572_000_000, "2008-11-05"),
+            _fact("2008-09-27", 36_171_000_000, "2010-01-25", form="10-K/A"),
+            _fact("2022-03-26", 350_662_000_000, "2022-04-29", form="10-Q", fp="Q2"),
+            _fact("2024-09-28", 364_980_000_000, "2024-11-01"),
+        ]}},
+        "Liabilities": {"units": {"USD": [_fact("2024-09-28", 308_030_000_000, "2024-11-01")]}},
+        "EarningsPerShareDiluted": {"units": {"USD/shares": [
+            _fact("2024-09-28", 6.08, "2024-11-01", start="2023-09-30"),
+        ]}},
+        "RevenueFromContractWithCustomerExcludingAssessedTax": {"units": {"USD": [
+            # One filing reports the quarter and the year to date under one end date.
+            _fact("2025-12-31", 81_300_000_000, "2026-01-29", form="10-Q", fp="Q2", start="2025-10-01"),
+            _fact("2025-12-31", 158_900_000_000, "2026-01-29", form="10-Q", fp="Q2", start="2025-07-01"),
+            _fact("2024-09-28", 391_035_000_000, "2024-11-01", start="2023-09-30"),
+        ]}},
+    }},
+}
+
+
+@pytest.fixture(autouse=True)
+def _no_network_or_cache(tmp_path, monkeypatch):
+    monkeypatch.setattr(sec_edgar, "get_config", lambda: {"data_cache_dir": str(tmp_path)})
+    monkeypatch.setattr(sec_edgar, "_fetch_json", lambda url: TICKER_MAP if "company_tickers" in url else FACTS)
+
+
+@pytest.mark.unit
+def test_a_us_filer_resolves_to_its_cik():
+    assert sec_edgar.cik_for("AAPL") == "0000320193"
+    assert sec_edgar.cik_for("aapl") == "0000320193"
+
+
+@pytest.mark.unit
+def test_a_non_filer_is_reported_as_such_not_as_missing_data():
+    with pytest.raises(NoMarketDataError, match="not a US SEC filer"):
+        sec_edgar.get_balance_sheet("0700.HK", "annual", "2026-01-01")
+
+
+@pytest.mark.unit
+def test_a_restated_figure_reads_as_it_did_at_the_time():
+    """The value published then, not the correction filed later."""
+    as_filed = sec_edgar.get_balance_sheet("AAPL", "annual", "2009-06-30")
+    restated = sec_edgar.get_balance_sheet("AAPL", "annual", "2011-01-01")
+    assert "39572" in as_filed and "36171" not in as_filed
+    assert "36171" in restated
+
+
+@pytest.mark.unit
+def test_a_period_that_ended_but_was_not_filed_yet_is_not_served():
+    """The fiscal year ended 2024-09-28; it reached the public on 2024-11-01."""
+    before = sec_edgar.get_balance_sheet("AAPL", "annual", "2024-10-15")
+    after = sec_edgar.get_balance_sheet("AAPL", "annual", "2024-11-15")
+    assert "2024-09-28" not in before
+    assert "2024-09-28" in after and "364980" in after
+
+
+@pytest.mark.unit
+def test_the_quarter_is_not_confused_with_the_year_to_date():
+    """One filing carries both spans under the same end date (#MSFT-shaped)."""
+    out = sec_edgar.get_income_statement("AAPL", "quarterly", "2026-06-01")
+    assert "81300" in out
+    assert "158900" not in out
+
+
+@pytest.mark.unit
+def test_a_line_the_filer_does_not_tag_is_named_unavailable():
+    out = sec_edgar.get_balance_sheet("AAPL", "annual", "2024-11-15")
+    assert "Stockholders Equity" in out and "unavailable" in out
+    assert "364980" in out  # the rest of the statement still returns
+
+
+@pytest.mark.unit
+def test_the_report_states_the_vintage_rule():
+    out = sec_edgar.get_balance_sheet("AAPL", "annual", "2024-11-15")
+    assert "filed on or before 2024-11-15" in out
+
+
+@pytest.mark.unit
+def test_a_filer_with_no_usable_facts_reads_differently_from_a_non_filer(monkeypatch):
+    monkeypatch.setattr(sec_edgar, "_fetch_json",
+                        lambda url: TICKER_MAP if "company_tickers" in url else {"facts": {}})
+    with pytest.raises(NoMarketDataError, match="no us-gaap facts"):
+        sec_edgar.get_balance_sheet("AAPL", "annual", "2026-01-01")
+
+
+@pytest.mark.unit
+def test_company_facts_are_fetched_once_per_company_not_once_per_date(tmp_path, monkeypatch):
+    """A sweep asks for many dates; the filing history is the same file."""
+    calls = []
+    monkeypatch.setattr(sec_edgar, "_fetch_json",
+                        lambda url: calls.append(url) or (TICKER_MAP if "company_tickers" in url else FACTS))
+    for date in ("2024-11-15", "2025-01-15", "2025-06-15"):
+        sec_edgar.get_balance_sheet("AAPL", "annual", date)
+    assert len([u for u in calls if "companyfacts" in u]) == 1
+
+
+@pytest.mark.unit
+def test_it_works_unconfigured_and_takes_the_caller_s_own_contact(monkeypatch):
+    """SEC returns 403 for a User-Agent with no contact address, so the default
+    carries one; a caller who sets their own replaces it."""
+    monkeypatch.delenv("SEC_EDGAR_USER_AGENT", raising=False)
+    assert "@" in sec_edgar._user_agent()
+
+    monkeypatch.setenv("SEC_EDGAR_USER_AGENT", "MyDesk research@example.com")
+    assert sec_edgar._user_agent() == "MyDesk research@example.com"
+
+
+@pytest.mark.unit
+def test_a_throttle_lets_the_next_vendor_try(monkeypatch):
+    """SEC throttles by refusing the request; the router then tries yfinance."""
+    import requests
+
+    from tradingagents.dataflows.errors import VendorRateLimitError
+
+    def _throttled(*a, **k):
+        raise requests.HTTPError(response=mock.Mock(status_code=429))
+
+    monkeypatch.setattr(sec_edgar.requests, "get", _throttled)
+    with pytest.raises(VendorRateLimitError):
+        _REAL_FETCH("https://data.sec.gov/api/xbrl/companyfacts/CIK0000320193.json")
+
+
+@pytest.mark.unit
+def test_values_do_not_break_the_columns():
+    """Figures run to the billions; a thousands separator would split the field."""
+    out = sec_edgar.get_balance_sheet("AAPL", "annual", "2024-11-15")
+    body = [row for row in out.splitlines() if row.startswith("Total Assets")][0]
+    assert body.count(",") == out.splitlines()[3].count(",")
+
+
+@pytest.mark.unit
+def test_a_per_share_figure_keeps_its_own_unit():
+    """Statements are reported in millions, but EPS is dollars per share: scaling
+    it the same way prints a real figure as zero."""
+    out = sec_edgar.get_income_statement("AAPL", "annual", "2024-11-15")
+    row = [r for r in out.splitlines() if r.startswith("Diluted EPS")][0]
+    assert "6.08" in row
+    assert "USD/shares" in row or "per share" in row
+
+
+@pytest.mark.unit
+def test_every_row_has_one_cell_per_period():
+    """An untagged line still has to line up with the columns, or the table is
+    misread by position."""
+    out = sec_edgar.get_balance_sheet("AAPL", "annual", "2024-11-15")
+    table = [r for r in out.splitlines() if r and not r.startswith("#")]
+    widths = {row.count(",") for row in table}
+    assert len(widths) == 1, table
+
+
+@pytest.mark.unit
+def test_a_server_error_lets_the_next_vendor_try(monkeypatch):
+    import requests
+
+    from tradingagents.dataflows.errors import VendorError
+
+    def _server_error(*a, **k):
+        raise requests.HTTPError(response=mock.Mock(status_code=503))
+
+    monkeypatch.setattr(sec_edgar.requests, "get", _server_error)
+    with pytest.raises(VendorError):  # not a bare HTTPError
+        _REAL_FETCH("https://data.sec.gov/api/xbrl/companyfacts/CIK0000320193.json")
+
+
+@pytest.mark.unit
+def test_older_periods_fall_back_to_the_tag_the_filer_used_then():
+    """Filers renamed lines when the revenue standard changed, so one tag covers
+    only recent years. Each period takes one tag, never a sum of two."""
+    facts = {"Revenues": {"units": {"USD": [_fact("2015-09-26", 233_715_000_000, "2015-10-28",
+                                                 start="2014-09-28")]}},
+             "RevenueFromContractWithCustomerExcludingAssessedTax": {"units": {"USD": [
+                 _fact("2024-09-28", 391_035_000_000, "2024-11-01", start="2023-09-30")]}}}
+    values, unit = sec_edgar._as_of(facts, ("RevenueFromContractWithCustomerExcludingAssessedTax",
+                                            "Revenues"), "2026-01-01", (300, 400))
+    assert values == {"2015-09-26": 233_715_000_000, "2024-09-28": 391_035_000_000}
+    assert unit == "USD"
+
+
+@pytest.mark.unit
+def test_a_period_reported_under_two_tags_takes_the_preferred_one_not_both():
+    facts = {"Revenues": {"units": {"USD": [_fact("2024-09-28", 111, "2024-11-01", start="2023-09-30")]}},
+             "RevenueFromContractWithCustomerExcludingAssessedTax": {"units": {"USD": [
+                 _fact("2024-09-28", 999, "2024-11-01", start="2023-09-30")]}}}
+    values, _ = sec_edgar._as_of(facts, ("RevenueFromContractWithCustomerExcludingAssessedTax",
+                                         "Revenues"), "2026-01-01", (300, 400))
+    assert values == {"2024-09-28": 999}
+
+
+@pytest.mark.unit
+def test_the_default_identification_tracks_the_installed_version(monkeypatch):
+    """A release should identify itself, not a version frozen in the source."""
+    monkeypatch.delenv("SEC_EDGAR_USER_AGENT", raising=False)
+    monkeypatch.setattr(sec_edgar.metadata, "version", lambda name: "9.9.9")
+    assert sec_edgar._user_agent() == "TradingAgents/9.9.9 (contact@example.com)"
+
+
+@pytest.mark.unit
+def test_an_uninstalled_checkout_still_identifies_itself(monkeypatch):
+    monkeypatch.delenv("SEC_EDGAR_USER_AGENT", raising=False)
+
+    def _missing(name):
+        raise sec_edgar.metadata.PackageNotFoundError(name)
+
+    monkeypatch.setattr(sec_edgar.metadata, "version", _missing)
+    assert "@" in sec_edgar._user_agent()

tests/test_signal_processing.py

@@ -0,0 +1,141 @@
+"""Tests for the shared rating heuristic and the SignalProcessor adapter.
+
+The Portfolio Manager produces a typed PortfolioDecision via structured
+output and renders it to markdown that always contains a ``**Rating**: X``
+header.  The deterministic heuristic in ``tradingagents.agents.utils.rating``
+is therefore sufficient to extract the rating downstream — no second LLM
+call is needed — and SignalProcessor is now a thin adapter that delegates
+to it.
+"""
+
+import pytest
+
+from tradingagents.agents.utils.rating import (
+    RATING_REVIEW,
+    RATINGS_5_TIER,
+    extract_rating,
+    is_review,
+    parse_rating,
+)
+from tradingagents.graph.signal_processing import SignalProcessor
+
+# ---------------------------------------------------------------------------
+# Heuristic parser
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.unit
+class TestParseRating:
+    def test_explicit_label_buy(self):
+        assert parse_rating("Rating: Buy\nReasoning here.") == "Buy"
+
+    def test_explicit_label_overweight(self):
+        assert parse_rating("Rating: Overweight\nDetails.") == "Overweight"
+
+    def test_explicit_label_with_markdown_bold_value(self):
+        # Regression: Rating: **Sell** — markdown around the value.
+        assert parse_rating("Rating: **Sell**\nExit immediately.") == "Sell"
+
+    def test_explicit_label_with_markdown_bold_label(self):
+        assert parse_rating("**Rating**: Underweight\nTrim exposure.") == "Underweight"
+
+    def test_rendered_pm_markdown_shape(self):
+        # The exact shape produced by render_pm_decision must always parse.
+        text = (
+            "**Rating**: Buy\n\n"
+            "**Executive Summary**: Enter at $189-192, 6% portfolio cap.\n\n"
+            "**Investment Thesis**: AI capex cycle intact; institutional flows constructive."
+        )
+        assert parse_rating(text) == "Buy"
+
+    def test_explicit_label_wins_over_prose_with_markdown(self):
+        text = (
+            "The buy thesis is weakened by guidance.\n"
+            "Rating: **Sell**\n"
+            "Exit before earnings."
+        )
+        assert parse_rating(text) == "Sell"
+
+    def test_no_rating_is_flagged_for_review_not_defaulted(self):
+        # A decision nobody can read is not a Hold; recording one invents a call.
+        assert parse_rating("No clear directional signal at this time.") == RATING_REVIEW
+
+    def test_no_rating_custom_default(self):
+        assert parse_rating("Plain prose.", default="Underweight") == "Underweight"
+
+    def test_all_five_tiers_recognised(self):
+        for r in RATINGS_5_TIER:
+            assert parse_rating(f"Rating: {r}") == r
+
+
+# ---------------------------------------------------------------------------
+# SignalProcessor: thin adapter over the heuristic
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.unit
+class TestSignalProcessor:
+    def test_returns_rating_from_pm_markdown(self):
+        sp = SignalProcessor()
+        md = "**Rating**: Overweight\n\n**Executive Summary**: Build gradually."
+        assert sp.process_signal(md) == "Overweight"
+
+    def test_makes_no_llm_calls(self):
+        """SignalProcessor must not invoke the LLM it was constructed with —
+        the rating is parseable from the rendered PM markdown directly."""
+        from unittest.mock import MagicMock
+
+        llm = MagicMock()
+        sp = SignalProcessor(llm)
+        sp.process_signal("Rating: Buy\nDetails.")
+        llm.invoke.assert_not_called()
+        llm.with_structured_output.assert_not_called()
+
+    def test_unparseable_signal_is_review_not_silent_hold(self):
+        # #1170: an unrecognizable decision must surface REVIEW, not a fabricated
+        # tradeable Hold.
+        sp = SignalProcessor()
+        signal = sp.process_signal("Plain prose without a recommendation.")
+        assert signal == RATING_REVIEW
+        assert is_review(signal)
+        assert signal not in RATINGS_5_TIER
+
+    def test_fullwidth_colon_is_parsed_not_reviewed(self):
+        # #1170: `Rating：Overweight` (fullwidth colon) used to defeat the regex
+        # and silently become Hold; NFKC normalization now parses it.
+        sp = SignalProcessor()
+        assert sp.process_signal("Rating：Overweight\n理由はこちら。") == "Overweight"
+
+
+@pytest.mark.unit
+class TestExtractRating:
+    def test_returns_none_when_absent(self):
+        assert extract_rating("No directional call here.") is None
+        assert extract_rating("") is None
+
+    def test_whole_word_only(self):
+        # substrings inside larger words must not match
+        assert extract_rating("The buyer was holding shares.") is None
+
+    def test_parse_rating_defaults_to_review(self):
+        # The memory log tags an unreadable decision REVIEW, never a tradeable rating.
+        assert parse_rating("No rating here.") == RATING_REVIEW
+        assert parse_rating("No rating here.", default="Underweight") == "Underweight"
+
+
+@pytest.mark.unit
+class TestGraphSignalContract:
+    """The graph-facing signal (TradingAgentsGraph.process_signal) honors the
+    documented "5-tier or REVIEW" contract, not just the parser in isolation."""
+
+    def _bare_graph(self):
+        from tradingagents.graph.trading_graph import TradingAgentsGraph
+        g = object.__new__(TradingAgentsGraph)
+        g.signal_processor = SignalProcessor()
+        return g
+
+    def test_graph_surfaces_review(self):
+        assert self._bare_graph().process_signal("no rating in here") == RATING_REVIEW
+
+    def test_graph_returns_rating(self):
+        assert self._bare_graph().process_signal("**Rating**: Sell") == "Sell"

tests/test_social_lookahead.py

@@ -0,0 +1,225 @@
+"""Historical social sentiment must not leak current data into a backtest (#1220).
+
+StockTwits and Reddit fetchers pull only recent items, so for a historical run
+they must be trimmed to the analysis window (and yield a clear placeholder when
+nothing qualifies) rather than showing today's chatter as if it were from the
+as-of date. All three sources share dataflows.date_window.in_window.
+"""
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+
+import pytest
+
+from tradingagents.dataflows import reddit, stocktwits
+from tradingagents.dataflows.date_window import in_window
+
+
+class _JsonResp:
+    """Minimal urlopen() context-manager stub returning a JSON body."""
+
+    def __init__(self, payload):
+        self._body = json.dumps(payload).encode()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *a):
+        return False
+
+    def read(self):
+        return self._body
+
+
+# --- shared window helper ---------------------------------------------------
+
+@pytest.mark.unit
+def test_in_window_bounds_and_exclusive_upper():
+    start = datetime(2026, 5, 1)
+    end = datetime(2026, 5, 9)
+    assert in_window(datetime(2026, 5, 5, tzinfo=timezone.utc), start, end) is True
+    assert in_window(datetime(2026, 5, 9, 23, 59, tzinfo=timezone.utc), start, end) is True
+    # exactly midnight after end -> excluded (no leak)
+    assert in_window(datetime(2026, 5, 10, 0, 0, tzinfo=timezone.utc), start, end) is False
+    # offset-aware converted, not truncated: 05-10T01:00+05:00 == 05-09T20:00Z
+    assert in_window(datetime.fromisoformat("2026-05-10T01:00:00+05:00"), start, end) is True
+
+
+@pytest.mark.unit
+def test_in_window_undated_excluded_in_backtest_kept_live():
+    old = datetime(2026, 5, 9)
+    assert in_window(None, datetime(2026, 5, 1), old) is False       # historical
+    now = datetime.now(timezone.utc)
+    assert in_window(None, now, now) is True                          # live
+
+
+# --- StockTwits -------------------------------------------------------------
+
+def _msg(created_iso, sentiment=None):
+    return {
+        "created_at": created_iso,
+        "user": {"username": "u"},
+        "entities": {"sentiment": {"basic": sentiment}},
+        "body": "text",
+    }
+
+
+@pytest.mark.unit
+def test_stocktwits_historical_window_excludes_recent(monkeypatch):
+    # All messages are "today"; a run as-of a past week must show none of them.
+    recent = [_msg("2026-08-30T12:00:00Z", "Bullish"), _msg("2026-08-29T09:00:00Z")]
+    monkeypatch.setattr(stocktwits, "urlopen", lambda *a, **k: _JsonResp({"messages": recent}))
+    out = stocktwits.fetch_stocktwits_messages("AAPL", start_date="2026-05-01", end_date="2026-05-08")
+    assert "2026-05-01..2026-05-08" in out
+    assert "Bullish: 1" not in out  # the recent bullish message did not leak
+    # Coverage starts after the window: unavailable, never a claim of silence.
+    assert "unavailable" in out and "not an absence" in out
+
+
+@pytest.mark.unit
+def test_stocktwits_live_window_keeps_in_range(monkeypatch):
+    msgs = [_msg("2026-05-05T12:00:00Z", "Bullish"), _msg("2026-05-07T09:00:00Z", "Bearish")]
+    monkeypatch.setattr(stocktwits, "urlopen", lambda *a, **k: _JsonResp({"messages": msgs}))
+    out = stocktwits.fetch_stocktwits_messages("AAPL", start_date="2026-05-01", end_date="2026-05-08")
+    assert "Total: 2" in out
+
+
+@pytest.mark.unit
+def test_stocktwits_no_window_is_unfiltered(monkeypatch):
+    msgs = [_msg("2026-08-30T12:00:00Z", "Bullish")]
+    monkeypatch.setattr(stocktwits, "urlopen", lambda *a, **k: _JsonResp({"messages": msgs}))
+    out = stocktwits.fetch_stocktwits_messages("AAPL")  # live caller, no dates
+    assert "Total: 1" in out
+
+
+# --- Reddit -----------------------------------------------------------------
+
+def _epoch(date_str):
+    return int(datetime.strptime(date_str, "%Y-%m-%d").replace(tzinfo=timezone.utc).timestamp())
+
+
+@pytest.mark.unit
+def test_reddit_historical_window_excludes_recent(monkeypatch):
+    posts = [{"title": "NOW", "created_utc": _epoch("2026-08-30"), "source": "rss"}]
+    monkeypatch.setattr(reddit, "_fetch_subreddit_rss", lambda *a, **k: posts)
+    out = reddit.fetch_reddit_posts(
+        "AAPL", subreddits=("stocks",),
+        start_date="2026-05-01", end_date="2026-05-08",
+    )
+    assert "NOW" not in out
+    assert "unavailable" in out and "not an absence" in out
+
+
+@pytest.mark.unit
+def test_reddit_live_window_keeps_in_range(monkeypatch):
+    posts = [{"title": "INRANGE", "created_utc": _epoch("2026-05-05"), "source": "rss"}]
+    monkeypatch.setattr(reddit, "_fetch_subreddit_rss", lambda *a, **k: posts)
+    out = reddit.fetch_reddit_posts(
+        "AAPL", subreddits=("stocks",),
+        start_date="2026-05-01", end_date="2026-05-08",
+    )
+    assert "INRANGE" in out
+
+
+# --- coverage vs absence --------------------------------------------------------
+# The public feeds only serve recent items. When everything fetched postdates the
+# window the source cannot answer for that date; reporting "no posts" there is a
+# claim about the market that was never observed.
+
+@pytest.mark.unit
+def test_stocktwits_covered_but_empty_window_is_a_real_absence(monkeypatch):
+    # The stream reaches back before the window (an older message exists) yet
+    # nothing falls inside it: that is genuine silence.
+    msgs = [_msg("2026-08-30T12:00:00Z"), _msg("2026-04-20T12:00:00Z")]
+    monkeypatch.setattr(stocktwits, "urlopen", lambda *a, **k: _JsonResp({"messages": msgs}))
+    out = stocktwits.fetch_stocktwits_messages("AAPL", start_date="2026-05-01", end_date="2026-05-08")
+    assert "no StockTwits messages" in out
+    assert "unavailable" not in out
+
+
+@pytest.mark.unit
+def test_reddit_covered_but_empty_window_is_a_real_absence(monkeypatch):
+    posts = [{"title": "NOW", "created_utc": _epoch("2026-08-30"), "source": "rss"},
+             {"title": "OLD", "created_utc": _epoch("2026-04-20"), "source": "rss"}]
+    monkeypatch.setattr(reddit, "_fetch_subreddit_rss", lambda *a, **k: posts)
+    out = reddit.fetch_reddit_posts(
+        "AAPL", subreddits=("stocks",),
+        start_date="2026-05-01", end_date="2026-05-08",
+    )
+    assert "no reddit posts" in out.lower()
+    assert "unavailable" not in out
+
+
+@pytest.mark.unit
+def test_reddit_empty_feed_for_an_old_window_is_unavailable(monkeypatch):
+    # Search is limited to the last week, so an empty response says nothing
+    # about a window from months ago: there are no timestamps to go on, and the
+    # lookback bound alone must decide.
+    monkeypatch.setattr(reddit, "_fetch_subreddit_rss", lambda *a, **k: [])
+    out = reddit.fetch_reddit_posts(
+        "AAPL", subreddits=("stocks",),
+        start_date="2024-05-01", end_date="2024-05-08",
+    )
+    assert "unavailable" in out and "not an absence" in out
+
+
+@pytest.mark.unit
+def test_reddit_live_empty_feed_is_a_real_absence(monkeypatch):
+    monkeypatch.setattr(reddit, "_fetch_subreddit_rss", lambda *a, **k: [])
+    out = reddit.fetch_reddit_posts("AAPL", subreddits=("stocks",))
+    assert "no reddit posts" in out.lower() and "past 7 days" in out
+    assert "unavailable" not in out
+
+
+
+@pytest.mark.unit
+def test_stocktwits_empty_stream_for_a_past_window_is_unavailable(monkeypatch):
+    monkeypatch.setattr(stocktwits, "urlopen", lambda *a, **k: _JsonResp({"messages": []}))
+    out = stocktwits.fetch_stocktwits_messages("AAPL", start_date="2026-05-01", end_date="2026-05-08")
+    assert "unavailable" in out and "not an absence" in out
+
+
+
+@pytest.mark.unit
+def test_reddit_window_straddling_the_lookback_is_unavailable(monkeypatch):
+    # Ten days ago through five days ago: the week-long search never reaches the
+    # first three days, so an empty result cannot stand for the whole window.
+    from datetime import timedelta
+    today = datetime.now(timezone.utc).date()
+    monkeypatch.setattr(reddit, "_fetch_subreddit_rss", lambda *a, **k: [])
+    out = reddit.fetch_reddit_posts(
+        "AAPL", subreddits=("stocks",),
+        start_date=str(today - timedelta(days=10)), end_date=str(today - timedelta(days=5)),
+    )
+    assert "unavailable" in out
+
+
+@pytest.mark.unit
+def test_reddit_standard_week_window_empty_is_a_real_absence(monkeypatch):
+    # The graph's window is [trade_date - 7, trade_date]; the week-long search
+    # covers it, so an empty result is genuine silence.
+    from datetime import timedelta
+    today = datetime.now(timezone.utc).date()
+    monkeypatch.setattr(reddit, "_fetch_subreddit_rss", lambda *a, **k: [])
+    out = reddit.fetch_reddit_posts(
+        "AAPL", subreddits=("stocks",),
+        start_date=str(today - timedelta(days=7)), end_date=str(today),
+    )
+    assert "no reddit posts" in out.lower() and "unavailable" not in out
+
+
+@pytest.mark.unit
+def test_reddit_full_page_does_not_vouch_for_older_days(monkeypatch):
+    # 100 posts from today say nothing about five days ago: the page may have
+    # cut older matches off, so the window stays unavailable.
+    from datetime import timedelta
+    today = datetime.now(timezone.utc).date()
+    ts = _epoch(str(today))
+    page = [{"title": f"T{i}", "created_utc": ts, "subreddit": "stocks"} for i in range(reddit._FEED_PAGE)]
+    monkeypatch.setattr(reddit, "_fetch_subreddit_rss", lambda *a, **k: page)
+    out = reddit.fetch_reddit_posts(
+        "AAPL", subreddits=("stocks",),
+        start_date=str(today - timedelta(days=6)), end_date=str(today - timedelta(days=5)),
+    )
+    assert "unavailable" in out and "no reddit posts" not in out.lower()

tests/test_stockstats_date_column.py

@@ -0,0 +1,70 @@
+"""Tests for tolerating a non-`Date` index column in stockstats_utils (#890).
+
+Guards against a download frame whose date column is `index` or `Datetime`
+instead of `Date`, which would otherwise silently drop every indicator.
+"""
+
+from __future__ import annotations
+
+import pandas as pd
+import pytest
+
+from tradingagents.dataflows import stockstats_utils as su
+
+
+def _ohlcv(date_col: str) -> pd.DataFrame:
+    """OHLCV frame whose date column is named `date_col`."""
+    dates = pd.bdate_range("2026-04-01", periods=10)
+    return pd.DataFrame({
+        date_col: dates,
+        "Open": [100.0 + i for i in range(10)],
+        "High": [101.0 + i for i in range(10)],
+        "Low": [99.0 + i for i in range(10)],
+        "Close": [100.5 + i for i in range(10)],
+        "Volume": [1_000_000 + i for i in range(10)],
+    })
+
+
+@pytest.mark.unit
+class TestEnsureDateColumn:
+    def test_renames_index_column(self):
+        out = su._ensure_date_column(_ohlcv("index"))
+        assert "Date" in out.columns and "index" not in out.columns
+
+    def test_renames_datetime_and_date_variants(self):
+        assert "Date" in su._ensure_date_column(_ohlcv("Datetime")).columns
+        assert "Date" in su._ensure_date_column(_ohlcv("date")).columns
+
+    def test_leaves_existing_date_untouched(self):
+        df = _ohlcv("Date")
+        assert su._ensure_date_column(df) is df  # no-op short-circuit
+
+    def test_no_datelike_column_is_left_alone(self):
+        df = pd.DataFrame({"Close": [1, 2, 3]})
+        out = su._ensure_date_column(df)
+        assert "Date" not in out.columns  # nothing to rename; caller handles
+
+
+@pytest.mark.unit
+class TestCleanDataframeAcrossVersions:
+    def test_clean_handles_index_column(self):
+        """A frame with `index` instead of `Date` must still clean to a
+        usable, date-parsed frame (was KeyError: 'Date')."""
+        cleaned = su._clean_dataframe(_ohlcv("index"))
+        assert "Date" in cleaned.columns
+        assert pd.api.types.is_datetime64_any_dtype(cleaned["Date"])
+        assert len(cleaned) == 10
+
+    def test_clean_handles_legacy_date_column(self):
+        cleaned = su._clean_dataframe(_ohlcv("Date"))
+        assert len(cleaned) == 10
+
+    def test_indicators_compute_after_index_rename(self):
+        """stockstats must compute indicators on a frame whose date column
+        arrived as `index`, instead of erroring per indicator."""
+        from stockstats import wrap
+        cleaned = su._clean_dataframe(_ohlcv("index"))
+        df = wrap(cleaned)
+        df["close_5_sma"]  # triggers calculation
+        assert "close_5_sma" in df.columns
+        assert df["close_5_sma"].notna().any()

tests/test_stocktwits_resilience.py

@@ -0,0 +1,77 @@
+"""StockTwits fetch: transport-error resilience (#1024) and crypto symbol
+mapping (#1113).
+
+StockTwits lists crypto under ``<BASE>.X`` (Yahoo's ``BTC-USD`` 404s), and any
+transport error must degrade to a placeholder rather than raise.
+"""
+
+from __future__ import annotations
+
+import http.client
+from unittest.mock import patch
+from urllib.error import HTTPError
+
+import pytest
+
+from tradingagents.dataflows import stocktwits
+
+
+def _raise(exc):
+    class _Resp:
+        def __enter__(self_inner):
+            return self_inner
+
+        def __exit__(self_inner, *a):
+            return False
+
+        def read(self_inner):
+            raise exc
+    return _Resp()
+
+
+@pytest.mark.unit
+class TestStockTwitsResilience:
+    @pytest.mark.parametrize(
+        "exc",
+        [
+            http.client.IncompleteRead(b""),
+            HTTPError("url", 503, "down", {}, None),
+            TimeoutError("slow"),
+        ],
+    )
+    def test_transport_errors_return_placeholder(self, exc):
+        with patch.object(stocktwits, "urlopen", return_value=_raise(exc)):
+            out = stocktwits.fetch_stocktwits_messages("NVDA")
+        assert "unavailable" in out.lower()
+        assert out.startswith("<stocktwits unavailable")
+
+
+@pytest.mark.unit
+class TestStockTwitsCryptoSymbols:
+    @pytest.mark.parametrize(
+        ("ticker", "expected"),
+        [
+            ("BTC-USD", "BTC.X"),
+            ("eth-usd", "ETH.X"),
+            ("SOL-USD", "SOL.X"),
+            ("BTCUSD", "BTC.X"),      # undashed broker form
+            ("BTC-USDT", "BTC.X"),    # stablecoin quote
+            ("AMD", "AMD"),
+            ("BRK-B", "BRK-B"),       # dashed class share: untouched
+            ("GOLD", "GOLD"),         # real equity (aliases elsewhere): untouched here
+            ("XYZ-USD", "XYZ-USD"),   # unknown base: not treated as crypto
+        ],
+    )
+    def test_symbol_mapping(self, ticker, expected):
+        assert stocktwits._stocktwits_symbol(ticker) == expected
+
+    def test_crypto_pair_requests_dot_x_endpoint(self):
+        seen = {}
+
+        def fake_urlopen(req, timeout=None):
+            seen["url"] = req.full_url
+            raise TimeoutError("stop after capturing the URL")
+
+        with patch.object(stocktwits, "urlopen", side_effect=fake_urlopen):
+            stocktwits.fetch_stocktwits_messages("BTC-USD")
+        assert "/symbol/BTC.X.json" in seen["url"]

tests/test_structured_agent_prompts.py

@@ -0,0 +1,148 @@
+"""Agents on the schema-only structured-output path must not invite tool calls (#1130).
+
+`with_structured_output` binds exactly one tool (the schema). A prompt that
+primes tool use makes models emit an unknown `web_search` call, which discards
+the structured attempt and forces a free-text retry — an extra LLM round trip
+and the loss of typed output.
+
+These assert the constraint reaches the *rendered* prompt each agent actually
+sends, not merely that the constant is referenced in the module.
+"""
+from __future__ import annotations
+
+import inspect
+from unittest.mock import MagicMock
+
+import pytest
+
+import tradingagents.agents.analysts.sentiment_analyst as sentiment
+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.agents.utils.structured import NO_EXTERNAL_TOOLS
+
+
+def _capturing_llm(captured: dict, result):
+    """LLM whose structured binding records the prompt it was handed."""
+    structured = MagicMock()
+    structured.invoke.side_effect = lambda prompt: (
+        captured.__setitem__("prompt", prompt) or result
+    )
+    llm = MagicMock()
+    llm.with_structured_output.return_value = structured
+    return llm
+
+
+def _prompt_text(prompt) -> str:
+    """Flatten a captured prompt (str, message list, or objects) to text."""
+    if isinstance(prompt, str):
+        return prompt
+    parts = []
+    for m in prompt:
+        parts.append(m.get("content", "") if isinstance(m, dict) else getattr(m, "content", ""))
+    return "\n".join(str(p) for p in parts)
+
+
+@pytest.mark.unit
+def test_trader_prompt_states_constraint():
+    from tradingagents.agents.schemas import TraderAction, TraderProposal
+
+    captured = {}
+    llm = _capturing_llm(captured, TraderProposal(action=TraderAction.BUY, reasoning="x"))
+    create_trader(llm)({
+        "company_of_interest": "NVDA",
+        "investment_plan": "**Recommendation**: Buy",
+        "market_report": "Current price $189.5; ATR 4.2.",
+    })
+    assert NO_EXTERNAL_TOOLS in _prompt_text(captured["prompt"])
+
+
+@pytest.mark.unit
+def test_research_manager_prompt_states_constraint():
+    from tradingagents.agents.schemas import PortfolioRating, ResearchPlan
+
+    captured = {}
+    llm = _capturing_llm(
+        captured,
+        ResearchPlan(
+            recommendation=PortfolioRating.BUY, rationale="x", strategic_actions="y"
+        ),
+    )
+    create_research_manager(llm)({
+        "company_of_interest": "NVDA",
+        "investment_debate_state": {
+            "history": "h", "bull_history": "b", "bear_history": "r",
+            "current_response": "", "judge_decision": "", "count": 1,
+        },
+    })
+    assert NO_EXTERNAL_TOOLS in _prompt_text(captured["prompt"])
+
+
+@pytest.mark.unit
+def test_portfolio_manager_prompt_states_constraint():
+    from tradingagents.agents.schemas import PortfolioDecision, PortfolioRating
+
+    captured = {}
+    llm = _capturing_llm(
+        captured,
+        PortfolioDecision(
+            rating=PortfolioRating.HOLD,
+            executive_summary="x",
+            investment_thesis="y",
+        ),
+    )
+    risk = {
+        "history": "h", "aggressive_history": "a", "conservative_history": "c",
+        "neutral_history": "n", "current_aggressive_response": "",
+        "current_conservative_response": "", "current_neutral_response": "",
+        "latest_speaker": "Neutral", "count": 1,
+    }
+    create_portfolio_manager(llm)({
+        "company_of_interest": "NVDA",
+        "risk_debate_state": risk,
+        "investment_plan": "plan",
+        "trader_investment_plan": "trader plan",
+    })
+    assert NO_EXTERNAL_TOOLS in _prompt_text(captured["prompt"])
+
+
+@pytest.mark.unit
+def test_sentiment_prompt_states_constraint(monkeypatch):
+    from tradingagents.agents.schemas import SentimentBand, SentimentReport
+
+    # Pre-fetched sources are stubbed so the prompt builds without network I/O.
+    monkeypatch.setattr(sentiment, "fetch_stocktwits_messages", lambda *a, **k: "st")
+    monkeypatch.setattr(sentiment, "fetch_reddit_posts", lambda *a, **k: "rd")
+    monkeypatch.setattr(sentiment.get_news, "func", lambda *a, **k: "news", raising=False)
+
+    captured = {}
+    llm = _capturing_llm(captured, SentimentReport(
+        overall_band=SentimentBand.BULLISH, overall_score=7.5,
+        confidence="high", narrative="n",
+    ))
+    sentiment.create_sentiment_analyst(llm)({
+        "company_of_interest": "NVDA", "trade_date": "2026-01-15",
+        "asset_type": "stock", "messages": [],
+    })
+    text = _prompt_text(captured["prompt"])
+    assert NO_EXTERNAL_TOOLS in text
+    # This agent binds no tools, so tool-range wording must not reappear.
+    assert "tool-call date ranges" not in text
+
+
+@pytest.mark.unit
+def test_tool_using_analysts_keep_their_date_guidance():
+    # The analysts that really do call tools keep the wording that anchors their
+    # tool date ranges (#836) — this fix is scoped to no-tool agents.
+    import tradingagents.agents.analysts.market_analyst as market
+    import tradingagents.agents.analysts.news_analyst as news
+    for module in (market, news):
+        assert "tool-call date ranges" in inspect.getsource(module)
+
+
+@pytest.mark.unit
+def test_constraint_text_is_unambiguous():
+    assert "do not call external tools" in NO_EXTERNAL_TOOLS.lower()
+    # No template braces: it is embedded in ChatPromptTemplate strings, where
+    # braces would be parsed as input variables.
+    assert "{" not in NO_EXTERNAL_TOOLS and "}" not in NO_EXTERNAL_TOOLS

tests/test_structured_agents.py

@@ -0,0 +1,548 @@
+"""Tests for structured-output agents (Trader, Research Manager, Sentiment Analyst).
+
+The Portfolio Manager has its own coverage in tests/test_memory_log.py
+(which exercises the full memory-log → PM injection cycle).  This file
+covers the parallel schemas, render functions, and graceful-fallback
+behavior we added for the Trader, Research Manager, and Sentiment Analyst
+so they share the same deterministic output shape.
+"""
+
+import inspect
+from unittest.mock import MagicMock
+
+import pytest
+from pydantic import ValidationError
+
+from tradingagents.agents.analysts.sentiment_analyst import create_sentiment_analyst
+from tradingagents.agents.managers.portfolio_manager import create_portfolio_manager
+from tradingagents.agents.managers.research_manager import create_research_manager
+from tradingagents.agents.schemas import (
+    PortfolioDecision,
+    PortfolioRating,
+    ResearchPlan,
+    SentimentBand,
+    SentimentReport,
+    TraderAction,
+    TraderProposal,
+    render_research_plan,
+    render_sentiment_report,
+    render_trader_proposal,
+)
+from tradingagents.agents.trader.trader import create_trader
+
+# ---------------------------------------------------------------------------
+# Render functions
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.unit
+class TestRenderTraderProposal:
+    def test_minimal_required_fields(self):
+        p = TraderProposal(action=TraderAction.HOLD, reasoning="Balanced setup; no edge.")
+        md = render_trader_proposal(p)
+        assert "**Action**: Hold" in md
+        assert "**Reasoning**: Balanced setup; no edge." in md
+        # The trailing FINAL TRANSACTION PROPOSAL line is preserved for the
+        # analyst stop-signal text and any external code that greps for it.
+        assert "FINAL TRANSACTION PROPOSAL: **HOLD**" in md
+
+    def test_optional_fields_included_when_present(self):
+        p = TraderProposal(
+            action=TraderAction.BUY,
+            reasoning="Strong technicals + fundamentals.",
+            entry_price=189.5,
+            stop_loss=178.0,
+            position_sizing="6% of portfolio",
+        )
+        md = render_trader_proposal(p)
+        assert "**Action**: Buy" in md
+        assert "**Entry Price**: 189.5" in md
+        assert "**Stop Loss**: 178.0" in md
+        assert "**Position Sizing**: 6% of portfolio" in md
+        assert "FINAL TRANSACTION PROPOSAL: **BUY**" in md
+
+    def test_optional_fields_are_named_as_not_provided(self):
+        """An omitted line reads as a field nobody asked for; the reader cannot
+        tell it from a level the trader declined to set."""
+        p = TraderProposal(action=TraderAction.SELL, reasoning="Guidance cut.")
+        md = render_trader_proposal(p)
+        for field in ("Entry Price", "Stop Loss", "Position Sizing"):
+            assert f"**{field}**: not provided" in md
+        assert "FINAL TRANSACTION PROPOSAL: **SELL**" in md
+
+
+@pytest.mark.unit
+class TestNullishFloatCoercion:
+    """A weak LLM may write "None"/"N/A" into an optional float field (#1058);
+    coerce those to None so the structured call validates instead of erroring."""
+
+    def test_trader_nullish_strings_coerce_to_none(self):
+        for sentinel in ("None", "N/A", "null", "-", "", "TBD"):
+            p = TraderProposal(
+                action=TraderAction.HOLD,
+                reasoning="x",
+                entry_price=sentinel,
+                stop_loss=sentinel,
+            )
+            assert p.entry_price is None
+            assert p.stop_loss is None
+
+    def test_trader_real_numeric_string_still_parses(self):
+        p = TraderProposal(action=TraderAction.BUY, reasoning="x", entry_price="189.5")
+        assert p.entry_price == 189.5
+
+    def test_pm_nullish_price_target_coerces_to_none(self):
+        d = PortfolioDecision(
+            rating=PortfolioRating.OVERWEIGHT,
+            executive_summary="s",
+            investment_thesis="t",
+            price_target="N/A",
+        )
+        assert d.price_target is None
+
+    def test_percentage_answer_to_a_price_field_becomes_none(self):
+        # The Trader is asked for concrete levels and may answer a price field
+        # with a distance ("15%"), which failed the whole proposal (#1288).
+        # A percentage cannot be salvaged: 15% must not become a $15 stop.
+        for pct in ("15%", " 7.5% ", "-10%"):
+            p = TraderProposal(
+                action=TraderAction.BUY,
+                reasoning="x",
+                entry_price=pct,
+                stop_loss=pct,
+            )
+            assert p.entry_price is None
+            assert p.stop_loss is None
+
+    def test_human_formatted_price_is_reduced_to_its_number(self):
+        p = TraderProposal(
+            action=TraderAction.BUY,
+            reasoning="x",
+            entry_price="$1,234.50",
+            stop_loss="1,180",
+        )
+        assert p.entry_price == 1234.50
+        assert p.stop_loss == 1180.0
+
+    def test_one_bad_field_no_longer_fails_the_whole_proposal(self):
+        # Previously a single '15%' raised, forcing a free-text retry that lost
+        # the action and reasoning; now the rest of the proposal survives.
+        p = TraderProposal(
+            action=TraderAction.SELL,
+            reasoning="downgrade on margin compression",
+            entry_price="612.40",
+            stop_loss="15%",
+        )
+        assert p.action is TraderAction.SELL
+        assert p.entry_price == 612.40
+        assert p.stop_loss is None
+
+
+@pytest.mark.unit
+class TestRenderResearchPlan:
+    def test_required_fields(self):
+        p = ResearchPlan(
+            recommendation=PortfolioRating.OVERWEIGHT,
+            rationale="Bull case carried; tailwinds intact.",
+            strategic_actions="Build position over two weeks; cap at 5%.",
+        )
+        md = render_research_plan(p)
+        assert "**Recommendation**: Overweight" in md
+        assert "**Rationale**: Bull case carried" in md
+        assert "**Strategic Actions**: Build position" in md
+
+    def test_all_5_tier_ratings_render(self):
+        for rating in PortfolioRating:
+            p = ResearchPlan(
+                recommendation=rating,
+                rationale="r",
+                strategic_actions="s",
+            )
+            md = render_research_plan(p)
+            assert f"**Recommendation**: {rating.value}" in md
+
+
+# ---------------------------------------------------------------------------
+# Trader agent: structured happy path + fallback
+# ---------------------------------------------------------------------------
+
+
+def _make_trader_state():
+    return {
+        "company_of_interest": "NVDA",
+        "investment_plan": "**Recommendation**: Buy\n**Rationale**: ...\n**Strategic Actions**: ...",
+        "market_report": "Current price $189.5; 14-day ATR 4.2; support $178, resistance $196.",
+    }
+
+
+def _structured_trader_llm(captured: dict, proposal: TraderProposal | None = None):
+    """Build a MagicMock LLM whose with_structured_output binding captures the
+    prompt and returns a real TraderProposal so render_trader_proposal works.
+    """
+    if proposal is None:
+        proposal = TraderProposal(
+            action=TraderAction.BUY,
+            reasoning="Strong setup.",
+        )
+    structured = MagicMock()
+    structured.invoke.side_effect = lambda prompt: (
+        captured.__setitem__("prompt", prompt) or proposal
+    )
+    llm = MagicMock()
+    llm.with_structured_output.return_value = structured
+    return llm
+
+
+@pytest.mark.unit
+def test_invoke_structured_falls_back_when_result_is_none():
+    # A thinking model can answer in plain text, leaving the parser with None.
+    # That must fall back to free text, not crash on render(None) (#1051).
+    from tradingagents.agents.utils.structured import invoke_structured_or_freetext
+
+    structured = MagicMock()
+    structured.invoke.return_value = None
+    plain = MagicMock()
+    plain.invoke.return_value = MagicMock(content="FREETEXT")
+
+    out = invoke_structured_or_freetext(
+        structured, plain, "prompt", render=lambda r: r.rating, agent_name="t"
+    )
+    assert out == "FREETEXT"
+    plain.invoke.assert_called_once()
+
+
+@pytest.mark.unit
+class TestTraderAgent:
+    def test_structured_path_produces_rendered_markdown(self):
+        captured = {}
+        proposal = TraderProposal(
+            action=TraderAction.BUY,
+            reasoning="AI capex cycle intact; institutional flows constructive.",
+            entry_price=189.5,
+            stop_loss=178.0,
+            position_sizing="6% of portfolio",
+        )
+        llm = _structured_trader_llm(captured, proposal)
+        trader = create_trader(llm)
+        result = trader(_make_trader_state())
+        plan = result["trader_investment_plan"]
+        assert "**Action**: Buy" in plan
+        assert "**Entry Price**: 189.5" in plan
+        assert "FINAL TRANSACTION PROPOSAL: **BUY**" in plan
+        # The same rendered markdown is also added to messages for downstream agents.
+        assert plan in result["messages"][0].content
+
+    def test_prompt_includes_investment_plan(self):
+        captured = {}
+        llm = _structured_trader_llm(captured)
+        trader = create_trader(llm)
+        trader(_make_trader_state())
+        # The investment plan is in the user message of the captured prompt.
+        prompt = captured["prompt"]
+        assert any("Proposed Investment Plan" in m["content"] for m in prompt)
+
+    def test_prompt_includes_market_report_for_price_levels(self):
+        # #1167: the Trader must see the technical market report so entry/stop
+        # levels are grounded in real price structure, not just the digested plan.
+        captured = {}
+        trader = create_trader(_structured_trader_llm(captured))
+        trader(_make_trader_state())
+        user = " ".join(m["content"] for m in captured["prompt"] if m["role"] == "user")
+        system = " ".join(m["content"] for m in captured["prompt"] if m["role"] == "system")
+        assert "Technical Market Report:" in user
+        assert "14-day ATR 4.2" in user            # the actual report content reached the Trader
+        assert "support $178, resistance $196" in user
+        assert "Ground concrete price levels" in system
+
+    def test_empty_market_report_omits_the_section_and_grounding(self):
+        # #1167: when the market analyst wasn't selected the report is empty, so
+        # don't tell the Trader to ground levels in a report it doesn't have.
+        captured = {}
+        state = _make_trader_state()
+        state["market_report"] = ""
+        create_trader(_structured_trader_llm(captured))(state)
+        text = " ".join(m["content"] for m in captured["prompt"])
+        assert "Technical Market Report:" not in text
+        assert "Ground concrete price levels" not in text
+        assert "Proposed Investment Plan" in text  # still present
+
+    def test_falls_back_to_freetext_when_structured_unavailable(self):
+        plain_response = (
+            "**Action**: Sell\n\nGuidance cut hits margins.\n\n"
+            "FINAL TRANSACTION PROPOSAL: **SELL**"
+        )
+        llm = MagicMock()
+        llm.with_structured_output.side_effect = NotImplementedError("provider unsupported")
+        llm.invoke.return_value = MagicMock(content=plain_response)
+        trader = create_trader(llm)
+        result = trader(_make_trader_state())
+        assert result["trader_investment_plan"] == plain_response
+
+
+# ---------------------------------------------------------------------------
+# Research Manager agent: structured happy path + fallback
+# ---------------------------------------------------------------------------
+
+
+def _make_rm_state():
+    return {
+        "company_of_interest": "NVDA",
+        "investment_debate_state": {
+            "history": "Bull and bear arguments here.",
+            "bull_history": "Bull says...",
+            "bear_history": "Bear says...",
+            "current_response": "",
+            "judge_decision": "",
+            "count": 1,
+        },
+    }
+
+
+def _structured_rm_llm(captured: dict, plan: ResearchPlan | None = None):
+    if plan is None:
+        plan = ResearchPlan(
+            recommendation=PortfolioRating.HOLD,
+            rationale="Balanced view across both sides.",
+            strategic_actions="Hold current position; reassess after earnings.",
+        )
+    structured = MagicMock()
+    structured.invoke.side_effect = lambda prompt: (
+        captured.__setitem__("prompt", prompt) or plan
+    )
+    llm = MagicMock()
+    llm.with_structured_output.return_value = structured
+    return llm
+
+
+@pytest.mark.unit
+class TestResearchManagerAgent:
+    def test_structured_path_produces_rendered_markdown(self):
+        captured = {}
+        plan = ResearchPlan(
+            recommendation=PortfolioRating.OVERWEIGHT,
+            rationale="Bull case is stronger; AI tailwind intact.",
+            strategic_actions="Build position gradually over two weeks.",
+        )
+        llm = _structured_rm_llm(captured, plan)
+        rm = create_research_manager(llm)
+        result = rm(_make_rm_state())
+        ip = result["investment_plan"]
+        assert "**Recommendation**: Overweight" in ip
+        assert "**Rationale**: Bull case" in ip
+        assert "**Strategic Actions**: Build position" in ip
+
+    def test_prompt_uses_5_tier_rating_scale(self):
+        """The RM prompt must list all five tiers so the schema enum matches user expectations."""
+        captured = {}
+        llm = _structured_rm_llm(captured)
+        rm = create_research_manager(llm)
+        rm(_make_rm_state())
+        prompt = captured["prompt"]
+        for tier in ("Buy", "Overweight", "Hold", "Underweight", "Sell"):
+            assert f"**{tier}**" in prompt, f"missing {tier} in prompt"
+
+    def test_falls_back_to_freetext_when_structured_unavailable(self):
+        plain_response = "**Recommendation**: Sell\n\n**Rationale**: ...\n\n**Strategic Actions**: ..."
+        llm = MagicMock()
+        llm.with_structured_output.side_effect = NotImplementedError("provider unsupported")
+        llm.invoke.return_value = MagicMock(content=plain_response)
+        rm = create_research_manager(llm)
+        result = rm(_make_rm_state())
+        assert result["investment_plan"] == plain_response
+
+
+# ---------------------------------------------------------------------------
+# Sentiment Analyst: schema, render, structured happy path + fallback
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.unit
+class TestRenderSentimentReport:
+    def test_header_contains_band_and_score(self):
+        report = SentimentReport(
+            overall_band=SentimentBand.BULLISH,
+            overall_score=7.2,
+            confidence="high",
+            narrative="Source breakdown here.",
+        )
+        md = render_sentiment_report(report)
+        assert "**Overall Sentiment:** **Bullish**" in md
+        assert "(Score: 7.2/10)" in md
+
+    def test_header_contains_confidence(self):
+        report = SentimentReport(
+            overall_band=SentimentBand.NEUTRAL,
+            overall_score=5.0,
+            confidence="low",
+            narrative="Limited data.",
+        )
+        assert "**Confidence:** Low" in render_sentiment_report(report)
+
+    def test_narrative_preserved_in_output(self):
+        narrative = "## Breakdown\n\nStockTwits: 70% bullish.\n\n| Signal | Direction |\n|---|---|\n| News | Neutral |"
+        report = SentimentReport(
+            overall_band=SentimentBand.MILDLY_BULLISH,
+            overall_score=6.0,
+            confidence="medium",
+            narrative=narrative,
+        )
+        assert narrative in render_sentiment_report(report)
+
+    def test_all_six_bands_render(self):
+        for band in SentimentBand:
+            report = SentimentReport(
+                overall_band=band, overall_score=5.0,
+                confidence="medium", narrative="n",
+            )
+            assert band.value in render_sentiment_report(report)
+
+    def test_score_out_of_range_rejected(self):
+        with pytest.raises(ValidationError):
+            SentimentReport(
+                overall_band=SentimentBand.BULLISH, overall_score=11.0,
+                confidence="high", narrative="n",
+            )
+
+
+def _make_sentiment_state():
+    return {
+        "company_of_interest": "NVDA",
+        "trade_date": "2026-01-15",
+        "asset_type": "stock",
+        "messages": [],
+    }
+
+
+def _structured_sentiment_llm(captured: dict, report: SentimentReport | None = None):
+    """MagicMock LLM whose structured binding captures the prompt and returns
+    a real SentimentReport so render_sentiment_report works."""
+    if report is None:
+        report = SentimentReport(
+            overall_band=SentimentBand.BULLISH, overall_score=7.5,
+            confidence="high",
+            narrative="StockTwits 75% bullish. News constructive. Reddit upbeat.",
+        )
+    structured = MagicMock()
+    structured.invoke.side_effect = lambda prompt: (
+        captured.__setitem__("prompt", prompt) or report
+    )
+    llm = MagicMock()
+    llm.with_structured_output.return_value = structured
+    return llm
+
+
+@pytest.mark.unit
+class TestSentimentAnalystAgent:
+    @pytest.fixture(autouse=True)
+    def _stub_prefetched_sources(self, monkeypatch):
+        """Stub the sources the analyst pre-fetches before prompting.
+
+        create_sentiment_analyst fetches news, StockTwits and Reddit itself, so
+        without this these tests hit the live network. A real Reddit 429 then
+        backs the fetcher off for a minute per subreddit, which is what turned
+        this file into a multi-minute hang.
+        """
+        from tradingagents.agents.analysts import sentiment_analyst as sentiment
+
+        monkeypatch.setattr(sentiment, "fetch_stocktwits_messages", lambda *a, **k: "st")
+        monkeypatch.setattr(sentiment, "fetch_reddit_posts", lambda *a, **k: "rd")
+        monkeypatch.setattr(sentiment.get_news, "func", lambda *a, **k: "news", raising=False)
+
+    def test_structured_path_produces_rendered_markdown(self):
+        captured = {}
+        report = SentimentReport(
+            overall_band=SentimentBand.MILDLY_BEARISH, overall_score=4.0,
+            confidence="medium", narrative="Mixed signals across sources.",
+        )
+        analyst = create_sentiment_analyst(_structured_sentiment_llm(captured, report))
+        sr = analyst(_make_sentiment_state())["sentiment_report"]
+        assert "**Overall Sentiment:** **Mildly Bearish**" in sr
+        assert "(Score: 4.0/10)" in sr
+        assert "Mixed signals across sources." in sr
+
+    def test_sentiment_report_also_in_messages(self):
+        captured = {}
+        analyst = create_sentiment_analyst(_structured_sentiment_llm(captured))
+        result = analyst(_make_sentiment_state())
+        assert len(result["messages"]) == 1
+        assert result["sentiment_report"] == result["messages"][0].content
+
+    def test_prompt_contains_ticker(self):
+        captured = {}
+        create_sentiment_analyst(_structured_sentiment_llm(captured))(_make_sentiment_state())
+        assert any("NVDA" in str(m) for m in captured["prompt"])
+
+    def test_falls_back_to_freetext_when_structured_unavailable(self):
+        plain = "**Overall Sentiment:** **Bearish** (Score: 3.0/10)\n**Confidence:** Low\n\nLimited data."
+        llm = MagicMock()
+        llm.with_structured_output.side_effect = NotImplementedError("provider unsupported")
+        llm.invoke.return_value = MagicMock(content=plain)
+        assert create_sentiment_analyst(llm)(_make_sentiment_state())["sentiment_report"] == plain
+
+    def test_falls_back_to_freetext_when_structured_call_fails(self):
+        plain = "Fallback free-text sentiment."
+        structured = MagicMock()
+        structured.invoke.side_effect = ValueError("bad JSON from model")
+        llm = MagicMock()
+        llm.with_structured_output.return_value = structured
+        llm.invoke.return_value = MagicMock(content=plain)
+        assert create_sentiment_analyst(llm)(_make_sentiment_state())["sentiment_report"] == plain
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("source", [
+    pytest.param(lambda: ResearchPlan.model_fields["recommendation"].description, id="ResearchPlan.recommendation"),
+    pytest.param(lambda: PortfolioDecision.model_fields["rating"].description, id="PortfolioDecision.rating"),
+    pytest.param(lambda: inspect.getsource(create_research_manager), id="research_manager prompt"),
+    pytest.param(lambda: inspect.getsource(create_portfolio_manager), id="portfolio_manager prompt"),
+])
+def test_conflict_alone_is_not_a_hold_trigger(source):
+    # The debate always contains conflicting arguments, so a Hold condition that
+    # conflict satisfies fires on every run and swallows directional calls
+    # (#1321). All four decision sites must state the same rule.
+    text = " ".join(source().split())
+    assert "conflict alone is not a reason to Hold" in text or \
+        "Conflicting arguments alone are not a reason to Hold" in text
+    assert "materially conflicting" not in text
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("written", ["150-160", "150 to 160", "around 150", "150/160", "~150"])
+def test_a_price_written_as_a_range_drops_only_that_field(written):
+    """Anything that is not a single number becomes None. Letting it through
+    fails the whole decision's validation, and the run falls back to free text,
+    losing every other field the model got right."""
+    from tradingagents.agents.schemas import PortfolioDecision, PortfolioRating
+
+    decision = PortfolioDecision(rating=PortfolioRating.BUY, executive_summary="s",
+                                 investment_thesis="t", price_target=written)
+    assert decision.price_target is None
+
+
+@pytest.mark.unit
+def test_a_price_that_is_a_number_survives():
+    from tradingagents.agents.schemas import PortfolioDecision, PortfolioRating
+
+    decision = PortfolioDecision(rating=PortfolioRating.BUY, executive_summary="s",
+                                 investment_thesis="t", price_target="$1,150.25")
+    assert decision.price_target == 1150.25
+
+
+@pytest.mark.unit
+def test_a_field_the_model_did_not_give_says_so():
+    """An omitted line and a line never asked for read the same to an analyst."""
+    from tradingagents.agents.schemas import PortfolioDecision, PortfolioRating, render_pm_decision
+
+    rendered = render_pm_decision(PortfolioDecision(
+        rating=PortfolioRating.HOLD, executive_summary="s", investment_thesis="t"))
+    assert "Price Target" in rendered and "not provided" in rendered.lower()
+
+
+@pytest.mark.unit
+def test_the_trader_names_the_levels_it_did_not_give():
+    from tradingagents.agents.schemas import TraderAction, TraderProposal, render_trader_proposal
+
+    rendered = render_trader_proposal(TraderProposal(action=TraderAction.HOLD, reasoning="r"))
+    for field in ("Entry Price", "Stop Loss", "Position Sizing"):
+        assert field in rendered
+    assert rendered.lower().count("not provided") == 3

tests/test_symbol_normalization_paths.py

@@ -0,0 +1,78 @@
+"""Symbol normalization must apply on every yfinance path, not just price fetch.
+
+Regression tests for #983 (instrument identity), #984 (reflection returns), and
+the news path: a broker symbol like XAUUSD must resolve to the same Yahoo symbol
+(GC=F) that the price path uses, so identity, realized-return, and news lookups
+hit the right instrument instead of failing/mismatching.
+"""
+import pandas as pd
+
+import tradingagents.agents.utils.agent_utils as au
+import tradingagents.dataflows.yfinance_news as ynews
+import tradingagents.graph.trading_graph as tg
+from tradingagents.graph.trading_graph import TradingAgentsGraph
+
+
+def test_identity_lookup_normalizes_symbol(monkeypatch):
+    seen = {}
+
+    class FakeTicker:
+        def __init__(self, symbol):
+            seen["symbol"] = symbol
+
+        @property
+        def info(self):
+            return {"longName": "Gold Futures", "quoteType": "FUTURE"}
+
+    monkeypatch.setattr(au.yf, "Ticker", FakeTicker)
+    au.resolve_instrument_identity.cache_clear()
+
+    identity = au.resolve_instrument_identity("XAUUSD")
+
+    assert seen["symbol"] == "GC=F"  # normalized, not the raw broker symbol
+    assert identity.get("company_name") == "Gold Futures"
+
+
+def test_fetch_returns_normalizes_symbol(monkeypatch):
+    queried = []
+
+    class FakeTicker:
+        def __init__(self, symbol):
+            queried.append(symbol)
+
+        def history(self, *args, **kwargs):
+            prices = [100.0, 101.0, 102.0, 103.0, 104.0, 105.0, 106.0]
+            idx = pd.date_range(start="2025-01-02", periods=len(prices), freq="D")
+            return pd.DataFrame({"Close": prices}, index=idx)
+
+    monkeypatch.setattr(tg.yf, "Ticker", FakeTicker)
+
+    # _fetch_returns does not use ``self``; call unbound to avoid building the graph.
+    raw, alpha, days, resolved = TradingAgentsGraph._fetch_returns(
+        None, "XAUUSD", "2025-01-02", holding_days=5, benchmark="SPY"
+    )
+
+    assert queried[0] == "GC=F"  # stock symbol normalized (#984)
+    assert queried[1] == "SPY"   # benchmark left as the canonical symbol
+    assert raw is not None and days is not None
+    assert resolved == "2025-01-07"  # resolution date recorded (#1251)
+
+
+def test_news_lookup_normalizes_symbol(monkeypatch):
+    seen = {}
+
+    class FakeTicker:
+        def __init__(self, symbol):
+            seen["symbol"] = symbol
+
+        def get_news(self, count):
+            return []
+
+    monkeypatch.setattr(ynews.yf, "Ticker", FakeTicker)
+    monkeypatch.setattr(ynews, "yf_retry", lambda fn: fn())
+
+    out = ynews.get_news_yfinance("XAUUSD", "2025-01-01", "2025-01-10")
+
+    assert seen["symbol"] == "GC=F"   # news queried with the canonical symbol
+    assert "XAUUSD" in out            # the user's ticker stays in the report
+    assert "GC=F" in out              # provenance noted

tests/test_symbol_utils.py

@@ -0,0 +1,123 @@
+"""Tests for symbol normalization and the no-data routing sentinel."""
+
+import unittest
+
+import pytest
+
+from tradingagents.dataflows.symbol_utils import (
+    NoMarketDataError,
+    crypto_base,
+    is_yahoo_safe,
+    normalize_symbol,
+)
+
+
+@pytest.mark.unit
+class TestNormalizeSymbol(unittest.TestCase):
+    def test_plain_equities_unchanged(self):
+        for sym in ("AAPL", "MSFT", "TSM", "BRK.B", "0700.HK", "^GSPC", "GC=F"):
+            self.assertEqual(normalize_symbol(sym), sym)
+
+    def test_lowercases_are_upper(self):
+        self.assertEqual(normalize_symbol("aapl"), "AAPL")
+        self.assertEqual(normalize_symbol("  msft  "), "MSFT")
+
+    def test_metal_aliases_map_to_futures(self):
+        self.assertEqual(normalize_symbol("XAUUSD"), "GC=F")
+        self.assertEqual(normalize_symbol("XAUUSD+"), "GC=F")   # broker CFD suffix
+        self.assertEqual(normalize_symbol("xauusd+"), "GC=F")
+        self.assertEqual(normalize_symbol("GOLD"), "GC=F")
+        self.assertEqual(normalize_symbol("XAGUSD"), "SI=F")
+
+    def test_energy_and_index_aliases(self):
+        self.assertEqual(normalize_symbol("USOIL"), "CL=F")
+        self.assertEqual(normalize_symbol("SPX500"), "^GSPC")
+        self.assertEqual(normalize_symbol("NAS100"), "^NDX")
+        self.assertEqual(normalize_symbol("US30"), "^DJI")
+
+    def test_forex_pairs_get_x_suffix(self):
+        self.assertEqual(normalize_symbol("EURUSD"), "EURUSD=X")
+        self.assertEqual(normalize_symbol("GBPJPY"), "GBPJPY=X")
+        self.assertEqual(normalize_symbol("eurusd"), "EURUSD=X")
+
+    def test_crypto_pairs_get_dash_usd(self):
+        self.assertEqual(normalize_symbol("BTCUSD"), "BTC-USD")
+        self.assertEqual(normalize_symbol("ETHUSD"), "ETH-USD")
+
+    def test_six_letter_non_currency_left_alone(self):
+        # GOOGLE-style 6-letter tickers that aren't two currency codes
+        # must not be mangled into a fake forex pair.
+        self.assertEqual(normalize_symbol("ABCDEF"), "ABCDEF")
+
+    def test_empty_input_passthrough(self):
+        self.assertEqual(normalize_symbol(""), "")
+
+    def test_hk_five_digit_code_repadded_to_four(self):
+        # HKEX lists up to 5-digit codes; Yahoo only accepts 4 (#957).
+        self.assertEqual(normalize_symbol("09992.HK"), "9992.HK")
+        self.assertEqual(normalize_symbol("00700.HK"), "0700.HK")
+        self.assertEqual(normalize_symbol("00001.HK"), "0001.HK")
+
+    def test_hk_four_digit_code_unchanged(self):
+        self.assertEqual(normalize_symbol("0700.HK"), "0700.HK")
+        self.assertEqual(normalize_symbol("9992.HK"), "9992.HK")
+        self.assertEqual(normalize_symbol("80737.HK"), "80737.HK")
+
+    def test_hk_short_code_padded_to_four(self):
+        self.assertEqual(normalize_symbol("700.HK"), "0700.HK")
+
+    def test_hk_code_case_insensitive_suffix(self):
+        self.assertEqual(normalize_symbol("09992.hk"), "9992.HK")
+
+    def test_shanghai_sh_suffix_maps_to_yahoo_ss(self):
+        self.assertEqual(normalize_symbol("600519.sh"), "600519.SS")
+        self.assertEqual(normalize_symbol("600519.SS"), "600519.SS")
+
+
+@pytest.mark.unit
+class TestNoMarketDataError(unittest.TestCase):
+    def test_message_includes_resolution(self):
+        err = NoMarketDataError("XAUUSD+", "GC=F", "no rows")
+        self.assertIn("XAUUSD+", str(err))
+        self.assertIn("GC=F", str(err))
+        self.assertEqual(err.symbol, "XAUUSD+")
+        self.assertEqual(err.canonical, "GC=F")
+
+    def test_canonical_defaults_to_symbol(self):
+        err = NoMarketDataError("FOOBAR")
+        self.assertEqual(err.canonical, "FOOBAR")
+
+
+@pytest.mark.unit
+class TestIsYahooSafe(unittest.TestCase):
+    def test_accepts_structural_chars(self):
+        for sym in ("AAPL", "GC=F", "^GSPC", "BRK.B", "BTC-USD"):
+            self.assertTrue(is_yahoo_safe(sym))
+
+    def test_rejects_slash_and_space(self):
+        for sym in ("a/b", "AA PL", ""):
+            self.assertFalse(is_yahoo_safe(sym))
+
+
+@pytest.mark.unit
+class TestCryptoBase(unittest.TestCase):
+    def test_resolves_known_crypto_forms(self):
+        for raw in ("BTC-USD", "BTCUSD", "btc-usdt", "BTC-USDC", "BTCUSD+"):
+            self.assertEqual(crypto_base(raw), "BTC")
+        self.assertEqual(crypto_base("ETH-USD"), "ETH")
+        self.assertEqual(crypto_base("sol-usd"), "SOL")
+
+    def test_non_crypto_returns_none(self):
+        # Plain equities, class shares, and real tickers that alias elsewhere
+        # (GOLD -> gold future on the Yahoo path) must NOT read as crypto.
+        for raw in ("AAPL", "BRK-B", "GOLD", "XYZ-USD", "EURUSD", "", None):
+            self.assertIsNone(crypto_base(raw))
+
+    def test_agrees_with_normalize_symbol(self):
+        # crypto_base is the shared primitive behind the -USD normalization.
+        self.assertEqual(normalize_symbol("BTCUSD"), "BTC-USD")
+        self.assertEqual(crypto_base("BTCUSD"), "BTC")
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_temperature_config.py

@@ -0,0 +1,83 @@
+"""Tests for the configurable sampling temperature (#178/#168).
+
+Temperature is a cross-provider knob: when set it must reach the underlying
+chat client; when unset the provider keeps its own default.
+"""
+
+import importlib
+
+import pytest
+
+from tradingagents.llm_clients.factory import create_llm_client
+
+
+@pytest.mark.unit
+class TestTemperatureForwarding:
+    @pytest.mark.parametrize(
+        "provider,model",
+        [
+            # gpt-4.1 is intentionally a non-reasoning model: the GPT-5 family
+            # are reasoning models and correctly drop temperature (see
+            # test_openai_reasoning_effort), so forwarding is tested on gpt-4.1.
+            ("openai", "gpt-4.1"),
+            ("anthropic", "claude-sonnet-5"),
+            ("google", "gemini-3.5-flash"),
+            ("deepseek", "deepseek-chat"),
+        ],
+    )
+    def test_temperature_reaches_client_when_set(self, provider, model):
+        llm = create_llm_client(
+            provider=provider, model=model, temperature=0.0, api_key="placeholder"
+        ).get_llm()
+        assert llm.temperature == 0.0
+
+    def test_temperature_omitted_leaves_provider_default(self):
+        # Not passing temperature must not force it to a value.
+        llm = create_llm_client(
+            provider="openai", model="gpt-4.1", api_key="placeholder"
+        ).get_llm()
+        # langchain's default is unset/None, not 0.0
+        assert llm.temperature is None
+
+
+@pytest.mark.unit
+class TestTemperatureEnvOverlay:
+    def test_env_sets_temperature(self, monkeypatch):
+        import tradingagents.default_config as dc
+        monkeypatch.setenv("TRADINGAGENTS_TEMPERATURE", "0.2")
+        importlib.reload(dc)
+        # Stored on config (string from env is fine; consumed via float()).
+        assert dc.DEFAULT_CONFIG["temperature"] in ("0.2", 0.2)
+        assert float(dc.DEFAULT_CONFIG["temperature"]) == 0.2
+        monkeypatch.delenv("TRADINGAGENTS_TEMPERATURE", raising=False)
+        importlib.reload(dc)
+
+    def test_default_temperature_is_none(self, monkeypatch):
+        import tradingagents.default_config as dc
+        monkeypatch.delenv("TRADINGAGENTS_TEMPERATURE", raising=False)
+        importlib.reload(dc)
+        assert dc.DEFAULT_CONFIG["temperature"] is None
+
+
+@pytest.mark.unit
+class TestProviderKwargsTemperature:
+    """_get_provider_kwargs float-coerces and forwards temperature, or omits it."""
+
+    def _kwargs_for(self, temperature):
+        from tradingagents.graph.trading_graph import TradingAgentsGraph
+        # Call the method without constructing the full graph.
+        graph = TradingAgentsGraph.__new__(TradingAgentsGraph)
+        graph.config = {"llm_provider": "openai", "temperature": temperature}
+        return TradingAgentsGraph._get_provider_kwargs(graph)
+
+    def test_float_string_coerced(self):
+        assert self._kwargs_for("0.3")["temperature"] == 0.3
+
+    def test_float_passthrough(self):
+        assert self._kwargs_for(0.0)["temperature"] == 0.0
+
+    def test_none_omitted(self):
+        assert "temperature" not in self._kwargs_for(None)
+
+    def test_empty_string_omitted(self):
+        assert "temperature" not in self._kwargs_for("")

tests/test_ticker_symbol_handling.py

@@ -0,0 +1,29 @@
+import unittest
+
+import pytest
+
+from cli.utils import normalize_ticker_symbol
+from tradingagents.agents.utils.agent_utils import build_instrument_context
+
+
+@pytest.mark.unit
+class TickerSymbolHandlingTests(unittest.TestCase):
+    def test_normalize_ticker_symbol_preserves_exchange_suffix(self):
+        self.assertEqual(normalize_ticker_symbol(" cnc.to "), "CNC.TO")
+
+    def test_build_instrument_context_mentions_exact_symbol(self):
+        context = build_instrument_context("7203.T")
+        self.assertIn("7203.T", context)
+        self.assertIn("exchange suffix", context)
+
+    def test_single_get_ticker_no_shadow(self):
+        # Regression: cli/main.py had a duplicate get_ticker with an empty
+        # questionary prompt (rendered as a bare "?") that shadowed the
+        # descriptive one in cli/utils. Keep a single canonical definition.
+        import cli.main
+        import cli.utils
+        self.assertIs(cli.main.get_ticker, cli.utils.get_ticker)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_tool_date_enforcement.py

@@ -0,0 +1,140 @@
+"""Dated tools take the analysis date from graph state, not from the model.
+
+Every point-in-time guard behind a tool trusts the date it is given. A model that
+omits the date, or passes today's instead of the analysis date, would otherwise
+walk past them. The run's trade_date is injected from state and hidden from the
+model-visible schema.
+"""
+
+from __future__ import annotations
+
+from unittest import mock
+
+import pytest
+from langchain_core.messages import AIMessage
+from langgraph.graph import END, START, MessagesState, StateGraph
+from langgraph.prebuilt import ToolNode
+
+from tradingagents.agents.utils import (
+    core_stock_tools,
+    fundamental_data_tools,
+    macro_data_tools,
+    market_data_validation_tools,
+    news_data_tools,
+    technical_indicators_tools,
+)
+from tradingagents.dataflows.date_window import as_of, as_of_window
+
+TRADE_DATE = "2026-08-14"
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("requested, expected", [
+    ("2026-09-14", TRADE_DATE),     # later than the run: clamped
+    ("2026-08-01", "2026-08-01"),   # earlier: narrows, allowed
+    (None, TRADE_DATE),             # omitted
+    ("Sept 1", TRADE_DATE),         # unparseable
+    ("", TRADE_DATE),
+])
+def test_as_of_takes_the_earlier_date(requested, expected):
+    assert as_of(requested, TRADE_DATE) == expected
+
+
+@pytest.mark.unit
+def test_as_of_without_a_trade_date_passes_the_request_through():
+    assert as_of("2026-09-14", "") == "2026-09-14"
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("start, end, expected", [
+    ("2026-08-01", "2026-09-14", ("2026-08-01", TRADE_DATE)),  # end clamped
+    ("2026-08-01", "2026-08-10", ("2026-08-01", "2026-08-10")),  # inside: unchanged
+    ("2026-09-01", "2026-09-08", ("2026-08-07", TRADE_DATE)),  # wholly later: span kept, moved back
+])
+def test_as_of_window(start, end, expected):
+    assert as_of_window(start, end, TRADE_DATE) == expected
+
+
+DATED_TOOLS = [
+    core_stock_tools.get_stock_data,
+    fundamental_data_tools.get_fundamentals,
+    fundamental_data_tools.get_balance_sheet,
+    fundamental_data_tools.get_cashflow,
+    fundamental_data_tools.get_income_statement,
+    news_data_tools.get_news,
+    news_data_tools.get_global_news,
+    technical_indicators_tools.get_indicators,
+    macro_data_tools.get_macro_indicators,
+    market_data_validation_tools.get_verified_market_snapshot,
+]
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("tool", DATED_TOOLS, ids=lambda t: t.name)
+def test_trade_date_is_hidden_from_the_model(tool):
+    assert "trade_date" not in tool.tool_call_schema.model_json_schema()["properties"]
+
+
+class _State(MessagesState):
+    trade_date: str
+
+
+def _run(tool, args, module):
+    """Call the tool through a ToolNode in a graph carrying the run's trade_date."""
+    graph = StateGraph(_State)
+    graph.add_node("tools", ToolNode([tool]))
+    graph.add_edge(START, "tools")
+    graph.add_edge("tools", END)
+    with mock.patch.object(module, "route_to_vendor", return_value="ok") as routed:
+        graph.compile().invoke({
+            "messages": [AIMessage("", tool_calls=[{"name": tool.name, "args": args, "id": "1"}])],
+            "trade_date": TRADE_DATE,
+        })
+    return routed.call_args.args
+
+
+@pytest.mark.unit
+def test_statement_tool_with_omitted_date_uses_the_run_date():
+    args = _run(fundamental_data_tools.get_balance_sheet, {"ticker": "AAPL"}, fundamental_data_tools)
+    assert args[-1] == TRADE_DATE  # #1331: an omitted date no longer means unfiltered
+
+
+@pytest.mark.unit
+def test_future_curr_date_from_the_model_is_clamped():
+    args = _run(fundamental_data_tools.get_fundamentals,
+                {"ticker": "AAPL", "curr_date": "2026-09-14"}, fundamental_data_tools)
+    assert args == ("get_fundamentals", "AAPL", TRADE_DATE)
+
+
+@pytest.mark.unit
+def test_future_window_from_the_model_is_clamped():
+    args = _run(core_stock_tools.get_stock_data,
+                {"symbol": "AAPL", "start_date": "2026-08-01", "end_date": "2026-09-14"}, core_stock_tools)
+    assert args == ("get_stock_data", "AAPL", "2026-08-01", TRADE_DATE)
+
+
+@pytest.mark.unit
+def test_direct_call_without_state_is_unchanged():
+    with mock.patch.object(news_data_tools, "route_to_vendor", return_value="ok") as routed:
+        news_data_tools.get_news.func("AAPL", "2026-09-01", "2026-09-08")
+    assert routed.call_args.args == ("get_news", "AAPL", "2026-09-01", "2026-09-08")
+
+
+# --- the run date itself (#1319) -------------------------------------------------
+
+@pytest.mark.unit
+@pytest.mark.parametrize("bad", ["2026-9-10", "2026-09-10 00:00", "Sept 10", None])
+def test_propagate_rejects_a_non_canonical_date(bad):
+    from tradingagents.graph.trading_graph import TradingAgentsGraph
+
+    with pytest.raises(ValueError, match="YYYY-MM-DD"):
+        object.__new__(TradingAgentsGraph).propagate("AAPL", bad)
+
+
+@pytest.mark.unit
+def test_propagate_rejects_a_future_date(monkeypatch):
+    import tradingagents.graph.trading_graph as tg
+
+    monkeypatch.setattr(tg, "get_current_date", lambda: "2026-09-10")
+    with pytest.raises(ValueError, match="future"):
+        object.__new__(tg.TradingAgentsGraph).propagate("AAPL", "2026-09-11")

tests/test_undated_tools_as_of.py

@@ -0,0 +1,248 @@
+"""Insider filings and prediction-market odds are bounded by the run's trade date.
+
+Neither tool takes a date from the model, so the run's trade_date is injected from
+graph state. Insider filings carry dates and are filtered to it; Polymarket serves
+only live odds, so a historical run withholds them.
+"""
+
+from __future__ import annotations
+
+import json
+from unittest import mock
+
+import pandas as pd
+import pytest
+
+from tradingagents.agents.utils import news_data_tools, prediction_markets_tools
+from tradingagents.dataflows import alpha_vantage_news, polymarket, y_finance
+
+
+def _insider_frame(*dates):
+    return pd.DataFrame({
+        "Shares": [100] * len(dates),
+        "Text": [f"Sale at price {100 + i} per share." for i in range(len(dates))],
+        "Start Date": pd.to_datetime(list(dates)),
+    })
+
+
+def _yf_insider(frame, curr_date):
+    ticker = mock.Mock(insider_transactions=frame)
+    with mock.patch.object(y_finance.yf, "Ticker", return_value=ticker):
+        return y_finance.get_insider_transactions("AAPL", curr_date)
+
+
+@pytest.mark.unit
+def test_yfinance_insider_filings_after_the_date_are_dropped():
+    out = _yf_insider(_insider_frame("2026-09-08", "2025-06-02", "2025-05-30", "2025-01-10"), "2025-06-01")
+    assert "2026-09-08" not in out and "2025-06-02" not in out
+    assert "2025-05-30" in out and "2025-01-10" in out
+
+
+@pytest.mark.unit
+def test_yfinance_insider_date_before_coverage_is_unavailable_not_absent():
+    out = _yf_insider(_insider_frame("2026-09-08", "2025-06-02"), "2024-01-01")
+    assert "unavailable" in out and "No insider transactions reported" not in out
+    assert "2025-06-02" in out  # where coverage starts
+
+
+@pytest.mark.unit
+def test_yfinance_insider_without_a_date_is_unfiltered():
+    out = _yf_insider(_insider_frame("2026-09-08", "2025-01-10"), None)
+    assert "2026-09-08" in out and "2025-01-10" in out
+
+
+@pytest.mark.unit
+def test_alpha_vantage_insider_filings_after_the_date_are_dropped():
+    body = json.dumps({"data": [
+        {"transaction_date": "2026-09-08", "executive": "A"},
+        {"transaction_date": "2025-05-30", "executive": "B"},
+    ]})
+    with mock.patch.object(alpha_vantage_news, "_make_api_request", return_value=body):
+        out = json.loads(alpha_vantage_news.get_insider_transactions("AAPL", "2025-06-01"))
+    assert [t["executive"] for t in out["data"]] == ["B"]
+
+
+@pytest.mark.unit
+def test_polymarket_withholds_live_odds_from_a_historical_run():
+    with mock.patch.object(polymarket, "_request", side_effect=AssertionError("must not fetch")):
+        out = polymarket.get_prediction_markets("Fed rate cut", curr_date="2025-06-01")
+    assert "withheld" in out
+
+
+@pytest.mark.unit
+def test_polymarket_serves_a_current_run():
+    with mock.patch.object(polymarket, "_request", return_value={"events": []}) as req:
+        polymarket.get_prediction_markets("Fed rate cut", curr_date=polymarket.get_current_date())
+    req.assert_called_once()
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("tool", [news_data_tools.get_insider_transactions,
+                                  prediction_markets_tools.get_prediction_markets], ids=lambda t: t.name)
+def test_trade_date_is_injected_not_model_visible(tool):
+    assert "trade_date" in tool.func.__code__.co_varnames
+    props = tool.tool_call_schema.model_json_schema()["properties"]
+    assert "trade_date" not in props and "curr_date" not in props
+
+
+# --- the instrument's identity -------------------------------------------------
+
+@pytest.mark.unit
+def test_a_historical_run_is_told_the_identity_is_current(monkeypatch):
+    """The company name, sector and industry come from today's vendor profile.
+    They are usually right for a past date, but a company that renamed or was
+    reclassified since would read wrong, and every agent is told to anchor to
+    this identity, so the run has to know which date it describes."""
+    from tradingagents.agents.utils.agent_utils import build_instrument_context
+
+    identity = {"company_name": "Example Corp", "sector": "Technology",
+                "industry": "Software", "exchange": "NMS"}
+
+    historical = build_instrument_context("EXMP", "stock", identity, curr_date="2024-03-14")
+    assert "Example Corp" in historical
+    assert "2024-03-14" in historical and "today" in historical.lower()
+
+
+@pytest.mark.unit
+def test_a_current_run_is_not_cluttered_with_a_vintage_note(monkeypatch):
+    from tradingagents.agents.utils.agent_utils import build_instrument_context
+    from tradingagents.dataflows.utils import get_current_date
+
+    today = build_instrument_context("EXMP", "stock", {"company_name": "Example Corp"},
+                                     curr_date=get_current_date())
+    assert "Example Corp" in today
+    assert "resolved today" not in today.lower()
+
+
+@pytest.mark.unit
+def test_insider_rows_are_dated_by_the_trade_not_the_filing():
+    """yfinance reports the transaction date and carries no filing date. A trade
+    becomes public when the Form 4 is filed, up to two business days later, so a
+    run must not be told these rows were public on their transaction date."""
+    import pandas as pd
+
+    from tradingagents.dataflows import y_finance
+
+    frame = pd.DataFrame({
+        "Shares": [100, 200],
+        "Text": ["Sale at price 10.00 per share.", "Sale at price 11.00 per share."],
+        "Start Date": pd.to_datetime(["2026-05-01", "2026-05-20"]),
+    })
+    ticker = mock.Mock(insider_transactions=frame)
+    with mock.patch.object(y_finance.yf, "Ticker", return_value=ticker):
+        out = y_finance.get_insider_transactions("AAPL", "2026-05-10")
+
+    assert "2026-05-01" in out and "2026-05-20" not in out   # still bounded by the date
+    assert "transaction date" in out.lower()                  # and says what the date means
+    assert "filed" in out.lower()                             # and that filing comes later
+
+
+@pytest.mark.unit
+def test_an_indicator_that_could_not_be_read_is_not_shown_as_a_blank_value():
+    """The per-day fallback returned an empty string for a failed read, so the
+    table rendered a row per day with nothing after the colon: an analyst reads
+    that as "no value on that day" rather than "could not be obtained"."""
+    from tradingagents.dataflows import y_finance
+    from tradingagents.dataflows.errors import VendorError
+
+    with mock.patch.object(y_finance.StockstatsUtils, "get_stock_stats",
+                           side_effect=RuntimeError("cache parse failed")), \
+            pytest.raises(VendorError):
+        y_finance.get_stockstats_indicator("AAPL", "rsi", "2026-05-08")
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("func, args", [
+    # A past date withholds the live profile before any request, so the
+    # fundamentals case is exercised on the date it does fetch.
+    ("get_fundamentals", ("AAPL", None)),
+    ("get_balance_sheet", ("AAPL", "annual", "2026-09-01")),
+    ("get_cashflow", ("AAPL", "annual", "2026-09-01")),
+    ("get_income_statement", ("AAPL", "annual", "2026-09-01")),
+    ("get_insider_transactions", ("AAPL", "2026-09-01")),
+])
+def test_a_yfinance_failure_is_a_vendor_error_not_a_report(func, args):
+    """Returning the failure as text makes the router count it as an answer, so
+    the chain stops and the analyst reads the error message as if it were data.
+    yfinance serves the default path, so this is the one that matters most."""
+    from tradingagents.dataflows import y_finance
+    from tradingagents.dataflows.errors import VendorError
+
+    with mock.patch.object(y_finance.yf, "Ticker", side_effect=RuntimeError("yahoo hiccup")), \
+            pytest.raises(VendorError):
+        getattr(y_finance, func)(*args)
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize("func, args", [
+    ("get_news_yfinance", ("AAPL", "2026-08-25", "2026-09-01")),
+    ("get_global_news_yfinance", ("2026-09-01", 7, 5)),
+])
+def test_a_yfinance_news_failure_is_a_vendor_error_not_a_report(func, args):
+    from tradingagents.dataflows import yfinance_news
+    from tradingagents.dataflows.errors import VendorError
+
+    target = "Ticker" if "global" not in func else "Search"
+    with mock.patch.object(yfinance_news.yf, target, side_effect=RuntimeError("yahoo hiccup")), \
+            pytest.raises(VendorError):
+        getattr(yfinance_news, func)(*args)
+
+
+@pytest.mark.unit
+def test_an_unreachable_vendor_is_not_reported_as_a_missing_symbol(monkeypatch):
+    """yfinance returns an empty frame when it cannot reach Yahoo, with no
+    exception. Reporting that as "no data for AAPL" tells the analyst the
+    company has no balance sheet, when the truth is we could not ask."""
+    import pandas as pd
+
+    from tradingagents.dataflows import stockstats_utils, y_finance
+    from tradingagents.dataflows.errors import NoMarketDataError, VendorRateLimitError
+
+    empty = mock.Mock(quarterly_balance_sheet=pd.DataFrame(), balance_sheet=pd.DataFrame())
+    monkeypatch.setattr(y_finance.yf, "Ticker", lambda s: empty)
+
+    monkeypatch.setattr(stockstats_utils, "vendor_reachable", lambda url: False)
+    with pytest.raises(VendorRateLimitError, match="unreachable"):
+        y_finance.get_balance_sheet("AAPL", "annual", "2026-09-01")
+
+    monkeypatch.setattr(stockstats_utils, "vendor_reachable", lambda url: True)
+    with pytest.raises(NoMarketDataError):
+        y_finance.get_balance_sheet("AAPL", "annual", "2026-09-01")
+
+
+@pytest.mark.unit
+def test_every_vendor_unavailable_says_so_rather_than_crashing(monkeypatch):
+    """A throttled or unreachable chain used to raise RuntimeError('No available
+    vendor'), which ends the run, and never said the vendor was the problem."""
+    from tradingagents.dataflows import interface
+    from tradingagents.dataflows.errors import VendorRateLimitError
+
+    def _down(*a, **k):
+        raise VendorRateLimitError("Yahoo Finance is unreachable")
+
+    monkeypatch.setitem(interface.VENDOR_METHODS["get_balance_sheet"], "yfinance", _down)
+
+    out = interface.route_to_vendor("get_balance_sheet", "AAPL", "annual", "2026-09-01")
+
+    assert "unavailable" in out.lower() and "unreachable" in out.lower()
+    assert "delisted" not in out.lower()  # not a claim about the symbol
+
+
+@pytest.mark.unit
+def test_the_price_path_also_tells_an_outage_from_an_unknown_symbol(monkeypatch):
+    """Prices are the most-used path, so an outage there must not read as a
+    delisted symbol either."""
+    import pandas as pd
+
+    from tradingagents.dataflows import stockstats_utils, y_finance
+    from tradingagents.dataflows.errors import NoMarketDataError, VendorRateLimitError
+
+    monkeypatch.setattr(y_finance.yf, "Ticker", lambda s: mock.Mock(history=lambda **k: pd.DataFrame()))
+
+    monkeypatch.setattr(stockstats_utils, "vendor_reachable", lambda url: False)
+    with pytest.raises(VendorRateLimitError, match="unreachable"):
+        y_finance.get_YFin_data_online("AAPL", "2026-09-01", "2026-09-10")
+
+    monkeypatch.setattr(stockstats_utils, "vendor_reachable", lambda url: True)
+    with pytest.raises(NoMarketDataError):
+        y_finance.get_YFin_data_online("AAPL", "2026-09-01", "2026-09-10")

tests/test_vendor_errors.py

@@ -0,0 +1,105 @@
+"""The vendor data-error hierarchy: every "vendor couldn't return usable data"
+condition derives from VendorError, so the router catches base types and any
+vendor slots in without new handling.
+"""
+import copy
+import unittest
+from unittest import mock
+
+import pytest
+
+import tradingagents.dataflows.config as config_module
+import tradingagents.default_config as default_config
+from tradingagents.dataflows import interface
+from tradingagents.dataflows.alpha_vantage_common import (
+    AlphaVantageNotConfiguredError,
+    AlphaVantageRateLimitError,
+)
+from tradingagents.dataflows.config import set_config
+from tradingagents.dataflows.errors import (
+    NoMarketDataError,
+    VendorError,
+    VendorNotConfiguredError,
+    VendorRateLimitError,
+)
+from tradingagents.dataflows.fred import FredNotConfiguredError
+
+
+@pytest.mark.unit
+class HierarchyTests(unittest.TestCase):
+    def test_all_conditions_derive_from_vendor_error(self):
+        for cls in (NoMarketDataError, VendorRateLimitError, VendorNotConfiguredError):
+            self.assertTrue(issubclass(cls, VendorError))
+
+    def test_not_configured_is_still_a_value_error(self):
+        # Back-compat: existing `except ValueError` callers keep working.
+        self.assertTrue(issubclass(VendorNotConfiguredError, ValueError))
+
+    def test_vendor_named_errors_subclass_the_generic_bases(self):
+        self.assertTrue(issubclass(AlphaVantageRateLimitError, VendorRateLimitError))
+        self.assertTrue(issubclass(AlphaVantageNotConfiguredError, VendorNotConfiguredError))
+        self.assertTrue(issubclass(FredNotConfiguredError, VendorNotConfiguredError))
+        # ... and therefore still ValueErrors
+        self.assertTrue(issubclass(FredNotConfiguredError, ValueError))
+
+    def test_symbol_utils_reexports_no_market_data_error(self):
+        from tradingagents.dataflows.symbol_utils import (
+            NoMarketDataError as ReExported,
+        )
+        self.assertIs(ReExported, NoMarketDataError)
+
+
+@pytest.mark.unit
+class RouterHandlesBaseTypesTests(unittest.TestCase):
+    def setUp(self):
+        config_module._config = copy.deepcopy(default_config.DEFAULT_CONFIG)
+
+    def tearDown(self):
+        config_module._config = copy.deepcopy(default_config.DEFAULT_CONFIG)
+
+    def test_rate_limit_subclass_caught_by_base(self):
+        # A vendor-named rate-limit error skips to the next vendor in the chain.
+        set_config({"data_vendors": {"core_stock_apis": "alpha_vantage,yfinance"}})
+
+        def _throttled(*a, **k):
+            raise AlphaVantageRateLimitError("slow down")
+
+        with mock.patch.dict(
+            interface.VENDOR_METHODS,
+            {"get_stock_data": {"alpha_vantage": _throttled, "yfinance": lambda *a, **k: "YF"}},
+            clear=False,
+        ):
+            out = interface.route_to_vendor("get_stock_data", "AAPL", "2026-01-01", "2026-01-10")
+        self.assertEqual(out, "YF")
+
+    def test_not_configured_falls_through_to_next_vendor(self):
+        set_config({"data_vendors": {"core_stock_apis": "alpha_vantage,yfinance"}})
+
+        def _unconfigured(*a, **k):
+            raise AlphaVantageNotConfiguredError("no key")
+
+        with mock.patch.dict(
+            interface.VENDOR_METHODS,
+            {"get_stock_data": {"alpha_vantage": _unconfigured, "yfinance": lambda *a, **k: "YF"}},
+            clear=False,
+        ):
+            out = interface.route_to_vendor("get_stock_data", "AAPL", "2026-01-01", "2026-01-10")
+        self.assertEqual(out, "YF")
+
+    def test_sole_unconfigured_vendor_surfaces_the_error(self):
+        # With no fallback, the not-configured condition must surface (not vanish).
+        set_config({"data_vendors": {"core_stock_apis": "alpha_vantage"}})
+
+        def _unconfigured(*a, **k):
+            raise AlphaVantageNotConfiguredError("no key")
+
+        with mock.patch.dict(
+            interface.VENDOR_METHODS,
+            {"get_stock_data": {"alpha_vantage": _unconfigured}},
+            clear=False,
+        ), self.assertRaises(AlphaVantageNotConfiguredError):
+            interface.route_to_vendor("get_stock_data", "AAPL", "2026-01-01", "2026-01-10")
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_vendor_routing.py

@@ -0,0 +1,123 @@
+"""Vendor router must respect the configured chain and never silently hide a
+broken primary.
+
+Regressions for #988 (explicit single-vendor config still fell back to others),
+#289 (fallback ran for unchosen vendors), and #989 (serious primary failures
+were swallowed without a trace).
+"""
+import copy
+import unittest
+from unittest import mock
+
+import pytest
+
+import tradingagents.dataflows.config as config_module
+import tradingagents.default_config as default_config
+from tradingagents.dataflows import interface
+from tradingagents.dataflows.config import set_config
+from tradingagents.dataflows.symbol_utils import NoMarketDataError
+
+
+def _reset_config():
+    # Hard reset: set_config() merges, so empty DEFAULT dicts (e.g. tool_vendors)
+    # don't clear keys leaked by other tests. Replace the global outright.
+    config_module._config = copy.deepcopy(default_config.DEFAULT_CONFIG)
+
+
+def _no_data(symbol, *a, **k):
+    raise NoMarketDataError(symbol, symbol, "no rows")
+
+
+def _returns(value):
+    def impl(symbol, *a, **k):
+        return value
+    return impl
+
+
+def _raises(exc):
+    def impl(symbol, *a, **k):
+        raise exc
+    return impl
+
+
+@pytest.mark.unit
+class VendorRoutingTests(unittest.TestCase):
+    def setUp(self):
+        _reset_config()
+
+    def tearDown(self):
+        _reset_config()
+
+    def _route(self, vendors_for_get_stock_data):
+        return mock.patch.dict(
+            interface.VENDOR_METHODS,
+            {"get_stock_data": vendors_for_get_stock_data},
+            clear=False,
+        )
+
+    def test_explicit_single_vendor_does_not_fall_back(self):
+        # #988: with yfinance pinned, a healthy alpha_vantage must NOT be used.
+        set_config({"data_vendors": {"core_stock_apis": "yfinance"}})
+        av = mock.Mock(side_effect=_returns("AV_DATA"))
+        with self._route({"yfinance": _no_data, "alpha_vantage": av}):
+            result = interface.route_to_vendor("get_stock_data", "FAKE", "2026-01-01", "2026-01-10")
+        self.assertIn("NO_DATA_AVAILABLE", result)
+        av.assert_not_called()  # the unchosen vendor was never tried
+
+    def test_explicit_multi_vendor_falls_back_within_chain(self):
+        # Listing both vendors opts in to ordered fallback.
+        set_config({"data_vendors": {"core_stock_apis": "yfinance,alpha_vantage"}})
+        with self._route({"yfinance": _no_data, "alpha_vantage": _returns("AV_DATA")}):
+            result = interface.route_to_vendor("get_stock_data", "AAPL", "2026-01-01", "2026-01-10")
+        self.assertEqual(result, "AV_DATA")
+
+    def test_primary_error_is_logged_not_masked(self):
+        # #989: primary errors + fallback no-data -> NO_DATA, but the failure
+        # must be visible in logs (broken primary not hidden).
+        set_config({"data_vendors": {"core_stock_apis": "yfinance,alpha_vantage"}})
+        with self._route({"yfinance": _raises(ValueError("boom")), "alpha_vantage": _no_data}), \
+                self.assertLogs("tradingagents.dataflows.interface", level="WARNING") as cm:
+            result = interface.route_to_vendor("get_stock_data", "AAPL", "2026-01-01", "2026-01-10")
+        self.assertIn("NO_DATA_AVAILABLE", result)
+        joined = "\n".join(cm.output)
+        self.assertIn("boom", joined)            # the real error surfaced in logs
+        self.assertIn("yfinance", joined)
+
+    def test_unknown_configured_vendor_raises(self):
+        set_config({"data_vendors": {"core_stock_apis": "bogus_vendor"}})
+        with self.assertRaises(ValueError) as ctx:
+            interface.route_to_vendor("get_stock_data", "AAPL", "2026-01-01", "2026-01-10")
+        self.assertIn("bogus_vendor", str(ctx.exception))
+
+    def test_default_sentinel_uses_all_vendors(self):
+        # No explicit choice ("default") keeps the resilient full-chain behavior.
+        set_config({"data_vendors": {"core_stock_apis": "default"}})
+        with self._route({"yfinance": _no_data, "alpha_vantage": _returns("AV_DATA")}):
+            result = interface.route_to_vendor("get_stock_data", "AAPL", "2026-01-01", "2026-01-10")
+        self.assertEqual(result, "AV_DATA")
+
+    def _route_method(self, method, vendors):
+        return mock.patch.dict(interface.VENDOR_METHODS, {method: vendors}, clear=False)
+
+    def test_optional_category_degrades_instead_of_raising(self):
+        # An optional enrichment vendor (FRED macro) that raises must NOT abort
+        # the run — the router returns a sentinel so the analysis proceeds.
+        set_config({"data_vendors": {"macro_data": "fred"}})
+        with self._route_method(
+            "get_macro_indicators", {"fred": _raises(ValueError("FRED 400: bad series"))}
+        ):
+            result = interface.route_to_vendor("get_macro_indicators", "cpi", "2026-01-01")
+        self.assertIn("DATA_UNAVAILABLE", result)
+        self.assertIn("macro_data", result)
+
+    def test_core_category_still_raises_on_error(self):
+        # A core category (single configured vendor) propagates the error so a
+        # broken primary is loud, not silently degraded.
+        set_config({"data_vendors": {"core_stock_apis": "yfinance"}})
+        with self._route({"yfinance": _raises(ValueError("boom"))}), \
+                self.assertRaises(ValueError):
+            interface.route_to_vendor("get_stock_data", "AAPL", "2026-01-01", "2026-01-10")
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_yfinance_stale_ohlcv_guard.py

@@ -0,0 +1,113 @@
+"""Stale OHLCV guard (#1021): a vendor returning a year-old partial frame must
+be rejected, not fed into the report as if it were current.
+
+The guard raises NoMarketDataError with a stale-specific detail, so the router's
+existing try-next-vendor + single-sentinel handling applies and the sentinel
+surfaces the reason.
+"""
+import copy
+import unittest
+from unittest import mock
+
+import pandas as pd
+import pytest
+
+import tradingagents.dataflows.config as config_module
+import tradingagents.dataflows.y_finance as y_finance
+import tradingagents.default_config as default_config
+from tradingagents.dataflows import interface
+from tradingagents.dataflows.config import set_config
+from tradingagents.dataflows.stockstats_utils import _assert_ohlcv_not_stale
+from tradingagents.dataflows.symbol_utils import NoMarketDataError
+
+
+def _frame(date):
+    return pd.DataFrame(
+        {
+            "Date": [pd.Timestamp(date)],
+            "Open": [330.0],
+            "High": [332.0],
+            "Low": [328.0],
+            "Close": [330.58],
+            "Volume": [1_000_000],
+        }
+    )
+
+
+@pytest.mark.unit
+class StaleGuardUnitTests(unittest.TestCase):
+    def test_recent_prior_trading_day_is_accepted(self):
+        # 1 day before curr_date — well within the freshness window.
+        _assert_ohlcv_not_stale(_frame("2026-06-10"), "2026-06-11", "CB")
+
+    def test_year_old_row_is_rejected_with_detail(self):
+        with self.assertRaises(NoMarketDataError) as ctx:
+            _assert_ohlcv_not_stale(_frame("2025-06-11"), "2026-06-11", "CB", "CB")
+        msg = str(ctx.exception)
+        self.assertIn("2025-06-11", msg)
+        self.assertIn("2026-06-11", msg)
+        self.assertIn("stale", msg)
+
+    def test_empty_frame_is_left_to_caller(self):
+        # Empty is a no-data condition handled elsewhere, not a staleness one.
+        _assert_ohlcv_not_stale(
+            pd.DataFrame(columns=["Date", "Close"]), "2026-06-11", "X"
+        )
+
+    def test_long_holiday_gap_within_threshold_is_accepted(self):
+        _assert_ohlcv_not_stale(_frame("2026-06-02"), "2026-06-11", "X")  # 9 days
+
+
+@pytest.mark.unit
+class StaleGuardPropagationTests(unittest.TestCase):
+    def test_get_yfin_data_online_raises_on_stale_frame(self):
+        stale = pd.DataFrame(
+            {
+                "Open": [280.0], "High": [286.0], "Low": [278.0],
+                "Close": [284.45], "Volume": [1_000_000],
+            },
+            index=pd.DatetimeIndex([pd.Timestamp("2025-06-11")], name="Date"),
+        )
+
+        class DummyTicker:
+            def __init__(self, symbol):
+                pass
+
+            def history(self, start, end):
+                return stale
+
+        with mock.patch.object(y_finance.yf, "Ticker", DummyTicker), \
+                self.assertRaises(NoMarketDataError):
+            y_finance.get_YFin_data_online("CB", "2026-06-01", "2026-06-11")
+
+
+@pytest.mark.unit
+class StaleGuardRoutingTests(unittest.TestCase):
+    def setUp(self):
+        config_module._config = copy.deepcopy(default_config.DEFAULT_CONFIG)
+
+    def tearDown(self):
+        config_module._config = copy.deepcopy(default_config.DEFAULT_CONFIG)
+
+    def test_router_sentinel_surfaces_stale_reason(self):
+        set_config({"data_vendors": {"core_stock_apis": "yfinance"}})
+
+        def _stale(symbol, *a, **k):
+            raise NoMarketDataError(
+                symbol, symbol, "latest row is 2025-06-11, 365 days before ... (stale)"
+            )
+
+        with mock.patch.dict(
+            interface.VENDOR_METHODS,
+            {"get_stock_data": {"yfinance": _stale}},
+            clear=False,
+        ):
+            out = interface.route_to_vendor(
+                "get_stock_data", "CB", "2026-06-01", "2026-06-11"
+            )
+        self.assertIn("NO_DATA_AVAILABLE", out)
+        self.assertIn("stale", out)  # the typed detail is surfaced to the agent
+
+
+if __name__ == "__main__":
+    unittest.main()

tradingagents/__init__.py

@@ -0,0 +1,37 @@
+import contextlib
+import warnings
+
+# Load .env files at package import so DEFAULT_CONFIG's env-var overlay
+# (and every llm_clients consumer) sees the user's keys regardless of
+# which entry point started the process. find_dotenv(usecwd=True) walks
+# from the CWD, so the installed `tradingagents` console script picks up
+# the project's .env instead of stepping up from site-packages.
+# load_dotenv defaults to override=False, so it never clobbers values
+# the caller has already exported.
+try:
+    from dotenv import find_dotenv, load_dotenv
+
+    load_dotenv(find_dotenv(usecwd=True))
+    load_dotenv(find_dotenv(".env.enterprise", usecwd=True), override=False)
+except ImportError:
+    pass
+
+# langchain-core 1.3.3 calls surface_langchain_deprecation_warnings() in
+# its own __init__, which prepends default-action filters for its
+# subclassed warning categories. To suppress a specific warning we must
+# install our filter AFTER langchain-core has installed its own, so import
+# it first. The package is a guaranteed transitive dep via langgraph.
+with contextlib.suppress(ImportError):
+    import langchain_core  # noqa: F401
+
+# langgraph-checkpoint 4.0.3 calls Reviver() at module load without an
+# explicit allowed_objects, which triggers a noisy pending-deprecation
+# warning from langchain-core 1.3.3 on every interpreter start. The fix
+# is already merged upstream (langchain-ai/langgraph#7743, 2026-05-08)
+# and will arrive in the next langgraph-checkpoint release. Remove this
+# block (and the langchain_core preload above) when we bump past it.
+warnings.filterwarnings(
+    "ignore",
+    message=r"The default value of `allowed_objects`.*",
+    category=PendingDeprecationWarning,
+)

tradingagents/agents/__init__.py

@@ -1,26 +1,22 @@
-from .utils.agent_utils import create_msg_delete
-from .utils.agent_states import AgentState, InvestDebateState, RiskDebateState
-from .utils.memory import FinancialSituationMemory
-
 from .analysts.fundamentals_analyst import create_fundamentals_analyst
 from .analysts.market_analyst import create_market_analyst
 from .analysts.news_analyst import create_news_analyst
-from .analysts.social_media_analyst import create_social_media_analyst
+from .analysts.sentiment_analyst import (
-
+    create_sentiment_analyst,
+    create_social_media_analyst,  # deprecated alias kept for back-compat
+)
+from .managers.portfolio_manager import create_portfolio_manager
+from .managers.research_manager import create_research_manager
 from .researchers.bear_researcher import create_bear_researcher
 from .researchers.bull_researcher import create_bull_researcher
-
 from .risk_mgmt.aggressive_debator import create_aggressive_debator
 from .risk_mgmt.conservative_debator import create_conservative_debator
 from .risk_mgmt.neutral_debator import create_neutral_debator
-
-from .managers.research_manager import create_research_manager
-from .managers.risk_manager import create_risk_manager
-
 from .trader.trader import create_trader
+from .utils.agent_states import AgentState, InvestDebateState, RiskDebateState
+from .utils.agent_utils import create_msg_delete
 
 __all__ = [
-    "FinancialSituationMemory",
     "AgentState",
     "create_msg_delete",
     "InvestDebateState",
@@ -33,8 +29,9 @@ __all__ = [
     "create_neutral_debator",
     "create_news_analyst",
     "create_aggressive_debator",
-    "create_risk_manager",
+    "create_portfolio_manager",
     "create_conservative_debator",
-    "create_social_media_analyst",
+    "create_sentiment_analyst",
+    "create_social_media_analyst",  # deprecated; will be removed in a future version
     "create_trader",
 ]

tradingagents/agents/analysts/fundamentals_analyst.py

@@ -1,15 +1,19 @@
 from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
-import time
+
-import json
+from tradingagents.agents.utils.agent_utils import (
-from tradingagents.agents.utils.agent_utils import get_fundamentals, get_balance_sheet, get_cashflow, get_income_statement, get_insider_transactions
+    get_balance_sheet,
-from tradingagents.dataflows.config import get_config
+    get_cashflow,
+    get_fundamentals,
+    get_income_statement,
+    get_instrument_context_from_state,
+    get_language_instruction,
+)
 
 
 def create_fundamentals_analyst(llm):
     def fundamentals_analyst_node(state):
         current_date = state["trade_date"]
-        ticker = state["company_of_interest"]
+        instrument_context = get_instrument_context_from_state(state)
-        company_name = state["company_of_interest"]
 
         tools = [
             get_fundamentals,
@@ -19,9 +23,10 @@ def create_fundamentals_analyst(llm):
         ]
 
         system_message = (
-            "You are a researcher tasked with analyzing fundamental information over the past week about a company. Please write a comprehensive report of the company's fundamental information such as financial documents, company profile, basic company financials, and company financial history to gain a full view of the company's fundamental information to inform traders. Make sure to include as much detail as possible. Do not simply state the trends are mixed, provide detailed and finegrained analysis and insights that may help traders make decisions."
+            "You are a researcher tasked with analyzing fundamental information over the past week about a company. Please write a comprehensive report of the company's fundamental information such as financial documents, company profile, basic company financials, and company financial history to gain a full view of the company's fundamental information to inform traders. Make sure to include as much detail as possible. Provide specific, actionable insights with supporting evidence to help traders make informed decisions."
             + " Make sure to append a Markdown table at the end of the report to organize key points in the report, organized and easy to read."
-            + " Use the available tools: `get_fundamentals` for comprehensive company analysis, `get_balance_sheet`, `get_cashflow`, and `get_income_statement` for specific financial statements.",
+            + " Use the available tools: `get_fundamentals` for comprehensive company analysis, `get_balance_sheet`, `get_cashflow`, and `get_income_statement` for specific financial statements."
+            + get_language_instruction()
         )
 
         prompt = ChatPromptTemplate.from_messages(
@@ -32,10 +37,10 @@ def create_fundamentals_analyst(llm):
                     " Use the provided tools to progress towards answering the question."
                     " If you are unable to fully answer, that's OK; another assistant with different tools"
                     " will help where you left off. Execute what you can to make progress."
-                    " If you or any other assistant has the FINAL TRANSACTION PROPOSAL: **BUY/HOLD/SELL** or deliverable,"
+                    " Report what your tools support; another agent decides the trade."
-                    " prefix your response with FINAL TRANSACTION PROPOSAL: **BUY/HOLD/SELL** so the team knows to stop."
+                    " You have access to the following tools: {tool_names}."
-                    " You have access to the following tools: {tool_names}.\n{system_message}"
+                    " Today's date is {current_date}; treat it as 'now' for all analysis and tool-call date ranges. {instrument_context}\n"
-                    "For your reference, the current date is {current_date}. The company we want to look at is {ticker}",
+                    "{system_message}",
                 ),
                 MessagesPlaceholder(variable_name="messages"),
             ]
@@ -44,7 +49,7 @@ def create_fundamentals_analyst(llm):
         prompt = prompt.partial(system_message=system_message)
         prompt = prompt.partial(tool_names=", ".join([tool.name for tool in tools]))
         prompt = prompt.partial(current_date=current_date)
-        prompt = prompt.partial(ticker=ticker)
+        prompt = prompt.partial(instrument_context=instrument_context)
 
         chain = prompt | llm.bind_tools(tools)
 

tradingagents/agents/analysts/market_analyst.py

@@ -1,20 +1,24 @@
 from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
-import time
+
-import json
+from tradingagents.agents.utils.agent_utils import (
-from tradingagents.agents.utils.agent_utils import get_stock_data, get_indicators
+    get_indicators,
-from tradingagents.dataflows.config import get_config
+    get_instrument_context_from_state,
+    get_language_instruction,
+    get_stock_data,
+    get_verified_market_snapshot,
+)
 
 
 def create_market_analyst(llm):
 
     def market_analyst_node(state):
         current_date = state["trade_date"]
-        ticker = state["company_of_interest"]
+        instrument_context = get_instrument_context_from_state(state)
-        company_name = state["company_of_interest"]
 
         tools = [
             get_stock_data,
             get_indicators,
+            get_verified_market_snapshot,
         ]
 
         system_message = (
@@ -42,8 +46,13 @@ Volatility Indicators:
 Volume-Based Indicators:
 - vwma: VWMA: A moving average weighted by volume. Usage: Confirm trends by integrating price action with volume data. Tips: Watch for skewed results from volume spikes; use in combination with other volume analyses.
 
-- Select indicators that provide diverse and complementary information. Avoid redundancy (e.g., do not select both rsi and stochrsi). Also briefly explain why they are suitable for the given market context. When you tool call, please use the exact name of the indicators provided above as they are defined parameters, otherwise your call will fail. Please make sure to call get_stock_data first to retrieve the CSV that is needed to generate indicators. Then use get_indicators with the specific indicator names. Write a very detailed and nuanced report of the trends you observe. Do not simply state the trends are mixed, provide detailed and finegrained analysis and insights that may help traders make decisions."""
+- Select indicators that provide diverse and complementary information. Avoid redundancy (e.g., do not select both rsi and stochrsi). Also briefly explain why they are suitable for the given market context. When you tool call, please use the exact name of the indicators provided above as they are defined parameters, otherwise your call will fail. Please make sure to call get_stock_data first to retrieve the CSV that is needed to generate indicators. Then use get_indicators with the specific indicator names.
+
+Before writing the final report, call get_verified_market_snapshot for this ticker and the current date, and treat it as the source of truth for any exact OHLCV, price-level, or indicator-value claim. If another tool's output conflicts with the verified snapshot, flag the discrepancy rather than inventing a reconciled number. Do not claim historical validation, support/resistance bounces, or exact percentage moves unless they are directly supported by tool output with concrete dates and prices.
+
+Write a very detailed and nuanced report of the trends you observe. Provide specific, actionable insights with supporting evidence to help traders make informed decisions."""
             + """ Make sure to append a Markdown table at the end of the report to organize key points in the report, organized and easy to read."""
+            + get_language_instruction()
         )
 
         prompt = ChatPromptTemplate.from_messages(
@@ -54,10 +63,10 @@ Volume-Based Indicators:
                     " Use the provided tools to progress towards answering the question."
                     " If you are unable to fully answer, that's OK; another assistant with different tools"
                     " will help where you left off. Execute what you can to make progress."
-                    " If you or any other assistant has the FINAL TRANSACTION PROPOSAL: **BUY/HOLD/SELL** or deliverable,"
+                    " Report what your tools support; another agent decides the trade."
-                    " prefix your response with FINAL TRANSACTION PROPOSAL: **BUY/HOLD/SELL** so the team knows to stop."
+                    " You have access to the following tools: {tool_names}."
-                    " You have access to the following tools: {tool_names}.\n{system_message}"
+                    " Today's date is {current_date}; treat it as 'now' for all analysis and tool-call date ranges. {instrument_context}\n"
-                    "For your reference, the current date is {current_date}. The company we want to look at is {ticker}",
+                    "{system_message}",
                 ),
                 MessagesPlaceholder(variable_name="messages"),
             ]
@@ -66,7 +75,7 @@ Volume-Based Indicators:
         prompt = prompt.partial(system_message=system_message)
         prompt = prompt.partial(tool_names=", ".join([tool.name for tool in tools]))
         prompt = prompt.partial(current_date=current_date)
-        prompt = prompt.partial(ticker=ticker)
+        prompt = prompt.partial(instrument_context=instrument_context)
 
         chain = prompt | llm.bind_tools(tools)
 

tradingagents/agents/analysts/news_analyst.py

@@ -1,23 +1,33 @@
 from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
-import time
+
-import json
+from tradingagents.agents.utils.agent_utils import (
-from tradingagents.agents.utils.agent_utils import get_news, get_global_news
+    get_global_news,
-from tradingagents.dataflows.config import get_config
+    get_instrument_context_from_state,
+    get_language_instruction,
+    get_macro_indicators,
+    get_news,
+    get_prediction_markets,
+)
 
 
 def create_news_analyst(llm):
     def news_analyst_node(state):
         current_date = state["trade_date"]
-        ticker = state["company_of_interest"]
+        asset_type = state.get("asset_type", "stock")
+        asset_label = "company" if asset_type == "stock" else "asset"
+        instrument_context = get_instrument_context_from_state(state)
 
         tools = [
             get_news,
             get_global_news,
+            get_macro_indicators,
+            get_prediction_markets,
         ]
 
         system_message = (
-            "You are a news researcher tasked with analyzing recent news and trends over the past week. Please write a comprehensive report of the current state of the world that is relevant for trading and macroeconomics. Use the available tools: get_news(query, start_date, end_date) for company-specific or targeted news searches, and get_global_news(curr_date, look_back_days, limit) for broader macroeconomic news. Do not simply state the trends are mixed, provide detailed and finegrained analysis and insights that may help traders make decisions."
+            f"You are a news researcher tasked with analyzing recent news and trends over the past week. Please write a comprehensive report of the current state of the world that is relevant for trading and macroeconomics. Use the available tools: get_news(ticker, start_date, end_date) for {asset_label}-specific news by ticker symbol, get_global_news(curr_date, look_back_days, limit) for broader macroeconomic news, get_macro_indicators(indicator, curr_date, look_back_days) to ground macro commentary in actual data from FRED (e.g. 'cpi', 'core_pce', 'unemployment', 'fed_funds_rate', '10y_treasury', 'yield_curve'), and get_prediction_markets(topic, limit) for live market-implied probabilities of forward-looking events (e.g. 'Fed rate cut', 'recession 2026', geopolitical or sector events). Provide specific, actionable insights with supporting evidence to help traders make informed decisions."
             + """ Make sure to append a Markdown table at the end of the report to organize key points in the report, organized and easy to read."""
+            + get_language_instruction()
         )
 
         prompt = ChatPromptTemplate.from_messages(
@@ -28,10 +38,10 @@ def create_news_analyst(llm):
                     " Use the provided tools to progress towards answering the question."
                     " If you are unable to fully answer, that's OK; another assistant with different tools"
                     " will help where you left off. Execute what you can to make progress."
-                    " If you or any other assistant has the FINAL TRANSACTION PROPOSAL: **BUY/HOLD/SELL** or deliverable,"
+                    " Report what your tools support; another agent decides the trade."
-                    " prefix your response with FINAL TRANSACTION PROPOSAL: **BUY/HOLD/SELL** so the team knows to stop."
+                    " You have access to the following tools: {tool_names}."
-                    " You have access to the following tools: {tool_names}.\n{system_message}"
+                    " Today's date is {current_date}; treat it as 'now' for all analysis and tool-call date ranges. {instrument_context}\n"
-                    "For your reference, the current date is {current_date}. We are looking at the company {ticker}",
+                    "{system_message}",
                 ),
                 MessagesPlaceholder(variable_name="messages"),
             ]
@@ -40,7 +50,7 @@ def create_news_analyst(llm):
         prompt = prompt.partial(system_message=system_message)
         prompt = prompt.partial(tool_names=", ".join([tool.name for tool in tools]))
         prompt = prompt.partial(current_date=current_date)
-        prompt = prompt.partial(ticker=ticker)
+        prompt = prompt.partial(instrument_context=instrument_context)
 
         chain = prompt | llm.bind_tools(tools)
         result = chain.invoke(state["messages"])

tradingagents/agents/analysts/sentiment_analyst.py

@@ -0,0 +1,217 @@
+"""Sentiment analyst — multi-source sentiment analysis for a target ticker.
+
+Previously named ``social_media_analyst``. Renamed and redesigned because
+the old version had a prompt that demanded social-media analysis but the
+only tool available was Yahoo Finance news — which led LLMs to fabricate
+Reddit/X/StockTwits content under prompt pressure (verified live).
+
+The redesigned agent pre-fetches three complementary data sources before
+the LLM is invoked and injects them into the prompt as structured blocks:
+
+  1. News headlines     — Yahoo Finance (institutional framing)
+  2. StockTwits messages — retail-trader posts indexed by cashtag, with
+                           user-labeled Bullish/Bearish sentiment tags
+  3. Reddit posts        — r/wallstreetbets, r/stocks, r/investing
+
+Each source is trimmed to the analysis window. These text feeds serve recent
+items and are not archived as of a past date, so sentiment inputs for a
+historical run are not guaranteed to be point-in-time.
+
+The agent does not use tool-calling; the data is in the prompt from
+turn 0. Output uses the structured-output pattern (json_schema for
+OpenAI/xAI, response_schema for Gemini, tool-use for Anthropic), falling
+back to free-text generation for providers that lack native support, so
+the sentiment header (band + score + confidence) is deterministic across
+runs and providers instead of free-form per-model prose.
+
+See: https://github.com/TauricResearch/TradingAgents/issues/557
+See: https://github.com/TauricResearch/TradingAgents/issues/796
+"""
+
+from datetime import datetime, timedelta
+
+from langchain_core.messages import AIMessage
+from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
+
+from tradingagents.agents.schemas import SentimentReport, render_sentiment_report
+from tradingagents.agents.utils.agent_utils import (
+    get_instrument_context_from_state,
+    get_language_instruction,
+    get_news,
+)
+from tradingagents.agents.utils.structured import (
+    NO_EXTERNAL_TOOLS,
+    bind_structured,
+    invoke_structured_or_freetext,
+)
+from tradingagents.dataflows.reddit import fetch_reddit_posts
+from tradingagents.dataflows.stocktwits import fetch_stocktwits_messages
+
+
+def _seven_days_back(trade_date: str) -> str:
+    return (datetime.strptime(trade_date, "%Y-%m-%d") - timedelta(days=7)).strftime("%Y-%m-%d")
+
+
+def create_sentiment_analyst(llm):
+    """Create a sentiment analyst node for the trading graph.
+
+    Pre-fetches news + StockTwits + Reddit data, injects them into the
+    prompt as structured blocks, and produces a deterministic sentiment
+    report via structured output (with a free-text fallback for providers
+    that do not support it).
+    """
+    structured_llm = bind_structured(llm, SentimentReport, "Sentiment Analyst")
+
+    def sentiment_analyst_node(state):
+        ticker = state["company_of_interest"]
+        end_date = state["trade_date"]
+        start_date = _seven_days_back(end_date)
+        instrument_context = get_instrument_context_from_state(state)
+
+        # Pre-fetch all three sources. Each fetcher degrades gracefully and
+        # returns a string (no exceptions surface from here), so the LLM
+        # always sees something — either real data or a clear placeholder.
+        news_block = get_news.func(ticker, start_date, end_date)
+        # Pass the analysis window so a historical run trims social posts to it
+        # instead of leaking today's chatter into a backtest (#1220).
+        stocktwits_block = fetch_stocktwits_messages(
+            ticker, limit=30, start_date=start_date, end_date=end_date
+        )
+        reddit_block = fetch_reddit_posts(ticker, start_date=start_date, end_date=end_date)
+
+        system_message = _build_system_message(
+            ticker=ticker,
+            start_date=start_date,
+            end_date=end_date,
+            news_block=news_block,
+            stocktwits_block=stocktwits_block,
+            reddit_block=reddit_block,
+        )
+
+        prompt = ChatPromptTemplate.from_messages(
+            [
+                (
+                    "system",
+                    "You are a helpful AI assistant, collaborating with other assistants."
+                    " Report what your tools support; another agent decides the trade."
+                    # No tool-calling here: the data is pre-fetched into the
+                    # prompt, so tool-range wording would only invite a
+                    # hallucinated tool call (#1130).
+                    " Today's date is {current_date}; treat it as 'now' for all analysis. {instrument_context}"
+                    " " + NO_EXTERNAL_TOOLS +
+                    "\n{system_message}",
+                ),
+                MessagesPlaceholder(variable_name="messages"),
+            ]
+        )
+
+        prompt = prompt.partial(system_message=system_message)
+        prompt = prompt.partial(current_date=end_date)
+        prompt = prompt.partial(instrument_context=instrument_context)
+
+        # Format the template into a concrete message list so the structured
+        # and free-text paths receive the same input. No bind_tools — the
+        # data is already in the prompt.
+        formatted_messages = prompt.format_messages(messages=state["messages"])
+
+        report_text = invoke_structured_or_freetext(
+            structured_llm,
+            llm,
+            formatted_messages,
+            render_sentiment_report,
+            "Sentiment Analyst",
+        )
+
+        return {
+            "messages": [AIMessage(content=report_text)],
+            "sentiment_report": report_text,
+        }
+
+    return sentiment_analyst_node
+
+
+def _build_system_message(
+    *,
+    ticker: str,
+    start_date: str,
+    end_date: str,
+    news_block: str,
+    stocktwits_block: str,
+    reddit_block: str,
+) -> str:
+    """Assemble the sentiment-analyst system message with structured data blocks."""
+    return f"""You are a financial market sentiment analyst. Your task is to produce a comprehensive sentiment report for {ticker} covering the period from {start_date} to {end_date}, drawing on three complementary data sources that have already been collected for you.
+
+## Data sources (pre-fetched, in this prompt)
+
+### News headlines — Yahoo Finance, past 7 days
+Institutional framing. Fact-driven, slower-moving signal.
+
+<start_of_news>
+{news_block}
+<end_of_news>
+
+### StockTwits messages — retail-trader social platform indexed by cashtag
+Fast-moving signal. Each message carries a user-labeled sentiment tag (Bullish / Bearish / no-label) plus the message body.
+
+<start_of_stocktwits>
+{stocktwits_block}
+<end_of_stocktwits>
+
+### Reddit posts — r/wallstreetbets, r/stocks, r/investing (past 7 days)
+Community discussion, without vote or comment counts. Subreddit character matters (r/wallstreetbets is often contrarian/exuberant; r/stocks more measured; r/investing longer-term).
+
+<start_of_reddit>
+{reddit_block}
+<end_of_reddit>
+
+## How to analyze this data (best practices)
+
+1. **Read the StockTwits Bullish/Bearish ratio as a leading retail-sentiment signal.** A 70/30 bullish/bearish split is moderately bullish; ≥90/10 may indicate over-extension and contrarian risk; 50/50 is uncertainty. Sample size matters — base rates on the actual message count, not percentages alone.
+
+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. **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.
+
+5. **Identify recurring narrative themes.** What topic keeps coming up across sources? That's the dominant narrative driving current sentiment.
+
+6. **Be honest about data limits.** If StockTwits returned only a handful of messages, or one or more sources returned an "<unavailable>" placeholder, the sentiment read is less robust — flag this explicitly in the `confidence` field and the narrative. If the sources are silent on a given subreddit, say so.
+
+7. **Identify catalysts and risks** that emerge across sources — news of upcoming earnings, product launches, competitive threats, macro headlines, etc.
+
+8. **Past sentiment is not predictive.** Frame your conclusions as signal for the trader to weigh alongside fundamentals and technicals, not as a price call.
+
+## Output fields
+
+Fill the following fields:
+
+- **overall_band**: Exactly one of Bullish / Mildly Bullish / Neutral / Mixed / Mildly Bearish / Bearish. Use Mixed when sources point in clearly different directions; Neutral only when all sources are genuinely silent.
+- **overall_score**: A number from 0 (maximally bearish) to 10 (maximally bullish); 5 is neutral. Keep it consistent with overall_band.
+- **confidence**: low / medium / high, based on data quality and sample size.
+- **narrative**: Full source-by-source breakdown, divergences, dominant narrative themes, catalysts and risks, and a markdown summary table of key sentiment signals (direction, source, supporting evidence).
+
+{get_language_instruction()}"""
+
+
+# ---------------------------------------------------------------------------
+# Backwards-compatibility shim
+# ---------------------------------------------------------------------------
+def create_social_media_analyst(llm):
+    """Deprecated alias for :func:`create_sentiment_analyst`.
+
+    Kept so existing code that imports ``create_social_media_analyst``
+    continues to work.
+
+    .. deprecated::
+        Import :func:`create_sentiment_analyst` directly instead.
+    """
+    import warnings
+    warnings.warn(
+        "create_social_media_analyst is deprecated and will be removed in a "
+        "future version. Use create_sentiment_analyst instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return create_sentiment_analyst(llm)