Feature complete xau

.env.example

@@ -1,2 +1,15 @@
 ALPHA_VANTAGE_API_KEY=alpha_vantage_api_key_placeholder
-OPENAI_API_KEY=openai_api_key_placeholder
+OPENAI_API_KEY=openai_api_key_placeholder
+FRED_API_KEY=fred_api_key_placeholder
+
+# Crypto Exchange API Keys (for CCXT - optional, only needed for trading)
+BINANCE_API_KEY=binance_api_key_placeholder
+BINANCE_API_SECRET=binance_api_secret_placeholder
+COINBASE_API_KEY=coinbase_api_key_placeholder
+COINBASE_API_SECRET=coinbase_api_secret_placeholder
+KRAKEN_API_KEY=kraken_api_key_placeholder
+KRAKEN_API_SECRET=kraken_api_secret_placeholder
+
+# Crypto Data Provider Keys
+GLASSNODE_API_KEY=glassnode_api_key_placeholder
+MESSARI_API_KEY=messari_api_key_placeholder

CLAUDE.md

@@ -0,0 +1,273 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+TradingAgents is a multi-agent LLM financial trading framework built with LangGraph that mirrors real-world trading firm dynamics. The framework uses specialized LLM agents (analysts, researchers, traders, and risk managers) to collaboratively evaluate market conditions and make informed trading decisions.
+
+**Research Paper**: arXiv:2412.20138
+
+## Core Architecture
+
+### Multi-Agent Pipeline Flow
+
+The system follows a sequential pipeline mimicking institutional trading:
+
+```
+Analyst Team → Research Team → Trader → Risk Management → Portfolio Manager
+```
+
+### Agent Teams Structure
+
+**1. Analyst Team** (`tradingagents/agents/analysts/`)
+- `market_analyst.py` - Technical analysis using MACD, RSI, price patterns
+- `social_media_analyst.py` - Sentiment analysis from social media
+- `news_analyst.py` - Global news and macroeconomic indicators
+- `fundamentals_analyst.py` - Company financials and intrinsic values
+
+**2. Research Team** (`tradingagents/agents/researchers/`)
+- `bull_researcher.py` - Bullish perspective analysis
+- `bear_researcher.py` - Bearish perspective analysis
+- `research_manager.py` - Debate moderator and final decision maker
+
+**3. Trading Team** (`tradingagents/agents/trader/`)
+- `trader.py` - Composes reports and makes trading decisions
+
+**4. Risk Management** (`tradingagents/agents/risk_mgmt/`)
+- `aggresive_debator.py` - High-risk tolerance perspective
+- `conservative_debator.py` - Low-risk tolerance perspective
+- `neutral_debator.py` - Balanced risk perspective
+
+**5. Portfolio Management** (`tradingagents/agents/managers/`)
+- `risk_manager.py` - Final approval/rejection of trades
+
+### State Management
+
+States are defined in `tradingagents/agents/utils/agent_states.py`:
+
+- **AgentState**: Main state flowing through the graph (company, date, reports, decisions)
+- **InvestDebateState**: Research team debate state (bull/bear history, judge decision)
+- **RiskDebateState**: Risk management debate state (risky/safe/neutral perspectives)
+
+### Graph Orchestration
+
+The LangGraph workflow is managed in `tradingagents/graph/`:
+
+- `trading_graph.py` - Main orchestration class (`TradingAgentsGraph`)
+- `setup.py` - Graph construction and node configuration (`GraphSetup`)
+- `propagation.py` - State initialization and execution (`Propagator`)
+- `conditional_logic.py` - Routing logic between nodes (`ConditionalLogic`)
+- `reflection.py` - Learning from past decisions (`Reflector`)
+- `signal_processing.py` - Extract trading signals from decisions (`SignalProcessor`)
+
+### Data Layer
+
+Data flows through an abstraction layer in `tradingagents/dataflows/`:
+
+**Configuration System**:
+- `config.py` - Global config management with `set_config()` and `get_config()`
+- `interface.py` - Abstract tool interface that routes to appropriate vendor
+- `default_config.py` - Default settings including data vendors
+
+**Vendor Implementations**:
+- `alpha_vantage*.py` - Alpha Vantage API (fundamental, news, stock data)
+- `y_finance.py` / `yfin_utils.py` - Yahoo Finance API (market data, indicators)
+- `google.py` / `googlenews_utils.py` - Google News (alternative news source)
+- `local.py` - Local data vendor for offline testing
+- `openai.py` - LLM-based data vendor for fundamental/news analysis
+
+**Tool Abstraction** (`tradingagents/agents/utils/agent_utils.py`):
+Abstract functions automatically route to configured vendor:
+- `get_stock_data()`, `get_indicators()` - Market data
+- `get_fundamentals()`, `get_balance_sheet()`, `get_cashflow()`, `get_income_statement()` - Fundamental data
+- `get_news()`, `get_global_news()` - News data
+- `get_insider_sentiment()`, `get_insider_transactions()` - Insider data
+
+## Installation and Setup
+
+### Environment Setup
+
+```bash
+# Clone and create virtual environment
+conda create -n tradingagents python=3.13
+conda activate tradingagents
+
+# Install dependencies
+pip install -r requirements.txt
+```
+
+### API Keys Configuration
+
+**Required APIs**:
+- OpenAI API (for LLM agents)
+- Alpha Vantage API (for fundamental and news data - default config)
+
+**Setup via environment variables**:
+```bash
+export OPENAI_API_KEY=$YOUR_OPENAI_API_KEY
+export ALPHA_VANTAGE_API_KEY=$YOUR_ALPHA_VANTAGE_API_KEY
+```
+
+**Setup via .env file**:
+```bash
+cp .env.example .env
+# Edit .env with your actual API keys
+```
+
+### Data Vendor Configuration
+
+Modify `tradingagents/default_config.py` to change data sources:
+
+```python
+"data_vendors": {
+    "core_stock_apis": "yfinance",       # yfinance, alpha_vantage, local
+    "technical_indicators": "yfinance",  # yfinance, alpha_vantage, local
+    "fundamental_data": "alpha_vantage", # openai, alpha_vantage, local
+    "news_data": "alpha_vantage",        # openai, alpha_vantage, google, local
+}
+```
+
+## Running the Framework
+
+### CLI Mode (Interactive)
+
+```bash
+python -m cli.main
+```
+
+This launches an interactive CLI with:
+- Ticker selection
+- Date selection
+- Analyst team selection
+- Research depth configuration (debate rounds)
+- LLM provider and model selection
+- Real-time progress tracking
+
+### Python API Mode
+
+**Basic usage** (`main.py`):
+```python
+from tradingagents.graph.trading_graph import TradingAgentsGraph
+from tradingagents.default_config import DEFAULT_CONFIG
+
+ta = TradingAgentsGraph(debug=True, config=DEFAULT_CONFIG.copy())
+
+# Run analysis
+_, decision = ta.propagate("NVDA", "2024-05-10")
+print(decision)
+```
+
+**Custom configuration**:
+```python
+config = DEFAULT_CONFIG.copy()
+config["deep_think_llm"] = "gpt-4o-mini"      # Deep thinking model
+config["quick_think_llm"] = "gpt-4o-mini"     # Quick thinking model
+config["max_debate_rounds"] = 1               # Research debate rounds
+config["max_risk_discuss_rounds"] = 1         # Risk debate rounds
+
+# LLM provider options: "openai", "anthropic", "google", "ollama", "openrouter"
+config["llm_provider"] = "openai"
+config["backend_url"] = "https://api.openai.com/v1"
+
+ta = TradingAgentsGraph(debug=True, config=config)
+_, decision = ta.propagate("AAPL", "2024-05-10")
+```
+
+**Reflection and learning**:
+```python
+# After getting returns, reflect and update memory
+ta.reflect_and_remember(returns_losses=1000)  # Positive returns
+```
+
+## LLM Provider Support
+
+The framework supports multiple LLM providers (configured in `tradingagents/graph/trading_graph.py:75-85`):
+
+- **OpenAI**: `llm_provider: "openai"`, backend_url: `https://api.openai.com/v1`
+- **Anthropic**: `llm_provider: "anthropic"`
+- **Google**: `llm_provider: "google"`
+- **Ollama**: `llm_provider: "ollama"` (local models)
+- **OpenRouter**: `llm_provider: "openrouter"`
+
+## Key Configuration Parameters
+
+Located in `tradingagents/default_config.py`:
+
+- `results_dir` - Output directory for results (default: `./results`)
+- `deep_think_llm` - Model for complex reasoning (default: `o4-mini`)
+- `quick_think_llm` - Model for quick tasks (default: `gpt-4o-mini`)
+- `max_debate_rounds` - Research team debate rounds (default: `1`)
+- `max_risk_discuss_rounds` - Risk team debate rounds (default: `1`)
+- `data_vendors` - Data source configuration per category
+
+## Output Structure
+
+Results are saved to:
+```
+results/
+└── {TICKER}/
+    └── {DATE}/
+        ├── reports/
+        │   ├── market_report.md
+        │   ├── sentiment_report.md
+        │   ├── news_report.md
+        │   ├── fundamentals_report.md
+        │   ├── investment_plan.md
+        │   ├── trader_investment_plan.md
+        │   └── final_trade_decision.md
+        └── message_tool.log
+
+eval_results/
+└── {TICKER}/
+    └── TradingAgentsStrategy_logs/
+        └── full_states_log_{DATE}.json
+```
+
+## Memory System
+
+The framework includes a reflection-based learning system (`tradingagents/agents/utils/memory.py`):
+
+- **FinancialSituationMemory**: Stores past decisions and outcomes
+- Memories are agent-specific (bull, bear, trader, judge, risk manager)
+- Uses ChromaDB for vector storage
+- Enables learning from past trading mistakes
+
+Memory is updated via:
+```python
+ta.reflect_and_remember(returns_losses)
+```
+
+## Testing and Development
+
+**Cost-saving for testing**:
+- Use `gpt-4o-mini` or `gpt-4.1-mini` instead of `o1-preview`/`gpt-4o`
+- Set `max_debate_rounds: 1` to reduce API calls
+- Use `local` data vendor with pre-downloaded data
+
+**Debug mode**:
+```python
+ta = TradingAgentsGraph(debug=True, config=config)
+```
+This enables:
+- LangGraph state tracing
+- Pretty-printed message outputs
+- Detailed logging
+
+## Important Notes
+
+1. **API Rate Limits**: The framework makes many API calls. Consider Alpha Vantage Premium for production use.
+
+2. **Data Vendor Fallbacks**: The system has fallback logic when primary vendors fail (see `tradingagents/agents/utils/core_stock_tools.py:23-45`).
+
+3. **Research Disclaimer**: This framework is designed for research purposes. Trading performance varies based on LLM models, temperature, data quality, and other factors. Not intended as financial advice.
+
+4. **Analyst Selection**: When initializing `TradingAgentsGraph`, you can select specific analysts:
+   ```python
+   ta = TradingAgentsGraph(
+       selected_analysts=["market", "news", "fundamentals"],  # Skip social
+       config=config
+   )
+   ```
+
+5. **State Logging**: All states are automatically logged to JSON files for analysis and debugging.

README.md

@@ -204,6 +204,63 @@ print(decision)
 
 You can view the full list of configurations in `tradingagents/default_config.py`.
 
+## Cryptocurrency Trading Module
+
+TradingAgents includes a dedicated cryptocurrency trading module with specialized agents and tools for crypto markets. The crypto module provides:
+
+- **Crypto-Specific Agents**: Technical, fundamental, news, and sentiment analysts adapted for 24/7 crypto markets
+- **Backtesting Framework**: Test strategies against historical crypto data with realistic slippage and fees
+- **Paper Trading Engine**: Real-time simulation with live crypto data from 100+ exchanges via CCXT
+- **On-Chain Analytics**: Integration with Glassnode for blockchain metrics and whale activity
+- **Multi-Exchange Support**: Unified interface for Binance, Coinbase, Kraken, and more
+
+### Quick Start - Crypto
+
+```bash
+# Install crypto dependencies
+pip install ccxt pandas numpy
+
+# Test crypto data integration
+cd crypto_trading
+python tests/test_crypto_data.py
+
+# Run crypto agents
+python tests/test_crypto_agents.py
+
+# Start paper trading
+python scripts/run_paper_trading.py
+```
+
+### Documentation
+
+For complete cryptocurrency trading documentation, see:
+- `crypto_trading/README.md` - Main crypto module documentation
+- `crypto_trading/SETUP.md` - Installation and configuration
+- `crypto_trading/docs/` - Detailed guides for each phase
+
+### Example - Crypto Analysis
+
+```python
+from tradingagents.crypto_config import get_crypto_config
+from tradingagents.dataflows.config import set_config
+from crypto_trading.src.agents.crypto_technical_analyst import create_crypto_technical_analyst
+
+# Configure for crypto markets
+crypto_config = get_crypto_config()
+set_config(crypto_config)
+
+# Use crypto-specific agents
+ta = TradingAgentsGraph(
+    debug=True,
+    config=crypto_config,
+    selected_analysts=["crypto_technical", "crypto_fundamentals"]
+)
+
+# Analyze Bitcoin
+_, decision = ta.propagate("BTC/USDT", "2024-10-07")
+print(decision)
+```
+
 ## Contributing
 
 We welcome contributions from the community! Whether it's fixing a bug, improving documentation, or suggesting a new feature, your input helps make this project better. If you are interested in this line of research, please consider joining our open-source financial AI research community [Tauric Research](https://tauric.ai/).