feat(ml): WAVE 29 DQN Codebase Cleanup & Refactoring Campaign
BREAKING CHANGES: - Removed orphaned dqn.rs monolithic trainer (4,975 lines) - Removed orphaned dqn_ensemble.rs module (816 lines) - Removed orphaned tft.rs and tft_complete_int8_integration_test.rs - TFT trainer split into modular directory structure DQN Module Refactoring: - Split trainers/dqn.rs into modular structure (config.rs, statistics.rs, trainer.rs) - Fixed hyperopt 39D search space (continuous params only) - Boolean flags (use_dueling, use_double_dqn, use_per, use_noisy_nets) are now FIXED architectural decisions - use_distributional defaults to false (Candle BUG #36 - scatter_add gradient issues) Clean Module Structure: - ml/src/trainers/dqn/ directory with proper mod.rs exports - ml/src/trainers/tft/ directory with config.rs, types.rs, model.rs, trainer.rs, tests.rs - All P0 features validated: TD-error clamping, batch diversity, LR scheduler, priority staleness Documentation: - Added comprehensive docs in docs/codebase-cleanup/ - ADR-001 for DQN refactoring decisions - Rainbow DQN component matrix and quick reference guides Build Status: Compiles with zero errors 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
jgrusewski
172
docs/REFACTORING_SUMMARY.md
Normal file
172
docs/REFACTORING_SUMMARY.md
Normal file
@@ -0,0 +1,172 @@
|
||||
# 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! 🚀
|
||||
Reference in New Issue
Block a user