From ff81333f5b1b62a36890bf3a0fbf70fa98fea0ed Mon Sep 17 00:00:00 2001
From: Copilot <198982749+Copilot@users.noreply.github.com>
Date: Tue, 17 Mar 2026 22:31:40 +0100
Subject: [PATCH] docs: add all environment variables to .env.example (#15)

* Initial plan

* docs: add all environment variables to .env.example

Comprehensively document all 28 TRADINGAGENTS_* config overrides and 6 API
keys used by the framework, organized into logical sections with inline
comments showing defaults and valid options.

Co-authored-by: aguzererler <6199053+aguzererler@users.noreply.github.com>

* Update .env.example

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: aguzererler <6199053+aguzererler@users.noreply.github.com>
Co-authored-by: ahmet guzererler <guzererler@gmail.com>
---
 .env.example | 74 ++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 60 insertions(+), 14 deletions(-)

diff --git a/.env.example b/.env.example
index 47ac745d..952da298 100644
--- a/.env.example
+++ b/.env.example
@@ -1,23 +1,69 @@
-# LLM Provider API Keys (set the ones you use)
+# ── LLM Provider API Keys ────────────────────────────────────────────
+# Set the key(s) for the provider(s) you use.
 OPENAI_API_KEY=
 GOOGLE_API_KEY=
 ANTHROPIC_API_KEY=
 XAI_API_KEY=
 OPENROUTER_API_KEY=
 
-# Data Provider API Keys
+# ── Data Provider API Keys ───────────────────────────────────────────
 ALPHA_VANTAGE_API_KEY=
 
+TRADINGAGENTS_RESULTS_DIR=./my_results
+TRADINGAGENTS_MAX_DEBATE_ROUNDS=2
+#TRADINGAGENTS_VENDOR_SCANNER_DATA=alpha_vantage
+
 # ── Configuration overrides ──────────────────────────────────────────
-# Any setting in DEFAULT_CONFIG can be overridden with a
-# TRADINGAGENTS_<KEY> environment variable.  Unset or empty values
-# are ignored (the hardcoded default is kept).
-#
-# Examples:
-#   TRADINGAGENTS_LLM_PROVIDER=openrouter
-#   TRADINGAGENTS_QUICK_THINK_LLM=deepseek/deepseek-chat-v3-0324
-#   TRADINGAGENTS_DEEP_THINK_LLM=deepseek/deepseek-r1-0528
-#   TRADINGAGENTS_BACKEND_URL=https://openrouter.ai/api/v1
-#   TRADINGAGENTS_RESULTS_DIR=./my_results
-#   TRADINGAGENTS_MAX_DEBATE_ROUNDS=2
-#   TRADINGAGENTS_VENDOR_SCANNER_DATA=alpha_vantage
+# Any setting in DEFAULT_CONFIG (tradingagents/default_config.py) can be
+# overridden with a TRADINGAGENTS_<KEY> environment variable.
+# Unset or empty values are ignored (the hardcoded default is kept).
+
+# ── General ──────────────────────────────────────────────────────────
+# TRADINGAGENTS_RESULTS_DIR=./results
+
+# ── LLM model selection ─────────────────────────────────────────────
+# Top-level provider & model (applies to all tiers unless overridden)
+# TRADINGAGENTS_LLM_PROVIDER=openai          # openai | google | anthropic | xai | openrouter | ollama
+# TRADINGAGENTS_BACKEND_URL=https://api.openai.com/v1
+
+# Deep-think tier (complex reasoning — e.g. research manager, risk judge)
+# TRADINGAGENTS_DEEP_THINK_LLM=gpt-5.2
+# TRADINGAGENTS_DEEP_THINK_LLM_PROVIDER=     # override provider for this tier only
+# TRADINGAGENTS_DEEP_THINK_BACKEND_URL=       # override backend URL for this tier only
+
+# Mid-think tier (balanced analysis — e.g. debate agents)
+# Falls back to quick_think_llm when left empty.
+# TRADINGAGENTS_MID_THINK_LLM=
+# TRADINGAGENTS_MID_THINK_LLM_PROVIDER=
+# TRADINGAGENTS_MID_THINK_BACKEND_URL=
+
+# Quick-think tier (fast responses — e.g. analysts, scanners)
+# TRADINGAGENTS_QUICK_THINK_LLM=gpt-5-mini
+# TRADINGAGENTS_QUICK_THINK_LLM_PROVIDER=
+# TRADINGAGENTS_QUICK_THINK_BACKEND_URL=
+
+# ── Provider-specific thinking / reasoning controls ──────────────────
+# Global (applies to all tiers unless overridden per-tier below)
+# TRADINGAGENTS_GOOGLE_THINKING_LEVEL=       # "high", "minimal", etc.
+# TRADINGAGENTS_OPENAI_REASONING_EFFORT=     # "low", "medium", "high"
+
+# Per-tier overrides
+# TRADINGAGENTS_DEEP_THINK_GOOGLE_THINKING_LEVEL=
+# TRADINGAGENTS_DEEP_THINK_OPENAI_REASONING_EFFORT=
+# TRADINGAGENTS_MID_THINK_GOOGLE_THINKING_LEVEL=
+# TRADINGAGENTS_MID_THINK_OPENAI_REASONING_EFFORT=
+# TRADINGAGENTS_QUICK_THINK_GOOGLE_THINKING_LEVEL=
+# TRADINGAGENTS_QUICK_THINK_OPENAI_REASONING_EFFORT=
+
+# ── Debate & discussion settings ─────────────────────────────────────
+# TRADINGAGENTS_MAX_DEBATE_ROUNDS=1          # bull/bear investment debate rounds (1–5)
+# TRADINGAGENTS_MAX_RISK_DISCUSS_ROUNDS=1    # risk analyst discussion rounds (1–5)
+# TRADINGAGENTS_MAX_RECUR_LIMIT=100          # LangGraph recursion limit
+
+# ── Data vendor routing ──────────────────────────────────────────────
+# Category-level vendor selection (yfinance | alpha_vantage)
+# TRADINGAGENTS_VENDOR_CORE_STOCK_APIS=yfinance
+# TRADINGAGENTS_VENDOR_TECHNICAL_INDICATORS=yfinance
+# TRADINGAGENTS_VENDOR_FUNDAMENTAL_DATA=yfinance
+# TRADINGAGENTS_VENDOR_NEWS_DATA=yfinance
+# TRADINGAGENTS_VENDOR_SCANNER_DATA=yfinance