# ML Trainer Refactoring - Quick Reference

## Status: ANALYSIS COMPLETE ✅

**All planning, documentation, and extraction scripts are ready for execution.**

---

## Files to Refactor

| File | Lines | Target Modules | Status |
|------|-------|----------------|--------|
| `trainers/dqn.rs` | 4,975 | 8 modules | 🔄 Backup created, scripts ready |
| `trainers/tft.rs` | 2,915 | 6 modules | 📋 Plan documented |
| `hyperopt/adapters/dqn.rs` | 3,162 | 4 modules | 📋 Plan documented |
| `trainers/mamba2.rs` | 544 | - | ✅ OK (under 1K) |

---

## Quick Start for Next Agent

### Step 1: Execute DQN Extraction Scripts

```bash
cd /home/jgrusewski/Work/foxhunt

# Extract config module
sed -n '48,747p' ml/src/trainers/dqn.rs.backup > ml/src/trainers/dqn/config.rs
# Add header (see docs/dqn_refactoring_implementation.md Script 1)
cargo check --package ml

# Extract agent wrapper
sed -n '164,424p' ml/src/trainers/dqn.rs.backup > ml/src/trainers/dqn/agent_wrapper.rs
# Add header (see docs/dqn_refactoring_implementation.md Script 2)
cargo check --package ml

# Extract training monitor
sed -n '728,1012p' ml/src/trainers/dqn.rs.backup > ml/src/trainers/dqn/training_monitor.rs
# Add header (see docs/dqn_refactoring_implementation.md Script 3)
cargo check --package ml
```

### Step 2: Manual Extractions (Complex)

See `docs/dqn_refactoring_implementation.md` for detailed line mappings:
- `trainer_core.rs`: Lines 1013-1680 (~600 lines)
- `training_loop.rs`: Lines 1464-2980 (~1500 lines)
- `data_loading.rs`: Lines 3482-4600 (~600 lines)
- `checkpointing.rs`: Scattered locations (~200 lines)

### Step 3: Create Module Root

Create `ml/src/trainers/dqn/mod.rs` with public re-exports (see ADR-001 for template).

### Step 4: Verify

```bash
cargo build --package ml
cargo test --package ml --lib
# Expect: All 19 DQN tests pass
```

---

## Documentation Files

1. **REFACTORING_REPORT.md** (this is the master document)
   - Complete project overview
   - Timeline estimates
   - Risk mitigation

2. **ADR-001-dqn-refactoring.md**
   - Architecture decision rationale
   - Module responsibilities
   - Public API strategy

3. **dqn_refactoring_plan.md**
   - High-level strategy
   - Module boundaries

4. **dqn_refactoring_implementation.md**
   - Detailed extraction scripts
   - Line-by-line mappings
   - Execution checklist

---

## Backup Information

- **Original file**: `ml/src/trainers/dqn.rs` (4,975 lines)
- **Backup location**: `ml/src/trainers/dqn.rs.backup`
- **Created**: 2025-11-27 15:33

### Rollback Procedure (if needed)

```bash
rm -rf ml/src/trainers/dqn/
mv ml/src/trainers/dqn.rs.backup ml/src/trainers/dqn.rs
cargo check --package ml
```

---

## Expected Results

### Before Refactoring
```
ml/src/trainers/
├── dqn.rs          (4,975 lines) ❌
├── tft.rs          (2,915 lines) ❌
├── mamba2.rs       (544 lines) ✅
└── mod.rs
```

### After Refactoring
```
ml/src/trainers/
├── dqn/
│   ├── mod.rs                (~50 lines) ✅
│   ├── config.rs             (~800 lines) ✅
│   ├── agent_wrapper.rs      (~260 lines) ✅
│   ├── training_monitor.rs   (~265 lines) ✅
│   ├── trainer_core.rs       (~600 lines) ✅
│   ├── training_loop.rs      (~1500 lines) ⚠️ (target: split further to <1K)
│   ├── data_loading.rs       (~600 lines) ✅
│   └── checkpointing.rs      (~200 lines) ✅
├── tft/
│   ├── mod.rs                (~50 lines) ✅
│   ├── config.rs             (~400 lines) ✅
│   ├── encoder.rs            (~600 lines) ✅
│   ├── attention.rs          (~500 lines) ✅
│   ├── decoder.rs            (~400 lines) ✅
│   └── training.rs           (~900 lines) ✅
├── mamba2.rs       (544 lines) ✅
└── mod.rs
```

**Note**: `training_loop.rs` at ~1500 lines may need further splitting into:
- `training_loop.rs` (main training logic, ~800 lines)
- `training_helpers.rs` (helper methods, ~700 lines)

---

## Key Decisions

1. **Zero breaking changes**: Public API preserved via re-exports in `mod.rs`
2. **Incremental verification**: `cargo check` after each extraction
3. **Safe rollback**: Backup file maintained until full verification
4. **Clear boundaries**: Each module has single responsibility

---

## Contact Information

**Swarm ID**: `swarm_1764253799645_zlazqh589`
**Agent Role**: `ml-refactorer` (System Architecture Designer)
**Task**: Split oversized ML trainer files into maintainable modules

---

## Next Agent Instructions

You have everything you need:
1. ✅ Backup created
2. ✅ Directories ready
3. ✅ Extraction scripts documented
4. ✅ Architecture decisions documented
5. ✅ Implementation guide complete

**Start with Phase 1 (DQN)**, verify each step with `cargo check`, then proceed to TFT and hyperopt adapter.

Good luck! 🚀