Model Package Support (Phase 2)

include/onnxruntime/core/session/onnxruntime_c_api.h

@@ -341,6 +341,9 @@ ORT_RUNTIME_CLASS(ExternalSemaphoreHandle);   // EP-imported view of shared exte
 ORT_RUNTIME_CLASS(DeviceEpIncompatibilityDetails);
 ORT_RUNTIME_CLASS(EpAssignedSubgraph);
 ORT_RUNTIME_CLASS(EpAssignedNode);
+ORT_RUNTIME_CLASS(ModelPackageOptions);
+ORT_RUNTIME_CLASS(ModelPackageContext);
+ORT_RUNTIME_CLASS(ModelPackageComponentContext);
 
 #ifdef _MSC_VER
 typedef _Return_type_success_(return == 0) OrtStatus* OrtStatusPtr;
@@ -918,6 +921,9 @@ typedef struct OrtCompileApi OrtCompileApi;
 struct OrtInteropApi;
 typedef struct OrtInteropApi OrtInteropApi;
 
+struct OrtModelPackageApi;
+typedef struct OrtModelPackageApi OrtModelPackageApi;
+
 struct OrtEpApi;
 typedef struct OrtEpApi OrtEpApi;
 
@@ -7464,6 +7470,19 @@ struct OrtApi {
    * \see OrtApi::SetSessionExecutionMode
    */
   ORT_API2_STATUS(GetSessionExecutionMode, _In_ const OrtSessionOptions* options, _Out_ ExecutionMode* out);
+
+  /** \brief Get the OrtModelPackageApi instance, providing APIs for loading, inspecting,
+   *         and creating sessions from ORT model packages.
+   *
+   * ONNX Runtime releases guarantee that ::OrtApi is forward- and backward-compatible;
+   * ::OrtModelPackageApi carries its own independent versioning.
+   *
+   * \return Pointer to an ::OrtModelPackageApi, or NULL if model package support is not
+   *         available in this build (e.g., minimal builds).
+   *
+   * \since Version 1.27.
+   */
+  const OrtModelPackageApi*(ORT_API_CALL* GetModelPackageApi)(void);
 };
 
 /*
@@ -8551,6 +8570,158 @@ struct OrtInteropApi {
   /// @}
 };
 
+/** \brief APIs for loading, inspecting, and creating sessions from ONNX model packages.
+ *
+ * Obtain via OrtApi::GetModelPackageApi. Mirrors the shape of OrtCompileApi.
+ *
+ * Typical flow:
+ *
+ *   const OrtModelPackageApi* pkg = g_ort->GetModelPackageApi();
+ *
+ *   OrtModelPackageOptions* options = nullptr;
+ *   pkg->CreateModelPackageOptionsFromSessionOptions(env, session_options, &options);
+ *
+ *   OrtModelPackageContext* ctx = nullptr;
+ *   pkg->CreateModelPackageContext(env, package_root, options, &ctx);
+ *
+ *   size_t component_count = 0;
+ *   pkg->ModelPackageContext_GetComponentModelCount(ctx, &component_count);
+ *
+ *   const char* component_name = nullptr;
+ *   pkg->ModelPackageContext_GetComponentModelName(ctx, 0, &component_name);
+ *
+ *   OrtSession* session = nullptr;
+ *   pkg->CreateSession(env, ctx, component_name, nullptr, nullptr, &session);
+ *   g_ort->ReleaseSession(session);
+ *   pkg->ReleaseModelPackageContext(ctx);
+ *   pkg->ReleaseModelPackageOptions(options);
+ *
+ * \since Version 1.27.
+ */
+struct OrtModelPackageApi {
+  /// \name OrtModelPackageOptions
+  /// @{
+  ORT_API2_STATUS(CreateModelPackageOptionsFromSessionOptions,
+                  _In_ const OrtEnv* env,
+                  _In_ const OrtSessionOptions* session_options,
+                  _Outptr_ OrtModelPackageOptions** out);
+
+  ORT_CLASS_RELEASE(ModelPackageOptions);
+  /// @}
+  /// \name OrtModelPackageContext
+  /// @{
+  ORT_API2_STATUS(CreateModelPackageContext,
+                  _In_ const ORTCHAR_T* package_root,
+                  _Outptr_ OrtModelPackageContext** out);
+
+  ORT_CLASS_RELEASE(ModelPackageContext);
+
+  ORT_API2_STATUS(ModelPackage_GetComponentModelCount,
+                  _In_ const OrtModelPackageContext* ctx,
+                  _Out_ size_t* out_count);
+
+  ORT_API2_STATUS(ModelPackage_GetComponentModelNames,
+                  _In_ const OrtModelPackageContext* ctx,
+                  _Outptr_result_buffer_maybenull_(*out_count) const char* const** out_names,
+                  _Out_ size_t* out_count);
+
+  ORT_API2_STATUS(ModelPackage_GetModelVariantCount,
+                  _In_ const OrtModelPackageContext* ctx,
+                  _In_ const char* component_name,
+                  _Out_ size_t* out_count);
+
+  ORT_API2_STATUS(ModelPackage_GetModelVariantNames,
+                  _In_ const OrtModelPackageContext* ctx,
+                  _In_ const char* component_name,
+                  _Outptr_result_buffer_maybenull_(*out_count) const char* const** out_variant_names,
+                  _Out_ size_t* out_count);
+
+  /** \brief Select a component model and return an opaque component instance.
+   *
+   * The variant selection is also performed during this call based on the component metadata and the provided options.
+   * The returned `OrtModelPackgeComponentContext*` is independent of `context` lifetime and must be released via
+   * `ReleaseComponentInstance`.
+   *
+   * \since Version 1.27.
+   */
+  ORT_API2_STATUS(SelectComponent,
+                  _In_ const OrtModelPackageContext* context,
+                  _In_ const char* component_name,
+                  _In_ const OrtModelPackageOptions* options,
+                  _Outptr_ OrtModelPackageComponentContext** out);
+
+  ORT_CLASS_RELEASE(ModelPackageComponentContext);
+
+  ORT_API2_STATUS(ModelPackageComponent_GetSelectedVariantFolderPath,
+                  _In_ const OrtModelPackageComponentContext* ctx,
+                  _Outptr_ const ORTCHAR_T** folder_path);
+
+  ORT_API2_STATUS(ModelPackageComponent_GetSelectedVariantFileCount,
+                  _In_ const OrtModelPackageComponentContext* ctx,
+                  _Out_ size_t* num_files);
+
+  ORT_API2_STATUS(ModelPackageComponent_GetSelectedVariantFilePath,
+                  _In_ const OrtModelPackageComponentContext* ctx,
+                  _In_ size_t file_idx,
+                  _Outptr_ const ORTCHAR_T** out_path);
+
+  /** \brief Get session options for the specific model file within the selected variant as flat key/value entries.
+   *
+   * Returns NULL/empty arrays when none specified.
+   * Memory is owned by `ctx` and valid until the next model-package query call on that context.
+   *
+   * \since Version 1.27.
+   */
+  ORT_API2_STATUS(ModelPackageComponent_GetSelectedVariantFileSessionOptions,
+                  _In_ const OrtModelPackageComponentContext* ctx,
+                  _In_ size_t file_idx,
+                  _Outptr_result_buffer_maybenull_(*num_entries) const char* const** option_keys,
+                  _Outptr_result_buffer_maybenull_(*num_entries) const char* const** option_values,
+                  _Out_ size_t* num_entries);
+
+  /** \brief Get provider options for the specific model file within the selected variant as flat key/value entries.
+   *
+   * Returns NULL/empty arrays when none specified.
+   * Memory is owned by `ctx` and valid until the next model-package query call on that context.
+   *
+   * \since Version 1.27.
+   */
+  ORT_API2_STATUS(ModelPackageComponent_GetSelectedVariantFileProviderOptions,
+                  _In_ const OrtModelPackageComponentContext* ctx,
+                  _In_ size_t file_idx,
+                  _Outptr_result_buffer_maybenull_(*num_entries) const char* const** option_keys,
+                  _Outptr_result_buffer_maybenull_(*num_entries) const char* const** option_values,
+                  _Out_ size_t* num_entries);
+
+  /// @}
+  /** \brief Create an OrtSession for a selected file within a component model variant.
+   *
+   * The chosen variant (and thus its EP selection) is determined by `context`, which
+   * was built from an OrtSessionOptions via CreateModelPackageOptionsFromSessionOptions.
+   *
+   * Session options precedence:
+   *   1. session_options == NULL (default path):
+   *      ORT uses the OrtSessionOptions that was captured when `context` was created.
+   *      Any variant-specific session and provider options declared in the package
+   *      metadata are merged on top.
+   *
+   *   2. session_options != NULL (advanced path):
+   *      ORT uses the caller-provided OrtSessionOptions as-is. Variant-specific
+   *      session and provider options from the package metadata are NOT applied.
+   *      Use this when custom EP setup is required (e.g., shared CUDA streams,
+   *      shared QNN EP contexts, custom allocators).
+   *
+   * \since Version 1.27.
+   */
+  ORT_API2_STATUS(CreateSession,
+                  _In_ const OrtEnv* env,
+                  _In_ OrtModelPackageComponentContext* context,
+                  _In_opt_ const OrtSessionOptions* session_options,
+                  _Outptr_ OrtSession** session);
+
+  // End of Version 1.27 - DO NOT MODIFY ABOVE
+};
+
 /*
  * This is the old way to add the CUDA provider to the session, please use SessionOptionsAppendExecutionProvider_CUDA above to access the latest functionality
  * This function always exists, but will only succeed if Onnxruntime was built with CUDA support and the CUDA provider shared library exists