docs: Comprehensive .env.example and configuration guide
Major updates to environment configuration: ## .env.example Updates (291 lines) - Added 7 deployment scenarios with complete examples - Scenario 1: OpenAI Everything (Production) - Scenario 2: OpenRouter + OpenAI Embeddings (Cost Optimized) - Scenario 3: All Local with Ollama (Privacy/Offline) - Scenario 4: Anthropic + OpenAI Embeddings (High Quality) - Scenario 5: Google Gemini + OpenAI Embeddings (Balanced) - Scenario 6: OpenRouter + No Memory (Minimal) - Scenario 7: Mixed Models (Advanced) Each scenario includes: - Complete configuration example - Use case description - Pros/cons analysis - Cost estimates - Prerequisites ## New Documentation - docs/CONFIGURATION_GUIDE.md (691 lines) - Complete setup guide for all scenarios - API key acquisition instructions - CLI vs Module usage comparison - Environment variable reference - Troubleshooting section - Security best practices ## Additional Features - API key sources and links - Security notes and best practices - Troubleshooting common issues - Configuration validation checklist - Multiple deployment patterns - Cost optimization strategies Makes it easy for users to: - Choose the right setup for their needs - Understand cost implications - Configure mixed provider scenarios - Troubleshoot authentication issues - Switch between CLI and module usage
This commit is contained in:
Surapong Kanoktipsatharporn
parent
3eab3e81cb
commit
08bad661c3
296
.env.example
296
.env.example
|
|
@ -1,11 +1,291 @@
|
|||
# For OpenAI (default)
|
||||
OPENAI_API_KEY=your_openai_api_key_here
|
||||
ALPHA_VANTAGE_API_KEY=your_alpha_vantage_key_here
|
||||
TRADINGAGENTS_LLM_PROVIDER=openai
|
||||
TRADINGAGENTS_BACKEND_URL=https://api.openai.com/v1
|
||||
# ============================================================================
|
||||
# TradingAgents Environment Configuration
|
||||
# ============================================================================
|
||||
#
|
||||
# This file contains example configurations for different deployment scenarios.
|
||||
# Copy this file to .env and uncomment/modify the section that matches your setup.
|
||||
#
|
||||
# Quick Start:
|
||||
# 1. Copy this file: cp .env.example .env
|
||||
# 2. Choose a scenario below and uncomment it
|
||||
# 3. Add your actual API keys
|
||||
# 4. Run TradingAgents!
|
||||
#
|
||||
# ============================================================================
|
||||
|
||||
# For OpenRouter
|
||||
# OPENROUTER_API_KEY=your_openrouter_api_key_here # OpenRouter uses OPENAI_API_KEY env var
|
||||
# ALPHA_VANTAGE_API_KEY=your_alpha_vantage_key_here
|
||||
# ============================================================================
|
||||
# SCENARIO 1: OpenAI Everything (Recommended for Production)
|
||||
# ============================================================================
|
||||
# Use OpenAI for both chat models and embeddings
|
||||
# Best for: Production deployment with full features
|
||||
# Cost: Moderate (chat + embeddings)
|
||||
# ============================================================================
|
||||
|
||||
OPENAI_API_KEY=sk-proj-your_openai_api_key_here
|
||||
ALPHA_VANTAGE_API_KEY=your_alpha_vantage_api_key_here
|
||||
|
||||
# Optional: Explicitly set provider (defaults to openai)
|
||||
# TRADINGAGENTS_LLM_PROVIDER=openai
|
||||
# TRADINGAGENTS_BACKEND_URL=https://api.openai.com/v1
|
||||
# TRADINGAGENTS_EMBEDDING_PROVIDER=openai
|
||||
# TRADINGAGENTS_EMBEDDING_BACKEND_URL=https://api.openai.com/v1
|
||||
|
||||
|
||||
# ============================================================================
|
||||
# SCENARIO 2: OpenRouter Chat + OpenAI Embeddings (Cost Optimized)
|
||||
# ============================================================================
|
||||
# Use OpenRouter for free/cheap chat models, OpenAI for reliable embeddings
|
||||
# Best for: Development, testing, cost optimization
|
||||
# Cost: Low (free chat) + Low (embeddings only)
|
||||
# ============================================================================
|
||||
|
||||
# OPENROUTER_API_KEY=sk-or-v1-your_openrouter_api_key_here
|
||||
# OPENAI_API_KEY=sk-proj-your_openai_api_key_here
|
||||
# ALPHA_VANTAGE_API_KEY=your_alpha_vantage_api_key_here
|
||||
#
|
||||
# TRADINGAGENTS_LLM_PROVIDER=openrouter
|
||||
# TRADINGAGENTS_BACKEND_URL=https://openrouter.ai/api/v1
|
||||
# TRADINGAGENTS_EMBEDDING_PROVIDER=openai
|
||||
# TRADINGAGENTS_EMBEDDING_BACKEND_URL=https://api.openai.com/v1
|
||||
|
||||
|
||||
# ============================================================================
|
||||
# SCENARIO 3: All Local with Ollama (Offline/Private)
|
||||
# ============================================================================
|
||||
# Run completely offline with local Ollama models
|
||||
# Best for: Privacy, offline deployment, no API costs
|
||||
# Cost: Free (requires local compute)
|
||||
# Prerequisites:
|
||||
# - Install Ollama: https://ollama.ai
|
||||
# - Pull models: ollama pull llama3.1 llama3.2 nomic-embed-text
|
||||
# ============================================================================
|
||||
|
||||
# ALPHA_VANTAGE_API_KEY=your_alpha_vantage_api_key_here
|
||||
#
|
||||
# TRADINGAGENTS_LLM_PROVIDER=ollama
|
||||
# TRADINGAGENTS_BACKEND_URL=http://localhost:11434/v1
|
||||
# TRADINGAGENTS_EMBEDDING_PROVIDER=ollama
|
||||
# TRADINGAGENTS_EMBEDDING_BACKEND_URL=http://localhost:11434/v1
|
||||
# TRADINGAGENTS_EMBEDDING_MODEL=nomic-embed-text
|
||||
|
||||
|
||||
# ============================================================================
|
||||
# SCENARIO 4: Anthropic Chat + OpenAI Embeddings
|
||||
# ============================================================================
|
||||
# Use Claude models for chat, OpenAI for embeddings
|
||||
# Best for: High-quality reasoning with reliable embeddings
|
||||
# Cost: High (Claude) + Low (embeddings only)
|
||||
# ============================================================================
|
||||
|
||||
# ANTHROPIC_API_KEY=sk-ant-your_anthropic_api_key_here
|
||||
# OPENAI_API_KEY=sk-proj-your_openai_api_key_here
|
||||
# ALPHA_VANTAGE_API_KEY=your_alpha_vantage_api_key_here
|
||||
#
|
||||
# TRADINGAGENTS_LLM_PROVIDER=anthropic
|
||||
# TRADINGAGENTS_BACKEND_URL=https://api.anthropic.com/
|
||||
# TRADINGAGENTS_EMBEDDING_PROVIDER=openai
|
||||
# TRADINGAGENTS_EMBEDDING_BACKEND_URL=https://api.openai.com/v1
|
||||
|
||||
|
||||
# ============================================================================
|
||||
# SCENARIO 5: Google Gemini Chat + OpenAI Embeddings
|
||||
# ============================================================================
|
||||
# Use Google Gemini models for chat, OpenAI for embeddings
|
||||
# Best for: Cost-effective with good performance
|
||||
# Cost: Low-Moderate
|
||||
# ============================================================================
|
||||
|
||||
# GOOGLE_API_KEY=your_google_api_key_here
|
||||
# OPENAI_API_KEY=sk-proj-your_openai_api_key_here
|
||||
# ALPHA_VANTAGE_API_KEY=your_alpha_vantage_api_key_here
|
||||
#
|
||||
# TRADINGAGENTS_LLM_PROVIDER=google
|
||||
# TRADINGAGENTS_BACKEND_URL=https://generativelanguage.googleapis.com/v1
|
||||
# TRADINGAGENTS_EMBEDDING_PROVIDER=openai
|
||||
# TRADINGAGENTS_EMBEDDING_BACKEND_URL=https://api.openai.com/v1
|
||||
|
||||
|
||||
# ============================================================================
|
||||
# SCENARIO 6: OpenRouter Chat + No Memory (Minimal)
|
||||
# ============================================================================
|
||||
# Use OpenRouter without memory/embeddings
|
||||
# Best for: Testing, debugging, minimal cost
|
||||
# Cost: Very Low (chat only, no embeddings)
|
||||
# Note: Agents will run without historical context
|
||||
# ============================================================================
|
||||
|
||||
# OPENROUTER_API_KEY=sk-or-v1-your_openrouter_api_key_here
|
||||
# ALPHA_VANTAGE_API_KEY=your_alpha_vantage_api_key_here
|
||||
#
|
||||
# TRADINGAGENTS_LLM_PROVIDER=openrouter
|
||||
# TRADINGAGENTS_BACKEND_URL=https://openrouter.ai/api/v1
|
||||
# TRADINGAGENTS_ENABLE_MEMORY=false
|
||||
|
||||
|
||||
# ============================================================================
|
||||
# SCENARIO 7: Mixed Models (Advanced)
|
||||
# ============================================================================
|
||||
# Use different providers for different components
|
||||
# Best for: Advanced users optimizing for cost/performance
|
||||
# ============================================================================
|
||||
|
||||
# # Chat models
|
||||
# OPENROUTER_API_KEY=sk-or-v1-your_openrouter_api_key_here
|
||||
# TRADINGAGENTS_LLM_PROVIDER=openrouter
|
||||
# TRADINGAGENTS_BACKEND_URL=https://openrouter.ai/api/v1
|
||||
# TRADINGAGENTS_DEEP_THINK_LLM=deepseek/deepseek-chat-v3-0324:free
|
||||
# TRADINGAGENTS_QUICK_THINK_LLM=meta-llama/llama-3.3-8b-instruct:free
|
||||
#
|
||||
# # Embeddings
|
||||
# OPENAI_API_KEY=sk-proj-your_openai_api_key_here
|
||||
# TRADINGAGENTS_EMBEDDING_PROVIDER=openai
|
||||
# TRADINGAGENTS_EMBEDDING_BACKEND_URL=https://api.openai.com/v1
|
||||
# TRADINGAGENTS_EMBEDDING_MODEL=text-embedding-3-small
|
||||
#
|
||||
# # Data sources
|
||||
# ALPHA_VANTAGE_API_KEY=your_alpha_vantage_api_key_here
|
||||
|
||||
|
||||
# ============================================================================
|
||||
# Additional Configuration Options
|
||||
# ============================================================================
|
||||
|
||||
# Logging Configuration
|
||||
# TRADINGAGENTS_LOG_LEVEL=INFO # DEBUG, INFO, WARNING, ERROR, CRITICAL
|
||||
# TRADINGAGENTS_LOG_DIR=logs # Directory for log files
|
||||
# TRADINGAGENTS_LOG_TO_CONSOLE=true # Enable console logging
|
||||
# TRADINGAGENTS_LOG_TO_FILE=true # Enable file logging
|
||||
|
||||
# Memory/Embedding Configuration
|
||||
# TRADINGAGENTS_ENABLE_MEMORY=true # Enable/disable memory system
|
||||
# TRADINGAGENTS_EMBEDDING_MODEL=text-embedding-3-small # Embedding model
|
||||
|
||||
# Research Depth
|
||||
# TRADINGAGENTS_MAX_DEBATE_ROUNDS=1 # Number of debate rounds (1-5)
|
||||
# TRADINGAGENTS_MAX_RISK_DISCUSS_ROUNDS=1 # Risk discussion rounds (1-5)
|
||||
|
||||
# Data Vendors
|
||||
# TRADINGAGENTS_CORE_STOCK_API=yfinance # yfinance, alpha_vantage, local
|
||||
# TRADINGAGENTS_TECHNICAL_INDICATORS=yfinance
|
||||
# TRADINGAGENTS_FUNDAMENTAL_DATA=alpha_vantage
|
||||
# TRADINGAGENTS_NEWS_DATA=alpha_vantage
|
||||
|
||||
|
||||
# ============================================================================
|
||||
# CLI vs Module Usage
|
||||
# ============================================================================
|
||||
|
||||
# Option A: CLI Usage (Interactive)
|
||||
# ------------------------------------
|
||||
# When running via CLI, the interactive prompts will guide you through
|
||||
# selecting providers, models, and embedding options.
|
||||
#
|
||||
# Usage:
|
||||
# python -m cli.main
|
||||
#
|
||||
# The CLI will:
|
||||
# 1. Ask for ticker symbol
|
||||
# 2. Ask for analysis date
|
||||
# 3. Ask for analyst selection
|
||||
# 4. Ask for research depth
|
||||
# 5. Ask for LLM provider
|
||||
# 6. Ask for thinking agents
|
||||
# 7. Ask for embedding provider ← NEW!
|
||||
#
|
||||
# Environment variables in this file provide defaults and API keys.
|
||||
|
||||
|
||||
# Option B: Module Usage (Programmatic)
|
||||
# ---------------------------------------
|
||||
# When using TradingAgents as a Python module, you configure everything
|
||||
# in code using the config dictionary.
|
||||
#
|
||||
# Example:
|
||||
# from tradingagents.graph.trading_graph import TradingAgentsGraph
|
||||
#
|
||||
# config = {
|
||||
# "llm_provider": "openrouter",
|
||||
# "backend_url": "https://openrouter.ai/api/v1",
|
||||
# "deep_think_llm": "deepseek/deepseek-chat-v3-0324:free",
|
||||
# "quick_think_llm": "meta-llama/llama-3.3-8b-instruct:free",
|
||||
#
|
||||
# "embedding_provider": "openai",
|
||||
# "embedding_backend_url": "https://api.openai.com/v1",
|
||||
# "embedding_model": "text-embedding-3-small",
|
||||
# "enable_memory": True,
|
||||
#
|
||||
# "log_level": "INFO",
|
||||
# }
|
||||
#
|
||||
# graph = TradingAgentsGraph(["market", "news"], config=config)
|
||||
# final_state, decision = graph.propagate("AAPL", "2025-01-15")
|
||||
|
||||
|
||||
# ============================================================================
|
||||
# API Key Sources & Links
|
||||
# ============================================================================
|
||||
|
||||
# OpenAI API Key
|
||||
# Get from: https://platform.openai.com/api-keys
|
||||
# Format: sk-proj-...
|
||||
|
||||
# OpenRouter API Key
|
||||
# Get from: https://openrouter.ai/keys
|
||||
# Format: sk-or-v1-...
|
||||
|
||||
# Anthropic API Key
|
||||
# Get from: https://console.anthropic.com/
|
||||
# Format: sk-ant-...
|
||||
|
||||
# Google API Key
|
||||
# Get from: https://makersuite.google.com/app/apikey
|
||||
# Format: AI...
|
||||
|
||||
# Alpha Vantage API Key
|
||||
# Get from: https://www.alphavantage.co/support/#api-key
|
||||
# Format: alphanumeric string
|
||||
|
||||
|
||||
# ============================================================================
|
||||
# Security Notes
|
||||
# ============================================================================
|
||||
|
||||
# 1. NEVER commit this file with real API keys to version control
|
||||
# 2. Add .env to your .gitignore file
|
||||
# 3. Use separate API keys for development and production
|
||||
# 4. Rotate keys regularly
|
||||
# 5. Use least-privilege keys when possible
|
||||
# 6. Monitor API usage and set spending limits
|
||||
|
||||
|
||||
# ============================================================================
|
||||
# Troubleshooting
|
||||
# ============================================================================
|
||||
|
||||
# Issue: "No auth credentials found"
|
||||
# Solution: Make sure the correct API key is set for your provider
|
||||
# - OpenRouter needs: OPENROUTER_API_KEY
|
||||
# - OpenAI needs: OPENAI_API_KEY (for chat AND embeddings if used)
|
||||
# - Anthropic needs: ANTHROPIC_API_KEY
|
||||
# - Google needs: GOOGLE_API_KEY
|
||||
|
||||
# Issue: "Failed to get embedding: 401 Unauthorized"
|
||||
# Solution: Set OPENAI_API_KEY if using OpenAI for embeddings,
|
||||
# even if using a different provider for chat
|
||||
|
||||
# Issue: Memory disabled unexpectedly
|
||||
# Solution: Check TRADINGAGENTS_ENABLE_MEMORY=true and that
|
||||
# embedding provider is set correctly
|
||||
|
||||
# Check your environment:
|
||||
# python3 check_env_setup.py
|
||||
|
||||
# For more help:
|
||||
# - docs/EMBEDDING_CONFIGURATION.md
|
||||
# - docs/LOGGING.md
|
||||
# - FEATURE_EMBEDDING_README.md
|
||||
|
||||
|
||||
# ============================================================================
|
||||
# End of Configuration
|
||||
# ============================================================================
|
||||
|
|
|
|||
|
|
@ -0,0 +1,691 @@
|
|||
# TradingAgents Configuration Guide
|
||||
|
||||
**Complete guide to configuring TradingAgents for different scenarios**
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Quick Start](#quick-start)
|
||||
2. [Configuration Methods](#configuration-methods)
|
||||
3. [Deployment Scenarios](#deployment-scenarios)
|
||||
4. [API Keys Setup](#api-keys-setup)
|
||||
5. [Configuration Reference](#configuration-reference)
|
||||
6. [CLI vs Module Usage](#cli-vs-module-usage)
|
||||
7. [Environment Variables](#environment-variables)
|
||||
8. [Troubleshooting](#troubleshooting)
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Copy Environment Template
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
### 2. Choose Your Scenario
|
||||
|
||||
Open `.env` and uncomment one of the scenarios:
|
||||
|
||||
- **Scenario 1**: OpenAI Everything (Recommended)
|
||||
- **Scenario 2**: OpenRouter + OpenAI Embeddings (Cost Optimized)
|
||||
- **Scenario 3**: All Local with Ollama (Offline/Private)
|
||||
- **Scenario 4**: Anthropic + OpenAI Embeddings
|
||||
- **Scenario 5**: Google Gemini + OpenAI Embeddings
|
||||
- **Scenario 6**: OpenRouter + No Memory (Minimal)
|
||||
- **Scenario 7**: Mixed Models (Advanced)
|
||||
|
||||
### 3. Add Your API Keys
|
||||
|
||||
Replace placeholder values with your actual API keys.
|
||||
|
||||
### 4. Run TradingAgents
|
||||
|
||||
**CLI Mode:**
|
||||
```bash
|
||||
python -m cli.main
|
||||
```
|
||||
|
||||
**Module Mode:**
|
||||
```python
|
||||
from tradingagents.graph.trading_graph import TradingAgentsGraph
|
||||
|
||||
graph = TradingAgentsGraph(["market", "news"])
|
||||
final_state, decision = graph.propagate("AAPL", "2025-01-15")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuration Methods
|
||||
|
||||
### Method 1: Environment Variables (.env file)
|
||||
|
||||
**Best for**: CLI usage, development
|
||||
|
||||
```bash
|
||||
# .env file
|
||||
OPENAI_API_KEY=sk-proj-...
|
||||
OPENROUTER_API_KEY=sk-or-v1-...
|
||||
TRADINGAGENTS_LLM_PROVIDER=openrouter
|
||||
```
|
||||
|
||||
The system automatically loads `.env` file on startup.
|
||||
|
||||
### Method 2: Config Dictionary (Python)
|
||||
|
||||
**Best for**: Module usage, programmatic control
|
||||
|
||||
```python
|
||||
config = {
|
||||
"llm_provider": "openrouter",
|
||||
"backend_url": "https://openrouter.ai/api/v1",
|
||||
"deep_think_llm": "deepseek/deepseek-chat-v3-0324:free",
|
||||
"quick_think_llm": "meta-llama/llama-3.3-8b-instruct:free",
|
||||
|
||||
"embedding_provider": "openai",
|
||||
"embedding_backend_url": "https://api.openai.com/v1",
|
||||
"enable_memory": True,
|
||||
}
|
||||
|
||||
graph = TradingAgentsGraph(["market"], config=config)
|
||||
```
|
||||
|
||||
### Method 3: CLI Interactive
|
||||
|
||||
**Best for**: Quick testing, exploration
|
||||
|
||||
```bash
|
||||
python -m cli.main
|
||||
```
|
||||
|
||||
Follow the interactive prompts to select:
|
||||
- Ticker symbol
|
||||
- Analysis date
|
||||
- Analysts team
|
||||
- Research depth
|
||||
- LLM provider
|
||||
- Thinking agents
|
||||
- Embedding provider
|
||||
|
||||
---
|
||||
|
||||
## Deployment Scenarios
|
||||
|
||||
### Scenario 1: OpenAI Everything ⭐ Recommended
|
||||
|
||||
**Use Case**: Production deployment with full features
|
||||
|
||||
**Configuration:**
|
||||
|
||||
```bash
|
||||
# .env
|
||||
OPENAI_API_KEY=sk-proj-your_key_here
|
||||
ALPHA_VANTAGE_API_KEY=your_key_here
|
||||
```
|
||||
|
||||
**Pros:**
|
||||
- ✅ Full feature support
|
||||
- ✅ Reliable and fast
|
||||
- ✅ Single provider simplicity
|
||||
|
||||
**Cons:**
|
||||
- 💰 Moderate cost (chat + embeddings)
|
||||
|
||||
**Cost**: ~$0.50-$2.00 per analysis (depending on depth)
|
||||
|
||||
---
|
||||
|
||||
### Scenario 2: OpenRouter + OpenAI Embeddings 💰 Cost Optimized
|
||||
|
||||
**Use Case**: Development, testing, cost optimization
|
||||
|
||||
**Configuration:**
|
||||
|
||||
```bash
|
||||
# .env
|
||||
OPENROUTER_API_KEY=sk-or-v1-your_key_here
|
||||
OPENAI_API_KEY=sk-proj-your_key_here
|
||||
ALPHA_VANTAGE_API_KEY=your_key_here
|
||||
|
||||
TRADINGAGENTS_LLM_PROVIDER=openrouter
|
||||
TRADINGAGENTS_BACKEND_URL=https://openrouter.ai/api/v1
|
||||
TRADINGAGENTS_EMBEDDING_PROVIDER=openai
|
||||
TRADINGAGENTS_EMBEDDING_BACKEND_URL=https://api.openai.com/v1
|
||||
```
|
||||
|
||||
**Pros:**
|
||||
- ✅ Very low cost (free chat models)
|
||||
- ✅ Full memory/embedding support
|
||||
- ✅ Good for development
|
||||
|
||||
**Cons:**
|
||||
- ⚠️ Free models may be slower
|
||||
- ⚠️ Quality varies by model
|
||||
|
||||
**Cost**: ~$0.05-$0.20 per analysis (embeddings only)
|
||||
|
||||
---
|
||||
|
||||
### Scenario 3: All Local with Ollama 🔒 Privacy First
|
||||
|
||||
**Use Case**: Offline deployment, privacy requirements, no API costs
|
||||
|
||||
**Prerequisites:**
|
||||
|
||||
```bash
|
||||
# Install Ollama
|
||||
# Visit: https://ollama.ai
|
||||
|
||||
# Pull required models
|
||||
ollama pull llama3.1
|
||||
ollama pull llama3.2
|
||||
ollama pull nomic-embed-text
|
||||
```
|
||||
|
||||
**Configuration:**
|
||||
|
||||
```bash
|
||||
# .env
|
||||
ALPHA_VANTAGE_API_KEY=your_key_here
|
||||
|
||||
TRADINGAGENTS_LLM_PROVIDER=ollama
|
||||
TRADINGAGENTS_BACKEND_URL=http://localhost:11434/v1
|
||||
TRADINGAGENTS_EMBEDDING_PROVIDER=ollama
|
||||
TRADINGAGENTS_EMBEDDING_BACKEND_URL=http://localhost:11434/v1
|
||||
TRADINGAGENTS_EMBEDDING_MODEL=nomic-embed-text
|
||||
```
|
||||
|
||||
**Pros:**
|
||||
- ✅ Completely free
|
||||
- ✅ Full privacy (no data leaves your machine)
|
||||
- ✅ Works offline
|
||||
- ✅ No rate limits
|
||||
|
||||
**Cons:**
|
||||
- ⚠️ Requires local compute resources
|
||||
- ⚠️ Slower than cloud APIs
|
||||
- ⚠️ Quality depends on local model
|
||||
|
||||
**Cost**: $0 (requires GPU for best performance)
|
||||
|
||||
---
|
||||
|
||||
### Scenario 4: Anthropic + OpenAI Embeddings 🧠 High Quality
|
||||
|
||||
**Use Case**: High-quality reasoning and analysis
|
||||
|
||||
**Configuration:**
|
||||
|
||||
```bash
|
||||
# .env
|
||||
ANTHROPIC_API_KEY=sk-ant-your_key_here
|
||||
OPENAI_API_KEY=sk-proj-your_key_here
|
||||
ALPHA_VANTAGE_API_KEY=your_key_here
|
||||
|
||||
TRADINGAGENTS_LLM_PROVIDER=anthropic
|
||||
TRADINGAGENTS_BACKEND_URL=https://api.anthropic.com/
|
||||
TRADINGAGENTS_EMBEDDING_PROVIDER=openai
|
||||
TRADINGAGENTS_EMBEDDING_BACKEND_URL=https://api.openai.com/v1
|
||||
```
|
||||
|
||||
**Pros:**
|
||||
- ✅ Excellent reasoning (Claude)
|
||||
- ✅ Long context support
|
||||
- ✅ High-quality outputs
|
||||
|
||||
**Cons:**
|
||||
- 💰 Higher cost
|
||||
|
||||
**Cost**: ~$1.00-$5.00 per analysis (depending on model)
|
||||
|
||||
---
|
||||
|
||||
### Scenario 5: Google Gemini + OpenAI Embeddings 📊 Balanced
|
||||
|
||||
**Use Case**: Cost-effective with good performance
|
||||
|
||||
**Configuration:**
|
||||
|
||||
```bash
|
||||
# .env
|
||||
GOOGLE_API_KEY=your_key_here
|
||||
OPENAI_API_KEY=sk-proj-your_key_here
|
||||
ALPHA_VANTAGE_API_KEY=your_key_here
|
||||
|
||||
TRADINGAGENTS_LLM_PROVIDER=google
|
||||
TRADINGAGENTS_EMBEDDING_PROVIDER=openai
|
||||
```
|
||||
|
||||
**Pros:**
|
||||
- ✅ Good quality/cost ratio
|
||||
- ✅ Fast response times
|
||||
- ✅ Multimodal capabilities
|
||||
|
||||
**Cons:**
|
||||
- ⚠️ Newer, less tested in production
|
||||
|
||||
**Cost**: ~$0.30-$1.00 per analysis
|
||||
|
||||
---
|
||||
|
||||
### Scenario 6: OpenRouter + No Memory 🚀 Minimal
|
||||
|
||||
**Use Case**: Testing, debugging, minimal cost
|
||||
|
||||
**Configuration:**
|
||||
|
||||
```bash
|
||||
# .env
|
||||
OPENROUTER_API_KEY=sk-or-v1-your_key_here
|
||||
ALPHA_VANTAGE_API_KEY=your_key_here
|
||||
|
||||
TRADINGAGENTS_LLM_PROVIDER=openrouter
|
||||
TRADINGAGENTS_BACKEND_URL=https://openrouter.ai/api/v1
|
||||
TRADINGAGENTS_ENABLE_MEMORY=false
|
||||
```
|
||||
|
||||
**Pros:**
|
||||
- ✅ Minimal cost
|
||||
- ✅ Fast setup
|
||||
- ✅ No embedding API needed
|
||||
|
||||
**Cons:**
|
||||
- ⚠️ No historical context
|
||||
- ⚠️ Agents can't learn from past decisions
|
||||
|
||||
**Cost**: ~$0.00-$0.10 per analysis (free models)
|
||||
|
||||
---
|
||||
|
||||
### Scenario 7: Mixed Models 🎛️ Advanced
|
||||
|
||||
**Use Case**: Optimize for specific use cases
|
||||
|
||||
**Configuration:**
|
||||
|
||||
```bash
|
||||
# .env
|
||||
# Cheap chat models
|
||||
OPENROUTER_API_KEY=sk-or-v1-your_key_here
|
||||
TRADINGAGENTS_LLM_PROVIDER=openrouter
|
||||
TRADINGAGENTS_DEEP_THINK_LLM=deepseek/deepseek-chat-v3-0324:free
|
||||
TRADINGAGENTS_QUICK_THINK_LLM=meta-llama/llama-3.3-8b-instruct:free
|
||||
|
||||
# Reliable embeddings
|
||||
OPENAI_API_KEY=sk-proj-your_key_here
|
||||
TRADINGAGENTS_EMBEDDING_PROVIDER=openai
|
||||
TRADINGAGENTS_EMBEDDING_MODEL=text-embedding-3-small
|
||||
|
||||
# Data sources
|
||||
ALPHA_VANTAGE_API_KEY=your_key_here
|
||||
```
|
||||
|
||||
**Pros:**
|
||||
- ✅ Maximum flexibility
|
||||
- ✅ Optimize each component
|
||||
- ✅ Balance cost/performance
|
||||
|
||||
**Cons:**
|
||||
- ⚠️ More complex setup
|
||||
- ⚠️ Multiple API keys required
|
||||
|
||||
**Cost**: Varies based on choices
|
||||
|
||||
---
|
||||
|
||||
## API Keys Setup
|
||||
|
||||
### OpenAI
|
||||
|
||||
1. Visit: https://platform.openai.com/api-keys
|
||||
2. Click "Create new secret key"
|
||||
3. Copy key (format: `sk-proj-...`)
|
||||
4. Add to `.env`: `OPENAI_API_KEY=sk-proj-...`
|
||||
|
||||
**Used for**: Chat models, embeddings
|
||||
|
||||
### OpenRouter
|
||||
|
||||
1. Visit: https://openrouter.ai/keys
|
||||
2. Create account and generate key
|
||||
3. Copy key (format: `sk-or-v1-...`)
|
||||
4. Add to `.env`: `OPENROUTER_API_KEY=sk-or-v1-...`
|
||||
|
||||
**Used for**: Chat models (many providers)
|
||||
|
||||
### Anthropic
|
||||
|
||||
1. Visit: https://console.anthropic.com/
|
||||
2. Navigate to API Keys
|
||||
3. Create new key (format: `sk-ant-...`)
|
||||
4. Add to `.env`: `ANTHROPIC_API_KEY=sk-ant-...`
|
||||
|
||||
**Used for**: Claude chat models
|
||||
|
||||
### Google
|
||||
|
||||
1. Visit: https://makersuite.google.com/app/apikey
|
||||
2. Create API key
|
||||
3. Copy key (format: `AI...`)
|
||||
4. Add to `.env`: `GOOGLE_API_KEY=AI...`
|
||||
|
||||
**Used for**: Gemini chat models
|
||||
|
||||
### Alpha Vantage
|
||||
|
||||
1. Visit: https://www.alphavantage.co/support/#api-key
|
||||
2. Get free API key
|
||||
3. Add to `.env`: `ALPHA_VANTAGE_API_KEY=...`
|
||||
|
||||
**Used for**: Financial data, news
|
||||
|
||||
---
|
||||
|
||||
## Configuration Reference
|
||||
|
||||
### Complete Config Dictionary
|
||||
|
||||
```python
|
||||
config = {
|
||||
# LLM Provider Settings
|
||||
"llm_provider": "openai", # openai, openrouter, anthropic, google, ollama
|
||||
"backend_url": "https://api.openai.com/v1",
|
||||
"deep_think_llm": "o4-mini", # Model for deep reasoning
|
||||
"quick_think_llm": "gpt-4o-mini", # Model for quick tasks
|
||||
|
||||
# Embedding Settings (Separate from chat)
|
||||
"embedding_provider": "openai", # openai, ollama, none
|
||||
"embedding_backend_url": "https://api.openai.com/v1",
|
||||
"embedding_model": "text-embedding-3-small",
|
||||
"enable_memory": True, # Enable/disable memory system
|
||||
|
||||
# Logging Settings
|
||||
"log_level": "INFO", # DEBUG, INFO, WARNING, ERROR, CRITICAL
|
||||
"log_dir": "logs",
|
||||
"log_to_console": True,
|
||||
"log_to_file": True,
|
||||
|
||||
# Research Settings
|
||||
"max_debate_rounds": 1, # 1-5, higher = deeper analysis
|
||||
"max_risk_discuss_rounds": 1, # 1-5, higher = more thorough risk assessment
|
||||
|
||||
# Data Vendor Settings
|
||||
"data_vendors": {
|
||||
"core_stock_apis": "yfinance", # yfinance, alpha_vantage, local
|
||||
"technical_indicators": "yfinance",
|
||||
"fundamental_data": "alpha_vantage",
|
||||
"news_data": "alpha_vantage",
|
||||
},
|
||||
|
||||
# Directory Settings
|
||||
"project_dir": ".",
|
||||
"results_dir": "./results",
|
||||
"data_cache_dir": "./dataflows/data_cache",
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CLI vs Module Usage
|
||||
|
||||
### CLI Usage (Interactive)
|
||||
|
||||
**When to use**: Quick analysis, exploration, non-technical users
|
||||
|
||||
**Run:**
|
||||
```bash
|
||||
python -m cli.main
|
||||
```
|
||||
|
||||
**Workflow:**
|
||||
1. Select ticker (e.g., AAPL)
|
||||
2. Select date
|
||||
3. Choose analysts (market, news, fundamentals, social)
|
||||
4. Choose research depth (shallow, medium, deep)
|
||||
5. Choose LLM provider (OpenAI, OpenRouter, Anthropic, Google, Ollama)
|
||||
6. Choose thinking agents (quick/deep models)
|
||||
7. Choose embedding provider (OpenAI, Ollama, Disable)
|
||||
|
||||
**Configuration:**
|
||||
- API keys from `.env` file
|
||||
- Prompts guide you through options
|
||||
- Results saved to `results/` directory
|
||||
|
||||
### Module Usage (Programmatic)
|
||||
|
||||
**When to use**: Automation, integration, batch processing
|
||||
|
||||
**Example:**
|
||||
|
||||
```python
|
||||
from tradingagents.graph.trading_graph import TradingAgentsGraph
|
||||
from datetime import datetime
|
||||
|
||||
# Configure
|
||||
config = {
|
||||
"llm_provider": "openrouter",
|
||||
"backend_url": "https://openrouter.ai/api/v1",
|
||||
"deep_think_llm": "deepseek/deepseek-chat-v3-0324:free",
|
||||
"quick_think_llm": "meta-llama/llama-3.3-8b-instruct:free",
|
||||
"embedding_provider": "openai",
|
||||
"embedding_backend_url": "https://api.openai.com/v1",
|
||||
"enable_memory": True,
|
||||
"log_level": "INFO",
|
||||
}
|
||||
|
||||
# Initialize
|
||||
graph = TradingAgentsGraph(
|
||||
selected_analysts=["market", "news", "fundamentals"],
|
||||
config=config,
|
||||
debug=False
|
||||
)
|
||||
|
||||
# Run analysis
|
||||
tickers = ["AAPL", "GOOGL", "MSFT"]
|
||||
for ticker in tickers:
|
||||
final_state, decision = graph.propagate(ticker, datetime.now().strftime("%Y-%m-%d"))
|
||||
print(f"{ticker}: {decision}")
|
||||
|
||||
# Optionally reflect on results
|
||||
# graph.reflect_and_remember(returns_losses)
|
||||
```
|
||||
|
||||
**Configuration:**
|
||||
- Full control in code
|
||||
- No interactive prompts
|
||||
- Ideal for automation
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables
|
||||
|
||||
### Provider Configuration
|
||||
|
||||
| Variable | Description | Example |
|
||||
|----------|-------------|---------|
|
||||
| `TRADINGAGENTS_LLM_PROVIDER` | Chat LLM provider | `openrouter` |
|
||||
| `TRADINGAGENTS_BACKEND_URL` | Chat API endpoint | `https://openrouter.ai/api/v1` |
|
||||
| `TRADINGAGENTS_DEEP_THINK_LLM` | Deep reasoning model | `deepseek/deepseek-chat-v3-0324:free` |
|
||||
| `TRADINGAGENTS_QUICK_THINK_LLM` | Quick thinking model | `meta-llama/llama-3.3-8b-instruct:free` |
|
||||
|
||||
### Embedding Configuration
|
||||
|
||||
| Variable | Description | Example |
|
||||
|----------|-------------|---------|
|
||||
| `TRADINGAGENTS_EMBEDDING_PROVIDER` | Embedding provider | `openai` |
|
||||
| `TRADINGAGENTS_EMBEDDING_BACKEND_URL` | Embedding API endpoint | `https://api.openai.com/v1` |
|
||||
| `TRADINGAGENTS_EMBEDDING_MODEL` | Embedding model | `text-embedding-3-small` |
|
||||
| `TRADINGAGENTS_ENABLE_MEMORY` | Enable memory system | `true` or `false` |
|
||||
|
||||
### Logging Configuration
|
||||
|
||||
| Variable | Description | Example |
|
||||
|----------|-------------|---------|
|
||||
| `TRADINGAGENTS_LOG_LEVEL` | Logging verbosity | `INFO` |
|
||||
| `TRADINGAGENTS_LOG_DIR` | Log directory | `logs` |
|
||||
| `TRADINGAGENTS_LOG_TO_CONSOLE` | Console logging | `true` |
|
||||
| `TRADINGAGENTS_LOG_TO_FILE` | File logging | `true` |
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Issue: No auth credentials found
|
||||
|
||||
**Error:**
|
||||
```
|
||||
AuthenticationError: Error code: 401 - {'error': {'message': 'No auth credentials found'}}
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
1. Check if API key is set in `.env`
|
||||
2. Verify key format (e.g., `sk-proj-...` for OpenAI)
|
||||
3. Run environment checker:
|
||||
```bash
|
||||
python3 check_env_setup.py
|
||||
```
|
||||
|
||||
### Issue: Failed to get embedding
|
||||
|
||||
**Error:**
|
||||
```
|
||||
ERROR | MEMORY | Failed to get embedding: 401 Unauthorized
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
1. Set `OPENAI_API_KEY` if using OpenAI for embeddings
|
||||
2. OR set `TRADINGAGENTS_ENABLE_MEMORY=false` to disable
|
||||
3. OR use Ollama for local embeddings
|
||||
|
||||
### Issue: Memory disabled unexpectedly
|
||||
|
||||
**Logs:**
|
||||
```
|
||||
WARNING | MEMORY | Memory disabled for 'bull_memory'
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
1. Check `TRADINGAGENTS_ENABLE_MEMORY=true`
|
||||
2. Verify embedding provider is valid
|
||||
3. Check embedding API key is set
|
||||
|
||||
### Issue: Wrong provider selected
|
||||
|
||||
**Error:**
|
||||
```
|
||||
Unsupported LLM provider: xyz
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
1. Check `TRADINGAGENTS_LLM_PROVIDER` value
|
||||
2. Valid options: `openai`, `openrouter`, `anthropic`, `google`, `ollama`
|
||||
3. Case-sensitive!
|
||||
|
||||
### Issue: Module not found
|
||||
|
||||
**Error:**
|
||||
```
|
||||
ModuleNotFoundError: No module named 'tradingagents'
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Install in development mode
|
||||
pip install -e .
|
||||
|
||||
# Or install dependencies
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
Before running TradingAgents, verify:
|
||||
|
||||
- [ ] `.env` file exists (copied from `.env.example`)
|
||||
- [ ] API keys are set correctly
|
||||
- [ ] Provider configuration matches your API keys
|
||||
- [ ] Embedding provider is configured if memory enabled
|
||||
- [ ] Log directory is writable
|
||||
- [ ] Dependencies are installed
|
||||
|
||||
**Quick check:**
|
||||
```bash
|
||||
python3 check_env_setup.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Development
|
||||
|
||||
```bash
|
||||
# Use cost-optimized setup
|
||||
OPENROUTER_API_KEY=sk-or-v1-...
|
||||
OPENAI_API_KEY=sk-proj-...
|
||||
TRADINGAGENTS_LLM_PROVIDER=openrouter
|
||||
TRADINGAGENTS_EMBEDDING_PROVIDER=openai
|
||||
TRADINGAGENTS_LOG_LEVEL=DEBUG
|
||||
```
|
||||
|
||||
### Production
|
||||
|
||||
```bash
|
||||
# Use reliable providers
|
||||
OPENAI_API_KEY=sk-proj-...
|
||||
TRADINGAGENTS_LLM_PROVIDER=openai
|
||||
TRADINGAGENTS_LOG_LEVEL=INFO
|
||||
TRADINGAGENTS_LOG_TO_FILE=true
|
||||
```
|
||||
|
||||
### Testing/CI
|
||||
|
||||
```bash
|
||||
# Disable expensive features
|
||||
OPENROUTER_API_KEY=sk-or-v1-...
|
||||
TRADINGAGENTS_LLM_PROVIDER=openrouter
|
||||
TRADINGAGENTS_ENABLE_MEMORY=false
|
||||
TRADINGAGENTS_LOG_LEVEL=WARNING
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Security Notes
|
||||
|
||||
1. **Never commit `.env` to git**
|
||||
```bash
|
||||
# Add to .gitignore
|
||||
echo ".env" >> .gitignore
|
||||
```
|
||||
|
||||
2. **Use separate keys for dev/prod**
|
||||
|
||||
3. **Rotate keys regularly**
|
||||
|
||||
4. **Monitor API usage**
|
||||
- Set spending limits in provider dashboards
|
||||
- Review `logs/api_calls.log` for usage tracking
|
||||
|
||||
5. **Use least-privilege keys**
|
||||
- Restrict key permissions when possible
|
||||
|
||||
---
|
||||
|
||||
## Support
|
||||
|
||||
For more help:
|
||||
|
||||
- **Environment Setup**: `check_env_setup.py`
|
||||
- **Embedding Configuration**: `docs/EMBEDDING_CONFIGURATION.md`
|
||||
- **Logging System**: `docs/LOGGING.md`
|
||||
- **Feature Overview**: `FEATURE_EMBEDDING_README.md`
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-01-15
|
||||
**Version**: 2.0
|
||||
**Status**: Production Ready ✅
|
||||
Loading…
Reference in New Issue