fix(us-if-003): implement ifullmodel interfaces in predictionmodelresult (#245)

* fix(us-if-003): implement ifullmodel interfaces in predictionmodelresult

- add constructor accepting IFullModel parameter
- implement Train method throwing InvalidOperationException
- implement GetParameters, SetParameters, ParameterCount methods
- implement WithParameters method
- implement GetActiveFeatureIndices, SetActiveFeatureIndices methods
- implement IsFeatureUsed method
- implement GetFeatureImportance method
- implement DeepCopy and Clone methods
- all methods delegate to underlying Model property

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

Co-Authored-By: Claude <[email protected]>

* fix(us-if-003): implement train delegation in predictionmodelresult

Update PredictionModelResult.Train() to delegate training to the inner model instead of throwing an exception. This completes the IFullModel implementation and allows the model to be trained through the wrapper.

Changes:
- Modified Train() method to check for null Model and delegate to Model.Train()
- Updated XML documentation to reflect the delegation behavior
- Ensures consistency with acceptance criteria for US-IF-003

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

Co-Authored-By: Claude <[email protected]>

* refactor(us-if-003): enforce immutability in predictionmodelresult

PredictionModelResult represents an already-trained model snapshot and should
not allow mutation. This aligns with the architectural vision that users must
use PredictionModelBuilder to create and train models.

Changes:
1. Remove redundant IPredictiveModel interface (IFullModel is superset)
2. Revert Train() to throw InvalidOperationException (was delegating)
3. SetParameters() now throws InvalidOperationException (was delegating)
4. SetActiveFeatureIndices() now throws exception (was delegating)
5. Update IPredictionModelBuilder and PredictionModelBuilder to use
   PredictionModelResult<T, TInput, TOutput> directly

Rationale:
- PredictionModelResult is a snapshot with OptimizationResult and metadata
- Retraining/mutation would invalidate the optimization results
- Users can still: Predict(), GetParameters(), Clone(), DeepCopy(), Save/Load
- Mutation is prevented: Train(), SetParameters(), SetActiveFeatureIndices()
- Even DeepCopy() returns PredictionModelResult, so copies can't be retrained

This enforces correct usage: use PredictionModelBuilder for training.

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

Co-Authored-By: Claude <[email protected]>

* fix(us-nf-009): ensure optimizationresult.bestsolution references correct model instance

**Changes:**
- WithParameters(): deep-copy OptimizationResult and update BestSolution to reference newModel
- Clone(): delegate to WithParameters for consistency
- DeepCopy(): update clonedOptimizationResult.BestSolution to reference clonedModel
- All methods now preserve BiasDetector and FairnessEvaluator components

**Rationale:**
Previously WithParameters() and Clone() reused the existing OptimizationResult instance,
which meant OptimizationResult.BestSolution still pointed to the old model instead of
the new model with updated parameters. This created inconsistent metadata.

Now all three methods (WithParameters, Clone, DeepCopy) ensure that
OptimizationResult.BestSolution always references the correct model instance.

Addresses code review feedback on PR #245.

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

Co-Authored-By: Claude <[email protected]>

* fix(testconsole): update examples to use predictionmodelresult instead of ipredictivemodel

**Changes:**
- TimeSeriesExample.cs: fix pattern matching to check model.Model instead of model
- EnhancedTimeSeriesExample.cs:
  - Add using AiDotNet.Models.Results
  - Change return types from IPredictiveModel to PredictionModelResult
  - Update EvaluateModel parameter type to PredictionModelResult
- RegressionExample.cs: update model property access to use model.Model
- EnhancedRegressionExample.cs: update model property access to use model.Model

**Rationale:**
These testconsole examples were broken by removing IPredictiveModel from
PredictionModelResult's interface declaration (PR #245). The examples now
correctly work with PredictionModelResult and access the wrapped model
via the Model property when needed.

Fixes build errors introduced by PR #245 architectural changes.

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

Co-Authored-By: Claude <[email protected]>

---------

Co-authored-by: Claude <[email protected]>

Author: ooples

src/Interfaces/IPredictionModelBuilder.cs

@@ -1,3 +1,5 @@
+using AiDotNet.Models.Results;
+
 namespace AiDotNet.Interfaces;
 
 /// <summary>
@@ -200,7 +202,7 @@ public interface IPredictionModelBuilder<T, TInput, TOutput>
     /// <param name="x">The input features matrix, where each row is a data point and each column is a feature.</param>
     /// <param name="y">The target values vector that the model will learn to predict.</param>
     /// <returns>A trained predictive model ready to make predictions.</returns>
-    IPredictiveModel<T, TInput, TOutput> Build(TInput x, TOutput y);
+    PredictionModelResult<T, TInput, TOutput> Build(TInput x, TOutput y);
 
     /// <summary>
     /// Uses a trained model to make predictions on new data.
@@ -216,7 +218,7 @@ public interface IPredictionModelBuilder<T, TInput, TOutput>
     /// <param name="newData">The new input data to make predictions for.</param>
     /// <param name="model">The trained model to use for making predictions.</param>
     /// <returns>A vector of predicted values.</returns>
-    TOutput Predict(TInput newData, IPredictiveModel<T, TInput, TOutput> model);
+    TOutput Predict(TInput newData, PredictionModelResult<T, TInput, TOutput> model);
 
     /// <summary>
     /// Saves a trained model to a file.
@@ -230,7 +232,7 @@ public interface IPredictionModelBuilder<T, TInput, TOutput>
     /// </remarks>
     /// <param name="model">The trained model to save.</param>
     /// <param name="filePath">The file path where the model should be saved.</param>
-    void SaveModel(IPredictiveModel<T, TInput, TOutput> model, string filePath);
+    void SaveModel(PredictionModelResult<T, TInput, TOutput> model, string filePath);
 
     /// <summary>
     /// Loads a previously saved model from a file.
@@ -244,7 +246,7 @@ public interface IPredictionModelBuilder<T, TInput, TOutput>
     /// </remarks>
     /// <param name="filePath">The file path where the model is stored.</param>
     /// <returns>The loaded predictive model.</returns>
-    IPredictiveModel<T, TInput, TOutput> LoadModel(string filePath);
+    PredictionModelResult<T, TInput, TOutput> LoadModel(string filePath);
 
     /// <summary>
     /// Converts a trained model into a byte array for storage or transmission.
@@ -266,7 +268,7 @@ public interface IPredictionModelBuilder<T, TInput, TOutput>
     /// </remarks>
     /// <param name="model">The trained model to serialize.</param>
     /// <returns>A byte array containing the serialized model data.</returns>
-    byte[] SerializeModel(IPredictiveModel<T, TInput, TOutput> model);
+    byte[] SerializeModel(PredictionModelResult<T, TInput, TOutput> model);
 
     /// <summary>
     /// Reconstructs a model from a previously serialized byte array.
@@ -286,7 +288,7 @@ public interface IPredictionModelBuilder<T, TInput, TOutput>
     /// </remarks>
     /// <param name="modelData">The byte array containing the serialized model data.</param>
     /// <returns>The reconstructed predictive model.</returns>
-    IPredictiveModel<T, TInput, TOutput> DeserializeModel(byte[] modelData);
+    PredictionModelResult<T, TInput, TOutput> DeserializeModel(byte[] modelData);
 
     /// <summary>
     /// Configures the bias detector component for ethical AI evaluation.

src/Models/Results/PredictionModelResult.cs

@@ -41,7 +41,7 @@ namespace AiDotNet.Models.Results;
 /// </remarks>
 /// <typeparam name="T">The numeric type used for calculations, typically float or double.</typeparam>
 [Serializable]
-public class PredictionModelResult<T, TInput, TOutput> : IPredictiveModel<T, TInput, TOutput>
+public class PredictionModelResult<T, TInput, TOutput> : IFullModel<T, TInput, TOutput>
 {
     /// <summary>
     /// Gets or sets the underlying model used for making predictions.
@@ -183,28 +183,43 @@ public class PredictionModelResult<T, TInput, TOutput> : IPredictiveModel<T, TIn
     /// <param name="normalizationInfo">The normalization information used to preprocess input data and postprocess predictions.</param>
     /// <remarks>
     /// <para>
-    /// This constructor creates a new PredictionModelResult instance with the specified model, optimization results, and 
-    /// normalization information. It also initializes the ModelMetadata property by calling the GetModelMetadata method on 
-    /// the provided model. This constructor is typically used when a new model has been trained and needs to be packaged 
+    /// This constructor creates a new PredictionModelResult instance with the specified model, optimization results, and
+    /// normalization information. It also initializes the ModelMetadata property by calling the GetModelMetadata method on
+    /// the provided model. This constructor is typically used when a new model has been trained and needs to be packaged
     /// with all the necessary information for making predictions and for later serialization.
     /// </para>
     /// <para><b>For Beginners:</b> This constructor creates a new prediction model result with all the necessary components.
-    /// 
+    ///
     /// When creating a new PredictionModelResult:
     /// - You provide the trained model that will make predictions
     /// - You provide the optimization results that describe how the model was created
     /// - You provide the normalization information needed to process data
     /// - The constructor automatically extracts metadata from the model
-    /// 
+    ///
     /// This constructor is typically used when:
     /// - You've just finished training a model
     /// - You want to package it with all the information needed to use it
     /// - You plan to save it for later use or deploy it in an application
-    /// 
+    ///
     /// For example, after training a house price prediction model, you would use this constructor
     /// to create a complete package that can be saved and used for making predictions.
     /// </para>
     /// </remarks>
+    public PredictionModelResult(IFullModel<T, TInput, TOutput> model,
+        OptimizationResult<T, TInput, TOutput> optimizationResult,
+        NormalizationInfo<T, TInput, TOutput> normalizationInfo)
+    {
+        Model = model;
+        OptimizationResult = optimizationResult;
+        NormalizationInfo = normalizationInfo;
+        ModelMetaData = model?.GetModelMetadata() ?? new();
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the PredictionModelResult class with optimization results and normalization information.
+    /// </summary>
+    /// <param name="optimizationResult">The results of the optimization process that created the model.</param>
+    /// <param name="normalizationInfo">The normalization information used to preprocess input data and postprocess predictions.</param>
     public PredictionModelResult(OptimizationResult<T, TInput, TOutput> optimizationResult,
         NormalizationInfo<T, TInput, TOutput> normalizationInfo,
         IBiasDetector<T>? biasDetector = null,
@@ -328,6 +343,211 @@ public TOutput Predict(TInput newData)
         return NormalizationInfo.Normalizer.Denormalize(normalizedPredictions, NormalizationInfo.YParams);
     }
 
+    /// <summary>
+    /// Training is not supported on PredictionModelResult. Use PredictionModelBuilder to create and train new models.
+    /// </summary>
+    /// <param name="input">Input training data (not used).</param>
+    /// <param name="expectedOutput">Expected output values (not used).</param>
+    /// <exception cref="InvalidOperationException">Always thrown - PredictionModelResult represents an already-trained model and cannot be retrained.</exception>
+    /// <remarks>
+    /// PredictionModelResult is a snapshot of a trained model with its optimization results and metadata.
+    /// Retraining would invalidate the OptimizationResult and metadata.
+    /// To train a new model or retrain with different data, use PredictionModelBuilder.Build() instead.
+    /// </remarks>
+    public void Train(TInput input, TOutput expectedOutput)
+    {
+        throw new InvalidOperationException(
+            "PredictionModelResult represents an already-trained model and cannot be retrained. " +
+            "The OptimizationResult and metadata reflect the original training process. " +
+            "To train a new model, use PredictionModelBuilder.Build() instead.");
+    }
+
+    /// <summary>
+    /// Gets the parameters of the underlying model.
+    /// </summary>
+    /// <returns>A vector containing the model parameters.</returns>
+    /// <exception cref="InvalidOperationException">Thrown when the Model is not initialized.</exception>
+    public Vector<T> GetParameters()
+    {
+        if (Model == null)
+        {
+            throw new InvalidOperationException("Model is not initialized.");
+        }
+
+        return Model.GetParameters();
+    }
+
+    /// <summary>
+    /// Setting parameters is not supported on PredictionModelResult.
+    /// </summary>
+    /// <param name="parameters">The parameter vector (not used).</param>
+    /// <exception cref="InvalidOperationException">Always thrown - PredictionModelResult parameters cannot be modified.</exception>
+    /// <remarks>
+    /// Modifying parameters would invalidate the OptimizationResult which reflects the optimized parameter values.
+    /// To create a model with different parameters, use PredictionModelBuilder with custom initial parameters.
+    /// </remarks>
+    public void SetParameters(Vector<T> parameters)
+    {
+        throw new InvalidOperationException(
+            "PredictionModelResult parameters cannot be modified. " +
+            "The current parameters reflect the optimized solution from the training process. " +
+            "To create a model with different parameters, use PredictionModelBuilder.");
+    }
+
+    /// <summary>
+    /// Gets the number of parameters in the underlying model.
+    /// </summary>
+    public int ParameterCount
+    {
+        get
+        {
+            if (Model == null)
+            {
+                return 0;
+            }
+
+            return Model.ParameterCount;
+        }
+    }
+
+    /// <summary>
+    /// Creates a new instance with the specified parameters.
+    /// </summary>
+    /// <param name="parameters">The parameter vector to use.</param>
+    /// <returns>A new PredictionModelResult with updated parameters.</returns>
+    /// <exception cref="InvalidOperationException">Thrown when the Model is not initialized.</exception>
+    public IFullModel<T, TInput, TOutput> WithParameters(Vector<T> parameters)
+    {
+        if (Model == null)
+        {
+            throw new InvalidOperationException("Model is not initialized.");
+        }
+
+        var newModel = Model.WithParameters(parameters);
+
+        // Deep-copy OptimizationResult and update its BestSolution to reference newModel
+        // This ensures metadata consistency - BestSolution should always point to the current model
+        var updatedOptimizationResult = OptimizationResult.DeepCopy();
+        updatedOptimizationResult.BestSolution = newModel;
+
+        // Create new result with updated optimization result
+        // Use constructor that preserves BiasDetector and FairnessEvaluator
+        return new PredictionModelResult<T, TInput, TOutput>(
+            updatedOptimizationResult,
+            NormalizationInfo,
+            BiasDetector,
+            FairnessEvaluator);
+    }
+
+    /// <summary>
+    /// Gets the indices of features that are actively used by the underlying model.
+    /// </summary>
+    /// <returns>An enumerable of active feature indices.</returns>
+    /// <exception cref="InvalidOperationException">Thrown when the Model is not initialized.</exception>
+    public IEnumerable<int> GetActiveFeatureIndices()
+    {
+        if (Model == null)
+        {
+            throw new InvalidOperationException("Model is not initialized.");
+        }
+
+        return Model.GetActiveFeatureIndices();
+    }
+
+    /// <summary>
+    /// Setting active feature indices is not supported on PredictionModelResult.
+    /// </summary>
+    /// <param name="featureIndices">The feature indices (not used).</param>
+    /// <exception cref="InvalidOperationException">Always thrown - PredictionModelResult feature configuration cannot be modified.</exception>
+    /// <remarks>
+    /// Changing active features would invalidate the trained model and optimization results.
+    /// To train a model with different features, use PredictionModelBuilder with the desired feature configuration.
+    /// </remarks>
+    public void SetActiveFeatureIndices(IEnumerable<int> featureIndices)
+    {
+        throw new InvalidOperationException(
+            "PredictionModelResult active features cannot be modified. " +
+            "The model was trained with a specific feature set. " +
+            "To use different features, train a new model using PredictionModelBuilder.");
+    }
+
+    /// <summary>
+    /// Checks if a specific feature is used by the underlying model.
+    /// </summary>
+    /// <param name="featureIndex">The index of the feature to check.</param>
+    /// <returns>True if the feature is used, false otherwise.</returns>
+    /// <exception cref="InvalidOperationException">Thrown when the Model is not initialized.</exception>
+    public bool IsFeatureUsed(int featureIndex)
+    {
+        if (Model == null)
+        {
+            throw new InvalidOperationException("Model is not initialized.");
+        }
+
+        return Model.IsFeatureUsed(featureIndex);
+    }
+
+    /// <summary>
+    /// Gets the feature importance scores from the underlying model.
+    /// </summary>
+    /// <returns>A dictionary mapping feature names to importance scores.</returns>
+    /// <exception cref="InvalidOperationException">Thrown when the Model is not initialized.</exception>
+    public Dictionary<string, T> GetFeatureImportance()
+    {
+        if (Model == null)
+        {
+            throw new InvalidOperationException("Model is not initialized.");
+        }
+
+        return Model.GetFeatureImportance();
+    }
+
+    /// <summary>
+    /// Creates a deep copy of this PredictionModelResult.
+    /// </summary>
+    /// <returns>A new PredictionModelResult instance that is a deep copy of this one.</returns>
+    public IFullModel<T, TInput, TOutput> DeepCopy()
+    {
+        if (Model == null)
+        {
+            throw new InvalidOperationException("Cannot deep copy PredictionModelResult with null Model.");
+        }
+
+        var clonedModel = Model.DeepCopy();
+        var clonedOptimizationResult = OptimizationResult.DeepCopy();
+
+        // Update OptimizationResult.BestSolution to reference the cloned model
+        // This ensures metadata consistency across the deep copy
+        clonedOptimizationResult.BestSolution = clonedModel;
+
+        var clonedNormalizationInfo = NormalizationInfo.DeepCopy();
+
+        // Use constructor that preserves BiasDetector and FairnessEvaluator
+        return new PredictionModelResult<T, TInput, TOutput>(
+            clonedOptimizationResult,
+            clonedNormalizationInfo,
+            BiasDetector,
+            FairnessEvaluator);
+    }
+
+    /// <summary>
+    /// Creates a shallow copy of this PredictionModelResult.
+    /// </summary>
+    /// <returns>A new PredictionModelResult instance that is a shallow copy of this one.</returns>
+    /// <remarks>
+    /// This method delegates to WithParameters to ensure consistency in how OptimizationResult is handled.
+    /// The cloned instance will have a new model with the same parameters and updated OptimizationResult metadata.
+    /// </remarks>
+    public IFullModel<T, TInput, TOutput> Clone()
+    {
+        if (Model == null)
+        {
+            throw new InvalidOperationException("Cannot clone PredictionModelResult with null Model.");
+        }
+
+        return WithParameters(Model.GetParameters());
+    }
+
     /// <summary>
     /// Serializes the model to a byte array.
     /// </summary>

src/PredictionModelBuilder.cs

@@ -205,7 +205,7 @@ public IPredictionModelBuilder<T, TInput, TOutput> ConfigureOutlierRemoval(IOutl
     /// The input matrix 'x' contains your features (like house size, number of bedrooms, etc. if predicting house prices),
     /// and the vector 'y' contains the known answers (actual house prices) for those examples.
     /// </remarks>
-    public IPredictiveModel<T, TInput, TOutput> Build(TInput x, TOutput y)
+    public PredictionModelResult<T, TInput, TOutput> Build(TInput x, TOutput y)
     {
         var convertedX = ConversionsHelper.ConvertToMatrix<T, TInput>(x);
         var convertedY = ConversionsHelper.ConvertToVector<T, TOutput>(y);
@@ -253,7 +253,7 @@ public IPredictiveModel<T, TInput, TOutput> Build(TInput x, TOutput y)
     /// 
     /// The input matrix should have the same number of columns (features) as the data you used to train the model.
     /// </remarks>
-    public TOutput Predict(TInput newData, IPredictiveModel<T, TInput, TOutput> modelResult)
+    public TOutput Predict(TInput newData, PredictionModelResult<T, TInput, TOutput> modelResult)
     {
         return modelResult.Predict(newData);
     }
@@ -271,7 +271,7 @@ public TOutput Predict(TInput newData, IPredictiveModel<T, TInput, TOutput> mode
     /// Think of it like saving a document in a word processor - you can close the program and come back later
     /// to continue where you left off.
     /// </remarks>
-    public void SaveModel(IPredictiveModel<T, TInput, TOutput> modelResult, string filePath)
+    public void SaveModel(PredictionModelResult<T, TInput, TOutput> modelResult, string filePath)
     {
         File.WriteAllBytes(filePath, SerializeModel(modelResult));
     }
@@ -288,7 +288,7 @@ public void SaveModel(IPredictiveModel<T, TInput, TOutput> modelResult, string f
     /// This is useful when you want to use your model in different applications or at different times
     /// without the time and computational cost of retraining.
     /// </remarks>
-    public IPredictiveModel<T, TInput, TOutput> LoadModel(string filePath)
+    public PredictionModelResult<T, TInput, TOutput> LoadModel(string filePath)
     {
         byte[] modelData = File.ReadAllBytes(filePath);
         return DeserializeModel(modelData);
@@ -306,7 +306,7 @@ public IPredictiveModel<T, TInput, TOutput> LoadModel(string filePath)
     /// You might use this directly if you want to store the model in a database or send it over a network,
     /// rather than saving it to a file.
     /// </remarks>
-    public byte[] SerializeModel(IPredictiveModel<T, TInput, TOutput> modelResult)
+    public byte[] SerializeModel(PredictionModelResult<T, TInput, TOutput> modelResult)
     {
         return modelResult.Serialize();
     }
@@ -323,7 +323,7 @@ public byte[] SerializeModel(IPredictiveModel<T, TInput, TOutput> modelResult)
     /// 
     /// You might use this directly if you retrieved a serialized model from a database or received it over a network.
     /// </remarks>
-    public IPredictiveModel<T, TInput, TOutput> DeserializeModel(byte[] modelData)
+    public PredictionModelResult<T, TInput, TOutput> DeserializeModel(byte[] modelData)
     {
         var result = new PredictionModelResult<T, TInput, TOutput>();
         result.Deserialize(modelData);

testconsole/Examples/EnhancedRegressionExample.cs

@@ -176,11 +176,11 @@ public void RunExample()
             Console.WriteLine($"\nBest model based on R² score: {bestModelName}");
 
             // 8. Analyze feature importance (for the best model)
-            if (bestModel is IPredictiveModel<double, Matrix<double>, Vector<double>> predictiveModel)
+            if (bestModel.Model != null)
             {
-                if (predictiveModel.GetType().GetProperty("Coefficients") != null)
+                if (bestModel.Model.GetType().GetProperty("Coefficients") != null)
                 {
-                    var coefficients = predictiveModel.GetType().GetProperty("Coefficients")?.GetValue(predictiveModel);
+                    var coefficients = bestModel.Model.GetType().GetProperty("Coefficients")?.GetValue(bestModel.Model);
 
                     if (coefficients is Vector<double> coefVector)
                     {