# Trading Agents Backend

This directory contains the Python backend for the Trading Agents system.

## Structure

- **`api.py`** - FastAPI server that exposes trading analysis endpoints
- **`run_api.py`** - Script to run the FastAPI server
- **`main.py`** - Main entry point for the trading system
- **`tradingagents/`** - Core trading logic and agents
  - `agents/` - Various AI agents (analysts, researchers, traders, risk managers)
  - `dataflows/` - Data fetching and processing utilities
  - `graph/` - Trading decision graph and workflow
- **`cli/`** - Command-line interface for the trading system
- **`results/`** - Output directory for analysis results
- **`requirements.txt`** - Python dependencies
- **`setup.py`** - Package setup configuration
- **`pyproject.toml`** - Modern Python project configuration

## Quick Start

1. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```

2. Run the FastAPI server:
   ```bash
   python run_api.py
   ```

3. Or use the CLI:
   ```bash
   python -m cli.main
   ```

## API Endpoints

- `GET /` - Root endpoint (API status)
- `GET /health` - Health check
- `POST /analyze` - Analyze a stock ticker
  - Request: `{"ticker": "AAPL"}`
  - Response: Comprehensive analysis including market, sentiment, news, and trading decisions
- `GET /docs` - Interactive API documentation (Swagger UI)

## Testing the API

### Quick Test
```bash
# Run the test script
python test_api.py
```

### Manual Testing
1. **Using Browser**: Navigate to http://localhost:8000/docs for interactive testing
2. **Using curl**: See `test_api.md` for detailed curl commands
3. **Using Python**: Use the provided `test_api.py` script

For detailed testing instructions, see [test_api.md](test_api.md).

## Environment Variables

Create a `.env` file in the project root with:

### Required
- `OPENAI_API_KEY` - Your OpenAI API key for AI agents
- `FINNHUB_API_KEY` - For market data (free tier available)

### Optional
- `REDDIT_CLIENT_ID` - For Reddit sentiment analysis
- `REDDIT_CLIENT_SECRET` - For Reddit sentiment analysis
- `TRADINGAGENTS_RESULTS_DIR` - Custom results directory (default: `backend/results`)
- `TRADINGAGENTS_DATA_DIR` - Custom data directory (default: `backend/data`)
- `TRADINGAGENTS_API_HOST` - API host (default: `localhost`)
- `TRADINGAGENTS_API_PORT` - API port (default: `8000`)

### Example `.env` file:
```bash
# API Keys
OPENAI_API_KEY=sk-your-key-here
FINNHUB_API_KEY=your-finnhub-key

# Optional Reddit API
REDDIT_CLIENT_ID=your-client-id
REDDIT_CLIENT_SECRET=your-client-secret

# Optional custom directories
# TRADINGAGENTS_RESULTS_DIR=/custom/path/to/results
# TRADINGAGENTS_API_PORT=3000
```

## Features

### Streaming Analysis (NEW!)

The TradingAgents CLI now supports real-time streaming of analysis reports as they're being generated by the AI agents. Instead of waiting for complete sections to be delivered, you can see the analysis content flowing in real-time.

#### Usage Options

1. **Dedicated Streaming Command:**
   ```bash
   python -m cli.main stream
   python -m cli.main stream --advanced  # With advanced configuration
   ```

2. **Streaming Flag with Analyze Command:**
   ```bash
   python -m cli.main analyze --streaming
   python -m cli.main analyze --streaming --advanced
   ```

3. **Default Command with Streaming:**
   ```bash
   python -m cli.main --streaming
   python -m cli.main --streaming --advanced
   ```

#### Streaming vs. Regular Analysis

- **Regular Analysis**: Shows progress updates and agent statuses, but reports are delivered only when complete sections are finished
- **Streaming Analysis**: Shows the same progress updates PLUS real-time streaming of report content as agents generate it

#### What You'll See in Streaming Mode

- 🔄 **Agent Progress**: Same as regular mode - shows which agents are working
- 📡 **Live Streaming Panel**: Real-time content from the currently active agent
- 🔴 **Live Indicator**: Shows which agent is currently generating content
- ⚡ **Higher Refresh Rate**: Updates 8 times per second for smooth streaming

#### Benefits

- **Real-time Insights**: See analysis developing as it happens
- **Better Understanding**: Watch the thought process of each agent
- **Immediate Feedback**: Know immediately when agents start working on different aspects
- **Enhanced Experience**: More engaging and informative than batch delivery

#### Technical Details

The streaming implementation:
- Uses a `StreamingMessageBuffer` that extends the regular `MessageBuffer`
- Detects agent transitions and content generation in real-time
- Maintains the same final report quality while providing streaming experience
- Automatically saves all content to report files as in regular mode