From f5026009f97b797541899bbd4e55e1f520e71df7 Mon Sep 17 00:00:00 2001
From: javierdejesusda <javier.dejesusj9@gmail.com>
Date: Tue, 24 Mar 2026 14:35:02 +0100
Subject: [PATCH 01/11] fix(llm_clients): standardize Google API key to unified
 api_key param

GoogleClient now accepts the unified `api_key` parameter used by
OpenAI and Anthropic clients, mapping it to the provider-specific
`google_api_key` that ChatGoogleGenerativeAI expects. Legacy
`google_api_key` still works for backward compatibility.

Resolves TODO.md item #2 (inconsistent parameter handling).
---
 tests/test_google_api_key.py               | 39 ++++++++++++++++++++++
 tradingagents/llm_clients/TODO.md          | 11 ++----
 tradingagents/llm_clients/google_client.py |  8 ++++-
 3 files changed, 49 insertions(+), 9 deletions(-)
 create mode 100644 tests/test_google_api_key.py

diff --git a/tests/test_google_api_key.py b/tests/test_google_api_key.py
new file mode 100644
index 00000000..1ec2301f
--- /dev/null
+++ b/tests/test_google_api_key.py
@@ -0,0 +1,39 @@
+import unittest
+from unittest.mock import patch
+
+
+class TestGoogleApiKeyStandardization(unittest.TestCase):
+    """Verify GoogleClient accepts unified api_key parameter."""
+
+    @patch("tradingagents.llm_clients.google_client.NormalizedChatGoogleGenerativeAI")
+    def test_api_key_mapped_to_google_api_key(self, mock_chat):
+        from tradingagents.llm_clients.google_client import GoogleClient
+
+        client = GoogleClient("gemini-2.5-flash", api_key="test-key-123")
+        client.get_llm()
+        call_kwargs = mock_chat.call_args[1]
+        self.assertEqual(call_kwargs["google_api_key"], "test-key-123")
+
+    @patch("tradingagents.llm_clients.google_client.NormalizedChatGoogleGenerativeAI")
+    def test_legacy_google_api_key_still_works(self, mock_chat):
+        from tradingagents.llm_clients.google_client import GoogleClient
+
+        client = GoogleClient("gemini-2.5-flash", google_api_key="legacy-key-456")
+        client.get_llm()
+        call_kwargs = mock_chat.call_args[1]
+        self.assertEqual(call_kwargs["google_api_key"], "legacy-key-456")
+
+    @patch("tradingagents.llm_clients.google_client.NormalizedChatGoogleGenerativeAI")
+    def test_api_key_takes_precedence_over_google_api_key(self, mock_chat):
+        from tradingagents.llm_clients.google_client import GoogleClient
+
+        client = GoogleClient(
+            "gemini-2.5-flash", api_key="unified", google_api_key="legacy"
+        )
+        client.get_llm()
+        call_kwargs = mock_chat.call_args[1]
+        self.assertEqual(call_kwargs["google_api_key"], "unified")
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tradingagents/llm_clients/TODO.md b/tradingagents/llm_clients/TODO.md
index d5b5ac9c..f666665d 100644
--- a/tradingagents/llm_clients/TODO.md
+++ b/tradingagents/llm_clients/TODO.md
@@ -5,14 +5,9 @@
 ### 1. `validate_model()` is never called
 - Add validation call in `get_llm()` with warning (not error) for unknown models
 
-### 2. Inconsistent parameter handling
-| Client | API Key Param | Special Params |
-|--------|---------------|----------------|
-| OpenAI | `api_key` | `reasoning_effort` |
-| Anthropic | `api_key` | `thinking_config` → `thinking` |
-| Google | `google_api_key` | `thinking_budget` |
-
-**Fix:** Standardize with unified `api_key` that maps to provider-specific keys
+### 2. ~~Inconsistent parameter handling~~ (Fixed)
+- GoogleClient now accepts unified `api_key` and maps it to `google_api_key`
+- Legacy `google_api_key` still works for backward compatibility
 
 ### 3. `base_url` accepted but ignored
 - `AnthropicClient`: accepts `base_url` but never uses it
diff --git a/tradingagents/llm_clients/google_client.py b/tradingagents/llm_clients/google_client.py
index 7401df0e..af8c6e48 100644
--- a/tradingagents/llm_clients/google_client.py
+++ b/tradingagents/llm_clients/google_client.py
@@ -27,10 +27,16 @@ class GoogleClient(BaseLLMClient):
         """Return configured ChatGoogleGenerativeAI instance."""
         llm_kwargs = {"model": self.model}
 
-        for key in ("timeout", "max_retries", "google_api_key", "callbacks", "http_client", "http_async_client"):
+        for key in ("timeout", "max_retries", "callbacks", "http_client", "http_async_client"):
             if key in self.kwargs:
                 llm_kwargs[key] = self.kwargs[key]
 
+        # Unified api_key maps to provider-specific google_api_key
+        if "api_key" in self.kwargs:
+            llm_kwargs["google_api_key"] = self.kwargs["api_key"]
+        elif "google_api_key" in self.kwargs:
+            llm_kwargs["google_api_key"] = self.kwargs["google_api_key"]
+
         # Map thinking_level to appropriate API param based on model
         # Gemini 3 Pro: low, high
         # Gemini 3 Flash: minimal, low, medium, high

From 047b38971cba6b390d04bb73e7191f2c05ee135e Mon Sep 17 00:00:00 2001
From: javierdejesusda <javier.dejesusj9@gmail.com>
Date: Tue, 24 Mar 2026 14:52:51 +0100
Subject: [PATCH 02/11] refactor: simplify api_key mapping and consolidate
 tests

Apply review suggestions: use concise `or` pattern for API key
resolution, consolidate tests into parameterized subTest, move
import to module level per PEP 8.
---
 tests/test_google_api_key.py               | 41 ++++++++--------------
 tradingagents/llm_clients/google_client.py |  7 ++--
 2 files changed, 18 insertions(+), 30 deletions(-)

diff --git a/tests/test_google_api_key.py b/tests/test_google_api_key.py
index 1ec2301f..e1607c49 100644
--- a/tests/test_google_api_key.py
+++ b/tests/test_google_api_key.py
@@ -1,38 +1,27 @@
 import unittest
 from unittest.mock import patch
 
+from tradingagents.llm_clients.google_client import GoogleClient
+
 
 class TestGoogleApiKeyStandardization(unittest.TestCase):
     """Verify GoogleClient accepts unified api_key parameter."""
 
     @patch("tradingagents.llm_clients.google_client.NormalizedChatGoogleGenerativeAI")
-    def test_api_key_mapped_to_google_api_key(self, mock_chat):
-        from tradingagents.llm_clients.google_client import GoogleClient
+    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"),
+        ]
 
-        client = GoogleClient("gemini-2.5-flash", api_key="test-key-123")
-        client.get_llm()
-        call_kwargs = mock_chat.call_args[1]
-        self.assertEqual(call_kwargs["google_api_key"], "test-key-123")
-
-    @patch("tradingagents.llm_clients.google_client.NormalizedChatGoogleGenerativeAI")
-    def test_legacy_google_api_key_still_works(self, mock_chat):
-        from tradingagents.llm_clients.google_client import GoogleClient
-
-        client = GoogleClient("gemini-2.5-flash", google_api_key="legacy-key-456")
-        client.get_llm()
-        call_kwargs = mock_chat.call_args[1]
-        self.assertEqual(call_kwargs["google_api_key"], "legacy-key-456")
-
-    @patch("tradingagents.llm_clients.google_client.NormalizedChatGoogleGenerativeAI")
-    def test_api_key_takes_precedence_over_google_api_key(self, mock_chat):
-        from tradingagents.llm_clients.google_client import GoogleClient
-
-        client = GoogleClient(
-            "gemini-2.5-flash", api_key="unified", google_api_key="legacy"
-        )
-        client.get_llm()
-        call_kwargs = mock_chat.call_args[1]
-        self.assertEqual(call_kwargs["google_api_key"], "unified")
+        for msg, kwargs, expected_key in test_cases:
+            with self.subTest(msg=msg):
+                mock_chat.reset_mock()
+                client = GoogleClient("gemini-2.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__":
diff --git a/tradingagents/llm_clients/google_client.py b/tradingagents/llm_clients/google_client.py
index af8c6e48..f9971aa6 100644
--- a/tradingagents/llm_clients/google_client.py
+++ b/tradingagents/llm_clients/google_client.py
@@ -32,10 +32,9 @@ class GoogleClient(BaseLLMClient):
                 llm_kwargs[key] = self.kwargs[key]
 
         # Unified api_key maps to provider-specific google_api_key
-        if "api_key" in self.kwargs:
-            llm_kwargs["google_api_key"] = self.kwargs["api_key"]
-        elif "google_api_key" in self.kwargs:
-            llm_kwargs["google_api_key"] = self.kwargs["google_api_key"]
+        google_api_key = self.kwargs.get("api_key") or self.kwargs.get("google_api_key")
+        if google_api_key:
+            llm_kwargs["google_api_key"] = google_api_key
 
         # Map thinking_level to appropriate API param based on model
         # Gemini 3 Pro: low, high

From 8793336dade0709b95233969147feafc00dc9ff4 Mon Sep 17 00:00:00 2001
From: CadeYu <yu83612457@gmail.com>
Date: Wed, 25 Mar 2026 21:23:02 +0800
Subject: [PATCH 03/11] sync model validation with cli catalog

---
 cli/utils.py                                  |  81 +------------
 tests/test_model_validation.py                |  52 +++++++++
 tradingagents/llm_clients/anthropic_client.py |   1 +
 tradingagents/llm_clients/base_client.py      |  22 ++++
 tradingagents/llm_clients/google_client.py    |   1 +
 tradingagents/llm_clients/model_catalog.py    | 106 ++++++++++++++++++
 tradingagents/llm_clients/openai_client.py    |   1 +
 tradingagents/llm_clients/validators.py       |  53 +--------
 8 files changed, 192 insertions(+), 125 deletions(-)
 create mode 100644 tests/test_model_validation.py
 create mode 100644 tradingagents/llm_clients/model_catalog.py

diff --git a/cli/utils.py b/cli/utils.py
index 5a8ec16c..9869fb4d 100644
--- a/cli/utils.py
+++ b/cli/utils.py
@@ -4,6 +4,7 @@ from typing import List, Optional, Tuple, Dict
 from rich.console import Console
 
 from cli.models import AnalystType
+from tradingagents.llm_clients.model_catalog import get_model_options
 
 console = Console()
 
@@ -129,48 +130,11 @@ def select_research_depth() -> int:
 def select_shallow_thinking_agent(provider) -> str:
     """Select shallow thinking llm engine using an interactive selection."""
 
-    # 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(
         "Select Your [Quick-Thinking LLM Engine]:",
         choices=[
             questionary.Choice(display, value=value)
-            for display, value in SHALLOW_AGENT_OPTIONS[provider.lower()]
+            for display, value in get_model_options(provider, "quick")
         ],
         instruction="\n- Use arrow keys to navigate\n- Press Enter to select",
         style=questionary.Style(
@@ -194,50 +158,11 @@ def select_shallow_thinking_agent(provider) -> str:
 def select_deep_thinking_agent(provider) -> str:
     """Select deep thinking llm engine using an interactive selection."""
 
-    # Define deep thinking llm engine options with their corresponding model names
-    # Ordering: heavy → medium → light (most capable first for deep tasks)
-    # Within same tier, newer models first
-    DEEP_AGENT_OPTIONS = {
-        "openai": [
-            ("GPT-5.4 - Latest frontier, 1M context", "gpt-5.4"),
-            ("GPT-5.2 - Strong reasoning, cost-effective", "gpt-5.2"),
-            ("GPT-5 Mini - Balanced speed, cost, and capability", "gpt-5-mini"),
-            ("GPT-5.4 Pro - Most capable, expensive ($30/$180 per 1M tokens)", "gpt-5.4-pro"),
-        ],
-        "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()]
+            for display, value in get_model_options(provider, "deep")
         ],
         instruction="\n- Use arrow keys to navigate\n- Press Enter to select",
         style=questionary.Style(
diff --git a/tests/test_model_validation.py b/tests/test_model_validation.py
new file mode 100644
index 00000000..50f26318
--- /dev/null
+++ b/tests/test_model_validation.py
@@ -0,0 +1,52 @@
+import unittest
+import warnings
+
+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)
+
+
+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, [])
diff --git a/tradingagents/llm_clients/anthropic_client.py b/tradingagents/llm_clients/anthropic_client.py
index 8539c752..939c7488 100644
--- a/tradingagents/llm_clients/anthropic_client.py
+++ b/tradingagents/llm_clients/anthropic_client.py
@@ -14,6 +14,7 @@ class AnthropicClient(BaseLLMClient):
 
     def get_llm(self) -> Any:
         """Return configured ChatAnthropic instance."""
+        self.warn_if_unknown_model()
         llm_kwargs = {"model": self.model}
 
         for key in ("timeout", "max_retries", "api_key", "max_tokens", "callbacks", "http_client", "http_async_client"):
diff --git a/tradingagents/llm_clients/base_client.py b/tradingagents/llm_clients/base_client.py
index 43845575..81880856 100644
--- a/tradingagents/llm_clients/base_client.py
+++ b/tradingagents/llm_clients/base_client.py
@@ -1,5 +1,6 @@
 from abc import ABC, abstractmethod
 from typing import Any, Optional
+import warnings
 
 
 class BaseLLMClient(ABC):
@@ -10,6 +11,27 @@ class BaseLLMClient(ABC):
         self.base_url = base_url
         self.kwargs = kwargs
 
+    def get_provider_name(self) -> str:
+        """Return the provider name used in warning messages."""
+        provider = getattr(self, "provider", None)
+        if provider:
+            return str(provider)
+        return self.__class__.__name__.removesuffix("Client").lower()
+
+    def warn_if_unknown_model(self) -> None:
+        """Warn when the model is outside the known list for the provider."""
+        if self.validate_model():
+            return
+
+        warnings.warn(
+            (
+                f"Model '{self.model}' is not in the known model list for "
+                f"provider '{self.get_provider_name()}'. Continuing anyway."
+            ),
+            RuntimeWarning,
+            stacklevel=2,
+        )
+
     @abstractmethod
     def get_llm(self) -> Any:
         """Return the configured LLM instance."""
diff --git a/tradingagents/llm_clients/google_client.py b/tradingagents/llm_clients/google_client.py
index 3dd85e3f..557e2640 100644
--- a/tradingagents/llm_clients/google_client.py
+++ b/tradingagents/llm_clients/google_client.py
@@ -36,6 +36,7 @@ class GoogleClient(BaseLLMClient):
 
     def get_llm(self) -> Any:
         """Return configured ChatGoogleGenerativeAI instance."""
+        self.warn_if_unknown_model()
         llm_kwargs = {"model": self.model}
 
         for key in ("timeout", "max_retries", "google_api_key", "callbacks", "http_client", "http_async_client"):
diff --git a/tradingagents/llm_clients/model_catalog.py b/tradingagents/llm_clients/model_catalog.py
new file mode 100644
index 00000000..58447a89
--- /dev/null
+++ b/tradingagents/llm_clients/model_catalog.py
@@ -0,0 +1,106 @@
+"""Shared model catalog for CLI selections and validation."""
+
+from __future__ import annotations
+
+from typing import Dict, List, Tuple
+
+ModelOption = Tuple[str, str]
+ProviderModeOptions = Dict[str, List[ModelOption]]
+
+
+MODEL_OPTIONS: ProviderModeOptions = {
+    "openai": {
+        "quick": [
+            ("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"),
+        ],
+        "deep": [
+            ("GPT-5.4 - Latest frontier, 1M context", "gpt-5.4"),
+            ("GPT-5.2 - Strong reasoning, cost-effective", "gpt-5.2"),
+            ("GPT-5 Mini - Balanced speed, cost, and capability", "gpt-5-mini"),
+            ("GPT-5.4 Pro - Most capable, expensive ($30/$180 per 1M tokens)", "gpt-5.4-pro"),
+        ],
+    },
+    "anthropic": {
+        "quick": [
+            ("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"),
+        ],
+        "deep": [
+            ("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": {
+        "quick": [
+            ("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"),
+        ],
+        "deep": [
+            ("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": {
+        "quick": [
+            ("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"),
+        ],
+        "deep": [
+            ("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": {
+        "quick": [
+            ("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"),
+        ],
+        "deep": [
+            ("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": {
+        "quick": [
+            ("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"),
+        ],
+        "deep": [
+            ("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"),
+        ],
+    },
+}
+
+
+def get_model_options(provider: str, mode: str) -> List[ModelOption]:
+    """Return shared model options for a provider and selection mode."""
+    return MODEL_OPTIONS[provider.lower()][mode]
+
+
+def get_known_models() -> Dict[str, List[str]]:
+    """Build known model names from the shared CLI catalog."""
+    known_models: Dict[str, List[str]] = {}
+    for provider, mode_options in MODEL_OPTIONS.items():
+        model_names = {
+            value
+            for options in mode_options.values()
+            for _, value in options
+        }
+        known_models[provider] = sorted(model_names)
+    return known_models
diff --git a/tradingagents/llm_clients/openai_client.py b/tradingagents/llm_clients/openai_client.py
index 4605c1f9..0629d894 100644
--- a/tradingagents/llm_clients/openai_client.py
+++ b/tradingagents/llm_clients/openai_client.py
@@ -41,6 +41,7 @@ class OpenAIClient(BaseLLMClient):
 
     def get_llm(self) -> Any:
         """Return configured ChatOpenAI instance."""
+        self.warn_if_unknown_model()
         llm_kwargs = {"model": self.model}
 
         if self.provider == "xai":
diff --git a/tradingagents/llm_clients/validators.py b/tradingagents/llm_clients/validators.py
index 1e2388b3..4e6d457b 100644
--- a/tradingagents/llm_clients/validators.py
+++ b/tradingagents/llm_clients/validators.py
@@ -1,53 +1,12 @@
-"""Model name validators for each provider.
+"""Model name validators for each provider."""
+
+from .model_catalog import get_known_models
 
-Only validates model names - does NOT enforce limits.
-Let LLM providers use their own defaults for unspecified params.
-"""
 
 VALID_MODELS = {
-    "openai": [
-        # GPT-5 series
-        "gpt-5.4-pro",
-        "gpt-5.4",
-        "gpt-5.2",
-        "gpt-5.1",
-        "gpt-5",
-        "gpt-5-mini",
-        "gpt-5-nano",
-        # GPT-4.1 series
-        "gpt-4.1",
-        "gpt-4.1-mini",
-        "gpt-4.1-nano",
-    ],
-    "anthropic": [
-        # Claude 4.6 series (latest)
-        "claude-opus-4-6",
-        "claude-sonnet-4-6",
-        # Claude 4.5 series
-        "claude-opus-4-5",
-        "claude-sonnet-4-5",
-        "claude-haiku-4-5",
-    ],
-    "google": [
-        # Gemini 3.1 series (preview)
-        "gemini-3.1-pro-preview",
-        "gemini-3.1-flash-lite-preview",
-        # Gemini 3 series (preview)
-        "gemini-3-flash-preview",
-        # Gemini 2.5 series
-        "gemini-2.5-pro",
-        "gemini-2.5-flash",
-        "gemini-2.5-flash-lite",
-    ],
-    "xai": [
-        # Grok 4.1 series
-        "grok-4-1-fast-reasoning",
-        "grok-4-1-fast-non-reasoning",
-        # Grok 4 series
-        "grok-4-0709",
-        "grok-4-fast-reasoning",
-        "grok-4-fast-non-reasoning",
-    ],
+    provider: models
+    for provider, models in get_known_models().items()
+    if provider not in ("ollama", "openrouter")
 }
 
 

From bd6a5b75b5361654acd8ed0d935b301573b8f992 Mon Sep 17 00:00:00 2001
From: CadeYu <yu83612457@gmail.com>
Date: Wed, 25 Mar 2026 21:46:56 +0800
Subject: [PATCH 04/11] fix model catalog typing and known-model helper

---
 tradingagents/llm_clients/model_catalog.py | 21 +++++++++++----------
 1 file changed, 11 insertions(+), 10 deletions(-)

diff --git a/tradingagents/llm_clients/model_catalog.py b/tradingagents/llm_clients/model_catalog.py
index 58447a89..f147c5e1 100644
--- a/tradingagents/llm_clients/model_catalog.py
+++ b/tradingagents/llm_clients/model_catalog.py
@@ -5,7 +5,7 @@ from __future__ import annotations
 from typing import Dict, List, Tuple
 
 ModelOption = Tuple[str, str]
-ProviderModeOptions = Dict[str, List[ModelOption]]
+ProviderModeOptions = Dict[str, Dict[str, List[ModelOption]]]
 
 
 MODEL_OPTIONS: ProviderModeOptions = {
@@ -95,12 +95,13 @@ def get_model_options(provider: str, mode: str) -> List[ModelOption]:
 
 def get_known_models() -> Dict[str, List[str]]:
     """Build known model names from the shared CLI catalog."""
-    known_models: Dict[str, List[str]] = {}
-    for provider, mode_options in MODEL_OPTIONS.items():
-        model_names = {
-            value
-            for options in mode_options.values()
-            for _, value in options
-        }
-        known_models[provider] = sorted(model_names)
-    return known_models
+    return {
+        provider: sorted(
+            {
+                value
+                for options in mode_options.values()
+                for _, value in options
+            }
+        )
+        for provider, mode_options in MODEL_OPTIONS.items()
+    }

From e1113880a1da00c80258612657fd4f8e68a79ef2 Mon Sep 17 00:00:00 2001
From: Yijia-Xiao <yijia-xiao@outlook.com>
Date: Sun, 29 Mar 2026 17:34:35 +0000
Subject: [PATCH 05/11] fix: prevent look-ahead bias in backtesting data
 fetchers (#475)

---
 .../dataflows/alpha_vantage_fundamentals.py   | 80 ++++++----------
 tradingagents/dataflows/stockstats_utils.py   | 94 ++++++++++++-------
 tradingagents/dataflows/y_finance.py          | 71 +++-----------
 tradingagents/dataflows/yfinance_news.py      |  5 +
 4 files changed, 108 insertions(+), 142 deletions(-)

diff --git a/tradingagents/dataflows/alpha_vantage_fundamentals.py b/tradingagents/dataflows/alpha_vantage_fundamentals.py
index 8b92faa6..a4ef24c0 100644
--- a/tradingagents/dataflows/alpha_vantage_fundamentals.py
+++ b/tradingagents/dataflows/alpha_vantage_fundamentals.py
@@ -1,6 +1,23 @@
 from .alpha_vantage_common import _make_api_request
 
 
+def _filter_reports_by_date(result, curr_date: str):
+    """Filter annualReports/quarterlyReports to exclude entries after curr_date.
+
+    Prevents look-ahead bias by removing fiscal periods that end after
+    the simulation's current date.
+    """
+    if not curr_date or not isinstance(result, dict):
+        return result
+    for key in ("annualReports", "quarterlyReports"):
+        if key in result:
+            result[key] = [
+                r for r in result[key]
+                if r.get("fiscalDateEnding", "") <= curr_date
+            ]
+    return result
+
+
 def get_fundamentals(ticker: str, curr_date: str = None) -> str:
     """
     Retrieve comprehensive fundamental data for a given ticker symbol using Alpha Vantage.
@@ -19,59 +36,20 @@ def get_fundamentals(ticker: str, curr_date: str = None) -> str:
     return _make_api_request("OVERVIEW", params)
 
 
-def get_balance_sheet(ticker: str, freq: str = "quarterly", curr_date: str = None) -> str:
-    """
-    Retrieve balance sheet data for a given ticker symbol using Alpha Vantage.
-
-    Args:
-        ticker (str): Ticker symbol of the company
-        freq (str): Reporting frequency: annual/quarterly (default quarterly) - not used for Alpha Vantage
-        curr_date (str): Current date you are trading at, yyyy-mm-dd (not used for Alpha Vantage)
-
-    Returns:
-        str: Balance sheet data with normalized fields
-    """
-    params = {
-        "symbol": ticker,
-    }
-
-    return _make_api_request("BALANCE_SHEET", params)
+def get_balance_sheet(ticker: str, freq: str = "quarterly", curr_date: str = None):
+    """Retrieve balance sheet data for a given ticker symbol using Alpha Vantage."""
+    result = _make_api_request("BALANCE_SHEET", {"symbol": ticker})
+    return _filter_reports_by_date(result, curr_date)
 
 
-def get_cashflow(ticker: str, freq: str = "quarterly", curr_date: str = None) -> str:
-    """
-    Retrieve cash flow statement data for a given ticker symbol using Alpha Vantage.
-
-    Args:
-        ticker (str): Ticker symbol of the company
-        freq (str): Reporting frequency: annual/quarterly (default quarterly) - not used for Alpha Vantage
-        curr_date (str): Current date you are trading at, yyyy-mm-dd (not used for Alpha Vantage)
-
-    Returns:
-        str: Cash flow statement data with normalized fields
-    """
-    params = {
-        "symbol": ticker,
-    }
-
-    return _make_api_request("CASH_FLOW", params)
+def get_cashflow(ticker: str, freq: str = "quarterly", curr_date: str = None):
+    """Retrieve cash flow statement data for a given ticker symbol using Alpha Vantage."""
+    result = _make_api_request("CASH_FLOW", {"symbol": ticker})
+    return _filter_reports_by_date(result, curr_date)
 
 
-def get_income_statement(ticker: str, freq: str = "quarterly", curr_date: str = None) -> str:
-    """
-    Retrieve income statement data for a given ticker symbol using Alpha Vantage.
-
-    Args:
-        ticker (str): Ticker symbol of the company
-        freq (str): Reporting frequency: annual/quarterly (default quarterly) - not used for Alpha Vantage
-        curr_date (str): Current date you are trading at, yyyy-mm-dd (not used for Alpha Vantage)
-
-    Returns:
-        str: Income statement data with normalized fields
-    """
-    params = {
-        "symbol": ticker,
-    }
-
-    return _make_api_request("INCOME_STATEMENT", params)
+def get_income_statement(ticker: str, freq: str = "quarterly", curr_date: str = None):
+    """Retrieve income statement data for a given ticker symbol using Alpha Vantage."""
+    result = _make_api_request("INCOME_STATEMENT", {"symbol": ticker})
+    return _filter_reports_by_date(result, curr_date)
 
diff --git a/tradingagents/dataflows/stockstats_utils.py b/tradingagents/dataflows/stockstats_utils.py
index 47d5460a..50747883 100644
--- a/tradingagents/dataflows/stockstats_utils.py
+++ b/tradingagents/dataflows/stockstats_utils.py
@@ -44,6 +44,64 @@ def _clean_dataframe(data: pd.DataFrame) -> pd.DataFrame:
     return data
 
 
+def load_ohlcv(symbol: str, curr_date: str) -> pd.DataFrame:
+    """Fetch OHLCV data with caching, filtered to prevent look-ahead bias.
+
+    Downloads 15 years of data up to today and caches per symbol. On
+    subsequent calls the cache is reused. Rows after curr_date are
+    filtered out so backtests never see future prices.
+    """
+    config = get_config()
+    curr_date_dt = pd.to_datetime(curr_date)
+
+    # Cache uses a fixed window (15y to today) so one file per symbol
+    today_date = pd.Timestamp.today()
+    start_date = today_date - pd.DateOffset(years=5)
+    start_str = start_date.strftime("%Y-%m-%d")
+    end_str = today_date.strftime("%Y-%m-%d")
+
+    os.makedirs(config["data_cache_dir"], exist_ok=True)
+    data_file = os.path.join(
+        config["data_cache_dir"],
+        f"{symbol}-YFin-data-{start_str}-{end_str}.csv",
+    )
+
+    if os.path.exists(data_file):
+        data = pd.read_csv(data_file, on_bad_lines="skip")
+    else:
+        data = yf_retry(lambda: yf.download(
+            symbol,
+            start=start_str,
+            end=end_str,
+            multi_level_index=False,
+            progress=False,
+            auto_adjust=True,
+        ))
+        data = data.reset_index()
+        data.to_csv(data_file, index=False)
+
+    data = _clean_dataframe(data)
+
+    # Filter to curr_date to prevent look-ahead bias in backtesting
+    data = data[data["Date"] <= curr_date_dt]
+
+    return data
+
+
+def filter_financials_by_date(data: pd.DataFrame, curr_date: str) -> pd.DataFrame:
+    """Drop financial statement columns (fiscal period timestamps) after curr_date.
+
+    yfinance financial statements use fiscal period end dates as columns.
+    Columns after curr_date represent future data and are removed to
+    prevent look-ahead bias.
+    """
+    if not curr_date or data.empty:
+        return data
+    cutoff = pd.Timestamp(curr_date)
+    mask = pd.to_datetime(data.columns, errors="coerce") <= cutoff
+    return data.loc[:, mask]
+
+
 class StockstatsUtils:
     @staticmethod
     def get_stock_stats(
@@ -55,42 +113,10 @@ class StockstatsUtils:
             str, "curr date for retrieving stock price data, YYYY-mm-dd"
         ],
     ):
-        config = get_config()
-
-        today_date = pd.Timestamp.today()
-        curr_date_dt = pd.to_datetime(curr_date)
-
-        end_date = today_date
-        start_date = today_date - pd.DateOffset(years=15)
-        start_date_str = start_date.strftime("%Y-%m-%d")
-        end_date_str = end_date.strftime("%Y-%m-%d")
-
-        # Ensure cache directory exists
-        os.makedirs(config["data_cache_dir"], exist_ok=True)
-
-        data_file = os.path.join(
-            config["data_cache_dir"],
-            f"{symbol}-YFin-data-{start_date_str}-{end_date_str}.csv",
-        )
-
-        if os.path.exists(data_file):
-            data = pd.read_csv(data_file, on_bad_lines="skip")
-        else:
-            data = yf_retry(lambda: yf.download(
-                symbol,
-                start=start_date_str,
-                end=end_date_str,
-                multi_level_index=False,
-                progress=False,
-                auto_adjust=True,
-            ))
-            data = data.reset_index()
-            data.to_csv(data_file, index=False)
-
-        data = _clean_dataframe(data)
+        data = load_ohlcv(symbol, curr_date)
         df = wrap(data)
         df["Date"] = df["Date"].dt.strftime("%Y-%m-%d")
-        curr_date_str = curr_date_dt.strftime("%Y-%m-%d")
+        curr_date_str = pd.to_datetime(curr_date).strftime("%Y-%m-%d")
 
         df[indicator]  # trigger stockstats to calculate the indicator
         matching_rows = df[df["Date"].str.startswith(curr_date_str)]
diff --git a/tradingagents/dataflows/y_finance.py b/tradingagents/dataflows/y_finance.py
index 3682a01d..8b4b93f5 100644
--- a/tradingagents/dataflows/y_finance.py
+++ b/tradingagents/dataflows/y_finance.py
@@ -3,7 +3,7 @@ from datetime import datetime
 from dateutil.relativedelta import relativedelta
 import yfinance as yf
 import os
-from .stockstats_utils import StockstatsUtils, _clean_dataframe, yf_retry
+from .stockstats_utils import StockstatsUtils, _clean_dataframe, yf_retry, load_ohlcv, filter_financials_by_date
 
 def get_YFin_data_online(
     symbol: Annotated[str, "ticker symbol of the company"],
@@ -194,58 +194,9 @@ def _get_stock_stats_bulk(
     Fetches data once and calculates indicator for all available dates.
     Returns dict mapping date strings to indicator values.
     """
-    from .config import get_config
-    import pandas as pd
     from stockstats import wrap
-    import os
-    
-    config = get_config()
-    online = config["data_vendors"]["technical_indicators"] != "local"
-    
-    if not online:
-        # Local data path
-        try:
-            data = pd.read_csv(
-                os.path.join(
-                    config.get("data_cache_dir", "data"),
-                    f"{symbol}-YFin-data-2015-01-01-2025-03-25.csv",
-                ),
-                on_bad_lines="skip",
-            )
-        except FileNotFoundError:
-            raise Exception("Stockstats fail: Yahoo Finance data not fetched yet!")
-    else:
-        # Online data fetching with caching
-        today_date = pd.Timestamp.today()
-        curr_date_dt = pd.to_datetime(curr_date)
 
-        end_date = today_date
-        start_date = today_date - pd.DateOffset(years=15)
-        start_date_str = start_date.strftime("%Y-%m-%d")
-        end_date_str = end_date.strftime("%Y-%m-%d")
-
-        os.makedirs(config["data_cache_dir"], exist_ok=True)
-
-        data_file = os.path.join(
-            config["data_cache_dir"],
-            f"{symbol}-YFin-data-{start_date_str}-{end_date_str}.csv",
-        )
-
-        if os.path.exists(data_file):
-            data = pd.read_csv(data_file, on_bad_lines="skip")
-        else:
-            data = yf_retry(lambda: yf.download(
-                symbol,
-                start=start_date_str,
-                end=end_date_str,
-                multi_level_index=False,
-                progress=False,
-                auto_adjust=True,
-            ))
-            data = data.reset_index()
-            data.to_csv(data_file, index=False)
-
-    data = _clean_dataframe(data)
+    data = load_ohlcv(symbol, curr_date)
     df = wrap(data)
     df["Date"] = df["Date"].dt.strftime("%Y-%m-%d")
     
@@ -353,7 +304,7 @@ def get_fundamentals(
 def get_balance_sheet(
     ticker: Annotated[str, "ticker symbol of the company"],
     freq: Annotated[str, "frequency of data: 'annual' or 'quarterly'"] = "quarterly",
-    curr_date: Annotated[str, "current date (not used for yfinance)"] = None
+    curr_date: Annotated[str, "current date in YYYY-MM-DD format"] = None
 ):
     """Get balance sheet data from yfinance."""
     try:
@@ -363,7 +314,9 @@ def get_balance_sheet(
             data = yf_retry(lambda: ticker_obj.quarterly_balance_sheet)
         else:
             data = yf_retry(lambda: ticker_obj.balance_sheet)
-            
+
+        data = filter_financials_by_date(data, curr_date)
+
         if data.empty:
             return f"No balance sheet data found for symbol '{ticker}'"
             
@@ -383,7 +336,7 @@ def get_balance_sheet(
 def get_cashflow(
     ticker: Annotated[str, "ticker symbol of the company"],
     freq: Annotated[str, "frequency of data: 'annual' or 'quarterly'"] = "quarterly",
-    curr_date: Annotated[str, "current date (not used for yfinance)"] = None
+    curr_date: Annotated[str, "current date in YYYY-MM-DD format"] = None
 ):
     """Get cash flow data from yfinance."""
     try:
@@ -393,7 +346,9 @@ def get_cashflow(
             data = yf_retry(lambda: ticker_obj.quarterly_cashflow)
         else:
             data = yf_retry(lambda: ticker_obj.cashflow)
-            
+
+        data = filter_financials_by_date(data, curr_date)
+
         if data.empty:
             return f"No cash flow data found for symbol '{ticker}'"
             
@@ -413,7 +368,7 @@ def get_cashflow(
 def get_income_statement(
     ticker: Annotated[str, "ticker symbol of the company"],
     freq: Annotated[str, "frequency of data: 'annual' or 'quarterly'"] = "quarterly",
-    curr_date: Annotated[str, "current date (not used for yfinance)"] = None
+    curr_date: Annotated[str, "current date in YYYY-MM-DD format"] = None
 ):
     """Get income statement data from yfinance."""
     try:
@@ -423,7 +378,9 @@ def get_income_statement(
             data = yf_retry(lambda: ticker_obj.quarterly_income_stmt)
         else:
             data = yf_retry(lambda: ticker_obj.income_stmt)
-            
+
+        data = filter_financials_by_date(data, curr_date)
+
         if data.empty:
             return f"No income statement data found for symbol '{ticker}'"
             
diff --git a/tradingagents/dataflows/yfinance_news.py b/tradingagents/dataflows/yfinance_news.py
index 20e9120d..7254ebc3 100644
--- a/tradingagents/dataflows/yfinance_news.py
+++ b/tradingagents/dataflows/yfinance_news.py
@@ -167,6 +167,11 @@ def get_global_news_yfinance(
             # Handle both flat and nested structures
             if "content" in article:
                 data = _extract_article_data(article)
+                # Skip articles published after curr_date (look-ahead guard)
+                if data.get("pub_date"):
+                    pub_naive = data["pub_date"].replace(tzinfo=None) if hasattr(data["pub_date"], "replace") else data["pub_date"]
+                    if pub_naive > curr_dt + relativedelta(days=1):
+                        continue
                 title = data["title"]
                 publisher = data["publisher"]
                 link = data["link"]

From f3f58bdbdcb6200e70dc1689254af19333f7c8f3 Mon Sep 17 00:00:00 2001
From: Yijia-Xiao <yijia-xiao@outlook.com>
Date: Sun, 29 Mar 2026 17:42:24 +0000
Subject: [PATCH 06/11] fix: add yf_retry to yfinance news fetchers (#445)

---
 tradingagents/dataflows/yfinance_news.py | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/tradingagents/dataflows/yfinance_news.py b/tradingagents/dataflows/yfinance_news.py
index 7254ebc3..dd1046f5 100644
--- a/tradingagents/dataflows/yfinance_news.py
+++ b/tradingagents/dataflows/yfinance_news.py
@@ -4,6 +4,8 @@ import yfinance as yf
 from datetime import datetime
 from dateutil.relativedelta import relativedelta
 
+from .stockstats_utils import yf_retry
+
 
 def _extract_article_data(article: dict) -> dict:
     """Extract article data from yfinance news format (handles nested 'content' structure)."""
@@ -64,7 +66,7 @@ def get_news_yfinance(
     """
     try:
         stock = yf.Ticker(ticker)
-        news = stock.get_news(count=20)
+        news = yf_retry(lambda: stock.get_news(count=20))
 
         if not news:
             return f"No news found for {ticker}"
@@ -131,11 +133,11 @@ def get_global_news_yfinance(
 
     try:
         for query in search_queries:
-            search = yf.Search(
-                query=query,
+            search = yf_retry(lambda q=query: yf.Search(
+                query=q,
                 news_count=limit,
                 enable_fuzzy_query=True,
-            )
+            ))
 
             if search.news:
                 for article in search.news:

From ae8c8aebe85179590a2af5ce4622de6b9067f9d1 Mon Sep 17 00:00:00 2001
From: Yijia-Xiao <yijia-xiao@outlook.com>
Date: Sun, 29 Mar 2026 17:50:30 +0000
Subject: [PATCH 07/11] fix: gracefully handle invalid indicator names in tool
 calls (#429)

---
 .../agents/utils/technical_indicators_tools.py        | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/tradingagents/agents/utils/technical_indicators_tools.py b/tradingagents/agents/utils/technical_indicators_tools.py
index 77acf09c..dc982580 100644
--- a/tradingagents/agents/utils/technical_indicators_tools.py
+++ b/tradingagents/agents/utils/technical_indicators_tools.py
@@ -23,9 +23,10 @@ def get_indicators(
     # LLMs sometimes pass multiple indicators as a comma-separated string;
     # split and process each individually.
     indicators = [i.strip() for i in indicator.split(",") if i.strip()]
-    if len(indicators) > 1:
-        results = []
-        for ind in indicators:
+    results = []
+    for ind in indicators:
+        try:
             results.append(route_to_vendor("get_indicators", symbol, ind, curr_date, look_back_days))
-        return "\n\n".join(results)
-    return route_to_vendor("get_indicators", symbol, indicator.strip(), curr_date, look_back_days)
\ No newline at end of file
+        except ValueError as e:
+            results.append(str(e))
+    return "\n\n".join(results)
\ No newline at end of file

From 58e99421bd8ae3cab7820f2ca0e8398892d71425 Mon Sep 17 00:00:00 2001
From: Yijia-Xiao <yijia-xiao@outlook.com>
Date: Sun, 29 Mar 2026 17:59:52 +0000
Subject: [PATCH 08/11] fix: pass base_url to Google and Anthropic clients for
 proxy support (#427)

---
 tradingagents/llm_clients/TODO.md             | 12 ++++--------
 tradingagents/llm_clients/anthropic_client.py |  3 +++
 tradingagents/llm_clients/google_client.py    |  3 +++
 3 files changed, 10 insertions(+), 8 deletions(-)

diff --git a/tradingagents/llm_clients/TODO.md b/tradingagents/llm_clients/TODO.md
index f666665d..2d3fe915 100644
--- a/tradingagents/llm_clients/TODO.md
+++ b/tradingagents/llm_clients/TODO.md
@@ -7,13 +7,9 @@
 
 ### 2. ~~Inconsistent parameter handling~~ (Fixed)
 - GoogleClient now accepts unified `api_key` and maps it to `google_api_key`
-- Legacy `google_api_key` still works for backward compatibility
 
-### 3. `base_url` accepted but ignored
-- `AnthropicClient`: accepts `base_url` but never uses it
-- `GoogleClient`: accepts `base_url` but never uses it (correct - Google doesn't support it)
+### 3. ~~`base_url` accepted but ignored~~ (Fixed)
+- All clients now pass `base_url` to their respective LLM constructors
 
-**Fix:** Remove unused `base_url` from clients that don't support it
-
-### 4. Update validators.py with models from CLI
-- Sync `VALID_MODELS` dict with CLI model options after Feature 2 is complete
+### 4. ~~Update validators.py with models from CLI~~ (Fixed)
+- Synced in v0.2.2
diff --git a/tradingagents/llm_clients/anthropic_client.py b/tradingagents/llm_clients/anthropic_client.py
index 2c1e5a67..27b01234 100644
--- a/tradingagents/llm_clients/anthropic_client.py
+++ b/tradingagents/llm_clients/anthropic_client.py
@@ -33,6 +33,9 @@ class AnthropicClient(BaseLLMClient):
         """Return configured ChatAnthropic instance."""
         llm_kwargs = {"model": self.model}
 
+        if self.base_url:
+            llm_kwargs["base_url"] = self.base_url
+
         for key in _PASSTHROUGH_KWARGS:
             if key in self.kwargs:
                 llm_kwargs[key] = self.kwargs[key]
diff --git a/tradingagents/llm_clients/google_client.py b/tradingagents/llm_clients/google_client.py
index f9971aa6..755ff4ed 100644
--- a/tradingagents/llm_clients/google_client.py
+++ b/tradingagents/llm_clients/google_client.py
@@ -27,6 +27,9 @@ class GoogleClient(BaseLLMClient):
         """Return configured ChatGoogleGenerativeAI instance."""
         llm_kwargs = {"model": self.model}
 
+        if self.base_url:
+            llm_kwargs["base_url"] = self.base_url
+
         for key in ("timeout", "max_retries", "callbacks", "http_client", "http_async_client"):
             if key in self.kwargs:
                 llm_kwargs[key] = self.kwargs[key]

From 6cddd26d6eab51e12ca8ab73b02bf9372980ca19 Mon Sep 17 00:00:00 2001
From: Yijia-Xiao <yijia-xiao@outlook.com>
Date: Sun, 29 Mar 2026 19:19:01 +0000
Subject: [PATCH 09/11] feat: multi-language output support for analyst reports
 and final decision (#472)

---
 cli/main.py                                   | 37 ++++++++++++-------
 cli/utils.py                                  | 34 +++++++++++++++++
 .../agents/analysts/fundamentals_analyst.py   |  4 +-
 .../agents/analysts/market_analyst.py         |  2 +
 tradingagents/agents/analysts/news_analyst.py |  2 +
 .../agents/analysts/social_media_analyst.py   |  3 +-
 .../agents/managers/portfolio_manager.py      |  4 +-
 tradingagents/agents/utils/agent_utils.py     | 14 +++++++
 tradingagents/default_config.py               |  3 ++
 9 files changed, 86 insertions(+), 17 deletions(-)

diff --git a/cli/main.py b/cli/main.py
index 53837db2..29294d8d 100644
--- a/cli/main.py
+++ b/cli/main.py
@@ -519,10 +519,19 @@ def get_user_selections():
     )
     analysis_date = get_analysis_date()
 
-    # Step 3: Select analysts
+    # Step 3: Output language
     console.print(
         create_question_box(
-            "Step 3: Analysts Team", "Select your LLM analyst agents for the analysis"
+            "Step 3: Output Language",
+            "Select the language for analyst reports and final decision"
+        )
+    )
+    output_language = ask_output_language()
+
+    # Step 4: Select analysts
+    console.print(
+        create_question_box(
+            "Step 4: Analysts Team", "Select your LLM analyst agents for the analysis"
         )
     )
     selected_analysts = select_analysts()
@@ -530,32 +539,32 @@ def get_user_selections():
         f"[green]Selected analysts:[/green] {', '.join(analyst.value for analyst in selected_analysts)}"
     )
 
-    # Step 4: Research depth
+    # Step 5: Research depth
     console.print(
         create_question_box(
-            "Step 4: Research Depth", "Select your research depth level"
+            "Step 5: Research Depth", "Select your research depth level"
         )
     )
     selected_research_depth = select_research_depth()
 
-    # Step 5: OpenAI backend
+    # Step 6: LLM Provider
     console.print(
         create_question_box(
-            "Step 5: OpenAI backend", "Select which service to talk to"
+            "Step 6: LLM Provider", "Select your LLM provider"
         )
     )
     selected_llm_provider, backend_url = select_llm_provider()
-    
-    # Step 6: Thinking agents
+
+    # Step 7: Thinking agents
     console.print(
         create_question_box(
-            "Step 6: Thinking Agents", "Select your thinking agents for analysis"
+            "Step 7: Thinking Agents", "Select your thinking agents for analysis"
         )
     )
     selected_shallow_thinker = select_shallow_thinking_agent(selected_llm_provider)
     selected_deep_thinker = select_deep_thinking_agent(selected_llm_provider)
 
-    # Step 7: Provider-specific thinking configuration
+    # Step 8: Provider-specific thinking configuration
     thinking_level = None
     reasoning_effort = None
     anthropic_effort = None
@@ -564,7 +573,7 @@ def get_user_selections():
     if provider_lower == "google":
         console.print(
             create_question_box(
-                "Step 7: Thinking Mode",
+                "Step 8: Thinking Mode",
                 "Configure Gemini thinking mode"
             )
         )
@@ -572,7 +581,7 @@ def get_user_selections():
     elif provider_lower == "openai":
         console.print(
             create_question_box(
-                "Step 7: Reasoning Effort",
+                "Step 8: Reasoning Effort",
                 "Configure OpenAI reasoning effort level"
             )
         )
@@ -580,7 +589,7 @@ def get_user_selections():
     elif provider_lower == "anthropic":
         console.print(
             create_question_box(
-                "Step 7: Effort Level",
+                "Step 8: Effort Level",
                 "Configure Claude effort level"
             )
         )
@@ -598,6 +607,7 @@ def get_user_selections():
         "google_thinking_level": thinking_level,
         "openai_reasoning_effort": reasoning_effort,
         "anthropic_effort": anthropic_effort,
+        "output_language": output_language,
     }
 
 
@@ -931,6 +941,7 @@ def run_analysis():
     config["google_thinking_level"] = selections.get("google_thinking_level")
     config["openai_reasoning_effort"] = selections.get("openai_reasoning_effort")
     config["anthropic_effort"] = selections.get("anthropic_effort")
+    config["output_language"] = selections.get("output_language", "English")
 
     # Create stats callback handler for tracking LLM/tool calls
     stats_handler = StatsCallbackHandler()
diff --git a/cli/utils.py b/cli/utils.py
index 0166cd95..62b50c9c 100644
--- a/cli/utils.py
+++ b/cli/utils.py
@@ -281,3 +281,37 @@ def ask_gemini_thinking_config() -> str | None:
             ("pointer", "fg:green noinherit"),
         ]),
     ).ask()
+
+
+def ask_output_language() -> str:
+    """Ask for report output language."""
+    choice = questionary.select(
+        "Select Output Language:",
+        choices=[
+            questionary.Choice("English (default)", "English"),
+            questionary.Choice("Chinese (中文)", "Chinese"),
+            questionary.Choice("Japanese (日本語)", "Japanese"),
+            questionary.Choice("Korean (한국어)", "Korean"),
+            questionary.Choice("Hindi (हिन्दी)", "Hindi"),
+            questionary.Choice("Spanish (Español)", "Spanish"),
+            questionary.Choice("Portuguese (Português)", "Portuguese"),
+            questionary.Choice("French (Français)", "French"),
+            questionary.Choice("German (Deutsch)", "German"),
+            questionary.Choice("Arabic (العربية)", "Arabic"),
+            questionary.Choice("Russian (Русский)", "Russian"),
+            questionary.Choice("Custom language", "custom"),
+        ],
+        style=questionary.Style([
+            ("selected", "fg:yellow noinherit"),
+            ("highlighted", "fg:yellow noinherit"),
+            ("pointer", "fg:yellow noinherit"),
+        ]),
+    ).ask()
+
+    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().strip()
+
+    return choice
diff --git a/tradingagents/agents/analysts/fundamentals_analyst.py b/tradingagents/agents/analysts/fundamentals_analyst.py
index 990398a6..3f70c734 100644
--- a/tradingagents/agents/analysts/fundamentals_analyst.py
+++ b/tradingagents/agents/analysts/fundamentals_analyst.py
@@ -8,6 +8,7 @@ from tradingagents.agents.utils.agent_utils import (
     get_fundamentals,
     get_income_statement,
     get_insider_transactions,
+    get_language_instruction,
 )
 from tradingagents.dataflows.config import get_config
 
@@ -27,7 +28,8 @@ 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. 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(
diff --git a/tradingagents/agents/analysts/market_analyst.py b/tradingagents/agents/analysts/market_analyst.py
index f5d17acd..680f9019 100644
--- a/tradingagents/agents/analysts/market_analyst.py
+++ b/tradingagents/agents/analysts/market_analyst.py
@@ -4,6 +4,7 @@ import json
 from tradingagents.agents.utils.agent_utils import (
     build_instrument_context,
     get_indicators,
+    get_language_instruction,
     get_stock_data,
 )
 from tradingagents.dataflows.config import get_config
@@ -47,6 +48,7 @@ Volume-Based Indicators:
 
 - 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. 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(
diff --git a/tradingagents/agents/analysts/news_analyst.py b/tradingagents/agents/analysts/news_analyst.py
index 3697c6f6..42fc7a61 100644
--- a/tradingagents/agents/analysts/news_analyst.py
+++ b/tradingagents/agents/analysts/news_analyst.py
@@ -4,6 +4,7 @@ import json
 from tradingagents.agents.utils.agent_utils import (
     build_instrument_context,
     get_global_news,
+    get_language_instruction,
     get_news,
 )
 from tradingagents.dataflows.config import get_config
@@ -22,6 +23,7 @@ def create_news_analyst(llm):
         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. 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(
diff --git a/tradingagents/agents/analysts/social_media_analyst.py b/tradingagents/agents/analysts/social_media_analyst.py
index 43df2258..67d78f4c 100644
--- a/tradingagents/agents/analysts/social_media_analyst.py
+++ b/tradingagents/agents/analysts/social_media_analyst.py
@@ -1,7 +1,7 @@
 from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
 import time
 import json
-from tradingagents.agents.utils.agent_utils import build_instrument_context, get_news
+from tradingagents.agents.utils.agent_utils import build_instrument_context, get_language_instruction, get_news
 from tradingagents.dataflows.config import get_config
 
 
@@ -17,6 +17,7 @@ def create_social_media_analyst(llm):
         system_message = (
             "You are a social media and company specific news researcher/analyst tasked with analyzing social media posts, recent company news, and public sentiment for a specific company over the past week. You will be given a company's name your objective is to write a comprehensive long report detailing your analysis, insights, and implications for traders and investors on this company's current state after looking at social media and what people are saying about that company, analyzing sentiment data of what people feel each day about the company, and looking at recent company news. Use the get_news(query, start_date, end_date) tool to search for company-specific news and social media discussions. Try to look at all sources possible from social media to sentiment to news. 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(
diff --git a/tradingagents/agents/managers/portfolio_manager.py b/tradingagents/agents/managers/portfolio_manager.py
index acdf940b..970efb46 100644
--- a/tradingagents/agents/managers/portfolio_manager.py
+++ b/tradingagents/agents/managers/portfolio_manager.py
@@ -1,4 +1,4 @@
-from tradingagents.agents.utils.agent_utils import build_instrument_context
+from tradingagents.agents.utils.agent_utils import build_instrument_context, get_language_instruction
 
 
 def create_portfolio_manager(llm, memory):
@@ -50,7 +50,7 @@ def create_portfolio_manager(llm, memory):
 
 ---
 
-Be decisive and ground every conclusion in specific evidence from the analysts."""
+Be decisive and ground every conclusion in specific evidence from the analysts.{get_language_instruction()}"""
 
         response = llm.invoke(prompt)
 
diff --git a/tradingagents/agents/utils/agent_utils.py b/tradingagents/agents/utils/agent_utils.py
index e4abc4cd..4ba40a80 100644
--- a/tradingagents/agents/utils/agent_utils.py
+++ b/tradingagents/agents/utils/agent_utils.py
@@ -20,6 +20,20 @@ from tradingagents.agents.utils.news_data_tools import (
 )
 
 
+def get_language_instruction() -> str:
+    """Return a prompt instruction for the configured output language.
+
+    Returns empty string when English (default), so no extra tokens are used.
+    Only applied to user-facing agents (analysts, portfolio manager).
+    Internal debate agents stay in English for reasoning quality.
+    """
+    from tradingagents.dataflows.config import get_config
+    lang = get_config().get("output_language", "English")
+    if lang.strip().lower() == "english":
+        return ""
+    return f" Write your entire response in {lang}."
+
+
 def build_instrument_context(ticker: str) -> str:
     """Describe the exact instrument so agents preserve exchange-qualified tickers."""
     return (
diff --git a/tradingagents/default_config.py b/tradingagents/default_config.py
index 898e1e1e..31952c00 100644
--- a/tradingagents/default_config.py
+++ b/tradingagents/default_config.py
@@ -16,6 +16,9 @@ DEFAULT_CONFIG = {
     "google_thinking_level": None,      # "high", "minimal", etc.
     "openai_reasoning_effort": None,    # "medium", "high", "low"
     "anthropic_effort": None,           # "high", "medium", "low"
+    # Output language for analyst reports and final decision
+    # Internal agent debate stays in English for reasoning quality
+    "output_language": "English",
     # Debate and discussion settings
     "max_debate_rounds": 1,
     "max_risk_discuss_rounds": 1,

From e75d17bc51981b49ed47c6a2c2016100e0689e09 Mon Sep 17 00:00:00 2001
From: Yijia-Xiao <yijia-xiao@outlook.com>
Date: Sun, 29 Mar 2026 19:45:36 +0000
Subject: [PATCH 10/11] chore: update model lists and defaults to GPT-5.4
 family

---
 README.md                                  | 4 ++--
 main.py                                    | 4 ++--
 tradingagents/default_config.py            | 4 ++--
 tradingagents/llm_clients/model_catalog.py | 6 +++---
 4 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 4c4856d1..41a124c7 100644
--- a/README.md
+++ b/README.md
@@ -189,8 +189,8 @@ from tradingagents.default_config import DEFAULT_CONFIG
 
 config = DEFAULT_CONFIG.copy()
 config["llm_provider"] = "openai"        # openai, google, anthropic, xai, openrouter, ollama
-config["deep_think_llm"] = "gpt-5.2"     # Model for complex reasoning
-config["quick_think_llm"] = "gpt-5-mini" # Model for quick tasks
+config["deep_think_llm"] = "gpt-5.4"     # Model for complex reasoning
+config["quick_think_llm"] = "gpt-5.4-mini" # Model for quick tasks
 config["max_debate_rounds"] = 2
 
 ta = TradingAgentsGraph(debug=True, config=config)
diff --git a/main.py b/main.py
index 26cab658..c94fde32 100644
--- a/main.py
+++ b/main.py
@@ -8,8 +8,8 @@ load_dotenv()
 
 # 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["deep_think_llm"] = "gpt-5.4-mini"  # Use a different model
+config["quick_think_llm"] = "gpt-5.4-mini"  # Use a different model
 config["max_debate_rounds"] = 1  # Increase debate rounds
 
 # Configure data vendors (default uses yfinance, no extra API keys needed)
diff --git a/tradingagents/default_config.py b/tradingagents/default_config.py
index 31952c00..26a4e4d2 100644
--- a/tradingagents/default_config.py
+++ b/tradingagents/default_config.py
@@ -9,8 +9,8 @@ DEFAULT_CONFIG = {
     ),
     # LLM settings
     "llm_provider": "openai",
-    "deep_think_llm": "gpt-5.2",
-    "quick_think_llm": "gpt-5-mini",
+    "deep_think_llm": "gpt-5.4",
+    "quick_think_llm": "gpt-5.4-mini",
     "backend_url": "https://api.openai.com/v1",
     # Provider-specific thinking configuration
     "google_thinking_level": None,      # "high", "minimal", etc.
diff --git a/tradingagents/llm_clients/model_catalog.py b/tradingagents/llm_clients/model_catalog.py
index f147c5e1..91e1659c 100644
--- a/tradingagents/llm_clients/model_catalog.py
+++ b/tradingagents/llm_clients/model_catalog.py
@@ -11,15 +11,15 @@ ProviderModeOptions = Dict[str, Dict[str, List[ModelOption]]]
 MODEL_OPTIONS: ProviderModeOptions = {
     "openai": {
         "quick": [
-            ("GPT-5 Mini - Balanced speed, cost, and capability", "gpt-5-mini"),
-            ("GPT-5 Nano - High-throughput, simple tasks", "gpt-5-nano"),
+            ("GPT-5.4 Mini - Fast, strong coding and tool use", "gpt-5.4-mini"),
+            ("GPT-5.4 Nano - Cheapest, high-volume tasks", "gpt-5.4-nano"),
             ("GPT-5.4 - Latest frontier, 1M context", "gpt-5.4"),
             ("GPT-4.1 - Smartest non-reasoning model", "gpt-4.1"),
         ],
         "deep": [
             ("GPT-5.4 - Latest frontier, 1M context", "gpt-5.4"),
             ("GPT-5.2 - Strong reasoning, cost-effective", "gpt-5.2"),
-            ("GPT-5 Mini - Balanced speed, cost, and capability", "gpt-5-mini"),
+            ("GPT-5.4 Mini - Fast, strong coding and tool use", "gpt-5.4-mini"),
             ("GPT-5.4 Pro - Most capable, expensive ($30/$180 per 1M tokens)", "gpt-5.4-pro"),
         ],
     },

From 4641c03340c70e0e75e74234c998325164c72b36 Mon Sep 17 00:00:00 2001
From: Yijia-Xiao <yijia-xiao@outlook.com>
Date: Sun, 29 Mar 2026 19:50:46 +0000
Subject: [PATCH 11/11] TradingAgents v0.2.3

---
 README.md      | 1 +
 pyproject.toml | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 41a124c7..4cfeb4e5 100644
--- a/README.md
+++ b/README.md
@@ -28,6 +28,7 @@
 # TradingAgents: Multi-Agents LLM Financial Trading Framework
 
 ## News
+- [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.
diff --git a/pyproject.toml b/pyproject.toml
index de27a2b9..0decedb0 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tradingagents"
-version = "0.2.2"
+version = "0.2.3"
 description = "TradingAgents: Multi-Agents LLM Financial Trading Framework"
 readme = "README.md"
 requires-python = ">=3.10"