Qualcomm AI Engine Direct - [GenAI Pipeline] PR1: Core Data Model, Engine Routing & Exceptions

[qti-horodnic]

Summary

This pr introduces the foundational data model for the GenAI pipeline under backends/qualcomm/genai_pipeline/. This is the first of 6 PRs total in phase 1, creating the skeleton framework. It covers configuration data classes, pipeline context with builder pattern, engine routing, exception hierarchy, and constants. No existing files are modified.

What's included

InputConfig / OutputConfig data classes:

• ModelPreparationInputConfig / ModelPreparationOutputConfig
• QuantizationInputConfig / QuantizationOutputConfig
• CompilationInputConfig / CompilationOutputConfig
• InferenceInputConfig / InferenceOutputConfig

Each stage receives an InputConfig and produces an OutputConfig — no ambiguity about which fields are inputs vs outputs.

Pipeline context:

• PipelineContext: immutable frozen data class carrying user inputs (model_name, soc_model, prompt, artifact_dir).
• PipelineContextBuilder: builder pattern with required-field validation at build() time.

Engine routing:

• EngineProxy: maps pipeline stages to engine types with construction-time validation.
• EngineType enum: (EXECUTORCH).

Exception hierarchy:

• PipelineError: base exception.
• StageError: stage execution errors with stage name + original exception chaining.
• ConfigValidationError: build-time validation errors.
• EngineNotAvailableError: engine not installed errors.

Constants & versioning:

• pipeline_types.py: stage name constants (STAGE_QUANTIZATION, etc.).
• __version__ = "1.0.0".

Unit tests:

• Config defaults, field independence, mutable defaults.
• Context builder validation (success + all failure paths).
• Context immutability.
• Engine proxy routing, defaults, validation.
• Shared test utilities in test_utils.py.

PR Review Checklist

All new classes follow single responsibility (one class per file) - Yes.
All dependencies are injected via constructor with sensible defaults - Yes.
All external calls are behind injectable interfaces - N/A, no external calls in this PR.
Unit tests cover every public method - Yes.
No existing files are modified (Phase 1 constraint) - Yes
Docstrings on all public classes and methods - Yes.
Type annotations on all function signatures - Yes.
Logging follows the strategy in the LLD - N/A, no logging in this PR.

Future PRs

• PR 1: Core data model, engine routing & exceptions: this pr.
• PR 2: Strategy interfaces & stage wrappers: pending.
• PR 3: Pipeline orchestrator: pending.
• PR 4: Adapter interfaces & default implementations: pending.
• PR 5: Model preparation & quantization strategies: pending
• PR 6: Compilation & inference strategy implementations: pending.
• PR 7: Integration & E2E tests: pending.

Test plan

python -m pytest \
 backends/qualcomm/genai_pipeline/tests/test_pipeline_context.py \
  backends/qualcomm/genai_pipeline/tests/test_engine_proxy.py \
  backends/qualcomm/genai_pipeline/tests/test_exceptions.py \
  backends/qualcomm/genai_pipeline/tests/configs/ \
  -v

Test Coverage

Command to run:

python -m pytest \
  backends/qualcomm/genai_pipeline/tests/test_pipeline_context.py \
  backends/qualcomm/genai_pipeline/tests/test_engine_proxy.py \
  backends/qualcomm/genai_pipeline/tests/test_exceptions.py \
  backends/qualcomm/genai_pipeline/tests/configs/ \
  --cov=backends/qualcomm/genai_pipeline \
  --cov-config=backends/qualcomm/.coveragerc \
  --cov-report=term-missing \
  -v

Result:

Name                                                                          Stmts   Miss Branch BrPart  Cover   Missing
-------------------------------------------------------------------------------------------------------------------------
backends/qualcomm/genai_pipeline/configs/compilation_input_config.py             11      0      0      0   100%
backends/qualcomm/genai_pipeline/configs/compilation_output_config.py             8      0      0      0   100%
backends/qualcomm/genai_pipeline/configs/inference_input_config.py               12      0      0      0   100%
backends/qualcomm/genai_pipeline/configs/inference_output_config.py               9      0      0      0   100%
backends/qualcomm/genai_pipeline/configs/model_preparation_input_config.py        7      0      0      0   100%
backends/qualcomm/genai_pipeline/configs/model_preparation_output_config.py      11      0      0      0   100%
backends/qualcomm/genai_pipeline/configs/quantization_input_config.py            11      0      0      0   100%
backends/qualcomm/genai_pipeline/configs/quantization_output_config.py            5      0      0      0   100%
backends/qualcomm/genai_pipeline/engine_proxy.py                                 20      0      4      0   100%
backends/qualcomm/genai_pipeline/exceptions.py                                   18      0      4      0   100%
backends/qualcomm/genai_pipeline/pipeline_context.py                             47      0     10      0   100%
-------------------------------------------------------------------------------------------------------------------------
TOTAL                                                                           159      0     18      0   100%

[pytorch-bot]

🔗 Helpful Links

🧪 See artifacts and rendered test results at hud.pytorch.org/pr/pytorch/executorch/20409

• 📄 Preview Python docs built from this PR

Note: Links to docs will display an error until the docs builds have been completed.

❗ 1 Active SEVs

There are 1 currently active SEVs. If your PR is affected, please view them below:

• [ROCm] MI350 CI jobs will have longer queue times due to CI migration

⚠️ 11 Awaiting Approval

As of commit dbd0842 with merge base 55c54c7 ():

AWAITING APPROVAL - The following workflows need approval before CI can run:

• Build documentation (gh)
• Build Presets (gh)
• Lint (gh)
• periodic (gh)
• pull (gh)
• Test ARM Backend (gh)
• Test CoreML Backend (gh)
• Test QNN Backend (gh)
• Test Vulkan Backend (gh)
• Test WebGPU Backend (gh)
• Test XNNPACK Backend (gh)

This comment was automatically generated by Dr. CI and updates every 15 minutes.

[qti-horodnic]

@pytorchbot label "release notes: qualcomm"

[qti-horodnic]

@psiddh

This is the first pr in the GenAI framework changes. Feel free to let it sit until we discussed any comments you may have about the presentation I shared