Model Package Support (Phase 2)

[chilo-ms]

Summary

This PR implements the model package feature for ONNX Runtime — a structured packaging format that bundles multiple model variants (targeting different EPs) with metadata for automatic variant selection at runtime. It builds on the foundational model package support introduced in #27786 by extracting the parsing logic into a standalone reusable library, simplifying the public API surface, adding new query/traversal APIs, and hardening security and correctness.

Key Components

1. Standalone model_package/ library — A self-contained C library at the repo root that parses model packages (manifest.json, metadata.json, variant.json). No dependency on ONNX Runtime. Designed to be consumed independently by ORT, GenAI, and FL.

2. ORT integration — ORT links the standalone library as a static lib and uses its internal C++ types directly (not the public C API) to avoid double-wrapping overhead. The public C API exists for external consumers.

3. OrtModelPackageApi C API — A new vtable-based API surface (similar to OrtApi) exposing package parsing, variant enumeration, variant selection, and session creation.

4. C++ wrappers and Python bindings — RAII C++ wrappers (ModelPackageContext, ModelPackageComponentContext, ModelPackageOptions) and full Python bindings.

API Surface — Standalone Library (model_package/include/model_package_api.h)

A dependency-free C API for parsing and inspecting model packages without linking ONNX Runtime.

Category	Function
Status	ModelPackage_ReleaseStatus
	ModelPackage_GetErrorMessage
Context lifecycle	ModelPackage_CreateContext
	ModelPackage_ReleaseContext
Package queries	ModelPackage_GetSchemaVersion
Component queries	ModelPackage_GetComponentCount
	ModelPackage_GetComponentName
Variant queries	ModelPackage_GetVariantCount
	ModelPackage_GetVariantName
	ModelPackage_GetVariantFolderPath
EP compatibility	ModelPackage_GetVariantEpName

API Surface — ORT (OrtModelPackageApi in onnxruntime_c_api.h)

Accessed via OrtApi::GetModelPackageApi(). Extends the standalone surface with EP-aware variant selection and session creation.

Category	Function
Options	CreateModelPackageOptionsFromSessionOptions
	ReleaseModelPackageOptions
Context lifecycle	CreateModelPackageContext
	ReleaseModelPackageContext
Package queries	ModelPackage_GetSchemaVersion
	ModelPackage_GetComponentCount
	ModelPackage_GetComponentNames
	ModelPackage_GetVariantCount
	ModelPackage_GetVariantNames
	ModelPackage_GetVariantEpName
Selection	SelectComponent
	ReleaseModelPackageComponentContext
Selected variant	ModelPackageComponent_GetSelectedVariantName
	ModelPackageComponent_GetSelectedVariantFolderPath
Session	CreateSession

Security & Correctness

• Path traversal validation (ValidatePathSegment, ValidatePathConfinement)
• Use-after-free fix: ModelPackageComponentContext owns all state
• Deterministic tie-break in variant selection (first-declared wins)
• CPU fallback loop when requested EP has no match

Session Creation

• Clean-slate approach: default path starts from fresh OrtSessionOptions
• Variant session/provider options merged via AddSessionConfigEntry
• Advanced path: caller-supplied options used as-is (no metadata merge)

Files Added

• model_package/ — Standalone library (header, parser, C API, CMakeLists, README)
• onnxruntime/core/session/model_package_api.{h,cc} — ORT C API implementation + vtable
• onnxruntime/core/session/model_package/model_package_options.{h,cc} — Options/EP resolution
• onnxruntime/core/session/model_package/model_package_variant_selector.{h,cc} — Variant selector

Files Removed

• onnxruntime/core/session/model_package/model_package_descriptor_parser.{h,cc} — Replaced by standalone lib

Testing

• Extended test_model_package.cc with tests for all API functions, variant selection, tie-break determinism, session option dispatch, and error cases
• Python bindings tested via e2e notebooks (phi4, qwen3-vl, whisper, nemotron)

---

[github-actions]

You can commit the suggested changes from lintrunner.

[chilo-ms]

Please note that in variant selection, we need the new EP API SelectBestCompiledModelCompatibilityInfo from this PR.
Once that PR is merged, i can update the variant selection code accordingly.

[github-actions]

You can commit the suggested changes from lintrunner.

[github-actions]

You can commit the suggested changes from lintrunner.

[github-actions]

You can commit the suggested changes from lintrunner.