Model Package Support (Phase 2)

cmake/onnxruntime_session.cmake

@@ -11,6 +11,19 @@ file(GLOB onnxruntime_session_srcs CONFIGURE_DEPENDS
     "${ONNXRUNTIME_ROOT}/core/session/model_package/*.cc"
     )
 
+# Standalone model package library (parsing/inspection with no ORT dependency).
+# Compiled as a static library and linked into onnxruntime_session.
+# NOTE: ORT intentionally uses the library's internal C++ types directly (model_package::ParsePackage,
+# model_package_internal.h) rather than going through its public C API (ModelPackage_*). This avoids
+# double-wrapping (ORT C API -> standalone C API -> C++ internals). The public C API exists for
+# external consumers (GenAI, FL) who link against the standalone library independently.
+set(MODEL_PACKAGE_LIB_DIR "${REPO_ROOT}/model_package")
+if(NOT onnxruntime_MINIMAL_BUILD)
+  set(MODEL_PACKAGE_BUILD_SHARED OFF CACHE BOOL "" FORCE)
+  set(MODEL_PACKAGE_BUILD_TESTS OFF CACHE BOOL "" FORCE)
+  add_subdirectory(${MODEL_PACKAGE_LIB_DIR} ${CMAKE_CURRENT_BINARY_DIR}/model_package EXCLUDE_FROM_ALL)
+endif()
+
 if (onnxruntime_ENABLE_TRAINING_APIS)
   file(GLOB_RECURSE training_api_srcs CONFIGURE_DEPENDS
     "${ORTTRAINING_SOURCE_DIR}/training_api/*.cc"
@@ -44,6 +57,10 @@ source_group(TREE ${REPO_ROOT} FILES ${onnxruntime_session_srcs})
 onnxruntime_add_static_library(onnxruntime_session ${onnxruntime_session_srcs})
 onnxruntime_add_include_to_target(onnxruntime_session onnxruntime_common onnxruntime_framework onnxruntime_lora onnx onnx_proto ${PROTOBUF_LIB} flatbuffers::flatbuffers Boost::mp11 safeint_interface nlohmann_json::nlohmann_json Eigen3::Eigen)
 target_link_libraries(onnxruntime_session PRIVATE onnxruntime_lora)
+if(TARGET model_package)
+  target_link_libraries(onnxruntime_session PRIVATE model_package)
+  target_include_directories(onnxruntime_session PRIVATE ${MODEL_PACKAGE_LIB_DIR}/include ${MODEL_PACKAGE_LIB_DIR}/src)
+endif()
 if(onnxruntime_ENABLE_INSTRUMENT)
   target_compile_definitions(onnxruntime_session PUBLIC ONNXRUNTIME_ENABLE_INSTRUMENT)
 endif()
@@ -74,4 +91,10 @@ if (NOT onnxruntime_BUILD_SHARED_LIB)
             LIBRARY   DESTINATION ${CMAKE_INSTALL_LIBDIR}
             RUNTIME   DESTINATION ${CMAKE_INSTALL_BINDIR}
             FRAMEWORK DESTINATION ${CMAKE_INSTALL_BINDIR})
+    if(TARGET model_package)
+      install(TARGETS model_package EXPORT ${PROJECT_NAME}Targets
+              ARCHIVE   DESTINATION ${CMAKE_INSTALL_LIBDIR}
+              LIBRARY   DESTINATION ${CMAKE_INSTALL_LIBDIR}
+              RUNTIME   DESTINATION ${CMAKE_INSTALL_BINDIR})
+    endif()
 endif()

include/onnxruntime/core/session/onnxruntime_c_api.h

@@ -348,6 +348,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;
@@ -925,6 +928,9 @@ typedef struct OrtCompileApi OrtCompileApi;
 struct OrtInteropApi;
 typedef struct OrtInteropApi OrtInteropApi;
 
+struct OrtModelPackageApi;
+typedef struct OrtModelPackageApi OrtModelPackageApi;
+
 struct OrtEpApi;
 typedef struct OrtEpApi OrtEpApi;
 
@@ -7486,6 +7492,26 @@ struct OrtApi {
    * \since Version 1.27.
    */
   ORT_API2_STATUS(SessionReleaseCapturedGraph, _In_ OrtSession* session, _In_ int graph_annotation_id);
+
+  /** \brief Get the model package API table.
+   *
+   * Returns a pointer to the ::OrtModelPackageApi function table, which provides APIs to:
+   * - create and release model package options and contexts,
+   * - inspect model package metadata (components/variants),
+   * - select a component/variant and query selected files/options,
+   * - create a session from model package selection results.
+   *
+   * The returned pointer is owned by ONNX Runtime and is valid for the process lifetime.
+   * Do not free it.
+   *
+   * \note May return NULL if model package support is not available in the current build
+   *       (for example, minimal builds).
+   *
+   * \return Pointer to ::OrtModelPackageApi, or NULL if unsupported.
+   *
+   * \since Version 1.27.
+   */
+  const OrtModelPackageApi*(ORT_API_CALL* GetModelPackageApi)(void);
 };
 
 /*
@@ -8573,6 +8599,250 @@ struct OrtInteropApi {
   /// @}
 };
 
+/** \brief API table for model package workflows.
+ *
+ * A model package is a directory containing one or more *components* (logical models).
+ * Each component has one or more *variants*, where each variant targets a single
+ * execution provider (EP). The package manifest declares the EP name, device type,
+ * and an optional compatibility string for every variant so that the runtime can
+ * automatically select the best variant for the hardware and EPs available in the
+ * caller's session options.
+ *
+ * Obtain this table from OrtApi::GetModelPackageApi(). The APIs support:
+ * - creating model package options that capture EP configuration from OrtSessionOptions,
+ * - loading a package context (manifest + metadata) from a package root path,
+ * - querying component/variant metadata including per-variant EP information,
+ * - selecting a component (which also resolves the best-matching variant),
+ * - querying the selected variant's name and folder path,
+ * - creating an OrtSession from the selected component context.
+ *
+ * Typical flow:
+ * 1) Create model package options:
+ *    - CreateModelPackageOptionsFromSessionOptions()
+ * 2) Load package metadata:
+ *    - CreateModelPackageContext()
+ * 3) Query metadata (optional):
+ *    - ModelPackage_GetSchemaVersion()
+ *    - ModelPackage_GetComponentCount()
+ *    - ModelPackage_GetComponentNames()
+ *    - ModelPackage_GetVariantCount()
+ *    - ModelPackage_GetVariantNames()
+ *    - ModelPackage_GetVariantEpName()
+ * 4) Select a component and resolve variant:
+ *    - SelectComponent()
+ * 5) Query selected variant info (optional):
+ *    - ModelPackageComponent_GetSelectedVariantName()
+ *    - ModelPackageComponent_GetSelectedVariantFolderPath()
+ * 6) Create session:
+ *    - CreateSession()
+ *
+ * Ownership:
+ * - Release objects created by this API with the corresponding release methods:
+ *   ReleaseModelPackageOptions(), ReleaseModelPackageContext(),
+ *   ReleaseModelPackageComponentContext().
+ *
+ * \since Version 1.27.
+ */
+struct OrtModelPackageApi {
+  /// \name OrtModelPackageOptions
+  /// @{
+
+  /** \brief Create model package options from an existing OrtSessionOptions.
+   *
+   * Captures EP configuration (registered execution providers and their devices) from
+   * the session options for use during variant selection. The resulting OrtModelPackageOptions
+   * is passed to SelectComponent() to resolve the best variant for the available EPs.
+   *
+   * \param[in] env The ORT environment.
+   * \param[in] session_options Session options containing registered EPs.
+   * \param[out] out Receives the newly created OrtModelPackageOptions. Must be released
+   *             with ReleaseModelPackageOptions().
+   *
+   * \since Version 1.27.
+   */
+  ORT_API2_STATUS(CreateModelPackageOptionsFromSessionOptions,
+                  _In_ const OrtEnv* env,
+                  _In_ const OrtSessionOptions* session_options,
+                  _Outptr_ OrtModelPackageOptions** out);
+
+  ORT_CLASS_RELEASE(ModelPackageOptions);
+  /// @}
+  /// \name OrtModelPackageContext
+  /// @{
+
+  /** \brief Create a model package context by parsing the package at the given root path.
+   *
+   * Parses the manifest.json and component metadata from the specified directory.
+   * The returned context provides read-only access to the package structure (components,
+   * variants, EP declarations).
+   *
+   * \param[in] package_root Path to the model package root directory (containing manifest.json).
+   * \param[out] out Receives the newly created OrtModelPackageContext. Must be released
+   *             with ReleaseModelPackageContext().
+   *
+   * \since Version 1.27.
+   */
+  ORT_API2_STATUS(CreateModelPackageContext,
+                  _In_ const ORTCHAR_T* package_root,
+                  _Outptr_ OrtModelPackageContext** out);
+
+  ORT_CLASS_RELEASE(ModelPackageContext);
+
+  /** \brief Get the schema version declared in the model package manifest.
+   *
+   * \param[in] ctx The model package context.
+   * \param[out] out_version Receives the schema version number.
+   *
+   * \since Version 1.27.
+   */
+  ORT_API2_STATUS(ModelPackage_GetSchemaVersion,
+                  _In_ const OrtModelPackageContext* ctx,
+                  _Out_ int64_t* out_version);
+
+  /** \brief Get the number of components in the model package.
+   *
+   * \param[in] ctx The model package context.
+   * \param[out] out_count Receives the component count.
+   *
+   * \since Version 1.27.
+   */
+  ORT_API2_STATUS(ModelPackage_GetComponentCount,
+                  _In_ const OrtModelPackageContext* ctx,
+                  _Out_ size_t* out_count);
+
+  /** \brief Get the names of all components in the model package.
+   *
+   * Returns a pointer to an array of UTF-8 component name strings. The array and its
+   * strings are owned by `ctx` and remain valid until the context is released.
+   *
+   * \param[in] ctx The model package context.
+   * \param[out] out_names Receives a pointer to an array of component name strings.
+   * \param[out] out_count Receives the number of elements in the array.
+   *
+   * \since Version 1.27.
+   */
+  ORT_API2_STATUS(ModelPackage_GetComponentNames,
+                  _In_ const OrtModelPackageContext* ctx,
+                  _Outptr_result_buffer_maybenull_(*out_count) const char* const** out_names,
+                  _Out_ size_t* out_count);
+
+  /** \brief Get the number of variants for a given component.
+   *
+   * \param[in] ctx The model package context.
+   * \param[in] component_name Name of the component to query.
+   * \param[out] out_count Receives the variant count.
+   *
+   * \since Version 1.27.
+   */
+  ORT_API2_STATUS(ModelPackage_GetVariantCount,
+                  _In_ const OrtModelPackageContext* ctx,
+                  _In_ const char* component_name,
+                  _Out_ size_t* out_count);
+
+  /** \brief Get the names of all variants for a given component.
+   *
+   * Returns a pointer to an array of UTF-8 variant name strings. The array and its
+   * strings are owned by `ctx` and remain valid until the context is released.
+   *
+   * \param[in] ctx The model package context.
+   * \param[in] component_name Name of the component to query.
+   * \param[out] out_variant_names Receives a pointer to an array of variant name strings.
+   * \param[out] out_count Receives the number of elements in the array.
+   *
+   * \since Version 1.27.
+   */
+  ORT_API2_STATUS(ModelPackage_GetVariantNames,
+                  _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 Get the EP name declared for a (component, variant) pair.
+   *
+   * Each variant targets a single EP. `out_ep` receives the EP name string.
+   * When the variant does not declare an EP, the returned pointer is NULL.
+   * String memory is owned by `ctx` and remains valid until the context is released.
+   *
+   * \since Version 1.27.
+   */
+  ORT_API2_STATUS(ModelPackage_GetVariantEpName,
+                  _In_ const OrtModelPackageContext* ctx,
+                  _In_ const char* component_name,
+                  _In_ const char* variant_name,
+                  _Outptr_result_maybenull_ const char** out_ep);
+
+  /** \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);
+
+  /** \brief Get the name of the selected variant after SelectComponent has been called.
+   *
+   * String memory is owned by `ctx` and remains valid until the context is released.
+   *
+   * \param[in] ctx The component context returned by SelectComponent().
+   * \param[out] out_name Receives the selected variant's name string.
+   *
+   * \since Version 1.27.
+   */
+  ORT_API2_STATUS(ModelPackageComponent_GetSelectedVariantName,
+                  _In_ const OrtModelPackageComponentContext* ctx,
+                  _Outptr_ const char** out_name);
+
+  /** \brief Get the folder path of the selected variant.
+   *
+   * Returns the resolved absolute path to the variant's directory on disk.
+   * The string is owned by `ctx` and remains valid until the context is released.
+   *
+   * \param[in] ctx The component context returned by SelectComponent().
+   * \param[out] folder_path Receives the variant folder path string.
+   *
+   * \since Version 1.27.
+   */
+  ORT_API2_STATUS(ModelPackageComponent_GetSelectedVariantFolderPath,
+                  _In_ const OrtModelPackageComponentContext* ctx,
+                  _Outptr_ const ORTCHAR_T** folder_path);
+
+  /// @}
+  /** \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