trading_gnn/docs/DEVELOPMENT.md

Development Guide

Setting Up Development Environment

# Clone repo
git clone <repository-url>
cd stock_gnn_r9700

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install in editable mode + dev dependencies
pip install -r requirements.txt
pip install black isort mypy pytest pytest-asyncio

Code Style

Format with black and isort:

black src/ config.py main.py live_trading.py benchmark.py
isort src/ config.py main.py live_trading.py benchmark.py

Type-check with mypy:

mypy src/

Running Tests

pytest tests/ -v

Adding a New Data Processor

1. Create file in src/data/:

# src/data/earnings_processor.py
import logging
from typing import Dict, List

logger = logging.getLogger(__name__)

class EarningsProcessor:
    def __init__(self):
        self.earnings_data = {}

    def fetch_earnings(self, tickers: List[str], start_date: str, end_date: str):
        """Fetch earnings data."""
        pass

    def get_earnings_features(self, ticker: str, date: str) -> Dict:
        """Return earnings-based features."""
        return {"earnings_surprise": 0.0, "eps_growth": 0.0}

2. Import and initialize in StockDataPipeline.__init__:

from src.data.earnings_processor import EarningsProcessor

class StockDataPipeline:
    def __init__(self):
        ...
        self.earnings_processor = EarningsProcessor()

3. Call fetch_earnings in update_alternative_data and include features in create_training_dataset.

Adding a New Model

1. Create file in src/models/:

# src/models/my_model.py
import torch
import torch.nn as nn
from config import config

class MyModel(nn.Module):
    def __init__(self, num_features: int):
        super().__init__()
        self.fc = nn.Linear(num_features, 1)

    def forward(self, data):
        return self.fc(data.x)

2. Wrap with AMDOptimizer before training:

from src.amd.optimizations import AMDOptimizer

model = MyModel(num_features)
model = AMDOptimizer().optimize_model(model)

Adding a New Trading Strategy

1. Subclass Broker in src/trading/:

from src.trading.broker import Broker

class AlpacaBroker(Broker):
    def submit_order(self, order):
        # Implementation
        pass

2. Instantiate in live_trading.py and pass to RealTimeTrader.

Adding API Endpoints

1. Create router in src/web/api/:

from fastapi import APIRouter

router = APIRouter()

@router.get("/health")
async def health():
    return {"status": "ok"}

2. Include in src/web/app.py:

from src.web.api import my_endpoints
app.include_router(my_endpoints.router, prefix="/api/my")

Environment Variables

Set in .env file (not committed):

POLYGON_API_KEY=your_key
ALPHA_VANTAGE_API_KEY=your_key
IB_CLIENT_ID=1

Load with python-dotenv if needed.

Git Workflow

# Feature branch
git checkout -b feature/my-feature

# Commit
git add .
git commit -m "feat: add my feature"

# Push
git push origin feature/my-feature

Debugging

GPU Memory Issues

from src.utils.memory_manager import MemoryManager

mm = MemoryManager()
print(mm.get_memory_stats())

Model Inspection

from src.models.gnn_model import CorporateActionAwareGNN

model = CorporateActionAwareGNN(num_features=10)
print(sum(p.numel() for p in model.parameters()))  # parameter count

Data Inspection

from src.data.pipeline import StockDataPipeline

pipe = StockDataPipeline()
print(pipe.price_data['AAPL'].tail())