refactor: Implement YAML-based difficulty and time system

- Added educational metadata (difficulty, time_estimate) to all module.yaml files
- Updated convert_readmes.py to read from YAML instead of hardcoded mappings
- Standardized difficulty progression: ⭐ → ⭐⭐ → ⭐⭐⭐ → ⭐⭐⭐⭐ → ⭐⭐⭐⭐⭐🥷
- Fixed path resolution for YAML reading in book build process
- Eliminated duplication: single source of truth for educational metadata
- Capstone gets special ninja treatment (⭐⭐⭐⭐⭐🥷) as beyond-expert level

book/convert_readmes.py

@@ -172,46 +172,18 @@ Ready for serious development? → [🏗️ Local Setup Guide](../usage-paths/se
     return '\n'.join(enhanced_lines)
 
 def get_difficulty_stars(module_name: str) -> str:
-    """Get difficulty stars based on module name."""
-    difficulty_map = {
-        '01_setup': '⭐',
-        '02_tensor': '⭐⭐',
-        '03_activations': '⭐⭐',
-        '04_layers': '⭐⭐⭐',
-        '05_networks': '⭐⭐⭐',
-        '06_cnn': '⭐⭐⭐⭐',
-        '07_dataloader': '⭐⭐⭐',
-        '08_autograd': '⭐⭐⭐⭐',
-        '09_optimizers': '⭐⭐⭐⭐',
-        '10_training': '⭐⭐⭐⭐',
-        '11_compression': '⭐⭐⭐⭐⭐',
-        '12_kernels': '⭐⭐⭐⭐⭐',
-        '13_benchmarking': '⭐⭐⭐⭐⭐',
-        '14_mlops': '⭐⭐⭐⭐⭐',
-        '15_capstone': '⭐⭐⭐⭐⭐'
-    }
-    return difficulty_map.get(module_name, '⭐⭐')
+    """Get difficulty stars from module.yaml file."""
+    # Map module number to module folder name  
+    module_path = Path(f'../modules/source/{module_name}')
+    module_info = get_module_info(module_path)
+    return module_info.get('difficulty', '⭐⭐')
 
 def get_time_estimate(module_name: str) -> str:
-    """Get time estimate based on module name."""
-    time_map = {
-        '01_setup': '1-2 hours',
-        '02_tensor': '4-6 hours',
-        '03_activations': '3-4 hours',
-        '04_layers': '4-5 hours',
-        '05_networks': '5-6 hours',
-        '06_cnn': '6-8 hours',
-        '07_dataloader': '4-5 hours',
-        '08_autograd': '6-8 hours',
-        '09_optimizers': '5-6 hours',
-        '10_training': '6-8 hours',
-        '11_compression': '4-5 hours',
-        '12_kernels': '5-6 hours',
-        '13_benchmarking': '4-5 hours',
-        '14_mlops': '6-8 hours',
-        '15_capstone': 'Capstone Project'
-    }
-    return time_map.get(module_name, '3-4 hours')
+    """Get time estimate from module.yaml file."""
+    # Map module number to module folder name
+    module_path = Path(f'../modules/source/{module_name}')
+    module_info = get_module_info(module_path)
+    return module_info.get('time_estimate', '3-4 hours')
 
 def get_prev_module_name(module_num: int) -> str:
     """Get previous module name."""

modules/source/01_setup/module.yaml

@@ -19,6 +19,10 @@ files:
   readme: "README.md"
   tests: "inline"
 
+# Educational Metadata
+difficulty: "⭐"
+time_estimate: "1-2 hours"
+
 # Components - What's implemented in this module
 components:
   - "personal_info"

modules/source/02_tensor/module.yaml

@@ -16,8 +16,12 @@ exports_to: "tinytorch.core.tensor"
 # File Structure - What files exist in this module
 files:
   dev_file: "tensor_dev.py"
-  test_file: "tests/test_tensor.py"
   readme: "README.md"
+  tests: "inline"
+
+# Educational Metadata
+difficulty: "⭐⭐"
+time_estimate: "4-6 hours"
 
 # Components - What's implemented in this module
 components:

modules/source/03_activations/module.yaml

@@ -16,8 +16,12 @@ exports_to: "tinytorch.core.activations"
 # File Structure - What files exist in this module
 files:
   dev_file: "activations_dev.py"
-  test_file: "tests/test_activations.py"
   readme: "README.md"
+  tests: "inline"
+
+# Educational Metadata
+difficulty: "⭐⭐"
+time_estimate: "3-4 hours"
 
 # Components - What's implemented in this module
 components:

modules/source/04_layers/module.yaml

@@ -16,8 +16,12 @@ exports_to: "tinytorch.core.layers"
 # File Structure - What files exist in this module
 files:
   dev_file: "layers_dev.py"
-  test_file: "tests/test_layers.py"
   readme: "README.md"
+  tests: "inline"
+
+# Educational Metadata
+difficulty: "⭐⭐"
+time_estimate: "4-5 hours"
 
 # Components - What's implemented in this module
 components:

modules/source/05_networks/module.yaml

@@ -19,6 +19,10 @@ files:
   readme: "README.md"
   tests: "inline"
 
+# Educational Metadata
+difficulty: "⭐⭐⭐"
+time_estimate: "5-6 hours"
+
 # Components - What's implemented in this module
 components:
   - "Sequential"

modules/source/06_cnn/module.yaml

@@ -19,6 +19,10 @@ files:
   readme: "README.md"
   tests: "inline"
 
+# Educational Metadata
+difficulty: "⭐⭐⭐"
+time_estimate: "6-8 hours"
+
 # Components - What's implemented in this module
 components:
   - "conv2d_naive"

modules/source/07_dataloader/module.yaml

@@ -19,6 +19,10 @@ files:
   readme: "README.md"
   tests: "inline"
 
+# Educational Metadata
+difficulty: "⭐⭐⭐"
+time_estimate: "5-6 hours"
+
 # Components - What's implemented in this module
 components:
   - "Dataset"

modules/source/08_autograd/module.yaml

@@ -19,6 +19,10 @@ files:
   test_file: "tests/test_autograd.py"
   readme: "README.md"
 
+# Educational Metadata
+difficulty: "⭐⭐⭐⭐"
+time_estimate: "8-10 hours"
+
 # Components - What's implemented in this module
 components:
   - "Variable"

modules/source/09_optimizers/module.yaml

@@ -19,6 +19,10 @@ files:
   readme: "README.md"
   tests: "inline"
 
+# Educational Metadata
+difficulty: "⭐⭐⭐⭐"
+time_estimate: "6-8 hours"
+
 # Components - What's implemented in this module
 components:
   - "SGD"

modules/source/10_training/module.yaml

@@ -19,6 +19,10 @@ files:
   readme: "README.md"
   tests: "inline"
 
+# Educational Metadata
+difficulty: "⭐⭐⭐⭐"
+time_estimate: "8-10 hours"
+
 # Components - What's implemented in this module
 components:
   - "MeanSquaredError"

modules/source/11_compression/module.yaml

@@ -114,4 +114,14 @@ assessment_criteria:
 next_steps:
   - "Module 11: Kernels - Hardware-aware optimization"
   - "Module 12: Benchmarking - Performance measurement"
-  - "Module 13: MLOps - Production deployment" 
+  - "Module 13: MLOps - Production deployment" 
+
+# File Structure - What files exist in this module
+files:
+  dev_file: "compression_dev.py"
+  readme: "README.md"
+  tests: "inline"
+
+# Educational Metadata
+difficulty: "⭐⭐⭐⭐"
+time_estimate: "8-10 hours" 

modules/source/12_kernels/module.yaml

@@ -23,6 +23,10 @@ files:
   readme: "README.md"
   tests: "inline"
 
+# Educational Metadata
+difficulty: "⭐⭐⭐⭐"
+time_estimate: "8-10 hours"
+
 # Components - What's implemented in this module
 components:
   - "matmul_custom"

modules/source/13_benchmarking/module.yaml

@@ -23,6 +23,10 @@ files:
   readme: "README.md"
   tests: "inline"
 
+# Educational Metadata
+difficulty: "⭐⭐⭐⭐"
+time_estimate: "4-5 hours"
+
 # Components - What's implemented in this module
 components:
   - "TinyTorchPerf"

modules/source/14_mlops/module.yaml

@@ -24,6 +24,10 @@ files:
   readme: "README.md"
   tests: "inline"
 
+# Educational Metadata
+difficulty: "⭐⭐⭐⭐"
+time_estimate: "8-10 hours"
+
 # Components - What's implemented in this module
 components:
   - "ModelMonitor"

modules/source/15_capstone/module.yaml

@@ -2,7 +2,7 @@
 # Essential system information for CLI tools and build systems
 
 name: "capstone"
-title: "Capstone: Framework Optimization"
+title: "Capstone Project"
 description: "Optimize and extend your complete TinyTorch framework through systems engineering"
 
 # Dependencies - Used by CLI for module ordering and prerequisites
@@ -19,9 +19,13 @@ exports_to: "tinytorch.capstone"
 
 # File Structure - What files exist in this module
 files:
-  dev_file: "capstone_guide.md"
+  dev_file: "capstone_dev.py"
   readme: "README.md"
-  tests: "project_based"
+  tests: "inline"
+
+# Educational Metadata
+difficulty: "⭐⭐⭐⭐⭐ 🥷"
+time_estimate: "Capstone Project"
 
 # Components - What's implemented in this module
 components: