Use IModel in the public API. (#556)

Use IModel in the public API. Changes allow ICatalog and IModel to be
stubbed for testing as you no longer need a concrete Model or
ModelVariant class.
- Make Model and ModelVariant implementation details
- Add variant info and selection to IModel so it works with either Model
or ModelVariant
- Move GetLatestVersion to Catalog and take IModel as input
- ModelVariant has insufficient info to implement this and intuitively
the catalog should know this information.
- Update tests
  - fix usage of test config file for shared test data path

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: skottmckay <979079+skottmckay@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: 3 people

samples/cs/GettingStarted/src/ModelManagementExample/Program.cs

@@ -51,39 +51,35 @@
 // Get a model using an alias from the catalog
 var model = await catalog.GetModelAsync("qwen2.5-0.5b") ?? throw new Exception("Model not found");
 
-// `model.SelectedVariant` indicates which variant will be used by default.
-//
 // Models in Model.Variants are ordered by priority, with the highest priority first.
 // The first downloaded model is selected by default.
 // The highest priority is selected if no models have been downloaded.
 // If the selected variant is not the highest priority, it means that Foundry Local
 // has found a locally cached variant for you to improve performance (remove need to download).
 Console.WriteLine("\nThe default selected model variant is: " + model.Id);
-if (model.SelectedVariant != model.Variants.First())
+if (model.Id != model.Variants.First().Id)
 {
-    Debug.Assert(await model.SelectedVariant.IsCachedAsync());
+    Debug.Assert(await model.IsCachedAsync());
     Console.WriteLine("The model variant was selected due to being locally cached.");
 }
 
 
-// OPTIONAL: `model` can be used directly and `model.SelectedVariant` will be used as the default.
-//           You can explicitly select or use a specific ModelVariant if you want more control
-//           over the device and/or execution provider used.
-//           Model and ModelVariant can be used interchangeably in methods such as
-//           DownloadAsync, LoadAsync, UnloadAsync and GetChatClientAsync.
+// OPTIONAL: `model` can be used directly with its currently selected variant.
+//           You can explicitly select (`model.SelectVariant`) or use a specific variant from `model.Variants`
+//           if you want more control over the device and/or execution provider used.
 //
 // Choices:
-//   - Use a ModelVariant directly from the catalog if you know the variant Id
+//   - Use a model variant directly from the catalog if you know the variant Id
 //     - `var modelVariant = await catalog.GetModelVariantAsync("qwen2.5-0.5b-instruct-generic-gpu:3")`
 //
-//   - Get the ModelVariant from Model.Variants
+//   - Get the model variant from IModel.Variants
 //     - `var modelVariant = model.Variants.First(v => v.Id == "qwen2.5-0.5b-instruct-generic-cpu:4")`
 //     - `var modelVariant = model.Variants.First(v => v.Info.Runtime?.DeviceType == DeviceType.GPU)`
 //       - optional: update selected variant in `model` using `model.SelectVariant(modelVariant);` if you wish to use
 //                   `model` in your code.
 
 // For this example we explicitly select the CPU variant, and call SelectVariant so all the following example code
-// uses the `model` instance.
+// uses the `model` instance. It would be equally valid to use `modelVariant` directly.
 Console.WriteLine("Selecting CPU variant of model");
 var modelVariant = model.Variants.First(v => v.Info.Runtime?.DeviceType == DeviceType.CPU);
 model.SelectVariant(modelVariant);

sdk/cs/src/Catalog.cs

@@ -52,51 +52,59 @@ internal static async Task<Catalog> CreateAsync(IModelLoadManager modelManager,
         return catalog;
     }
 
-    public async Task<List<Model>> ListModelsAsync(CancellationToken? ct = null)
+    public async Task<List<IModel>> ListModelsAsync(CancellationToken? ct = null)
     {
         return await Utils.CallWithExceptionHandling(() => ListModelsImplAsync(ct),
                                                      "Error listing models.", _logger).ConfigureAwait(false);
     }
 
-    public async Task<List<ModelVariant>> GetCachedModelsAsync(CancellationToken? ct = null)
+    public async Task<List<IModel>> GetCachedModelsAsync(CancellationToken? ct = null)
     {
         return await Utils.CallWithExceptionHandling(() => GetCachedModelsImplAsync(ct),
                                                      "Error getting cached models.", _logger).ConfigureAwait(false);
     }
 
-    public async Task<List<ModelVariant>> GetLoadedModelsAsync(CancellationToken? ct = null)
+    public async Task<List<IModel>> GetLoadedModelsAsync(CancellationToken? ct = null)
     {
         return await Utils.CallWithExceptionHandling(() => GetLoadedModelsImplAsync(ct),
                                                      "Error getting loaded models.", _logger).ConfigureAwait(false);
     }
 
-    public async Task<Model?> GetModelAsync(string modelAlias, CancellationToken? ct = null)
+    public async Task<IModel?> GetModelAsync(string modelAlias, CancellationToken? ct = null)
     {
         return await Utils.CallWithExceptionHandling(() => GetModelImplAsync(modelAlias, ct),
                                                      $"Error getting model with alias '{modelAlias}'.", _logger)
                                                     .ConfigureAwait(false);
     }
 
-    public async Task<ModelVariant?> GetModelVariantAsync(string modelId, CancellationToken? ct = null)
+    public async Task<IModel?> GetModelVariantAsync(string modelId, CancellationToken? ct = null)
     {
         return await Utils.CallWithExceptionHandling(() => GetModelVariantImplAsync(modelId, ct),
                                                      $"Error getting model variant with ID '{modelId}'.", _logger)
                                                     .ConfigureAwait(false);
     }
 
-    private async Task<List<Model>> ListModelsImplAsync(CancellationToken? ct = null)
+    public async Task<IModel> GetLatestVersionAsync(IModel modelOrModelVariant, CancellationToken? ct = null)
+    {
+        return await Utils.CallWithExceptionHandling(
+            () => GetLatestVersionImplAsync(modelOrModelVariant, ct),
+            $"Error getting latest version for model with name '{modelOrModelVariant.Info.Name}'.",
+            _logger).ConfigureAwait(false);
+    }
+
+    private async Task<List<IModel>> ListModelsImplAsync(CancellationToken? ct = null)
     {
         await UpdateModels(ct).ConfigureAwait(false);
 
         using var disposable = await _lock.LockAsync().ConfigureAwait(false);
-        return _modelAliasToModel.Values.OrderBy(m => m.Alias).ToList();
+        return _modelAliasToModel.Values.OrderBy(m => m.Alias).Cast<IModel>().ToList();
     }
 
-    private async Task<List<ModelVariant>> GetCachedModelsImplAsync(CancellationToken? ct = null)
+    private async Task<List<IModel>> GetCachedModelsImplAsync(CancellationToken? ct = null)
     {
         var cachedModelIds = await Utils.GetCachedModelIdsAsync(_coreInterop, ct).ConfigureAwait(false);
 
-        List<ModelVariant> cachedModels = new();
+        List<IModel> cachedModels = [];
         foreach (var modelId in cachedModelIds)
         {
             if (_modelIdToModelVariant.TryGetValue(modelId, out ModelVariant? modelVariant))
@@ -108,10 +116,10 @@ private async Task<List<ModelVariant>> GetCachedModelsImplAsync(CancellationToke
         return cachedModels;
     }
 
-    private async Task<List<ModelVariant>> GetLoadedModelsImplAsync(CancellationToken? ct = null)
+    private async Task<List<IModel>> GetLoadedModelsImplAsync(CancellationToken? ct = null)
     {
         var loadedModelIds = await _modelLoadManager.ListLoadedModelsAsync(ct).ConfigureAwait(false);
-        List<ModelVariant> loadedModels = new();
+        List<IModel> loadedModels = [];
 
         foreach (var modelId in loadedModelIds)
         {
@@ -143,6 +151,45 @@ private async Task<List<ModelVariant>> GetLoadedModelsImplAsync(CancellationToke
         return modelVariant;
     }
 
+    private async Task<IModel> GetLatestVersionImplAsync(IModel modelOrModelVariant, CancellationToken? ct)
+    {
+        Model? model;
+
+        if (modelOrModelVariant is ModelVariant)
+        {
+            // For ModelVariant, resolve the owning Model via alias.
+            model = await GetModelImplAsync(modelOrModelVariant.Alias, ct);
+        }
+        else
+        {
+            // Try to use the concrete Model instance if this is our SDK type.
+            model = modelOrModelVariant as Model;
+
+            // If this is a different IModel implementation (e.g., a test stub),
+            // fall back to resolving the Model via alias.
+            if (model == null)
+            {
+                model = await GetModelImplAsync(modelOrModelVariant.Alias, ct);
+            }
+        }
+
+        if (model == null)
+        {
+            throw new FoundryLocalException($"Model with alias '{modelOrModelVariant.Alias}' not found in catalog.",
+                                            _logger);
+        }
+
+        // variants are sorted by version, so the first one matching the name is the latest version for that variant.
+        var latest = model!.Variants.FirstOrDefault(v => v.Info.Name == modelOrModelVariant.Info.Name) ??
+            // should not be possible given we internally manage all the state involved
+            throw new FoundryLocalException($"Internal error. Mismatch between model (alias:{model.Alias}) and " +
+                                            $"model variant (alias:{modelOrModelVariant.Alias}).", _logger);
+
+        // if input was the latest return the input (could be model or model variant)
+        // otherwise return the latest model variant
+        return latest.Id == modelOrModelVariant.Id ? modelOrModelVariant : latest;
+    }
+
     private async Task UpdateModels(CancellationToken? ct)
     {
         // TODO: make this configurable

sdk/cs/src/Model.cs sdk/cs/src/Detail/Model.cssdk/cs/src/Model.cs renamed to sdk/cs/src/Detail/Model.cs

@@ -12,11 +12,13 @@ public class Model : IModel
 {
     private readonly ILogger _logger;
 
-    public List<ModelVariant> Variants { get; internal set; }
-    public ModelVariant SelectedVariant { get; internal set; } = default!;
+    private readonly List<IModel> _variants;
+    public IReadOnlyList<IModel> Variants => _variants;
+    internal IModel SelectedVariant { get; set; } = default!;
 
     public string Alias { get; init; }
     public string Id => SelectedVariant.Id;
+    public ModelInfo Info => SelectedVariant.Info;
 
     /// <summary>
     /// Is the currently selected variant cached locally?
@@ -33,7 +35,7 @@ internal Model(ModelVariant modelVariant, ILogger logger)
         _logger = logger;
 
         Alias = modelVariant.Alias;
-        Variants = new() { modelVariant };
+        _variants = [modelVariant];
 
         // variants are sorted by Core, so the first one added is the default
         SelectedVariant = modelVariant;
@@ -48,7 +50,7 @@ internal void AddVariant(ModelVariant variant)
                                             _logger);
         }
 
-        Variants.Add(variant);
+        _variants.Add(variant);
 
         // prefer the highest priority locally cached variant
         if (variant.Info.Cached && !SelectedVariant.Info.Cached)
@@ -62,31 +64,15 @@ internal void AddVariant(ModelVariant variant)
     /// </summary>
     /// <param name="variant">Model variant to select. Must be one of the variants in <see cref="Variants"/>.</param>
     /// <exception cref="FoundryLocalException">If variant is not valid for this model.</exception>
-    public void SelectVariant(ModelVariant variant)
+    public void SelectVariant(IModel variant)
     {
         _ = Variants.FirstOrDefault(v => v == variant) ??
-            // user error so don't log
-            throw new FoundryLocalException($"Model {Alias} does not have a {variant.Id} variant.");
+            // user error so don't log. 
+            throw new FoundryLocalException($"Input variant was not found in Variants.");
 
         SelectedVariant = variant;
     }
 
-    /// <summary>
-    /// Get the latest version of the specified model variant.
-    /// </summary>
-    /// <param name="variant">Model variant.</param>
-    /// <returns>ModelVariant for latest version. Same as `variant` if that is the latest version.</returns>
-    /// <exception cref="FoundryLocalException">If variant is not valid for this model.</exception>
-    public ModelVariant GetLatestVersion(ModelVariant variant)
-    {
-        // variants are sorted by version, so the first one matching the name is the latest version for that variant.
-        var latest = Variants.FirstOrDefault(v => v.Info.Name == variant.Info.Name) ??
-            // user error so don't log
-            throw new FoundryLocalException($"Model {Alias} does not have a {variant.Id} variant.");
-
-        return latest;
-    }
-
     public async Task<string> GetPathAsync(CancellationToken? ct = null)
     {
         return await SelectedVariant.GetPathAsync(ct).ConfigureAwait(false);

sdk/cs/src/ModelVariant.cs sdk/cs/src/Detail/ModelVariant.cssdk/cs/src/ModelVariant.cs renamed to sdk/cs/src/Detail/ModelVariant.cs

@@ -9,7 +9,7 @@ namespace Microsoft.AI.Foundry.Local;
 using Microsoft.AI.Foundry.Local.Detail;
 using Microsoft.Extensions.Logging;
 
-public class ModelVariant : IModel
+internal class ModelVariant : IModel
 {
     private readonly IModelLoadManager _modelLoadManager;
     private readonly ICoreInterop _coreInterop;
@@ -22,6 +22,8 @@ public class ModelVariant : IModel
     public string Alias => Info.Alias;
     public int Version { get; init; }  // parsed from Info.Version if possible, else 0
 
+    public IReadOnlyList<IModel> Variants => [this];
+
     internal ModelVariant(ModelInfo modelInfo, IModelLoadManager modelLoadManager, ICoreInterop coreInterop,
                           ILogger logger)
     {
@@ -190,4 +192,11 @@ private async Task<OpenAIAudioClient> GetAudioClientImplAsync(CancellationToken?
 
         return new OpenAIAudioClient(Id);
     }
+
+    public void SelectVariant(IModel variant)
+    {
+        throw new FoundryLocalException(
+            $"SelectVariant is not supported on a ModelVariant. " +
+            $"Call Catalog.GetModelAsync(\"{Alias}\") to get an IModel with all variants available.");
+    }
 }

sdk/cs/src/ICatalog.cs

@@ -18,36 +18,46 @@ public interface ICatalog
     /// List the available models in the catalog.
     /// </summary>
     /// <param name="ct">Optional CancellationToken.</param>
-    /// <returns>List of Model instances.</returns>
-    Task<List<Model>> ListModelsAsync(CancellationToken? ct = null);
+    /// <returns>List of IModel instances.</returns>
+    Task<List<IModel>> ListModelsAsync(CancellationToken? ct = null);
 
     /// <summary>
     /// Lookup a model by its alias.
     /// </summary>
     /// <param name="modelAlias">Model alias.</param>
     /// <param name="ct">Optional CancellationToken.</param>
-    /// <returns>The matching Model, or null if no model with the given alias exists.</returns>
-    Task<Model?> GetModelAsync(string modelAlias, CancellationToken? ct = null);
+    /// <returns>The matching IModel, or null if no model with the given alias exists.</returns>
+    Task<IModel?> GetModelAsync(string modelAlias, CancellationToken? ct = null);
 
     /// <summary>
     /// Lookup a model variant by its unique model id.
+    /// NOTE: This will return an IModel with a single variant. Use GetModelAsync to get an IModel with all avaialable
+    ///       variants.
     /// </summary>
     /// <param name="modelId">Model id.</param>
     /// <param name="ct">Optional CancellationToken.</param>
-    /// <returns>The matching ModelVariant, or null if no variant with the given id exists.</returns>
-    Task<ModelVariant?> GetModelVariantAsync(string modelId, CancellationToken? ct = null);
+    /// <returns>The matching IModel, or null if no variant with the given id exists.</returns>
+    Task<IModel?> GetModelVariantAsync(string modelId, CancellationToken? ct = null);
 
     /// <summary>
     /// Get a list of currently downloaded models from the model cache.
     /// </summary>
     /// <param name="ct">Optional CancellationToken.</param>
-    /// <returns>List of ModelVariant instances.</returns>
-    Task<List<ModelVariant>> GetCachedModelsAsync(CancellationToken? ct = null);
+    /// <returns>List of IModel instances.</returns>
+    Task<List<IModel>> GetCachedModelsAsync(CancellationToken? ct = null);
 
     /// <summary>
     /// Get a list of the currently loaded models.
     /// </summary>
     /// <param name="ct">Optional CancellationToken.</param>
-    /// <returns>List of ModelVariant instances.</returns>
-    Task<List<ModelVariant>> GetLoadedModelsAsync(CancellationToken? ct = null);
+    /// <returns>List of IModel instances.</returns>
+    Task<List<IModel>> GetLoadedModelsAsync(CancellationToken? ct = null);
+
+    /// <summary>
+    /// Get the latest version of a model.
+    /// This is used to check if a newer version of a model is available in the catalog for download.
+    /// </summary>
+    /// <param name="model">The model to check for the latest version.</param>
+    /// <returns>The latest version of the model. Will match the input if it is the latest version.</returns>
+    Task<IModel> GetLatestVersionAsync(IModel model, CancellationToken? ct = null);
 }

sdk/cs/src/IModel.cs

@@ -16,6 +16,8 @@ public interface IModel
         Justification = "Alias is a suitable name in this context.")]
     string Alias { get; }
 
+    ModelInfo Info { get; }
+
     Task<bool> IsCachedAsync(CancellationToken? ct = null);
     Task<bool> IsLoadedAsync(CancellationToken? ct = null);
 
@@ -67,4 +69,17 @@ Task DownloadAsync(Action<float>? downloadProgress = null,
     /// <param name="ct">Optional cancellation token.</param>
     /// <returns>OpenAI.AudioClient</returns>
     Task<OpenAIAudioClient> GetAudioClientAsync(CancellationToken? ct = null);
+
+    /// <summary>
+    /// Variants of the model that are available. Variants of the model are optimized for different devices.
+    /// </summary>
+    IReadOnlyList<IModel> Variants { get; }
+
+    /// <summary>
+    /// Select a model variant from <see cref="Variants"/> to use for <see cref="IModel"/> operations.
+    /// An IModel from `Variants` can also be used directly.
+    /// </summary>
+    /// <param name="variant">Model variant to select. Must be one of the variants in <see cref="Variants"/>.</param>
+    /// <exception cref="FoundryLocalException">If variant is not valid for this model.</exception>
+    void SelectVariant(IModel variant);
 }

sdk/cs/test/FoundryLocal.Tests/AudioClientTests.cs

@@ -12,7 +12,7 @@ namespace Microsoft.AI.Foundry.Local.Tests;
 
 internal sealed class AudioClientTests
 {
-    private static Model? model;
+    private static IModel? model;
 
     [Before(Class)]
     public static async Task Setup()