fix: add validation and fix curriculum/teacher issues

Resolves multiple review comments:
- NeuralNetworkBase.cs:2153 - Implement SaveState/LoadState using Serialize/Deserialize
- SelfDistillationTrainer.cs:69 - Validate EMADecay is between 0 and 1
- SelfDistillationTrainer.cs:82 - Fix generation documentation off-by-one error
- CurriculumDistillationStrategyBase.cs:85 - Fix progress normalization to allow 100%
- HardToEasyCurriculumStrategy.cs:190 - Update comments for reachable thresholds
- TeacherModelFactory.cs:83 - Use Average aggregation when no weights supplied
- TeacherModelFactory.cs:117 - Validate modality weights array length
- TransformerTeacherModel.cs:39 - Validate outputDimension is positive
- SelfTeacherModel.cs:45 - Validate cached predictions before storing

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: ooples

src/KnowledgeDistillation/SelfDistillationTrainer.cs

@@ -66,7 +66,19 @@ public class SelfDistillationTrainer<T> : KnowledgeDistillationTrainerBase<T, Ve
     /// <summary>
     /// Gets or sets the EMA decay rate (default 0.99). Higher values give more weight to history.
     /// </summary>
-    public double EMADecay { get; set; }
+    /// <exception cref="ArgumentOutOfRangeException">Thrown when value is not between 0 and 1.</exception>
+    public double EMADecay 
+    { 
+        get => _emaDecay;
+        set
+        {
+            if (value <= 0 || value >= 1)
+                throw new ArgumentOutOfRangeException(nameof(value), 
+                    "EMADecay must be between 0 and 1 (exclusive). Typical values are 0.9-0.999.");
+            _emaDecay = value;
+        }
+    }
+    private double _emaDecay = 0.99;
 
     /// <summary>
     /// Initializes a new instance of the SelfDistillationTrainer class.
@@ -77,8 +89,9 @@ public class SelfDistillationTrainer<T> : KnowledgeDistillationTrainerBase<T, Ve
     /// <param name="seed">Optional random seed for reproducibility.</param>
     /// <remarks>
     /// <para><b>For Beginners:</b> Generations control how many times the model relearns from itself:
-    /// - 1 generation: Train normally, then retrain with self as teacher
-    /// - 2 generations: Do it twice (teacher → student1 → student2)
+    /// - 1 generation: Train normally (standard training, no self-distillation)
+    /// - 2 generations: Train, then retrain using self as teacher (first self-distillation)
+    /// - 3 generations: Train → self-teach → self-teach again
     /// - More generations: Diminishing returns, usually not worth it beyond 2-3</para>
     ///
     /// <para>Example:

src/KnowledgeDistillation/Strategies/CurriculumDistillationStrategyBase.cs

@@ -81,7 +81,8 @@ protected CurriculumDistillationStrategyBase(
     /// </summary>
     public virtual void UpdateProgress(int step)
     {
-        _currentStep = Math.Max(0, Math.Min(step, TotalSteps - 1));
+        // Don't clamp to TotalSteps - 1; allow reaching TotalSteps for full 100% progress
+        _currentStep = Math.Max(0, Math.Min(step, TotalSteps));
     }
 
     /// <summary>

src/KnowledgeDistillation/Strategies/HardToEasyCurriculumStrategy.cs

@@ -148,9 +148,11 @@ public override bool ShouldIncludeSample(int sampleIndex)
         if (difficulty == null)
             return true;
 
-        // Hard-to-Easy: Include samples with difficulty ≥ (1 - current progress)
-        // Progress 0.0 → only hardest samples (difficulty ≥ 1.0)
-        // Progress 1.0 → all samples (difficulty ≥ 0.0)
+        // Hard-to-Easy: Include samples with difficulty >= (1 - current progress)
+        // Progress 0.0 → only hardest samples (difficulty >= 1.0, threshold = 1.0)
+        // Progress 0.5 → medium samples (difficulty >= 0.5, threshold = 0.5)  
+        // Progress 1.0 → all samples (difficulty >= 0.0, threshold = 0.0)
+        // With progress now able to reach exactly 1.0, threshold can reach 0.0
         double threshold = 1.0 - CurriculumProgress;
         return difficulty.Value >= threshold;
     }

src/KnowledgeDistillation/TeacherModelFactory.cs

@@ -75,9 +75,10 @@ private static ITeacherModel<Vector<T>, Vector<T>> CreateEnsembleTeacher(
         if (ensembleModels == null || ensembleModels.Length == 0)
             throw new ArgumentException("Ensemble models are required for Ensemble teacher type");
 
-        var aggregation = ensembleWeights != null
+        // Use plain average when no weights are supplied
+        var aggregation = ensembleWeights != null && ensembleWeights.Length > 0
             ? EnsembleAggregationMode.WeightedAverage
-            : EnsembleAggregationMode.WeightedAverage;
+            : EnsembleAggregationMode.Average;
 
         return new EnsembleTeacherModel<T>(ensembleModels, ensembleWeights, aggregation);
     }
@@ -112,6 +113,9 @@ private static ITeacherModel<Vector<T>, Vector<T>> CreateMultiModalTeacher(
     {
         if (modalityTeachers == null || modalityTeachers.Length == 0)
             throw new ArgumentException("Modality teachers are required for MultiModal teacher type");
+        if (modalityWeights != null && modalityWeights.Length != modalityTeachers.Length)
+            throw new ArgumentException(
+                $"Modality weights length ({modalityWeights.Length}) must match modality teachers length ({modalityTeachers.Length})");
 
         return new MultiModalTeacherModel<T>(modalityTeachers, modalityWeights);
     }

src/KnowledgeDistillation/Teachers/SelfTeacherModel.cs

@@ -18,8 +18,28 @@ public SelfTeacherModel(int outputDimension)
         _outputDim = outputDimension;
     }
 
+    /// <summary>
+    /// Caches predictions from the student model for later use.
+    /// </summary>
+    /// <param name="predictions">The predictions to cache.</param>
+    /// <exception cref="ArgumentNullException">Thrown when predictions is null.</exception>
+    /// <exception cref="ArgumentException">Thrown when predictions array is empty or contains null/zero-length vectors.</exception>
     public void CachePredictions(Vector<T>[] predictions)
     {
+        if (predictions == null)
+            throw new ArgumentNullException(nameof(predictions));
+        if (predictions.Length == 0)
+            throw new ArgumentException("Predictions array cannot be empty.", nameof(predictions));
+        
+        // Validate that all prediction vectors are non-null and non-empty
+        for (int i = 0; i < predictions.Length; i++)
+        {
+            if (predictions[i] == null)
+                throw new ArgumentException($"Prediction at index {i} is null.", nameof(predictions));
+            if (predictions[i].Length == 0)
+                throw new ArgumentException($"Prediction at index {i} has zero length.", nameof(predictions));
+        }
+        
         _cachedPredictions = predictions;
     }
 

src/KnowledgeDistillation/Teachers/TransformerTeacherModel.cs

@@ -30,11 +30,16 @@ public class TransformerTeacherModel<T> : TeacherModelBase<Vector<T>, Vector<T>,
     /// </summary>
     /// <param name="forwardFunc">Function that performs forward pass and returns logits.</param>
     /// <param name="outputDimension">The number of output dimensions.</param>
+    /// <exception cref="ArgumentNullException">Thrown when forwardFunc is null.</exception>
+    /// <exception cref="ArgumentOutOfRangeException">Thrown when outputDimension is not positive.</exception>
     public TransformerTeacherModel(
         Func<Vector<T>, Vector<T>> forwardFunc,
         int outputDimension)
     {
         _forwardFunc = forwardFunc ?? throw new ArgumentNullException(nameof(forwardFunc));
+        if (outputDimension <= 0)
+            throw new ArgumentOutOfRangeException(nameof(outputDimension), 
+                "Output dimension must be positive.");
         _outputDim = outputDimension;
     }
 

src/NeuralNetworks/NeuralNetworkBase.cs

@@ -2140,7 +2140,11 @@ public virtual void ApplyGradients(Vector<T> gradients, T learningRate)
     /// <param name="stream">The stream to write the model state to.</param>
     public virtual void SaveState(Stream stream)
     {
-        throw new NotImplementedException("SaveState is not yet implemented for NeuralNetworkBase. Consider using explicit serialization of layer parameters.");
+        if (stream == null) throw new ArgumentNullException(nameof(stream));
+        if (!stream.CanWrite) throw new ArgumentException("Stream must be writable.", nameof(stream));
+        var data = Serialize();
+        stream.Write(data, 0, data.Length);
+        stream.Flush();
     }
 
     /// <summary>
@@ -2149,6 +2153,12 @@ public virtual void SaveState(Stream stream)
     /// <param name="stream">The stream to read the model state from.</param>
     public virtual void LoadState(Stream stream)
     {
-        throw new NotImplementedException("LoadState is not yet implemented for NeuralNetworkBase. Consider using explicit deserialization of layer parameters.");
+        if (stream == null) throw new ArgumentNullException(nameof(stream));
+        if (!stream.CanRead) throw new ArgumentException("Stream must be readable.", nameof(stream));
+        using var ms = new MemoryStream();
+        stream.CopyTo(ms);
+        var data = ms.ToArray();
+        if (data.Length == 0) throw new InvalidOperationException("Stream contains no data.");
+        Deserialize(data);
     }
 }