a

TradingAgents/tradingagents/agents/utils/agent_states.py

@@ -0,0 +1,73 @@
+from typing import Annotated
+from typing_extensions import TypedDict
+from langgraph.graph import MessagesState
+
+
+# Researcher team state
+class InvestDebateState(TypedDict):
+    bull_history: Annotated[
+        str, "Bullish Conversation history"
+    ]  # Bullish Conversation history
+    bear_history: Annotated[
+        str, "Bearish Conversation history"
+    ]  # Bullish Conversation history
+    history: Annotated[str, "Conversation history"]  # Conversation history
+    current_response: Annotated[str, "Latest response"]  # Last response
+    judge_decision: Annotated[str, "Final judge decision"]  # Last response
+    count: Annotated[int, "Length of the current conversation"]  # Conversation length
+
+
+# Risk management team state
+class RiskDebateState(TypedDict):
+    aggressive_history: Annotated[
+        str, "Aggressive Agent's Conversation history"
+    ]  # Conversation history
+    conservative_history: Annotated[
+        str, "Conservative Agent's Conversation history"
+    ]  # Conversation history
+    neutral_history: Annotated[
+        str, "Neutral Agent's Conversation history"
+    ]  # Conversation history
+    history: Annotated[str, "Conversation history"]  # Conversation history
+    latest_speaker: Annotated[str, "Analyst that spoke last"]
+    current_aggressive_response: Annotated[
+        str, "Latest response by the aggressive analyst"
+    ]  # Last response
+    current_conservative_response: Annotated[
+        str, "Latest response by the conservative analyst"
+    ]  # Last response
+    current_neutral_response: Annotated[
+        str, "Latest response by the neutral analyst"
+    ]  # Last response
+    judge_decision: Annotated[str, "Judge's decision"]
+    count: Annotated[int, "Length of the current conversation"]  # Conversation length
+
+
+class AgentState(MessagesState):
+    company_of_interest: Annotated[str, "Company that we are interested in trading"]
+    trade_date: Annotated[str, "What date we are trading at"]
+
+    sender: Annotated[str, "Agent that sent this message"]
+
+    # research step
+    market_report: Annotated[str, "Report from the Market Analyst"]
+    sentiment_report: Annotated[str, "Report from the Social Media Analyst"]
+    news_report: Annotated[
+        str, "Report from the News Researcher of current world affairs"
+    ]
+    fundamentals_report: Annotated[str, "Report from the Fundamentals Researcher"]
+
+    # researcher team discussion step
+    investment_debate_state: Annotated[
+        InvestDebateState, "Current state of the debate on if to invest or not"
+    ]
+    investment_plan: Annotated[str, "Plan generated by the Analyst"]
+
+    trader_investment_plan: Annotated[str, "Plan generated by the Trader"]
+
+    # risk management team discussion step
+    risk_debate_state: Annotated[
+        RiskDebateState, "Current state of the debate on evaluating risk"
+    ]
+    final_trade_decision: Annotated[str, "Final decision made by the Risk Analysts"]
+    past_context: Annotated[str, "Memory log context injected at run start (same-ticker decisions + cross-ticker lessons)"]

TradingAgents/tradingagents/agents/utils/agent_utils.py

@@ -0,0 +1,61 @@
+from langchain_core.messages import HumanMessage, RemoveMessage
+
+# Import tools from separate utility files
+from tradingagents.agents.utils.core_stock_tools import (
+    get_stock_data
+)
+from tradingagents.agents.utils.technical_indicators_tools import (
+    get_indicators
+)
+from tradingagents.agents.utils.fundamental_data_tools import (
+    get_fundamentals,
+    get_balance_sheet,
+    get_cashflow,
+    get_income_statement
+)
+from tradingagents.agents.utils.news_data_tools import (
+    get_news,
+    get_insider_transactions,
+    get_global_news
+)
+
+
+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 (
+        f"The instrument to analyze is `{ticker}`. "
+        "Use this exact ticker in every tool call, report, and recommendation, "
+        "preserving any exchange suffix (e.g. `.TO`, `.L`, `.HK`, `.T`)."
+    )
+
+def create_msg_delete():
+    def delete_messages(state):
+        """Clear messages and add placeholder for Anthropic compatibility"""
+        messages = state["messages"]
+
+        # Remove all messages
+        removal_operations = [RemoveMessage(id=m.id) for m in messages]
+
+        # Add a minimal placeholder message
+        placeholder = HumanMessage(content="Continue")
+
+        return {"messages": removal_operations + [placeholder]}
+
+    return delete_messages
+
+
+        

TradingAgents/tradingagents/agents/utils/core_stock_tools.py

@@ -0,0 +1,22 @@
+from langchain_core.tools import tool
+from typing import Annotated
+from tradingagents.dataflows.interface import route_to_vendor
+
+
+@tool
+def get_stock_data(
+    symbol: Annotated[str, "ticker symbol of the company"],
+    start_date: Annotated[str, "Start date in yyyy-mm-dd format"],
+    end_date: Annotated[str, "End date in yyyy-mm-dd format"],
+) -> str:
+    """
+    Retrieve stock price data (OHLCV) for a given ticker symbol.
+    Uses the configured core_stock_apis vendor.
+    Args:
+        symbol (str): Ticker symbol of the company, e.g. AAPL, TSM
+        start_date (str): Start date in yyyy-mm-dd format
+        end_date (str): End date in yyyy-mm-dd format
+    Returns:
+        str: A formatted dataframe containing the stock price data for the specified ticker symbol in the specified date range.
+    """
+    return route_to_vendor("get_stock_data", symbol, start_date, end_date)

TradingAgents/tradingagents/agents/utils/fundamental_data_tools.py

@@ -0,0 +1,77 @@
+from langchain_core.tools import tool
+from typing import Annotated
+from tradingagents.dataflows.interface import route_to_vendor
+
+
+@tool
+def get_fundamentals(
+    ticker: Annotated[str, "ticker symbol"],
+    curr_date: Annotated[str, "current date you are trading at, yyyy-mm-dd"],
+) -> str:
+    """
+    Retrieve comprehensive fundamental data for a given ticker symbol.
+    Uses the configured fundamental_data vendor.
+    Args:
+        ticker (str): Ticker symbol of the company
+        curr_date (str): Current date you are trading at, yyyy-mm-dd
+    Returns:
+        str: A formatted report containing comprehensive fundamental data
+    """
+    return route_to_vendor("get_fundamentals", ticker, curr_date)
+
+
+@tool
+def get_balance_sheet(
+    ticker: Annotated[str, "ticker symbol"],
+    freq: Annotated[str, "reporting frequency: annual/quarterly"] = "quarterly",
+    curr_date: Annotated[str, "current date you are trading at, yyyy-mm-dd"] = None,
+) -> str:
+    """
+    Retrieve balance sheet data for a given ticker symbol.
+    Uses the configured fundamental_data vendor.
+    Args:
+        ticker (str): Ticker symbol of the company
+        freq (str): Reporting frequency: annual/quarterly (default quarterly)
+        curr_date (str): Current date you are trading at, yyyy-mm-dd
+    Returns:
+        str: A formatted report containing balance sheet data
+    """
+    return route_to_vendor("get_balance_sheet", ticker, freq, curr_date)
+
+
+@tool
+def get_cashflow(
+    ticker: Annotated[str, "ticker symbol"],
+    freq: Annotated[str, "reporting frequency: annual/quarterly"] = "quarterly",
+    curr_date: Annotated[str, "current date you are trading at, yyyy-mm-dd"] = None,
+) -> str:
+    """
+    Retrieve cash flow statement data for a given ticker symbol.
+    Uses the configured fundamental_data vendor.
+    Args:
+        ticker (str): Ticker symbol of the company
+        freq (str): Reporting frequency: annual/quarterly (default quarterly)
+        curr_date (str): Current date you are trading at, yyyy-mm-dd
+    Returns:
+        str: A formatted report containing cash flow statement data
+    """
+    return route_to_vendor("get_cashflow", ticker, freq, curr_date)
+
+
+@tool
+def get_income_statement(
+    ticker: Annotated[str, "ticker symbol"],
+    freq: Annotated[str, "reporting frequency: annual/quarterly"] = "quarterly",
+    curr_date: Annotated[str, "current date you are trading at, yyyy-mm-dd"] = None,
+) -> str:
+    """
+    Retrieve income statement data for a given ticker symbol.
+    Uses the configured fundamental_data vendor.
+    Args:
+        ticker (str): Ticker symbol of the company
+        freq (str): Reporting frequency: annual/quarterly (default quarterly)
+        curr_date (str): Current date you are trading at, yyyy-mm-dd
+    Returns:
+        str: A formatted report containing income statement data
+    """
+    return route_to_vendor("get_income_statement", ticker, freq, curr_date)

TradingAgents/tradingagents/agents/utils/memory.py

@@ -0,0 +1,300 @@
+"""Append-only markdown decision log for TradingAgents."""
+
+from typing import List, Optional
+from pathlib import Path
+import re
+
+from tradingagents.agents.utils.rating import parse_rating
+
+
+class TradingMemoryLog:
+    """Append-only markdown log of trading decisions and reflections."""
+
+    # HTML comment: cannot appear in LLM prose output, safe as a hard delimiter
+    _SEPARATOR = "\n\n<!-- ENTRY_END -->\n\n"
+    # Precompiled patterns — avoids re-compilation on every load_entries() call
+    _DECISION_RE = re.compile(r"DECISION:\n(.*?)(?=\nREFLECTION:|\Z)", re.DOTALL)
+    _REFLECTION_RE = re.compile(r"REFLECTION:\n(.*?)$", re.DOTALL)
+
+    def __init__(self, config: dict = None):
+        cfg = config or {}
+        self._log_path = None
+        path = cfg.get("memory_log_path")
+        if path:
+            self._log_path = Path(path).expanduser()
+            self._log_path.parent.mkdir(parents=True, exist_ok=True)
+        # Optional cap on resolved entries. None disables rotation.
+        self._max_entries = cfg.get("memory_log_max_entries")
+
+    # --- Write path (Phase A) ---
+
+    def store_decision(
+        self,
+        ticker: str,
+        trade_date: str,
+        final_trade_decision: str,
+    ) -> None:
+        """Append pending entry at end of propagate(). No LLM call."""
+        if not self._log_path:
+            return
+        # Idempotency guard: fast raw-text scan instead of full parse
+        if self._log_path.exists():
+            raw = self._log_path.read_text(encoding="utf-8")
+            for line in raw.splitlines():
+                if line.startswith(f"[{trade_date} | {ticker} |") and line.endswith("| pending]"):
+                    return
+        rating = parse_rating(final_trade_decision)
+        tag = f"[{trade_date} | {ticker} | {rating} | pending]"
+        entry = f"{tag}\n\nDECISION:\n{final_trade_decision}{self._SEPARATOR}"
+        with open(self._log_path, "a", encoding="utf-8") as f:
+            f.write(entry)
+
+    # --- Read path (Phase A) ---
+
+    def load_entries(self) -> List[dict]:
+        """Parse all entries from log. Returns list of dicts."""
+        if not self._log_path or not self._log_path.exists():
+            return []
+        text = self._log_path.read_text(encoding="utf-8")
+        raw_entries = [e.strip() for e in text.split(self._SEPARATOR) if e.strip()]
+        entries = []
+        for raw in raw_entries:
+            parsed = self._parse_entry(raw)
+            if parsed:
+                entries.append(parsed)
+        return entries
+
+    def get_pending_entries(self) -> List[dict]:
+        """Return entries with outcome:pending (for Phase B)."""
+        return [e for e in self.load_entries() if e.get("pending")]
+
+    def get_past_context(self, ticker: str, n_same: int = 5, n_cross: int = 3) -> str:
+        """Return formatted past context string for agent prompt injection."""
+        entries = [e for e in self.load_entries() if not e.get("pending")]
+        if not entries:
+            return ""
+
+        same, cross = [], []
+        for e in reversed(entries):
+            if len(same) >= n_same and len(cross) >= n_cross:
+                break
+            if e["ticker"] == ticker and len(same) < n_same:
+                same.append(e)
+            elif e["ticker"] != ticker and len(cross) < n_cross:
+                cross.append(e)
+
+        if not same and not cross:
+            return ""
+
+        parts = []
+        if same:
+            parts.append(f"Past analyses of {ticker} (most recent first):")
+            parts.extend(self._format_full(e) for e in same)
+        if cross:
+            parts.append("Recent cross-ticker lessons:")
+            parts.extend(self._format_reflection_only(e) for e in cross)
+        return "\n\n".join(parts)
+
+    # --- Update path (Phase B) ---
+
+    def update_with_outcome(
+        self,
+        ticker: str,
+        trade_date: str,
+        raw_return: float,
+        alpha_return: float,
+        holding_days: int,
+        reflection: str,
+    ) -> None:
+        """Replace pending tag and append REFLECTION section using atomic write.
+
+        Finds the first pending entry matching (trade_date, ticker), updates
+        its tag with return figures, and appends a REFLECTION section.  Uses
+        a temp-file + os.replace() so a crash mid-write never corrupts the log.
+        """
+        if not self._log_path or not self._log_path.exists():
+            return
+
+        text = self._log_path.read_text(encoding="utf-8")
+        blocks = text.split(self._SEPARATOR)
+
+        pending_prefix = f"[{trade_date} | {ticker} |"
+        raw_pct = f"{raw_return:+.1%}"
+        alpha_pct = f"{alpha_return:+.1%}"
+
+        updated = False
+        new_blocks = []
+        for block in blocks:
+            stripped = block.strip()
+            if not stripped:
+                new_blocks.append(block)
+                continue
+
+            lines = stripped.splitlines()
+            tag_line = lines[0].strip()
+
+            if (
+                not updated
+                and tag_line.startswith(pending_prefix)
+                and tag_line.endswith("| pending]")
+            ):
+                # Parse rating from the existing pending tag
+                fields = [f.strip() for f in tag_line[1:-1].split("|")]
+                rating = fields[2]
+                new_tag = (
+                    f"[{trade_date} | {ticker} | {rating}"
+                    f" | {raw_pct} | {alpha_pct} | {holding_days}d]"
+                )
+                rest = "\n".join(lines[1:])
+                new_blocks.append(
+                    f"{new_tag}\n\n{rest.lstrip()}\n\nREFLECTION:\n{reflection}"
+                )
+                updated = True
+            else:
+                new_blocks.append(block)
+
+        if not updated:
+            return
+
+        new_blocks = self._apply_rotation(new_blocks)
+        new_text = self._SEPARATOR.join(new_blocks)
+        tmp_path = self._log_path.with_suffix(".tmp")
+        tmp_path.write_text(new_text, encoding="utf-8")
+        tmp_path.replace(self._log_path)
+
+    def batch_update_with_outcomes(self, updates: List[dict]) -> None:
+        """Apply multiple outcome updates in a single read + atomic write.
+
+        Each element of updates must have keys: ticker, trade_date,
+        raw_return, alpha_return, holding_days, reflection.
+        """
+        if not self._log_path or not self._log_path.exists() or not updates:
+            return
+
+        text = self._log_path.read_text(encoding="utf-8")
+        blocks = text.split(self._SEPARATOR)
+
+        # Build lookup keyed by (trade_date, ticker) for O(1) dispatch
+        update_map = {(u["trade_date"], u["ticker"]): u for u in updates}
+
+        new_blocks = []
+        for block in blocks:
+            stripped = block.strip()
+            if not stripped:
+                new_blocks.append(block)
+                continue
+
+            lines = stripped.splitlines()
+            tag_line = lines[0].strip()
+
+            matched = False
+            for (trade_date, ticker), upd in list(update_map.items()):
+                pending_prefix = f"[{trade_date} | {ticker} |"
+                if tag_line.startswith(pending_prefix) and tag_line.endswith("| pending]"):
+                    fields = [f.strip() for f in tag_line[1:-1].split("|")]
+                    rating = fields[2]
+                    raw_pct = f"{upd['raw_return']:+.1%}"
+                    alpha_pct = f"{upd['alpha_return']:+.1%}"
+                    new_tag = (
+                        f"[{trade_date} | {ticker} | {rating}"
+                        f" | {raw_pct} | {alpha_pct} | {upd['holding_days']}d]"
+                    )
+                    rest = "\n".join(lines[1:])
+                    new_blocks.append(
+                        f"{new_tag}\n\n{rest.lstrip()}\n\nREFLECTION:\n{upd['reflection']}"
+                    )
+                    del update_map[(trade_date, ticker)]
+                    matched = True
+                    break
+
+            if not matched:
+                new_blocks.append(block)
+
+        new_blocks = self._apply_rotation(new_blocks)
+        new_text = self._SEPARATOR.join(new_blocks)
+        tmp_path = self._log_path.with_suffix(".tmp")
+        tmp_path.write_text(new_text, encoding="utf-8")
+        tmp_path.replace(self._log_path)
+
+    # --- Helpers ---
+
+    def _apply_rotation(self, blocks: List[str]) -> List[str]:
+        """Drop oldest resolved blocks when their count exceeds max_entries.
+
+        Pending blocks are always kept (they represent unprocessed work).
+        Returns ``blocks`` unchanged when rotation is disabled or under cap.
+        """
+        if not self._max_entries or self._max_entries <= 0:
+            return blocks
+
+        # Tag each block with (kept, is_resolved) by parsing tag-line markers.
+        decisions = []
+        for block in blocks:
+            stripped = block.strip()
+            if not stripped:
+                decisions.append((block, False))
+                continue
+            tag_line = stripped.splitlines()[0].strip()
+            is_resolved = (
+                tag_line.startswith("[")
+                and tag_line.endswith("]")
+                and not tag_line.endswith("| pending]")
+            )
+            decisions.append((block, is_resolved))
+
+        resolved_count = sum(1 for _, r in decisions if r)
+        if resolved_count <= self._max_entries:
+            return blocks
+
+        to_drop = resolved_count - self._max_entries
+        kept: List[str] = []
+        for block, is_resolved in decisions:
+            if is_resolved and to_drop > 0:
+                to_drop -= 1
+                continue
+            kept.append(block)
+        return kept
+
+    def _parse_entry(self, raw: str) -> Optional[dict]:
+        lines = raw.strip().splitlines()
+        if not lines:
+            return None
+        tag_line = lines[0].strip()
+        if not (tag_line.startswith("[") and tag_line.endswith("]")):
+            return None
+        fields = [f.strip() for f in tag_line[1:-1].split("|")]
+        if len(fields) < 4:
+            return None
+        entry = {
+            "date": fields[0],
+            "ticker": fields[1],
+            "rating": fields[2],
+            "pending": fields[3] == "pending",
+            "raw": fields[3] if fields[3] != "pending" else None,
+            "alpha": fields[4] if len(fields) > 4 else None,
+            "holding": fields[5] if len(fields) > 5 else None,
+        }
+        body = "\n".join(lines[1:]).strip()
+        decision_match = self._DECISION_RE.search(body)
+        reflection_match = self._REFLECTION_RE.search(body)
+        entry["decision"] = decision_match.group(1).strip() if decision_match else ""
+        entry["reflection"] = reflection_match.group(1).strip() if reflection_match else ""
+        return entry
+
+    def _format_full(self, e: dict) -> str:
+        raw = e["raw"] or "n/a"
+        alpha = e["alpha"] or "n/a"
+        holding = e["holding"] or "n/a"
+        tag = f"[{e['date']} | {e['ticker']} | {e['rating']} | {raw} | {alpha} | {holding}]"
+        parts = [tag, f"DECISION:\n{e['decision']}"]
+        if e["reflection"]:
+            parts.append(f"REFLECTION:\n{e['reflection']}")
+        return "\n\n".join(parts)
+
+    def _format_reflection_only(self, e: dict) -> str:
+        tag = f"[{e['date']} | {e['ticker']} | {e['rating']} | {e['raw'] or 'n/a'}]"
+        if e["reflection"]:
+            return f"{tag}\n{e['reflection']}"
+        text = e["decision"][:300]
+        suffix = "..." if len(e["decision"]) > 300 else ""
+        return f"{tag}\n{text}{suffix}"

TradingAgents/tradingagents/agents/utils/news_data_tools.py

@@ -0,0 +1,53 @@
+from langchain_core.tools import tool
+from typing import Annotated
+from tradingagents.dataflows.interface import route_to_vendor
+
+@tool
+def get_news(
+    ticker: Annotated[str, "Ticker symbol"],
+    start_date: Annotated[str, "Start date in yyyy-mm-dd format"],
+    end_date: Annotated[str, "End date in yyyy-mm-dd format"],
+) -> str:
+    """
+    Retrieve news data for a given ticker symbol.
+    Uses the configured news_data vendor.
+    Args:
+        ticker (str): Ticker symbol
+        start_date (str): Start date in yyyy-mm-dd format
+        end_date (str): End date in yyyy-mm-dd format
+    Returns:
+        str: A formatted string containing news data
+    """
+    return route_to_vendor("get_news", ticker, start_date, end_date)
+
+@tool
+def get_global_news(
+    curr_date: Annotated[str, "Current date in yyyy-mm-dd format"],
+    look_back_days: Annotated[int, "Number of days to look back"] = 7,
+    limit: Annotated[int, "Maximum number of articles to return"] = 5,
+) -> str:
+    """
+    Retrieve global news data.
+    Uses the configured news_data vendor.
+    Args:
+        curr_date (str): Current date in yyyy-mm-dd format
+        look_back_days (int): Number of days to look back (default 7)
+        limit (int): Maximum number of articles to return (default 5)
+    Returns:
+        str: A formatted string containing global news data
+    """
+    return route_to_vendor("get_global_news", curr_date, look_back_days, limit)
+
+@tool
+def get_insider_transactions(
+    ticker: Annotated[str, "ticker symbol"],
+) -> str:
+    """
+    Retrieve insider transaction information about a company.
+    Uses the configured news_data vendor.
+    Args:
+        ticker (str): Ticker symbol of the company
+    Returns:
+        str: A report of insider transaction data
+    """
+    return route_to_vendor("get_insider_transactions", ticker)

TradingAgents/tradingagents/agents/utils/rating.py

@@ -0,0 +1,50 @@
+"""Shared 5-tier rating vocabulary and a deterministic heuristic parser.
+
+The same five-tier scale (Buy, Overweight, Hold, Underweight, Sell) is used by:
+- The Research Manager (investment plan recommendation)
+- The Portfolio Manager (final position decision)
+- The signal processor (rating extracted for downstream consumers)
+- The memory log (rating tag stored alongside each decision entry)
+
+Centralising it here avoids drift between those call sites.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Tuple
+
+
+# Canonical, ordered 5-tier scale (most bullish to most bearish).
+RATINGS_5_TIER: Tuple[str, ...] = (
+    "Buy", "Overweight", "Hold", "Underweight", "Sell",
+)
+
+_RATING_SET = {r.lower() for r in RATINGS_5_TIER}
+
+# Matches "Rating: X" / "rating - X" / "Rating: **X**" — tolerates markdown
+# bold wrappers and either a colon or hyphen separator.
+_RATING_LABEL_RE = re.compile(r"rating.*?[:\-][\s*]*(\w+)", re.IGNORECASE)
+
+
+def parse_rating(text: str, default: str = "Hold") -> str:
+    """Heuristically extract a 5-tier rating from prose text.
+
+    Two-pass strategy:
+    1. Look for an explicit "Rating: X" label (tolerant of markdown bold).
+    2. Fall back to the first 5-tier rating word found anywhere in the text.
+
+    Returns a Title-cased rating string, or ``default`` if no rating word appears.
+    """
+    for line in text.splitlines():
+        m = _RATING_LABEL_RE.search(line)
+        if m and m.group(1).lower() in _RATING_SET:
+            return m.group(1).capitalize()
+
+    for line in text.splitlines():
+        for word in line.lower().split():
+            clean = word.strip("*:.,")
+            if clean in _RATING_SET:
+                return clean.capitalize()
+
+    return default

TradingAgents/tradingagents/agents/utils/structured.py

@@ -0,0 +1,73 @@
+"""Shared helpers for invoking an agent with structured output and a graceful fallback.
+
+The Portfolio Manager, Trader, and Research Manager all follow the same
+canonical pattern:
+
+1. At agent creation, wrap the LLM with ``with_structured_output(Schema)``
+   so the model returns a typed Pydantic instance. If the provider does
+   not support structured output (rare; mostly older Ollama models), the
+   wrap is skipped and the agent uses free-text generation instead.
+2. At invocation, run the structured call and render the result back to
+   markdown. If the structured call itself fails for any reason
+   (malformed JSON from a weak model, transient provider issue), fall
+   back to a plain ``llm.invoke`` so the pipeline never blocks.
+
+Centralising the pattern here keeps the agent factories small and ensures
+all three agents log the same warnings when fallback fires.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Callable, Optional, TypeVar
+
+from pydantic import BaseModel
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T", bound=BaseModel)
+
+
+def bind_structured(llm: Any, schema: type[T], agent_name: str) -> Optional[Any]:
+    """Return ``llm.with_structured_output(schema)`` or ``None`` if unsupported.
+
+    Logs a warning when the binding fails so the user understands the agent
+    will use free-text generation for every call instead of one-shot fallback.
+    """
+    try:
+        return llm.with_structured_output(schema)
+    except (NotImplementedError, AttributeError) as exc:
+        logger.warning(
+            "%s: provider does not support with_structured_output (%s); "
+            "falling back to free-text generation",
+            agent_name, exc,
+        )
+        return None
+
+
+def invoke_structured_or_freetext(
+    structured_llm: Optional[Any],
+    plain_llm: Any,
+    prompt: Any,
+    render: Callable[[T], str],
+    agent_name: str,
+) -> str:
+    """Run the structured call and render to markdown; fall back to free-text on any failure.
+
+    ``prompt`` is whatever the underlying LLM accepts (a string for chat
+    invocations, a list of message dicts for chat models that take that
+    shape). The same value is forwarded to the free-text path so the
+    fallback sees the same input the structured call did.
+    """
+    if structured_llm is not None:
+        try:
+            result = structured_llm.invoke(prompt)
+            return render(result)
+        except Exception as exc:
+            logger.warning(
+                "%s: structured-output invocation failed (%s); retrying once as free text",
+                agent_name, exc,
+            )
+
+    response = plain_llm.invoke(prompt)
+    return response.content

TradingAgents/tradingagents/agents/utils/technical_indicators_tools.py

@@ -0,0 +1,32 @@
+from langchain_core.tools import tool
+from typing import Annotated
+from tradingagents.dataflows.interface import route_to_vendor
+
+@tool
+def get_indicators(
+    symbol: Annotated[str, "ticker symbol of the company"],
+    indicator: Annotated[str, "technical indicator to get the analysis and report of"],
+    curr_date: Annotated[str, "The current trading date you are trading on, YYYY-mm-dd"],
+    look_back_days: Annotated[int, "how many days to look back"] = 30,
+) -> str:
+    """
+    Retrieve a single technical indicator for a given ticker symbol.
+    Uses the configured technical_indicators vendor.
+    Args:
+        symbol (str): Ticker symbol of the company, e.g. AAPL, TSM
+        indicator (str): A single technical indicator name, e.g. 'rsi', 'macd'. Call this tool once per indicator.
+        curr_date (str): The current trading date you are trading on, YYYY-mm-dd
+        look_back_days (int): How many days to look back, default is 30
+    Returns:
+        str: A formatted dataframe containing the technical indicators for the specified ticker symbol and indicator.
+    """
+    # LLMs sometimes pass multiple indicators as a comma-separated string;
+    # split and process each individually.
+    indicators = [i.strip().lower() for i in indicator.split(",") if i.strip()]
+    results = []
+    for ind in indicators:
+        try:
+            results.append(route_to_vendor("get_indicators", symbol, ind, curr_date, look_back_days))
+        except ValueError as e:
+            results.append(str(e))
+    return "\n\n".join(results)