Propagate IModel API changes across Python, JS, Rust SDKs and update C# docs (#565)

Mirrors the C# changes from #556 across all language bindings: public
APIs use the `IModel` interface instead of concrete
`Model`/`ModelVariant` types, `GetLatestVersion` moves from `Model` to
`Catalog`, and `ModelVariant` becomes an implementation detail.

- Added `info`, `variants`, `selected_variant`/`selectedVariant`,
`select_variant`/`selectVariant` to the abstract interface
- `ModelVariant` implements these as self-referential
(`variants=[self]`, `selected_variant=self`, `select_variant` throws)

```python
model = catalog.get_model("qwen2.5-0.5b")
for v in model.variants:          # List[IModel], not List[ModelVariant]
    print(v.info.name, v.id)
model.select_variant(v)           # takes IModel, not ModelVariant

latest = catalog.get_latest_version(model)  # moved from Model to Catalog
```

- `list_models()` → `List[IModel]` (was `List[Model]`)
- `get_model()` → `Optional[IModel]` (was `Optional[Model]`)
- `get_model_variant()` → `Optional[IModel]` (was
`Optional[ModelVariant]`)
- `get_cached_models()` / `get_loaded_models()` → `List[IModel]` (was
`List[ModelVariant]`)

Moved from `Model` to `Catalog` since `ModelVariant` lacks sufficient
context to implement it. Takes any `IModel` and resolves the latest
version by name matching against the variant list.

- Added `Model::info()` (delegates to selected variant)
- Added `Catalog::get_latest_version(&self, model: &Arc<Model>) ->
Result<Arc<ModelVariant>>`

- README, API docs (`ICatalog`, `IModel`, `Model`, `ModelVariant`)
updated to reflect `IModel` return types
- `ModelVariant` docs marked as internal
- Samples updated to avoid direct `ModelVariant` type references
- `GetLatestVersionAsync` added to `ICatalog` docs

---------

Co-authored-by: Baiju Meswani <bmeswani@microsoft.com>
Co-authored-by: Nenad Banfic <46795300+nenad1002@users.noreply.github.com>

Author: 3 people

sdk/cs/README.md

@@ -181,11 +181,11 @@ var loaded = await catalog.GetLoadedModelsAsync();
 
 ### Model Lifecycle
 
-Each `Model` wraps one or more `ModelVariant` entries (different quantizations, hardware targets). The SDK auto-selects the best variant, or you can pick one:
+Each model may have multiple variants (different quantizations, hardware targets). The SDK auto-selects the best variant, or you can pick one. All models implement the `IModel` interface.
 
 ```csharp
 // Check and select variants
-Console.WriteLine($"Selected: {model.SelectedVariant.Id}");
+Console.WriteLine($"Selected: {model.Id}");
 foreach (var v in model.Variants)
     Console.WriteLine($"  {v.Id} (cached: {await v.IsCachedAsync()})");
 
@@ -332,8 +332,8 @@ Key types:
 | [`FoundryLocalManager`](./docs/api/microsoft.ai.foundry.local.foundrylocalmanager.md) | Singleton entry point — create, catalog, web service |
 | [`Configuration`](./docs/api/microsoft.ai.foundry.local.configuration.md) | Initialization settings |
 | [`ICatalog`](./docs/api/microsoft.ai.foundry.local.icatalog.md) | Model catalog interface |
-| [`Model`](./docs/api/microsoft.ai.foundry.local.model.md) | Model with variant selection |
-| [`ModelVariant`](./docs/api/microsoft.ai.foundry.local.modelvariant.md) | Specific model variant (hardware/quantization) |
+| [`IModel`](./docs/api/microsoft.ai.foundry.local.imodel.md) | Model interface — identity, metadata, lifecycle, variant selection |
+| [`Model`](./docs/api/microsoft.ai.foundry.local.model.md) | Model with variant selection (implements `IModel`) |
 | [`OpenAIChatClient`](./docs/api/microsoft.ai.foundry.local.openaichatclient.md) | Chat completions (sync + streaming) |
 | [`OpenAIAudioClient`](./docs/api/microsoft.ai.foundry.local.openaiaudioclient.md) | Audio transcription (sync + streaming) |
 | [`ModelInfo`](./docs/api/microsoft.ai.foundry.local.modelinfo.md) | Full model metadata record |

sdk/js/README.md

@@ -148,7 +148,7 @@ const loaded = await catalog.getLoadedModels();
 
 ### Loading and Running Models
 
-Each `Model` can have multiple variants (different quantizations or formats). The SDK automatically selects the best available variant, preferring cached versions.
+Each model can have multiple variants (different quantizations or formats). The SDK automatically selects the best available variant, preferring cached versions. All models implement the `IModel` interface.
 
 ```typescript
 const model = await catalog.getModel('qwen2.5-0.5b');
@@ -259,8 +259,7 @@ Auto-generated class documentation lives in [`docs/classes/`](docs/classes/):
 
 - [FoundryLocalManager](docs/classes/FoundryLocalManager.md) — SDK entry point, web service management
 - [Catalog](docs/classes/Catalog.md) — Model discovery and browsing
-- [Model](docs/classes/Model.md) — High-level model with variant selection
-- [ModelVariant](docs/classes/ModelVariant.md) — Specific model variant: download, load, inference
+- [IModel](docs/README.md#imodel) — Model interface: variant selection, download, load, inference
 - [ChatClient](docs/classes/ChatClient.md) — Chat completions (sync and streaming)
 - [AudioClient](docs/classes/AudioClient.md) — Audio transcription (sync and streaming)
 - [ModelLoadManager](docs/classes/ModelLoadManager.md) — Low-level model loading management

sdk/js/docs/README.md

@@ -23,7 +23,6 @@
 - [FoundryLocalManager](classes/FoundryLocalManager.md)
 - [Model](classes/Model.md)
 - [ModelLoadManager](classes/ModelLoadManager.md)
-- [ModelVariant](classes/ModelVariant.md)
 - [ResponsesClient](classes/ResponsesClient.md)
 - [ResponsesClientSettings](classes/ResponsesClientSettings.md)
 
@@ -562,6 +561,18 @@ get id(): string;
 
 `string`
 
+##### info
+
+###### Get Signature
+
+```ts
+get info(): ModelInfo;
+```
+
+###### Returns
+
+[`ModelInfo`](#modelinfo)
+
 ##### inputModalities
 
 ###### Get Signature
@@ -622,6 +633,20 @@ get supportsToolCalling(): boolean | null;
 
 `boolean` \| `null`
 
+##### variants
+
+###### Get Signature
+
+```ts
+get variants(): IModel[];
+```
+
+Variants of the model that are available. Variants of the model are optimized for different devices.
+
+###### Returns
+
+[`IModel`](#imodel)[]
+
 #### Methods
 
 ##### createAudioClient()
@@ -710,6 +735,29 @@ removeFromCache(): void;
 
 `void`
 
+##### selectVariant()
+
+```ts
+selectVariant(variant): void;
+```
+
+Select a model variant from variants to use for IModel operations.
+An IModel from `variants` can also be used directly.
+
+###### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `variant` | [`IModel`](#imodel) | Model variant to select. Must be one of the variants in `variants`. |
+
+###### Returns
+
+`void`
+
+###### Throws
+
+Error if variant is not valid for this model.
+
 ##### unload()
 
 ```ts

sdk/js/docs/classes/Catalog.md

@@ -47,24 +47,47 @@ The name of the catalog.
 ### getCachedModels()
 
 ```ts
-getCachedModels(): Promise<ModelVariant[]>;
+getCachedModels(): Promise<IModel[]>;
 ```
 
 Retrieves a list of all locally cached model variants.
 This method is asynchronous as it may involve file I/O or querying the underlying core.
 
 #### Returns
 
-`Promise`\<[`ModelVariant`](ModelVariant.md)[]\>
+`Promise`\<[`IModel`](../README.md#imodel)[]\>
 
-A Promise that resolves to an array of cached ModelVariant objects.
+A Promise that resolves to an array of cached IModel objects.
+
+***
+
+### getLatestVersion()
+
+```ts
+getLatestVersion(modelOrModelVariant): Promise<IModel>;
+```
+
+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.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `modelOrModelVariant` | [`IModel`](../README.md#imodel) | The model to check for the latest version. |
+
+#### Returns
+
+`Promise`\<[`IModel`](../README.md#imodel)\>
+
+The latest version of the model. Will match the input if it is the latest version.
 
 ***
 
 ### getLoadedModels()
 
 ```ts
-getLoadedModels(): Promise<ModelVariant[]>;
+getLoadedModels(): Promise<IModel[]>;
 ```
 
 Retrieves a list of all currently loaded model variants.
@@ -73,16 +96,16 @@ the underlying core or an external service, which can be an I/O bound operation.
 
 #### Returns
 
-`Promise`\<[`ModelVariant`](ModelVariant.md)[]\>
+`Promise`\<[`IModel`](../README.md#imodel)[]\>
 
-A Promise that resolves to an array of loaded ModelVariant objects.
+A Promise that resolves to an array of loaded IModel objects.
 
 ***
 
 ### getModel()
 
 ```ts
-getModel(alias): Promise<Model>;
+getModel(alias): Promise<IModel>;
 ```
 
 Retrieves a model by its alias.
@@ -96,9 +119,9 @@ This method is asynchronous as it may ensure the catalog is up-to-date by fetchi
 
 #### Returns
 
-`Promise`\<[`Model`](Model.md)\>
+`Promise`\<[`IModel`](../README.md#imodel)\>
 
-A Promise that resolves to the Model object if found, otherwise throws an error.
+A Promise that resolves to the IModel object if found, otherwise throws an error.
 
 #### Throws
 
@@ -109,27 +132,29 @@ Error - If alias is null, undefined, or empty.
 ### getModels()
 
 ```ts
-getModels(): Promise<Model[]>;
+getModels(): Promise<IModel[]>;
 ```
 
 Lists all available models in the catalog.
 This method is asynchronous as it may fetch the model list from a remote service or perform file I/O.
 
 #### Returns
 
-`Promise`\<[`Model`](Model.md)[]\>
+`Promise`\<[`IModel`](../README.md#imodel)[]\>
 
-A Promise that resolves to an array of Model objects.
+A Promise that resolves to an array of IModel objects.
 
 ***
 
 ### getModelVariant()
 
 ```ts
-getModelVariant(modelId): Promise<ModelVariant>;
+getModelVariant(modelId): Promise<IModel>;
 ```
 
 Retrieves a specific model variant by its ID.
+NOTE: This will return an IModel with a single variant. Use getModel to get an IModel with all available
+variants.
 This method is asynchronous as it may ensure the catalog is up-to-date by fetching from a remote service.
 
 #### Parameters
@@ -140,9 +165,9 @@ This method is asynchronous as it may ensure the catalog is up-to-date by fetchi
 
 #### Returns
 
-`Promise`\<[`ModelVariant`](ModelVariant.md)\>
+`Promise`\<[`IModel`](../README.md#imodel)\>
 
-A Promise that resolves to the ModelVariant object if found, otherwise throws an error.
+A Promise that resolves to the IModel object if found, otherwise throws an error.
 
 #### Throws
 

sdk/js/docs/classes/Model.md

@@ -21,7 +21,7 @@ new Model(variant): Model;
 
 | Parameter | Type |
 | ------ | ------ |
-| `variant` | [`ModelVariant`](ModelVariant.md) |
+| `variant` | `ModelVariant` |
 
 #### Returns
 
@@ -109,6 +109,28 @@ The ID of the selected variant.
 
 ***
 
+### info
+
+#### Get Signature
+
+```ts
+get info(): ModelInfo;
+```
+
+Gets the ModelInfo of the currently selected variant.
+
+##### Returns
+
+[`ModelInfo`](../README.md#modelinfo)
+
+The ModelInfo object.
+
+#### Implementation of
+
+[`IModel`](../README.md#imodel).[`info`](../README.md#info)
+
+***
+
 ### inputModalities
 
 #### Get Signature
@@ -212,43 +234,22 @@ get supportsToolCalling(): boolean | null;
 #### Get Signature
 
 ```ts
-get variants(): ModelVariant[];
+get variants(): IModel[];
 ```
 
 Gets all available variants for this model.
 
 ##### Returns
 
-[`ModelVariant`](ModelVariant.md)[]
-
-An array of ModelVariant objects.
+[`IModel`](../README.md#imodel)[]
 
-## Methods
+An array of IModel objects.
 
-### addVariant()
-
-```ts
-addVariant(variant): void;
-```
-
-Adds a new variant to this model.
-Automatically selects the new variant if it is cached and the current one is not.
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `variant` | [`ModelVariant`](ModelVariant.md) | The model variant to add. |
-
-#### Returns
-
-`void`
-
-#### Throws
+#### Implementation of
 
-Error - If the argument is not a ModelVariant object, or if the variant's alias does not match the model's alias.
+[`IModel`](../README.md#imodel).[`variants`](../README.md#variants)
 
-***
+## Methods
 
 ### createAudioClient()
 
@@ -410,15 +411,19 @@ Selects a specific variant.
 
 | Parameter | Type | Description |
 | ------ | ------ | ------ |
-| `variant` | [`ModelVariant`](ModelVariant.md) | The model variant to select. |
+| `variant` | [`IModel`](../README.md#imodel) | The model variant to select. Must be one of the variants in `variants`. |
 
 #### Returns
 
 `void`
 
 #### Throws
 
-Error - If the argument is not a ModelVariant object, or if the variant does not belong to this model.
+Error - If the variant does not belong to this model.
+
+#### Implementation of
+
+[`IModel`](../README.md#imodel).[`selectVariant`](../README.md#selectvariant)
 
 ***