TradingAgents/FRED_MACRO_INTEGRATION.md

# FRED API Macro Data Integration

## Summary
Added FRED (Federal Reserve Economic Data) API support to the TradingAgents vendor methods system for macroeconomic analysis.

## Files Added

### 1. `tradingagents/dataflows/macro_utils.py`
New module providing FRED API integration with the following functions:

- **`get_fred_api_key()`** - Get FRED API key from config or environment
- **`get_fred_data(series_id, start_date, end_date)`** - Core FRED API wrapper
- **`get_treasury_yield_curve(curr_date)`** - Treasury yield curve data with inversion analysis
- **`get_economic_indicators_report(curr_date, lookback_days=90)`** - Comprehensive economic indicators
  - Federal Funds Rate
  - Consumer Price Index (CPI)
  - Producer Price Index (PPI)
  - Unemployment Rate
  - Nonfarm Payrolls
  - GDP Growth Rate
  - ISM Manufacturing PMI
  - Consumer Confidence
  - VIX (Market Volatility)
- **`get_fed_calendar_and_minutes(curr_date)`** - Federal Reserve meeting calendar and policy updates
- **`get_macro_economic_summary(curr_date, lookback_days=90)`** - Complete macro economic analysis combining all components

## Files Modified

### 2. `tradingagents/dataflows/interface.py`
Updated vendor routing system to include FRED macro data:

**Added Imports:**
```python
from .macro_utils import get_economic_indicators_report, get_treasury_yield_curve, get_fed_calendar_and_minutes
```

**Updated VENDOR_LIST:**
```python
VENDOR_LIST = [
    "local",
    "yfinance",
    "openai",
    "google",
    "fred"  # New
]
```

**New TOOLS_CATEGORIES Entry:**
```python
"macro_data": {
    "description": "Macroeconomic indicators and Federal Reserve data",
    "tools": [
        "get_economic_indicators",
        "get_yield_curve",
        "get_fed_calendar"
    ]
}
```

**New VENDOR_METHODS Entries:**
```python
# macro_data
"get_economic_indicators": {
    "fred": get_economic_indicators_report,
},
"get_yield_curve": {
    "fred": get_treasury_yield_curve,
},
"get_fed_calendar": {
    "fred": get_fed_calendar_and_minutes,
},
```

## Configuration Required

To use FRED API features, set the FRED API key via:

1. **Environment Variable:**
   ```bash
   export FRED_API_KEY="your_api_key_here"
   ```

2. **Or via Config System:**
   The `get_fred_api_key()` function will check:
   - Config system via `get_api_key("fred_api_key", "FRED_API_KEY")`
   - Environment variable `FRED_API_KEY`

3. **Get a Free API Key:**
   - Visit: https://fred.stlouisfed.org/
   - Register for a free account
   - Generate API key under "My Account" → "API Keys"

## Usage Examples

### Via Vendor Routing System

```python
from tradingagents.dataflows.interface import route_to_vendor

# Get economic indicators
indicators = route_to_vendor(
    "get_economic_indicators",
    curr_date="2025-10-06",
    lookback_days=90
)

# Get yield curve
yield_curve = route_to_vendor(
    "get_yield_curve",
    curr_date="2025-10-06"
)

# Get Fed calendar
fed_calendar = route_to_vendor(
    "get_fed_calendar",
    curr_date="2025-10-06"
)
```

### Direct Function Calls

```python
from tradingagents.dataflows.macro_utils import (
    get_economic_indicators_report,
    get_treasury_yield_curve,
    get_fed_calendar_and_minutes,
    get_macro_economic_summary
)

# Complete macro analysis
summary = get_macro_economic_summary(
    curr_date="2025-10-06",
    lookback_days=90
)

# Individual components
indicators = get_economic_indicators_report("2025-10-06", 90)
yield_curve = get_treasury_yield_curve("2025-10-06")
fed_data = get_fed_calendar_and_minutes("2025-10-06")
```

## Integration with Macro Analyst

The macro analyst can now use these tools through the vendor routing system. The tools are automatically available through the `macro_data` category:

```python
# In agent configuration
config = {
    "data_vendors": {
        "macro_data": "fred"  # Use FRED for macro data
    }
}
```

## Data Returned

All functions return formatted markdown strings suitable for LLM analysis:

- **Economic Indicators**: Markdown tables with current values, changes, and analysis
- **Yield Curve**: Markdown table with maturities, yields, and inversion warnings
- **Fed Calendar**: FOMC meeting schedule and policy trajectory
- **Trading Implications**: Actionable insights for different economic scenarios

## PR Compatibility Notes

Changes were made with minimal modifications to existing code:

1. ✅ **New file only** - `macro_utils.py` is a new addition
2. ✅ **Additive changes** - Only added new entries to existing dictionaries
3. ✅ **No breaking changes** - Existing functionality unchanged
4. ✅ **Follows existing patterns** - Uses same vendor routing architecture as other data sources
5. ✅ **Consistent naming** - Follows existing naming conventions (`get_*` pattern)

## Testing

To verify the integration works:

```python
# Test FRED API connection
from tradingagents.dataflows.macro_utils import get_fred_data

result = get_fred_data("FEDFUNDS", "2025-01-01", "2025-10-06")
print(result)

# Test vendor routing
from tradingagents.dataflows.interface import route_to_vendor

indicators = route_to_vendor(
    "get_economic_indicators",
    curr_date="2025-10-06",
    lookback_days=30
)
print(indicators)
```

## Dependencies

No new dependencies required. Uses existing dependencies:
- `requests` - For FRED API calls
- `pandas` - For data manipulation
- `datetime` - For date handling
- Existing config system for API key management

## Future Enhancements

Potential improvements:
- Add caching for FRED API responses (similar to YFinanceDataProvider)
- Add more FRED series (housing data, commodity prices, etc.)
- Add international economic indicators
- Add custom FRED series ID support for advanced users