Directory Organization Summary

Directory Organization Summary

✅ Completed Consolidations

1. `ui/` → `episode1/ui/` ✅

Moved: All UI components to Episode 1
- `dashboard.py` - Episode 1-specific dashboard (two-device balance, coherence, trajectories)
- `audio_viz.py` - Audio visualization utilities
- `gps_viz.py` - GPS visualization utilities

Status: ✅ Moved and `__init__.py` created

---

🔄 `fusion/` Directory Status

Current State

`fusion/` directory contains:
- `phase_lock.py` - Has both `PhaseLock` (general) and `DualPhaseLock` (Episode 1-specific)
- `transformer.py` - ✅ Duplicate of `cc-core/cc_core/fusion/transformer.py`
- `ekf.py` - ✅ Duplicate of `cc-core/cc_core/fusion/ekf.py`

`cc-core/cc_core/fusion/` already contains:
- `phase_lock.py` - Has `PhaseLock` (general-purpose) ✅
- `transformer.py` - ✅
- `ekf.py` - ✅

`episode1/control/` already contains:
- `dual_phase_lock.py` - Episode 1-specific `DualPhaseLock` ✅
- `balance.py` - Episode 1-specific `BalanceFuser` ✅

Issue: Old Imports Still Reference `fusion/`

Files importing from `fusion/`:
- `tests/test_fusion.py` - `from fusion.balance import BalanceFuser`
- `tests/test_performance.py` - `from fusion.balance import BalanceFuser`
- `tests/test_ep1_pll.py` - `from fusion.phase_lock import PhaseLock`
- `tests/test_ep1_balance.py` - `from fusion.balance import BalanceFuser`
- `scripts/replay_episode1_session.py` - `from fusion.balance import BalanceFuser`
- `scripts/run_episode1.py` - `from fusion.balance import BalanceFuser`, `from fusion.phase_lock import PhaseLock`
- `inference/controller/episode1_controller.py` - `from fusion.balance import BalanceFuser`, `from fusion.phase_lock import PhaseLock, DualPhaseLock`
- `inference/run_episode1_offline.py` - `from fusion.balance import BalanceFuser`

Recommendation

Option A: Update All Imports (Recommended)
1. Update all imports from `fusion.balance` → `episode1.control.balance`
2. Update all imports from `fusion.phase_lock` → `cc_core.fusion.phase_lock` (for `PhaseLock`) or `episode1.control.dual_phase_lock` (for `DualPhaseLock`)
3. Remove `fusion/` directory

Option B: Keep `fusion/` as Re-export Stub
- Keep `fusion/` but make it re-export from proper locations
- Less disruptive but adds technical debt

---

📚 `training/` vs `models/resonant_flow/` Relationship

Clear Separation ✅

`models/resonant_flow/` - Model Definitions:
- `conductor.py` (422 lines) - `Conductor` class definition
- `velocity_unet.py` (501 lines) - `VelocityUNet` class definition
- `vocoder.py` (400 lines) - `Vocoder` class definition
- These are PyTorch `nn.Module` classes

`training/` - Training Scripts:
- `train_conductor.py` (684 lines) - Full training pipeline
- `train_velocity_unet.py` (594 lines) - Full training pipeline
- `train_vocoder.py` (664 lines) - Full training pipeline
- `train_phrase_encoder.py` (472 lines) - Full training pipeline
- These import from `models.resonant_flow.*` and train the models

Why Training Scripts Are More Detailed

Training scripts are longer because they include:
- Data loading and preprocessing
- Dataset classes
- Optimizer setup (AdamW, learning rate schedulers)
- Training loops with progress bars
- Validation loops
- Checkpointing logic
- Logging (TensorBoard, console)
- Device management (CUDA/MPS)
- Mixed precision training
- Early stopping
- Model evaluation

This is CORRECT architecture ✅
- Models define architecture
- Training scripts train them
- No duplication, just different purposes

---

Summary

✅ `ui/` → `episode1/ui/` - Completed
🔄 `fusion/` - Needs import updates before removal
✅ `training/` vs `models/resonant_flow/` - Correctly separated (models vs training scripts)