Explicit EP Download & Per-EP Progress Reporting (#568)

Makes execution provider (EP) management explicit across all SDKs and
adds real-time per-EP download progress
reporting. Previously, EP downloads happened implicitly during catalog
access with no granular progress visibility.
Now callers explicitly discover, download, and monitor EPs with typed
APIs and streaming progress callbacks.

  What's included

  Explicit EP discovery and download (all SDKs)

- DiscoverEps() / discoverEps() / discover_eps() — returns typed EpInfo
with name and registration status
- DownloadAndRegisterEpsAsync() / downloadAndRegisterEps() /
download_and_register_eps() — downloads and registers
  EPs, returns typed EpDownloadResult
   - Catalog access no longer blocks on EP downloads

  Per-EP progress callbacks (all SDKs)

- C#: DownloadAndRegisterEpsAsync(names, Action<string, double>
progressCallback, ct) — uses
ExecuteCommandWithCallbackAsync; parses wire format with
CultureInfo.InvariantCulture for locale safety
- JS: downloadAndRegisterEpsWithProgress(names?, progressCallback?) —
uses executeCommandStreaming
- Python: download_and_register_eps(names, progress_callback) — uses
execute_command_with_callback
- Rust: download_and_register_eps_with_progress(names, FnMut(&str, f64))
— parses "name|percent" wire format inside
   the SDK

  Live Audio Transcription (C#)

- New LiveAudioTranscriptionSession with real-time streaming over
WebSocket
- Supports start/stop/send audio chunks with configurable output types
   - Unit tests with mocked CoreInterop

  Other improvements

- Typed EpInfo / EpDownloadResult in dedicated type files across all
SDKs
   - EP unit tests for JS and Python
- Removed implicit 6-hour catalog TTL caching (delegated to native core)
   - New CoreInterop methods for callback-based command execution (C#)
   - AOT-compatible JSON serialization context for EP types (C#)

  Testing
   - New unit tests for EP discovery/download in JS and Python

  Breaking changes

- Catalog no longer implicitly triggers EP downloads — callers must
explicitly call DownloadAndRegisterEpsAsync /
downloadAndRegisterEps / download_and_register_eps before accessing
hardware-accelerated models.

---------

Co-authored-by: Baiju Meswani <bmeswani@microsoft.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: 4 people

samples/cs/audio-transcription-example/Program.cs

@@ -20,7 +20,7 @@
 // EP packages include dependencies and may be large.
 // Download is only required again if a new version of the EP is released.
 // For cross platform builds there is no dynamic EP download and this will return immediately.
-await Utils.RunWithSpinner("Registering execution providers", mgr.EnsureEpsDownloadedAsync());
+await Utils.RunWithSpinner("Registering execution providers", mgr.DownloadAndRegisterEpsAsync());
 // </init>
 
 
@@ -56,6 +56,7 @@ await model.DownloadAsync(progress =>
 // <transcription>
 // Get an audio client
 var audioClient = await model.GetAudioClientAsync();
+audioClient.Settings.Language = "en";
 
 // Get a transcription with streaming outputs
 var audioFile = args.Length > 0 ? args[0] : Path.Combine(AppContext.BaseDirectory, "Recording.mp3");

samples/cs/foundry-local-web-server/Program.cs

@@ -26,7 +26,7 @@
 // EP packages include dependencies and may be large.
 // Download is only required again if a new version of the EP is released.
 // For cross platform builds there is no dynamic EP download and this will return immediately.
-await Utils.RunWithSpinner("Registering execution providers", mgr.EnsureEpsDownloadedAsync());
+await Utils.RunWithSpinner("Registering execution providers", mgr.DownloadAndRegisterEpsAsync());
 // </init>
 
 

samples/cs/live-audio-transcription-example/Program.cs

@@ -20,7 +20,7 @@
 await FoundryLocalManager.CreateAsync(config, Utils.GetAppLogger());
 var mgr = FoundryLocalManager.Instance;
 
-await Utils.RunWithSpinner("Registering execution providers", mgr.EnsureEpsDownloadedAsync());
+await mgr.DownloadAndRegisterEpsAsync();
 
 var catalog = await mgr.GetCatalogAsync();
 

samples/cs/model-management-example/Program.cs

@@ -16,11 +16,8 @@
 var mgr = FoundryLocalManager.Instance;
 
 
-// Ensure that any Execution Provider (EP) downloads run and are completed.
-// EP packages include dependencies and may be large.
-// Download is only required again if a new version of the EP is released.
-// For cross platform builds there is no dynamic EP download and this will return immediately.
-await Utils.RunWithSpinner("Registering execution providers", mgr.EnsureEpsDownloadedAsync());
+// Download and register all execution providers.
+await Utils.RunWithSpinner("Registering execution providers", mgr.DownloadAndRegisterEpsAsync());
 
 
 // Model catalog operations

samples/cs/native-chat-completions/Program.cs

@@ -19,11 +19,43 @@
 var mgr = FoundryLocalManager.Instance;
 
 
-// Ensure that any Execution Provider (EP) downloads run and are completed.
+// Discover available execution providers and their registration status.
+var eps = mgr.DiscoverEps();
+Console.WriteLine("Available execution providers:");
+foreach (var ep in eps)
+{
+    Console.WriteLine($"  {ep.Name} (registered: {ep.IsRegistered})");
+}
+
+// Download and register all execution providers with per-EP progress.
 // EP packages include dependencies and may be large.
 // Download is only required again if a new version of the EP is released.
 // For cross platform builds there is no dynamic EP download and this will return immediately.
-await Utils.RunWithSpinner("Registering execution providers", mgr.EnsureEpsDownloadedAsync());
+if (eps.Length > 0)
+{
+    int maxNameLen = eps.Max(e => e.Name.Length);
+    string currentEp = "";
+    await mgr.DownloadAndRegisterEpsAsync((epName, percent) =>
+    {
+        if (epName != currentEp)
+        {
+            if (currentEp != "")
+            {
+                Console.WriteLine();
+            }
+            currentEp = epName;
+        }
+        Console.Write($"\r  {epName.PadRight(maxNameLen)}  {percent,6:F1}%");
+        if (percent >= 100)
+        {
+            Console.WriteLine();
+        }
+    });
+}
+else
+{
+    Console.WriteLine("No execution providers to download.");
+}
 // </init>
 
 

samples/cs/tool-calling-foundry-local-sdk/Program.cs

@@ -26,7 +26,7 @@
 // EP packages include dependencies and may be large.
 // Download is only required again if a new version of the EP is released.
 // For cross platform builds there is no dynamic EP download and this will return immediately.
-await Utils.RunWithSpinner("Registering execution providers", mgr.EnsureEpsDownloadedAsync());
+await Utils.RunWithSpinner("Registering execution providers", mgr.DownloadAndRegisterEpsAsync());
 // </init>
 
 

samples/cs/tool-calling-foundry-local-web-server/Program.cs

@@ -21,11 +21,8 @@
 var mgr = FoundryLocalManager.Instance;
 
 
-// Ensure that any Execution Provider (EP) downloads run and are completed.
-// EP packages include dependencies and may be large.
-// Download is only required again if a new version of the EP is released.
-// For cross platform builds there is no dynamic EP download and this will return immediately.
-await Utils.RunWithSpinner("Registering execution providers", mgr.EnsureEpsDownloadedAsync());
+// Download and register all execution providers.
+await Utils.RunWithSpinner("Registering execution providers", mgr.DownloadAndRegisterEpsAsync());
 
 
 // Get the model catalog

samples/js/native-chat-completions/app.js

@@ -14,6 +14,35 @@ const manager = FoundryLocalManager.create({
 // </init>
 console.log('✓ SDK initialized successfully');
 
+// Discover available execution providers and their registration status.
+const eps = manager.discoverEps();
+console.log('\nAvailable execution providers:');
+for (const ep of eps) {
+    console.log(`  ${ep.name} (registered: ${ep.isRegistered})`);
+}
+
+// Download and register all execution providers with per-EP progress.
+// EP packages include dependencies and may be large.
+// Download is only required again if a new version of the EP is released.
+if (eps.length > 0) {
+    const maxNameLen = Math.max(...eps.map(e => e.name.length));
+    let currentEp = '';
+    await manager.downloadAndRegisterEps((epName, percent) => {
+        if (epName !== currentEp) {
+            if (currentEp !== '') {
+                process.stdout.write('\n');
+            }
+            currentEp = epName;
+        }
+        process.stdout.write(`\r  ${epName.padEnd(maxNameLen)}  ${percent.toFixed(1).padStart(5)}%`);
+        if (percent >= 100) {
+            process.stdout.write('\n');
+        }
+    });
+} else {
+    console.log('No execution providers to download.');
+}
+
 // <model_setup>
 // Get the model object
 const modelAlias = 'qwen2.5-0.5b'; // Using an available model from the list above

sdk/cs/README.md

@@ -48,21 +48,60 @@ dotnet build src/Microsoft.AI.Foundry.Local.csproj /p:UseWinML=true
 
 ### Triggering EP download
 
-EP download can be time-consuming. Call `DownloadAndRegisterEpsAsync` early (after initialization) to separate the download step from catalog access:
+EP management is explicit via two methods:
+
+- **`DiscoverEps()`** — returns an array of `EpInfo` describing each available EP and whether it is already registered.
+- **`DownloadAndRegisterEpsAsync(names?, progressCallback?, ct?)`** — downloads and registers the specified EPs (or all available EPs if no names are given). Returns an `EpDownloadResult`. Overloads are provided so you can pass just a callback without specifying names.
 
 ```csharp
 // Initialize the manager first (see Quick Start)
 await FoundryLocalManager.CreateAsync(
     new Configuration { AppName = "my-app" },
     NullLogger.Instance);
 
-await FoundryLocalManager.Instance.DownloadAndRegisterEpsAsync();
+var mgr = FoundryLocalManager.Instance;
 
-// Now catalog access won't trigger an EP download
-var catalog = await FoundryLocalManager.Instance.GetCatalogAsync();
+// Discover what EPs are available
+var eps = mgr.DiscoverEps();
+foreach (var ep in eps)
+{
+    Console.WriteLine($"{ep.Name} — registered: {ep.IsRegistered}");
+}
+
+// Download and register all EPs
+var result = await mgr.DownloadAndRegisterEpsAsync();
+Console.WriteLine($"Success: {result.Success}, Status: {result.Status}");
+
+// Or download only specific EPs
+var result2 = await mgr.DownloadAndRegisterEpsAsync(new[] { eps[0].Name });
+```
+
+#### Per-EP download progress
+
+Pass an optional `Action<string, double>` callback to receive `(epName, percent)` updates
+as each EP downloads (`percent` is 0–100):
+
+```csharp
+string currentEp = "";
+await mgr.DownloadAndRegisterEpsAsync((epName, percent) =>
+{
+    if (epName != currentEp)
+    {
+        if (currentEp != "")
+        {
+            Console.WriteLine();
+        }
+        currentEp = epName;
+    }
+    Console.Write($"\r  {epName}  {percent,6:F1}%");
+    if (percent >= 100)
+    {
+        Console.WriteLine();
+    }
+});
 ```
 
-If you skip this step, EPs are downloaded automatically the first time you access the catalog. Once cached, subsequent calls are fast.
+Catalog access no longer blocks on EP downloads. Call `DownloadAndRegisterEpsAsync` explicitly when you need hardware-accelerated execution providers.
 
 ## Quick Start
 

sdk/cs/docs/api/index.md

@@ -6,6 +6,10 @@
 
 [DeviceType](./microsoft.ai.foundry.local.devicetype.md)
 
+[EpDownloadResult](./microsoft.ai.foundry.local.epdownloadresult.md)
+
+[EpInfo](./microsoft.ai.foundry.local.epinfo.md)
+
 [FoundryLocalException](./microsoft.ai.foundry.local.foundrylocalexception.md)
 
 [FoundryLocalManager](./microsoft.ai.foundry.local.foundrylocalmanager.md)
@@ -22,8 +26,6 @@
 
 [ModelSettings](./microsoft.ai.foundry.local.modelsettings.md)
 
-[ModelVariant](./microsoft.ai.foundry.local.modelvariant.md)
-
 [OpenAIAudioClient](./microsoft.ai.foundry.local.openaiaudioclient.md)
 
 [OpenAIChatClient](./microsoft.ai.foundry.local.openaichatclient.md)
@@ -39,3 +41,11 @@
 [AsyncLock](./microsoft.ai.foundry.local.detail.asynclock.md)
 
 [CoreInteropRequest](./microsoft.ai.foundry.local.detail.coreinteroprequest.md)
+
+## Microsoft.AI.Foundry.Local.OpenAI
+
+[LiveAudioTranscriptionResponse](./microsoft.ai.foundry.local.openai.liveaudiotranscriptionresponse.md)
+
+[LiveAudioTranscriptionSession](./microsoft.ai.foundry.local.openai.liveaudiotranscriptionsession.md)
+
+[ResponseFormatExtended](./microsoft.ai.foundry.local.openai.responseformatextended.md)