refactor: apply facade pattern to automatic checkpointing architecture

claude · claude · commit b2ce7b417cb0 · 2025-11-12T02:30:09.000Z
Refactor checkpointing implementation to follow the library's facade pattern,
hiding implementation details and providing a clean, simple API.

Changes:
- Remove public CheckpointConfig and Student properties from trainer base
- Add checkpointConfig parameter to trainer constructor (optional)
- Add student parameter to Train method (optional)
- Make checkpoint manager and fields private/internal
- Update KnowledgeDistillationTrainer constructor to accept checkpointConfig
- Update CHECKPOINTING_GUIDE.md to show new facade-based usage

Architecture improvements:
- Follows facade pattern (hide complexity, expose simple interface)
- Configuration injected through constructor (proper DI pattern)
- Student model passed to Train method (clean method signature)
- No mutable public state exposed
- Internal implementation fully encapsulated

Old usage (anti-pattern):
trainer.CheckpointConfig = config;  // Public property mutation
trainer.Student = student;          // Public property mutation
trainer.Train(...);

New usage (facade pattern):
var trainer = new Trainer(teacher, strategy, checkpointConfig: config);
trainer.Train(..., student: student);

This matches the library's architectural principles and provides a cleaner API.
diff --git a/src/KnowledgeDistillation/CHECKPOINTING_GUIDE.md b/src/KnowledgeDistillation/CHECKPOINTING_GUIDE.md
@@ -62,25 +62,15 @@ DistillationCheckpointManager<T>
 
 ## Quick Start: Automatic Checkpointing (Recommended)
 
-The easiest way to enable checkpointing is through automatic checkpointing built into the trainer. Simply configure the checkpoint settings and the trainer handles everything automatically.
+The easiest way to enable checkpointing is through automatic checkpointing built into the trainer. Simply pass the checkpoint configuration to the trainer constructor and the student model to the Train method.
 
 ### Automatic Checkpointing Example
 
 ```csharp
 using AiDotNet.KnowledgeDistillation;
 
-// Create trainer
-var teacher = LoadPretrainedTeacher();
-var student = CreateStudentModel();  // Must implement ICheckpointableModel
-var strategy = new ConfidenceBasedAdaptiveStrategy<double>();
-
-var trainer = new KnowledgeDistillationTrainer<double, Vector<double>, Vector<double>>(
-    teacher,
-    strategy
-);
-
-// Enable automatic checkpointing by setting CheckpointConfig
-trainer.CheckpointConfig = new DistillationCheckpointConfig
+// Create checkpoint configuration
+var checkpointConfig = new DistillationCheckpointConfig
 {
     CheckpointDirectory = "./checkpoints",
     SaveEveryEpochs = 5,          // Auto-save every 5 epochs
@@ -90,10 +80,20 @@ trainer.CheckpointConfig = new DistillationCheckpointConfig
     LowerIsBetter = true
 };
 
-// Set the student model (required for checkpointing)
-trainer.Student = student as ICheckpointableModel;
+// Create trainer with checkpoint config
+var teacher = LoadPretrainedTeacher();
+var strategy = new ConfidenceBasedAdaptiveStrategy<double>();
+
+var trainer = new KnowledgeDistillationTrainer<double>(
+    teacher,
+    strategy,
+    checkpointConfig: checkpointConfig  // Pass config to constructor
+);
+
+// Create student model (must implement ICheckpointableModel)
+var student = CreateStudentModel();
 
-// Train - checkpointing happens automatically!
+// Train - pass student to Train method for automatic checkpointing!
 trainer.Train(
     studentForward: student.Predict,
     studentBackward: student.ApplyGradient,
@@ -102,7 +102,8 @@ trainer.Train(
     epochs: 100,
     batchSize: 32,
     validationInputs: validationData,
-    validationLabels: validationLabels
+    validationLabels: validationLabels,
+    student: student as ICheckpointableModel  // Pass student for checkpointing
 );
 
 // After training completes, the best checkpoint is automatically loaded!
@@ -120,13 +121,13 @@ Console.WriteLine("Training complete. Best checkpoint automatically restored.");
 - ✅ Automatic best model selection
 - ✅ Automatic checkpoint pruning (keeps only best N)
 - ✅ Curriculum state preservation (if using curriculum strategies)
-- ✅ Clean, simple API
+- ✅ Clean, simple API following facade pattern
 
 ### Disabling Automatic Checkpointing
 
 ```csharp
-// Default: no checkpointing
-trainer.CheckpointConfig = null;  // or simply don't set it
+// Default: no checkpointing (don't pass checkpointConfig)
+var trainer = new KnowledgeDistillationTrainer<double>(teacher, strategy);
 
 // Training proceeds without checkpointing
 trainer.Train(...);
diff --git a/src/KnowledgeDistillation/KnowledgeDistillationTrainer.cs b/src/KnowledgeDistillation/KnowledgeDistillationTrainer.cs
@@ -41,11 +41,13 @@ public class KnowledgeDistillationTrainer<T> : KnowledgeDistillationTrainerBase<
     /// </summary>
     /// <param name="teacher">The teacher model to learn from.</param>
     /// <param name="distillationStrategy">The strategy for computing distillation loss.</param>
+    /// <param name="checkpointConfig">Optional checkpoint configuration for automatic model saving during training.</param>
     /// <param name="seed">Optional random seed for reproducibility.</param>
     /// <remarks>
     /// <para><b>For Beginners:</b> Create a trainer by providing:
     /// 1. A trained teacher model (already performing well on your task)
-    /// 2. A distillation strategy (defines how to transfer knowledge)</para>
+    /// 2. A distillation strategy (defines how to transfer knowledge)
+    /// 3. Optional checkpoint configuration (for automatic model saving)</para>
     ///
     /// <para>Example:
     /// <code>
@@ -54,12 +56,28 @@ public class KnowledgeDistillationTrainer<T> : KnowledgeDistillationTrainerBase<
     /// var trainer = new KnowledgeDistillationTrainer&lt;double&gt;(teacher, distillationLoss);
     /// </code>
     /// </para>
+    ///
+    /// <para>Example with automatic checkpointing:
+    /// <code>
+    /// var checkpointConfig = new DistillationCheckpointConfig
+    /// {
+    ///     SaveEveryEpochs = 5,
+    ///     KeepBestN = 3
+    /// };
+    /// var trainer = new KnowledgeDistillationTrainer&lt;double&gt;(
+    ///     teacher,
+    ///     distillationLoss,
+    ///     checkpointConfig: checkpointConfig
+    /// );
+    /// </code>
+    /// </para>
     /// </remarks>
     public KnowledgeDistillationTrainer(
         ITeacherModel<Vector<T>, Vector<T>> teacher,
         IDistillationStrategy<T, Vector<T>> distillationStrategy,
+        DistillationCheckpointConfig? checkpointConfig = null,
         int? seed = null)
-        : base(teacher, distillationStrategy, seed)
+        : base(teacher, distillationStrategy, checkpointConfig, seed)
     {
     }
 
diff --git a/src/KnowledgeDistillation/KnowledgeDistillationTrainerBase.cs b/src/KnowledgeDistillation/KnowledgeDistillationTrainerBase.cs
@@ -57,41 +57,19 @@ public abstract class KnowledgeDistillationTrainerBase<T, TInput, TOutput> : IKn
     public IDistillationStrategy<T, TOutput> DistillationStrategy { get; protected set; }
 
     /// <summary>
-    /// Gets or sets the checkpoint configuration for automatic model saving during training.
+    /// Checkpoint configuration for automatic model saving during training (internal).
     /// </summary>
-    /// <remarks>
-    /// <para><b>For Beginners:</b> Set this property to enable automatic checkpointing.
-    /// If null (default), no automatic checkpointing occurs. If set, the trainer will automatically:
-    /// - Save checkpoints based on your configuration (e.g., every 5 epochs)
-    /// - Keep only the best N checkpoints to save disk space
-    /// - Load the best checkpoint after training completes</para>
-    ///
-    /// <para><b>Example:</b>
-    /// <code>
-    /// trainer.CheckpointConfig = new DistillationCheckpointConfig
-    /// {
-    ///     SaveEveryEpochs = 5,
-    ///     KeepBestN = 3,
-    ///     BestMetric = "validation_loss"
-    /// };
-    /// </code>
-    /// </para>
-    /// </remarks>
-    public DistillationCheckpointConfig? CheckpointConfig { get; set; }
+    private readonly DistillationCheckpointConfig? _checkpointConfig;
 
     /// <summary>
-    /// Gets or sets the student model for checkpointing.
+    /// Checkpoint manager for handling checkpoint operations (internal).
     /// </summary>
-    /// <remarks>
-    /// <para>Set this if you want automatic checkpointing. The student must implement
-    /// <see cref="ICheckpointableModel"/> for checkpoint saving/loading to work.</para>
-    /// </remarks>
-    public ICheckpointableModel? Student { get; set; }
+    private DistillationCheckpointManager<T>? _checkpointManager;
 
     /// <summary>
-    /// Gets the checkpoint manager (created automatically when CheckpointConfig is set).
+    /// Student model reference for checkpointing (internal).
     /// </summary>
-    protected DistillationCheckpointManager<T>? CheckpointManager { get; private set; }
+    private ICheckpointableModel? _student;
 
     private double _lastValidationMetric;
     private T _lastTrainingLoss;
@@ -102,22 +80,40 @@ public abstract class KnowledgeDistillationTrainerBase<T, TInput, TOutput> : IKn
     /// </summary>
     /// <param name="teacher">The teacher model.</param>
     /// <param name="distillationStrategy">The distillation strategy.</param>
+    /// <param name="checkpointConfig">Optional checkpoint configuration for automatic model saving during training.</param>
     /// <param name="seed">Optional random seed for reproducibility.</param>
     /// <remarks>
     /// <para><b>For Beginners:</b> The teacher and strategy are the core components:
     /// - Teacher: Provides the "expert" knowledge to transfer
     /// - Strategy: Defines how to measure and optimize the knowledge transfer</para>
     ///
-    /// <para><b>Automatic Checkpointing:</b> To enable automatic checkpointing, set the
-    /// <see cref="CheckpointConfig"/> and <see cref="Student"/> properties after construction.</para>
+    /// <para><b>Automatic Checkpointing:</b> To enable automatic checkpointing, pass a
+    /// <see cref="DistillationCheckpointConfig"/> instance. If null (default), no automatic checkpointing occurs.
+    /// When enabled, the trainer will automatically:
+    /// - Save checkpoints based on your configuration (e.g., every 5 epochs)
+    /// - Keep only the best N checkpoints to save disk space
+    /// - Load the best checkpoint after training completes</para>
+    ///
+    /// <para><b>Example with Checkpointing:</b>
+    /// <code>
+    /// var config = new DistillationCheckpointConfig
+    /// {
+    ///     SaveEveryEpochs = 5,
+    ///     KeepBestN = 3
+    /// };
+    /// var trainer = new KnowledgeDistillationTrainer(teacher, strategy, checkpointConfig: config);
+    /// </code>
+    /// </para>
     /// </remarks>
     protected KnowledgeDistillationTrainerBase(
         ITeacherModel<TInput, TOutput> teacher,
         IDistillationStrategy<T, TOutput> distillationStrategy,
+        DistillationCheckpointConfig? checkpointConfig = null,
         int? seed = null)
     {
         Teacher = teacher ?? throw new ArgumentNullException(nameof(teacher));
         DistillationStrategy = distillationStrategy ?? throw new ArgumentNullException(nameof(distillationStrategy));
+        _checkpointConfig = checkpointConfig;
         NumOps = MathHelper.GetNumericOperations<T>();
         Random = seed.HasValue ? new Random(seed.Value) : new Random();
         _lastTrainingLoss = NumOps.Zero;
@@ -186,6 +182,7 @@ public virtual T TrainBatch(
     /// <param name="batchSize">Batch size for mini-batch training.</param>
     /// <param name="validationInputs">Optional validation inputs for monitoring.</param>
     /// <param name="validationLabels">Optional validation labels.</param>
+    /// <param name="student">Optional student model for automatic checkpointing (must implement ICheckpointableModel).</param>
     /// <param name="onEpochComplete">Optional callback invoked after each epoch with (epoch, avgLoss).</param>
     /// <remarks>
     /// <para><b>For Beginners:</b> This method orchestrates the complete training process:
@@ -201,6 +198,9 @@ public virtual T TrainBatch(
     /// - Use batch sizes that fit in memory (32-128 typical)
     /// - Monitor validation loss to detect overfitting
     /// - Invoke callbacks to log progress or save checkpoints</para>
+    ///
+    /// <para><b>Automatic Checkpointing:</b> If a checkpoint configuration was provided to the constructor
+    /// and you pass the student model parameter, automatic checkpointing will be enabled.</para>
     /// </remarks>
     public virtual void Train(
         Func<TInput, TOutput> studentForward,
@@ -211,6 +211,7 @@ public virtual void Train(
         int batchSize = 32,
         Vector<TInput>? validationInputs = null,
         Vector<TOutput>? validationLabels = null,
+        ICheckpointableModel? student = null,
         Action<int, T>? onEpochComplete = null)
     {
         if (studentForward == null) throw new ArgumentNullException(nameof(studentForward));
@@ -226,6 +227,9 @@ public virtual void Train(
         if (validationInputs != null && validationLabels != null && validationInputs.Length != validationLabels.Length)
             throw new ArgumentException("Validation inputs and labels must have the same length");
 
+        // Store student reference for checkpointing
+        _student = student;
+
         // Prepare for training
         OnTrainingStart(trainInputs, trainLabels);
 
@@ -303,7 +307,7 @@ public virtual void Train(
         int batchSize = 32,
         Action<int, T>? onEpochComplete = null)
     {
-        Train(studentForward, studentBackward, trainInputs, trainLabels, epochs, batchSize, null, null, onEpochComplete);
+        Train(studentForward, studentBackward, trainInputs, trainLabels, epochs, batchSize, null, null, null, onEpochComplete);
     }
 
     /// <summary>
@@ -468,15 +472,15 @@ protected int ArgMax(Vector<T> vector)
     /// - Setup curriculum schedules
     /// - Allocate temporary buffers</para>
     ///
-    /// <para><b>Automatic Checkpointing:</b> If <see cref="CheckpointConfig"/> is set, this method
-    /// automatically initializes the checkpoint manager.</para>
+    /// <para><b>Automatic Checkpointing:</b> If checkpoint configuration was provided to the constructor,
+    /// this method automatically initializes the checkpoint manager.</para>
     /// </remarks>
     protected virtual void OnTrainingStart(Vector<TInput> trainInputs, Vector<TOutput>? trainLabels)
     {
         // Initialize checkpoint manager if config is provided
-        if (CheckpointConfig != null)
+        if (_checkpointConfig != null)
         {
-            CheckpointManager = new DistillationCheckpointManager<T>(CheckpointConfig);
+            _checkpointManager = new DistillationCheckpointManager<T>(_checkpointConfig);
         }
     }
 
@@ -492,25 +496,25 @@ protected virtual void OnTrainingStart(Vector<TInput> trainInputs, Vector<TOutpu
     /// - Log final metrics
     /// - Free temporary resources</para>
     ///
-    /// <para><b>Automatic Checkpointing:</b> If <see cref="CheckpointConfig"/> is set, this method
-    /// automatically loads the best checkpoint (based on validation metrics) after training completes.</para>
+    /// <para><b>Automatic Checkpointing:</b> If checkpoint configuration was provided to the constructor,
+    /// this method automatically loads the best checkpoint (based on validation metrics) after training completes.</para>
     /// </remarks>
     protected virtual void OnTrainingEnd(Vector<TInput> trainInputs, Vector<TOutput>? trainLabels)
     {
         // Load best checkpoint if checkpointing was enabled
-        if (CheckpointManager != null && Student != null)
+        if (_checkpointManager != null && _student != null)
         {
-            var bestCheckpoint = CheckpointManager.LoadBestCheckpoint(
-                student: Student,
+            var bestCheckpoint = _checkpointManager.LoadBestCheckpoint(
+                student: _student,
                 teacher: Teacher as ICheckpointableModel
             );
 
             if (bestCheckpoint != null)
             {
                 Console.WriteLine($"[Checkpointing] Loaded best checkpoint from epoch {bestCheckpoint.Epoch}");
-                if (bestCheckpoint.Metrics.ContainsKey(CheckpointConfig!.BestMetric))
+                if (bestCheckpoint.Metrics.ContainsKey(_checkpointConfig!.BestMetric))
                 {
-                    Console.WriteLine($"[Checkpointing] Best {CheckpointConfig.BestMetric}: {bestCheckpoint.Metrics[CheckpointConfig.BestMetric]:F4}");
+                    Console.WriteLine($"[Checkpointing] Best {_checkpointConfig.BestMetric}: {bestCheckpoint.Metrics[_checkpointConfig.BestMetric]:F4}");
                 }
             }
         }
@@ -550,8 +554,8 @@ protected virtual void OnEpochStart(int epoch, Vector<TInput> trainInputs, Vecto
     /// to flush partial batches and prevent buffer leakage between epochs. Derived classes should
     /// call base.OnEpochEnd() if they override this method.</para>
     ///
-    /// <para><b>Automatic Checkpointing:</b> If <see cref="CheckpointConfig"/> is set, this method
-    /// automatically saves checkpoints based on your configuration.</para>
+    /// <para><b>Automatic Checkpointing:</b> If checkpoint configuration was provided to the constructor,
+    /// this method automatically saves checkpoints based on your configuration.</para>
     /// </remarks>
     protected virtual void OnEpochEnd(int epoch, T avgLoss)
     {
@@ -567,7 +571,7 @@ protected virtual void OnEpochEnd(int epoch, T avgLoss)
         _lastTrainingLoss = avgLoss;
 
         // Automatic checkpoint saving
-        if (CheckpointManager != null)
+        if (_checkpointManager != null)
         {
             var metrics = new Dictionary<string, double>
             {
@@ -577,12 +581,12 @@ protected virtual void OnEpochEnd(int epoch, T avgLoss)
             // Include validation metric if available
             if (_lastValidationMetric > 0)
             {
-                metrics[CheckpointConfig!.BestMetric] = _lastValidationMetric;
+                metrics[_checkpointConfig!.BestMetric] = _lastValidationMetric;
             }
 
-            CheckpointManager.SaveCheckpointIfNeeded(
+            _checkpointManager.SaveCheckpointIfNeeded(
                 epoch: epoch,
-                student: Student,
+                student: _student,
                 teacher: Teacher as ICheckpointableModel,
                 strategy: DistillationStrategy,
                 metrics: metrics
