# DQN Trainer Refactoring Plan

## Current State
- **File**: `ml/src/trainers/dqn.rs`
- **Lines**: 4,975
- **Target**: <1,000 lines per module

## Module Extraction Strategy

### Module 1: `dqn/config.rs` (~800 lines)
**Lines 48-747**
- Constants: `EPISODE_LENGTH`, type aliases (`FeatureVector`, `FeatureVector51`)
- `FeatureStatistics` struct + impl (lines 78-157)
- `DQNHyperparameters` struct (lines 425-610)
- `DQNHyperparameters` impl methods (lines 615-747)

### Module 2: `dqn/agent_wrapper.rs` (~260 lines)
**Lines 164-424**
- `DQNAgentType` enum (wrapper for Standard/RegimeConditional)
- `QValueStats` struct
- All `DQNAgentType` impl methods (unified API)

### Module 3: `dqn/training_monitor.rs` (~270 lines)
**Lines 748-1012**
- `TrainingMonitor` struct
- All validation methods (rewards, actions, Q-values)
- Episode tracking

### Module 4: `dqn/trainer.rs` (~3900 lines -> split further)
**Lines 1013-4975**
This needs further breakdown:
- 4a. `trainer_core.rs`: Struct definition, constructors, epoch metrics
- 4b. `training_loop.rs`: Main `train()` and `train_from_parquet()` methods
- 4c. `data_loading.rs`: OHLCV extraction, feature creation
- 4d. `checkpointing.rs`: Checkpoint save/load logic

### Module 5: `dqn/mod.rs` (~50 lines)
- Public re-exports maintaining current API
- Module declarations

## Public API Preservation

**Current public exports from `trainers/dqn`:**
```rust
pub use dqn::{DQNHyperparameters, DQNTrainer};
```

**New structure ensures:**
```rust
// dqn/mod.rs re-exports everything
pub use config::{DQNHyperparameters, FeatureStatistics, EPISODE_LENGTH};
pub use agent_wrapper::{DQNAgentType, QValueStats};
pub use training_monitor::TrainingMonitor;
pub use trainer::DQNTrainer;
```

## Dependencies to Update

1. **Tests**: 19 DQN test files reference `trainers::dqn::`
2. **Hyperopt adapter**: `hyperopt/adapters/dqn.rs` (3,162 lines)
3. **Trainers mod**: `trainers/mod.rs` re-export

## Verification Steps

1. Extract modules incrementally
2. `cargo check --package ml` after each extraction
3. Update imports in dependent files
4. Run test suite: `cargo test --package ml --lib`
5. Verify no breaking changes to public API

## Risk Mitigation

- Keep original `dqn.rs` as `dqn.rs.backup` until verification complete
- Incremental extraction with build checks
- Test after each module extraction