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

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

Step 2: Create Virtual Environment

Using Conda (Recommended)

conda create -n tradingagents python=3.13
conda activate tradingagents

Using venv

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

Step 3: Install Dependencies

Production Dependencies

pip install -r requirements.txt

Development Dependencies

# 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:

cp .env.example .env

Edit .env with your API keys:

# 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:

# 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

# Format with black
black tradingagents/ tests/

# Sort imports with isort
isort tradingagents/ tests/

Linting

# Check style with flake8
flake8 tradingagents/ tests/

# Type checking with mypy
mypy tradingagents/

Testing

# 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:

{
    "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:

{
    "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

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

# Run all tests
pytest tests/

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

4. Format Code

# Format code
black tradingagents/ tests/

# Sort imports
isort tradingagents/ tests/

# Check linting
flake8 tradingagents/ tests/

5. Commit Changes

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

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

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

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

Using pytest with debugger

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

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

Logging

Enable debug logging:

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

Common Issues

Import Errors

Issue: ModuleNotFoundError: No module named 'tradingagents'

Solution: Install package in editable mode

pip install -e .

API Key Errors

Issue: ValueError: OPENAI_API_KEY not found

Solution: Check .env file exists and is loaded

# 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
• Testing Guide
• Architecture Documentation
• GitHub Repository

Getting Help

• Discord: Join our community
• GitHub Issues: Report issues
• Documentation: Read the docs