TradingAgents/docs/development/setup.md

# Development Environment Setup

Complete guide for setting up a TradingAgents development environment.

## Prerequisites

- Python >= 3.10 (Python 3.13 recommended)
- Git
- Conda or virtualenv
- Text editor or IDE (VS Code, PyCharm recommended)

## Step 1: Clone Repository

```bash
git clone https://github.com/TauricResearch/TradingAgents.git
cd TradingAgents
```

## Step 2: Create Virtual Environment

### Using Conda (Recommended)

```bash
conda create -n tradingagents python=3.13
conda activate tradingagents
```

### Using venv

```bash
python -m venv venv
source venv/bin/activate  # macOS/Linux
# or
venv\Scripts\activate  # Windows
```

## Step 3: Install Dependencies

### Production Dependencies

```bash
pip install -r requirements.txt
```

### Development Dependencies

```bash
# Install package in editable mode
pip install -e .

# Install testing dependencies
pip install pytest pytest-cov pytest-xdist pytest-mock

# Install linting/formatting tools
pip install black isort flake8 mypy

# Install pre-commit hooks
pip install pre-commit
pre-commit install
```

## Step 4: Configure Environment Variables

Create `.env` file:

```bash
cp .env.example .env
```

Edit `.env` with your API keys:

```env
# LLM Provider (choose one or more)
OPENAI_API_KEY=sk-your_key_here
ANTHROPIC_API_KEY=sk-ant-your_key_here
OPENROUTER_API_KEY=sk-or-v1-your_key_here
GOOGLE_API_KEY=your_key_here

# Data Vendor
ALPHA_VANTAGE_API_KEY=your_key_here

# Application Settings
TRADINGAGENTS_RESULTS_DIR=./results
```

## Step 5: Verify Installation

Run basic tests:

```bash
# Run smoke tests
pytest tests/regression/smoke/ -v

# Run unit tests
pytest tests/unit/ -v

# Quick integration test
python -c "from tradingagents.graph.trading_graph import TradingAgentsGraph; print('Import successful')"
```

## Development Tools

### Code Formatting

```bash
# Format with black
black tradingagents/ tests/

# Sort imports with isort
isort tradingagents/ tests/
```

### Linting

```bash
# Check style with flake8
flake8 tradingagents/ tests/

# Type checking with mypy
mypy tradingagents/
```

### Testing

```bash
# Run all tests
pytest tests/

# Run with coverage
pytest tests/ --cov=tradingagents --cov-report=html

# Run specific test file
pytest tests/unit/test_analysts.py -v
```

## IDE Configuration

### VS Code

Create `.vscode/settings.json`:

```json
{
    "python.defaultInterpreterPath": "${workspaceFolder}/venv/bin/python",
    "python.linting.enabled": true,
    "python.linting.flake8Enabled": true,
    "python.linting.mypyEnabled": true,
    "python.formatting.provider": "black",
    "python.sortImports.args": ["--profile", "black"],
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
        "source.organizeImports": true
    },
    "[python]": {
        "editor.defaultFormatter": "ms-python.black-formatter"
    }
}
```

Create `.vscode/launch.json` for debugging:

```json
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Current File",
            "type": "python",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal",
            "justMyCode": true,
            "envFile": "${workspaceFolder}/.env"
        },
        {
            "name": "Python: Pytest",
            "type": "python",
            "request": "launch",
            "module": "pytest",
            "args": [
                "tests/",
                "-v"
            ],
            "console": "integratedTerminal",
            "justMyCode": false
        }
    ]
}
```

### PyCharm

1. Open project in PyCharm
2. Configure interpreter:
   - File → Settings → Project → Python Interpreter
   - Select the virtual environment you created
3. Enable pytest:
   - File → Settings → Tools → Python Integrated Tools
   - Set "Default test runner" to pytest
4. Configure black:
   - File → Settings → Tools → External Tools
   - Add black as external tool

## Development Workflow

### 1. Create Feature Branch

```bash
git checkout -b feature/my-new-feature
```

### 2. Make Changes

Edit code following project conventions:
- Follow PEP 8 style guide
- Add docstrings to functions
- Write tests for new code
- Update documentation

### 3. Run Tests

```bash
# Run all tests
pytest tests/

# Run with coverage
pytest tests/ --cov=tradingagents --cov-report=term-missing
```

### 4. Format Code

```bash
# Format code
black tradingagents/ tests/

# Sort imports
isort tradingagents/ tests/

# Check linting
flake8 tradingagents/ tests/
```

### 5. Commit Changes

```bash
git add .
git commit -m "feat: Add new feature description"
```

Commit message format:
- `feat:` New feature
- `fix:` Bug fix
- `docs:` Documentation changes
- `test:` Test changes
- `refactor:` Code refactoring

### 6. Push and Create PR

```bash
git push origin feature/my-new-feature
```

Then create a pull request on GitHub.

## Project Structure

```
TradingAgents/
├── tradingagents/          # Main package
│   ├── agents/            # Agent implementations
│   │   ├── analysts/      # Analyst agents
│   │   ├── utils/         # Agent utilities
│   │   └── ...
│   ├── dataflows/         # Data vendor integrations
│   ├── graph/             # LangGraph workflow
│   ├── utils/             # Shared utilities
│   └── default_config.py  # Default configuration
├── tests/                 # Test suite
│   ├── unit/             # Unit tests
│   ├── integration/      # Integration tests
│   └── regression/       # Regression tests
├── cli/                  # CLI interface
├── docs/                 # Documentation
├── examples/             # Example scripts
├── requirements.txt      # Dependencies
└── setup.py             # Package setup
```

## Debugging

### Using Python Debugger

```python
# Add breakpoint in code
import pdb; pdb.set_trace()

# Or use built-in breakpoint()
breakpoint()
```

### Using pytest with debugger

```bash
# Drop into debugger on failure
pytest tests/ --pdb

# Drop into debugger on error
pytest tests/ --pdb -x
```

### Logging

Enable debug logging:

```python
import logging
logging.basicConfig(level=logging.DEBUG)
```

## Common Issues

### Import Errors

**Issue**: `ModuleNotFoundError: No module named 'tradingagents'`

**Solution**: Install package in editable mode
```bash
pip install -e .
```

### API Key Errors

**Issue**: `ValueError: OPENAI_API_KEY not found`

**Solution**: Check `.env` file exists and is loaded
```bash
# Verify environment variable
echo $OPENAI_API_KEY

# Or in Python
import os
print(os.getenv("OPENAI_API_KEY"))
```

### Test Failures

**Issue**: Tests fail with mocked data

**Solution**: Check mock data format matches expected schema

## Best Practices

1. **Use Virtual Environment**: Always work in a virtual environment
2. **Run Tests Frequently**: Run tests before committing
3. **Format Code**: Use black and isort consistently
4. **Write Tests**: Add tests for new features
5. **Update Documentation**: Keep docs in sync with code
6. **Small Commits**: Make focused, logical commits
7. **Branch Strategy**: Create feature branches for new work
8. **Code Review**: Get code reviewed before merging

## Resources

- [Contributing Guide](contributing.md)
- [Testing Guide](../testing/README.md)
- [Architecture Documentation](../architecture/multi-agent-system.md)
- [GitHub Repository](https://github.com/TauricResearch/TradingAgents)

## Getting Help

- **Discord**: [Join our community](https://discord.com/invite/hk9PGKShPK)
- **GitHub Issues**: [Report issues](https://github.com/TauricResearch/TradingAgents/issues)
- **Documentation**: [Read the docs](../README.md)