Merge c9b8afd0dd into fa4d01c23a
This commit is contained in:
Bishal Sarkar
GitHub
commit
daa56adf69
|
|
@ -0,0 +1,466 @@
|
|||
## Comprehensive Plan: Customizing the Repository for Forex Trading
|
||||
|
||||
### TL;DR
|
||||
Transform the equity-focused trading agents architecture into a multi-asset system supporting forex by:
|
||||
1. Creating an abstract `Instrument` layer (equity vs currency pairs)
|
||||
2. Establishing a unified configuration framework
|
||||
3. Implementing forex-specific data integrations
|
||||
4. Building forex-aware agents with proper leverage & commission handling
|
||||
5. Adding 24/5 market monitoring and compliance features
|
||||
|
||||
---
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
### Current State (Equity-Focused)
|
||||
- Agents designed for stock trading (tickers, market hours, fundamental analysis)
|
||||
- Data models assume single market open/close times
|
||||
- Risk management tailored to equity leverage constraints
|
||||
|
||||
### Target State (Multi-Asset)
|
||||
- Agents agnostic to instrument type (extensible to stocks, forex, crypto, commodities)
|
||||
- Configuration-driven asset switching
|
||||
- Specialized risk management rules per asset class
|
||||
|
||||
---
|
||||
|
||||
## Phase 0: Foundation & Configuration (Effort: 3-4 days) — **CRITICAL PATH**
|
||||
|
||||
### 0.1 Create Instrument Abstraction Layer
|
||||
**Why First**: All downstream phases depend on this abstraction.
|
||||
|
||||
**Changes**:
|
||||
- Create `tradingagents/models/instrument.py`:
|
||||
- Base `Instrument` class with common fields (symbol, name, type, exchange)
|
||||
- `EquityInstrument` subclass (ticker, sector, fundamentals)
|
||||
- `CurrencyPairInstrument` subclass (base currency, quote currency, pip size, lot sizes)
|
||||
- Update `tradingagents/agents/` to use `Instrument` instead of hardcoded ticker handling
|
||||
|
||||
**Concrete Example**:
|
||||
```python
|
||||
# tradingagents/models/instrument.py
|
||||
class Instrument(ABC):
|
||||
symbol: str
|
||||
name: str
|
||||
instrument_type: InstrumentType # Enum: EQUITY, FOREX
|
||||
|
||||
class CurrencyPair(Instrument):
|
||||
base_currency: str # "EUR"
|
||||
quote_currency: str # "USD"
|
||||
pip_size: float # 0.0001 for most pairs, 0.01 for JPY pairs
|
||||
standard_lot: float # 100,000
|
||||
mini_lot: float # 10,000
|
||||
micro_lot: float # 1,000
|
||||
```
|
||||
|
||||
### 0.2 Unified Configuration Schema
|
||||
**Create**: `tradingagents/config/forex_config.py`
|
||||
|
||||
**Config Structure**:
|
||||
```yaml
|
||||
trading_mode: "forex" # or "equity"
|
||||
forex:
|
||||
data_provider: "oanda" # OANDA, Forex.com, Alpha Vantage
|
||||
api_keys:
|
||||
oanda: ${OANDA_API_KEY}
|
||||
account_id: ${OANDA_ACCOUNT_ID}
|
||||
default_leverage: 50 # 1:50 leverage
|
||||
max_leverage: 500
|
||||
lot_type: "micro" # micro, mini, standard
|
||||
base_currency: "USD"
|
||||
trading_pairs:
|
||||
- "EUR/USD"
|
||||
- "GBP/USD"
|
||||
- "USD/JPY"
|
||||
market_hours:
|
||||
forex:
|
||||
open: "Sunday 17:00 EST" # 24/5 market
|
||||
close: "Friday 17:00 EST"
|
||||
```
|
||||
|
||||
### 0.3 Multi-Provider API Interface
|
||||
**Create**: `tradingagents/dataflows/forex_provider_factory.py`
|
||||
|
||||
- Implement factory pattern for forex data providers
|
||||
- Define common interface: `ForexDataProvider`
|
||||
- Fallback strategy between OANDA and Forex.com APIs
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Data Integration (Effort: 5-6 days) — *Parallel with Phase 2*
|
||||
|
||||
### 1.1 Forex Data Provider Implementation
|
||||
**Create New Files**:
|
||||
- `tradingagents/dataflows/oanda_api.py`
|
||||
- `tradingagents/dataflows/forexcom_api.py`
|
||||
- `tradingagents/dataflows/forex_common.py` (shared utilities)
|
||||
|
||||
**Implement**:
|
||||
- Real-time tick data fetching for currency pairs
|
||||
- Historical candle data (1m, 5m, 15m, 1h, 4h, 1d)
|
||||
- Bid/ask spread tracking
|
||||
- Account balance & margin info retrieval
|
||||
|
||||
**Concrete Example** (`oanda_api.py`):
|
||||
```python
|
||||
class OANDADataProvider(ForexDataProvider):
|
||||
def get_candles(self, pair: str, timeframe: str, count: int) -> DataFrame:
|
||||
"""Fetch historical OHLCV data"""
|
||||
|
||||
def get_live_quotes(self, pairs: List[str]) -> Dict[str, Quote]:
|
||||
"""Get real-time bid/ask for multiple pairs"""
|
||||
|
||||
def get_account_info(self) -> AccountInfo:
|
||||
"""Balance, margin used, available margin"""
|
||||
```
|
||||
|
||||
### 1.2 Forex-Specific Metrics & Normalization
|
||||
**Update**: `tradingagents/utils/` → Add `forex_metrics.py`
|
||||
|
||||
- Pip value calculation (varies by pair and lot size)
|
||||
- Spread normalization (in pips)
|
||||
- Slippage tracking
|
||||
- Margin requirement calculation per position
|
||||
|
||||
### 1.3 Data Validation & Error Handling
|
||||
**Add Tests**: `tests/test_forex_data_sources.py`
|
||||
- Validate bid/ask < spread tolerance
|
||||
- Verify pip calculations per pair
|
||||
- Test data continuity across sessions (no gaps at market open)
|
||||
- Handle connection failures & API rate limits
|
||||
|
||||
**Update**: `dataflows/` error handling for 24/5 operation
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Abstraction Refactoring (Effort: 6-8 days) — *Parallel with Phase 1*
|
||||
|
||||
### 2.1 Refactor Core Data Models
|
||||
**Update**:
|
||||
- `tradingagents/agents/utils/agent_states.py` — Store `Instrument` instead of `ticker`
|
||||
- `tradingagents/graph/trading_graph.py` — Accept generic instruments
|
||||
- Agent nodes to work with any `Instrument` subclass
|
||||
|
||||
### 2.2 Update Graph Structure
|
||||
**Modify**: `tradingagents/graph/setup.py`
|
||||
|
||||
The analysis graph remains the same, but information flows differently:
|
||||
- **For Equity**: Pull fundamentals, sector data
|
||||
- **For Forex**: Pull economic indicators, central bank decisions, geopolitical events
|
||||
|
||||
Add conditional logic in `conditional_logic.py` to route instrument-specific analysis.
|
||||
|
||||
### 2.3 Refactor Existing Agents
|
||||
**Update Agents** (in `tradingagents/agents/`):
|
||||
- `fundamentals_analyst.py` → Skip fundamentals for forex, pull macro data instead
|
||||
- `market_analyst.py` → Add forex-specific technical analysis (moving averages, Fibonacci, support/resistance)
|
||||
- `news_analyst.py` → Add economic calendar events, central bank statements
|
||||
- All agents accept `Instrument` instead of ticker
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Forex-Specific Strategy Implementation (Effort: 7-10 days) — *After Phase 1 & 2*
|
||||
|
||||
### 3.1 Create Forex Strategy Agents
|
||||
**New Files**:
|
||||
- `tradingagents/agents/analysts/forex_technician.py` — Technical analysis for pairs
|
||||
- `tradingagents/agents/analysts/macro_analyst.py` — Economic data & central bank tracking
|
||||
- `tradingagents/agents/traders/forex_trader.py` — Pair-specific trading decisions
|
||||
|
||||
### 3.2 Implement Trading Strategies
|
||||
**Extend**: `tradingagents/agents/trader/trader.py`
|
||||
|
||||
Strategies:
|
||||
- **Scalping**: Quick trades on micro-trends (1-5 minute candles)
|
||||
- **Swing Trading**: Hold 1-3 days on support/resistance breakouts
|
||||
- **Carry Trade**: Long-term holds with interest rate differentials
|
||||
- **Mean Reversion**: Identification via RSI, Bollinger Bands
|
||||
|
||||
### 3.3 Add Reversal & Position Management
|
||||
- Support both long & short positions (shorting is standard in forex)
|
||||
- Trailing stop-loss implementation
|
||||
- Breakeven adjustments
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Risk Management & Position Sizing (Effort: 4-5 days)
|
||||
|
||||
### 4.1 Forex-Specific Risk Models
|
||||
**Update**: `tradingagents/agents/risk_mgmt/`
|
||||
|
||||
**New Considerations**:
|
||||
- **Leverage Risk**: Enforce max leverage per position (e.g., max 5:1 on single pair)
|
||||
- **Margin Requirements**: Track used margin % (warn if >70% used)
|
||||
- **Liquidation Limits**: Flag if losses would exceed stop-out level (typically 50% margin)
|
||||
- **Correlation Risk**: Prevent over-exposure to related pairs (EUR/USD + EUR/GBP)
|
||||
|
||||
**Modify Debators**:
|
||||
- `aggressive_debator.py` → Allow higher leverage (up to 100:1)
|
||||
- `neutral_debator.py` → Medium leverage (20:1 to 50:1)
|
||||
- `conservative_debator.py` → Low leverage (1:1 to 10:1), wider stops
|
||||
|
||||
### 4.2 Position Sizing Engine
|
||||
**Create**: `tradingagents/utils/forex_position_sizing.py`
|
||||
|
||||
**Algorithm**:
|
||||
```
|
||||
position_size = (account_equity × risk_percent) / (stop_loss_in_pips × pip_value_per_unit)
|
||||
```
|
||||
|
||||
**Constraints**:
|
||||
- Risk no more than 1-2% of account per trade
|
||||
- Minimum position: 1 micro lot
|
||||
- Maximum position: Limited by leverage & margin available
|
||||
|
||||
**Concrete Example**:
|
||||
```python
|
||||
def calculate_position_size(
|
||||
account_equity: float,
|
||||
risk_percent: float = 0.02, # 2%
|
||||
leverage: int = 50,
|
||||
stop_loss_pips: int = 50,
|
||||
pair: str = "EUR/USD"
|
||||
) -> float:
|
||||
"""Returns position in units"""
|
||||
pip_value = get_pip_value(pair, lot_size=1000) # micro lot
|
||||
risk_amount = account_equity * risk_percent
|
||||
pips_at_risk = stop_loss_pips
|
||||
|
||||
position_units = (risk_amount / (pip_value * pips_at_risk)) * 1000
|
||||
return round(position_units / 1000) * 1000 # Round to micro lots
|
||||
```
|
||||
|
||||
### 4.3 Compliance & Regulation
|
||||
- **FIFO Rule**: Some jurisdictions (US) require First-In-First-Out closing
|
||||
- **PDT-like Restrictions**: Pattern day trade equivalents for some firms
|
||||
- Track & log regulatory compliance
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Market Monitoring & Operations (Effort: 3-4 days) — *After Phase 1*
|
||||
|
||||
### 5.1 24/5 Market Monitoring
|
||||
**Create**: `tradingagents/utils/market_monitor.py`
|
||||
|
||||
- Track trading sessions (London, NYSE, Asia sessions)
|
||||
- Monitor volatility spikes (especially at session opens)
|
||||
- Alert on economic calendar events
|
||||
- Handle disconnections gracefully (reconnect strategy)
|
||||
|
||||
### 5.2 Order Execution & Slippage Tracking
|
||||
**Update**: `tradingagents/agents/trader/trader.py`
|
||||
|
||||
- Simulate slippage based on spreads
|
||||
- Log actual fill prices vs expected
|
||||
- Track execution quality metrics
|
||||
|
||||
### 5.3 Trade Journaling
|
||||
**Create**: `tradingagents/utils/forex_trade_journal.py`
|
||||
|
||||
Log per trade:
|
||||
- Entry price, spread at entry
|
||||
- Exit price, slippage impact
|
||||
- PnL in pips and account currency
|
||||
- Trade reason (technical signal, macro event, etc.)
|
||||
|
||||
---
|
||||
|
||||
## Phase 6: User Interface & CLI (Effort: 3-4 days)
|
||||
|
||||
### 6.1 CLI Commands
|
||||
**Update**: `cli/main.py`
|
||||
|
||||
**New Commands**:
|
||||
```bash
|
||||
trading-agent --mode forex --pair EUR/USD --leverage 50
|
||||
trading-agent --mode forex --strategy scalping --pairs EUR/USD,GBP/USD
|
||||
trading-agent --backtest forex --pair EUR/USD --timeframe 1h --start 2024-01-01
|
||||
```
|
||||
|
||||
### 6.2 Configuration Management
|
||||
**Update**: `cli/config.py`
|
||||
|
||||
```python
|
||||
class ForexConfig:
|
||||
provider: str # "oanda", "forexcom"
|
||||
api_key: str
|
||||
leverage: int
|
||||
pairs: List[str]
|
||||
risk_percent: float
|
||||
strategy: str
|
||||
```
|
||||
|
||||
### 6.3 Dashboard/Status Display
|
||||
**Update**: `cli/static/welcome.txt` → Add forex-specific info
|
||||
- Current positions, open drawdown
|
||||
- Margin used / available
|
||||
- Today's PnL tracking
|
||||
|
||||
---
|
||||
|
||||
## Phase 7: Testing & Backtesting (Effort: 5-6 days) — *Parallel with Phase 6*
|
||||
|
||||
### 7.1 Unit Tests
|
||||
**Create/Update**:
|
||||
- `tests/test_forex_position_sizing.py`
|
||||
- `tests/test_instrument_abstraction.py`
|
||||
- `tests/test_risk_management_forex.py`
|
||||
- `tests/test_oanda_provider.py`
|
||||
|
||||
### 7.2 Backtesting Engine
|
||||
**Create**: `tradingagents/backtest/forex_backtest.py`
|
||||
|
||||
- Load historical forex data
|
||||
- Simulate trades with realistic spreads & slippage
|
||||
- Calculate metrics: Sharpe ratio, max drawdown, win rate
|
||||
- Compare strategies across pairs & timeframes
|
||||
|
||||
### 7.3 Integration Tests
|
||||
- End-to-end trading workflow (signal → order → execution)
|
||||
- Error recovery (reconnection, partial fills)
|
||||
- Regulatory compliance checks
|
||||
|
||||
---
|
||||
|
||||
## Phase 8: Documentation & Deployment (Effort: 2-3 days)
|
||||
|
||||
### 8.1 Update README.md
|
||||
- Forex setup instructions (API signup, credentials)
|
||||
- Example configurations for different strategies
|
||||
- Risk disclaimers for leverage trading
|
||||
|
||||
### 8.2 API Documentation
|
||||
- Document new forex data providers
|
||||
- Agent configuration reference
|
||||
- Position sizing formula explanation
|
||||
|
||||
### 8.3 Deployment
|
||||
- Docker configuration updates for 24/5 operation
|
||||
- Environment variable setup (API keys, secrets)
|
||||
- Monitoring & alerting setup
|
||||
|
||||
---
|
||||
|
||||
## Dependency Graph & Critical Path
|
||||
|
||||
```
|
||||
Phase 0: Configuration ◄── CRITICAL (blocks everything)
|
||||
↓
|
||||
├─→ Phase 1: Data Integration (5-6 days)
|
||||
│ ├─→ Phase 4: Risk Management (4-5 days)
|
||||
│
|
||||
└─→ Phase 2: Abstraction (6-8 days)
|
||||
└─→ Phase 3: Strategy (7-10 days)
|
||||
|
||||
Phase 5: Monitoring (3-4 days) ◄── After Phase 1
|
||||
Phase 6: CLI (3-4 days) ◄── After Phase 2 & 3
|
||||
Phase 7: Testing (5-6 days) ◄── Parallel throughout
|
||||
Phase 8: Documentation (2-3 days) ◄── Final
|
||||
```
|
||||
|
||||
**Total Sequential Time**: ~8-12 weeks (with parallelization)
|
||||
|
||||
---
|
||||
|
||||
## MVP vs. Enhancements
|
||||
|
||||
### MVP (Phase 0, 1, 2, 3, 4, 5) — **Weeks 1-8**
|
||||
- Single forex pair (EUR/USD)
|
||||
- Single provider (OANDA)
|
||||
- Swing trading strategy only
|
||||
- Basic risk management (leverage limits, position sizing)
|
||||
- Backtesting capability
|
||||
|
||||
### Phase 1 Enhancement (Week 9+)
|
||||
- Multi-pair support (5-10 major pairs)
|
||||
- Strategy selection (scalping, carry trade)
|
||||
- Economic calendar integration
|
||||
|
||||
### Phase 2 Enhancement (Week 12+)
|
||||
- Second provider (Forex.com)
|
||||
- Regulatory compliance (FIFO)
|
||||
- Advanced analytics (correlation heatmaps, volatility skew)
|
||||
|
||||
---
|
||||
|
||||
## File Structure Summary
|
||||
|
||||
```
|
||||
tradingagents/
|
||||
├── models/
|
||||
│ ├── instrument.py [NEW] Base Instrument, CurrencyPair
|
||||
├── config/
|
||||
│ ├── forex_config.py [NEW] Forex configuration schema
|
||||
├── dataflows/
|
||||
│ ├── oanda_api.py [NEW]
|
||||
│ ├── forexcom_api.py [NEW]
|
||||
│ ├── forex_common.py [NEW]
|
||||
│ └── forex_provider_factory.py [NEW]
|
||||
├── agents/
|
||||
│ ├── analysts/
|
||||
│ │ ├── forex_technician.py [NEW]
|
||||
│ │ └── macro_analyst.py [NEW]
|
||||
│ ├── traders/
|
||||
│ │ └── forex_trader.py [NEW]
|
||||
│ └── [UPDATED] All agents refactored for Instrument abstraction
|
||||
├── utils/
|
||||
│ ├── forex_position_sizing.py [NEW]
|
||||
│ ├── forex_metrics.py [NEW]
|
||||
│ ├── market_monitor.py [NEW]
|
||||
│ ├── forex_trade_journal.py [NEW]
|
||||
├── backtest/
|
||||
│ └── forex_backtest.py [NEW]
|
||||
├── graph/
|
||||
│ └── [UPDATED] Conditional logic for asset-specific analysis
|
||||
└── llm_clients/
|
||||
└── [UPDATED] Model selection for forex context
|
||||
|
||||
tests/
|
||||
├── test_forex_data_sources.py [NEW]
|
||||
├── test_forex_position_sizing.py [NEW]
|
||||
├── test_instrument_abstraction.py [NEW]
|
||||
├── test_risk_management_forex.py [NEW]
|
||||
└── test_oanda_provider.py [NEW]
|
||||
|
||||
cli/
|
||||
├── [UPDATED] main.py with forex commands
|
||||
├── [UPDATED] config.py with ForexConfig
|
||||
└── static/
|
||||
└── [UPDATED] welcome.txt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
✅ **Phase 0**: Configuration loads without errors, supports multi-provider setup
|
||||
✅ **Phase 1**: Real-time data streams for EUR/USD, GBP/USD, USD/JPY
|
||||
✅ **Phase 2**: Agents work with any instrument type (equity or forex)
|
||||
✅ **Phase 3**: Backtest shows consistent profitability across pairs
|
||||
✅ **Phase 4**: No positions exceed max leverage; margin alerts trigger correctly
|
||||
✅ **Phase 5**: 24/5 operation handles disconnects gracefully
|
||||
✅ **Phase 6**: CLI trades EUR/USD via simulated orders
|
||||
✅ **Phase 7**: Test coverage >80% for new modules; backtest results reproducible
|
||||
✅ **Phase 8**: Documentation covers all forex features; setup takes <30 min
|
||||
|
||||
---
|
||||
|
||||
## Key Technical Decisions
|
||||
|
||||
| Decision | Rationale |
|
||||
|----------|-----------|
|
||||
| Factory pattern for providers | Easy to add new data sources (Forex.com, IB, etc.) |
|
||||
| Instrument abstraction | Enables future crypto, commodities support |
|
||||
| Config-driven trading mode | No code changes to switch between forex & equity |
|
||||
| Micro-lot focus for MVP | Reduces capital requirements, good for testing |
|
||||
| 24/5 monitoring separate from agents | Decouples market ops from trading logic |
|
||||
| Backtesting module | Validate strategies before live trading |
|
||||
| FIFO compliance tracking | Regulatory risk mitigation |
|
||||
|
||||
---
|
||||
|
||||
## References & Compliance
|
||||
- **Forex Regulations**: FIFO rules (NFA, Canada), leverage limits by jurisdiction
|
||||
- **Trading Standards**: ISO 4217 (currency codes), OANDA API v20 spec
|
||||
- **Risk Management**: Position sizing formulas from "Money Management" (Vince, 1990)
|
||||
- **Technical Analysis**: Standard forex indicators (RSI, MACD, Bollinger Bands)
|
||||
Loading…
Reference in New Issue