2df1ea92e1
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>
173 lines
4.8 KiB
Markdown
173 lines
4.8 KiB
Markdown
# 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! 🚀
|