# Development Guide

## Setting Up Development Environment

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

```bash
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`:

```bash
mypy src/
```

## Running Tests

```bash
pytest tests/ -v
```

## Adding a New Data Processor

1. Create file in `src/data/`:

```python
# 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__`:

```python
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/`:

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

```python
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/`:

```python
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/`:

```python
from fastapi import APIRouter

router = APIRouter()

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

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

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

## Environment Variables

Set in `.env` file (not committed):

```bash
POLYGON_API_KEY=your_key
ALPHA_VANTAGE_API_KEY=your_key
IB_CLIENT_ID=1
```

Load with `python-dotenv` if needed.

## Git Workflow

```bash
# 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

```python
from src.utils.memory_manager import MemoryManager

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

### Model Inspection

```python
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

```python
from src.data.pipeline import StockDataPipeline

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