# GenAIExecutable

- *class* qairt.gen\_ai\_api.executors.gen\_ai\_executable.GenAIExecutable

    - Bases: `ABC`

- *abstract* clean\_environment() → [GenAIExecutable](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-executors.html#qairt.gen_ai_api.executors.gen_ai_executable.GenAIExecutable)

    - Removes artifacts from target environment.

- *abstract* evaluate\_perplexity(*dataset\_path: Union[str, PathLike]*, *\**, *engine\_convert\_to\_basic: bool = False*, *engine\_role: str = 'target'*) → PerplexityResult

    - Run on-device perplexity evaluation.

- Parameters

    - - **dataset\_path** – Host-side path to a plain-text dataset file.
- **engine\_convert\_to\_basic** – Set to `True` for non-basic dialogs (e.g. Eaglet
speculative decoding) to convert the dialog to basic mode.
- **engine\_role** – Engine role — `"target"` (default) or `"draft"`.

- Returns

    - A `PerplexityResult` with
`source="device_genie"`.

- Raises

    - - **NotImplementedError** – If the runner does not support perplexity.
- **ValueError** – If `engine_role` is invalid.

- *abstract* generate(*prompt: GenerationRequest*, *\**, *generation\_config: Optional[GenerationConfig] = None*) → GenerationExecutionResult

    - Executes a generation request.

Concrete executors should return a subclass of <cite>GenerationExecutionResult</cite>
(e.g., <cite>TextGenerationResult</cite>, <cite>ImageGenerationResult</cite>).

- Parameters

    - - **prompt** – The generation request containing the input messages.
- **generation\_config** – Optional per-call generation parameters that override
the static defaults baked into the runner at
[`prepare_environment()`](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-executors.html#qairt.gen_ai_api.executors.gen_ai_executable.GenAIExecutable.prepare_environment) time.  When `None` (the default)
the runner uses its base configuration unchanged.

- Returns

    - A <cite>GenerationExecutionResult</cite> (or subclass) with the generation
output.

- *abstract* prepare\_environment() → [GenAIExecutable](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-executors.html#qairt.gen_ai_api.executors.gen_ai_executable.GenAIExecutable)

    - Prepares artifacts for execution on target.

# GenAIExecutor

Deprecated: This module has been renamed to `gen_ai_executable`.

Please update your imports:

# Old (deprecated)
    from qairt.gen_ai_api.executors.gen_ai_executor import GenAIExecutor
    
    # New
    from qairt.gen_ai_api.executors.gen_ai_executable import GenAIExecutable
    Copy to clipboard

This compatibility shim will be removed in a future release.

## T2TExecutor

- *class* qairt.gen\_ai\_api.executors.t2t\_executor.T2TExecutor(*models: List[[CompiledModel](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-core-api.html#qairt.CompiledModel)]*, *genai\_config: [GenAIConfig](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-configs.html#qairt.gen_ai_api.configs.gen_ai_config.GenAIConfig)*, *backend: [BackendType](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-api-configs.html#qairt.api.configs.common.BackendType)*, *device: Optional[[Device](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-api-configs.html#qairt.api.configs.device.Device)] = None*, *\**, *workflow: Optional[[WorkflowGraph](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-configs-workflow.html#qairt.gen_ai_api.configs.workflow.WorkflowGraph)] = None*, *containers: Optional[Dict] = None*, *backend\_extensions\_config: Optional[Dict] = None*, *engine\_config: Optional[EngineConfig] = None*, *qairt\_sdk\_root: Optional[Union[str, PathLike]] = None*, *clean\_up: bool = True*, *draft\_models: Optional[List[[CompiledModel](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-core-api.html#qairt.CompiledModel)]] = None*, *draft\_model\_backend\_extensions\_config: Optional[Dict] = None*, *draft\_gen\_ai\_config: Optional[[GenAIConfig](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-configs.html#qairt.gen_ai_api.configs.gen_ai_config.GenAIConfig)] = None*)

    - Bases: [`GenAIExecutable`](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-executors.html#qairt.gen_ai_api.executors.gen_ai_executable.GenAIExecutable)

The T2TExecutor handles text-to-text generation on target via Genie. It supports two modes of execution:

- Native: This is the default mode of execution on platforms with native python support if no device is
specified. Execution is performed via native python bindings.
- Device: This is the mode of execution when a device is specified. Execution is performed via subprocess.
See [`qairt.api.configs.device.Device`](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-api-configs.html#qairt.api.configs.device.Device) for supported device types.

The appropriate runner is selected automatically by `GenieRunnerFactory` based on the device
configuration.  Both modes are accessed through the unified `GenieRunner` interface.

- clean\_environment() → Self

    - Removes artifacts from target environment

- evaluate\_perplexity(*dataset\_path: Union[str, PathLike]*, *\**, *engine\_convert\_to\_basic: bool = False*, *engine\_role: str = 'target'*) → PerplexityResult

    - Run on-device perplexity evaluation via the runner’s Genie Accuracy API.

- *classmethod* from\_container(*container: [LLMContainer](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-containers.html#qairt.gen_ai_api.containers.llm_container.LLMContainer)*, *device: Optional[[Device](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-api-configs.html#qairt.api.configs.device.Device)] = None*, *\**, *engine\_config: Optional[EngineConfig] = None*, *backend\_extensions\_config: Optional[Dict] = None*, *qairt\_sdk\_root: Optional[Union[str, PathLike]] = None*, *clean\_up: bool = True*) → [T2TExecutor](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-executors.html#qairt.gen_ai_api.executors.t2t_executor.T2TExecutor)

    - Construct a [`T2TExecutor`](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-executors.html#qairt.gen_ai_api.executors.t2t_executor.T2TExecutor) from a single [`GenAIContainer`](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-containers.html#qairt.gen_ai_api.containers.gen_ai_container.GenAIContainer).

This is the legacy / single-container construction path.  Draft models for
eaglet speculative decoding are extracted automatically from the container’s
`speculative_run_config` when present.

- Parameters

    - - **container** – The [`GenAIContainer`](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-containers.html#qairt.gen_ai_api.containers.gen_ai_container.GenAIContainer)
holding the compiled models and GenAI configuration.
- **device** – Optional device to run on.  `None` implies native execution.
- **engine\_config** – HTP-specific execution parameters.  When `None`,
factory defaults are used.
- **backend\_extensions\_config** – Backend extensions config dict.  When `None`,
falls back to `container._backend_extensions_config`.
- **qairt\_sdk\_root** – Path to the QAIRT SDK (overrides `QAIRT_SDK_ROOT` env var).
- **clean\_up** – Remove device artifacts on exit when `True`.

- Returns

    - A configured [`T2TExecutor`](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-executors.html#qairt.gen_ai_api.executors.t2t_executor.T2TExecutor) instance.

- *classmethod* from\_workflow(*target\_container: [LLMContainer](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-containers.html#qairt.gen_ai_api.containers.llm_container.LLMContainer)*, *workflow: [WorkflowGraph](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-configs-workflow.html#qairt.gen_ai_api.configs.workflow.WorkflowGraph)*, *containers: Dict*, *device: Optional[[Device](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-api-configs.html#qairt.api.configs.device.Device)] = None*, *\**, *engine\_config: Optional[EngineConfig] = None*, *backend\_extensions\_config: Optional[Dict] = None*, *qairt\_sdk\_root: Optional[Union[str, PathLike]] = None*, *clean\_up: bool = True*) → [T2TExecutor](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-executors.html#qairt.gen_ai_api.executors.t2t_executor.T2TExecutor)

    - Construct a [`T2TExecutor`](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-executors.html#qairt.gen_ai_api.executors.t2t_executor.T2TExecutor) from a workflow topology and its associated containers.

This is the workflow construction path used by
[`WorkflowContainer`](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-containers.html#qairt.gen_ai_api.containers.workflow_container.WorkflowContainer).
The caller is responsible for resolving the TEXT\_GENERATOR node and passing
the corresponding container as *target\_container*.  Draft models for eaglet
speculative decoding are extracted automatically from *target\_container*’s
`speculative_run_config` when present.

- Parameters

    - - **target\_container** – The [`GenAIContainer`](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-containers.html#qairt.gen_ai_api.containers.gen_ai_container.GenAIContainer)
for the `TEXT_GENERATOR` node in the workflow.
- **workflow** – The full workflow graph describing the pipeline.
- **containers** – Mapping of node name → container for every node in the workflow.
- **device** – Optional device to run on.  `None` implies native execution.
- **backend\_extensions\_config** – Backend extensions config dict.  When `None`,
falls back to `target_container._backend_extensions_config`.
- **qairt\_sdk\_root** – Path to the QAIRT SDK (overrides `QAIRT_SDK_ROOT` env var).
- **clean\_up** – Remove device artifacts on exit when `True`.

- Returns

    - A configured [`T2TExecutor`](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-executors.html#qairt.gen_ai_api.executors.t2t_executor.T2TExecutor) instance.

- generate(*prompt: GenerationRequest*, *\**, *generation\_config: Optional[GenerationConfig] = None*) → TextGenerationResult

- generate(*prompt: Union[str, List[Dict[str, str]], Path]*, *\**, *lora\_config: Optional[[UseCaseRunConfig](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-modules-lora.html#qairt.modules.lora.lora_config.UseCaseRunConfig)] = None*, *generation\_config: Optional[GenerationConfig] = None*) → TextGenerationResult

    - Executes a generation request.

Concrete executors should return a subclass of <cite>GenerationExecutionResult</cite>
(e.g., <cite>TextGenerationResult</cite>, <cite>ImageGenerationResult</cite>).

- Parameters

    - - **prompt** – The generation request containing the input messages.
- **generation\_config** – Optional per-call generation parameters that override
the static defaults baked into the runner at
[`prepare_environment()`](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-executors.html#qairt.gen_ai_api.executors.t2t_executor.T2TExecutor.prepare_environment) time.  When `None` (the default)
the runner uses its base configuration unchanged.

- Returns

    - A <cite>GenerationExecutionResult</cite> (or subclass) with the generation
output.

- prepare\_environment() → Self

    - Prepares artifacts for execution on target

- stream\_generate(*prompt: Union[str, List[Dict[str, str]], Path]*, *streamer: Queue*, *\**, *generation\_config: Optional[GenerationConfig] = None*) → Task

    - Starts streaming generation and returns the task that will produce the final result.

- Parameters

    - - **prompt** (*Union* *[* *str* *,* *List* *[* *Dict* *[* *str* *,* *str* *]* *]* *,* *Path* *]*) –

    The prompt to be used for generation.
Can be one of:

    - str: A raw text string prompt
    - Path: Path to a JSON file containing chat messages
    - List[Dict[str, str]]: A list of dicts with “role” and “content” keys. Each dict should contain:

        - ”role”: The role of the message sender (e.g., “system”, “user”, “assistant”)
        - ”content”: The actual message content
- **streamer** (*asyncio.Queue*) – An asyncio queue used to stream output chunks back to the caller.

- Returns

    - A task that will eventually return TextGenerationResult.

- Return type

    - asyncio.Task

- Raises

    - **NotImplementedError** – If the active runner does not support streaming (i.e. it is not a
    `StreamableGenieRunner`).

## ImageT2TExecutor

`ImageT2TExecutor` runs image-to-text (multimodal) inference for a workflow that
pairs a vision encoder with a text generator. It is selected automatically by
[`get_executor()`](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-containers.html#qairt.gen_ai_api.containers.workflow_container.WorkflowContainer.get_executor)
for a multimodal workflow.

- *class* qairt.gen\_ai\_api.executors.image\_t2t\_executor.ImageT2TExecutor(*genai\_config: [GenAIConfig](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-configs.html#qairt.gen_ai_api.configs.gen_ai_config.GenAIConfig)*, *workflow: [WorkflowGraph](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-configs-workflow.html#qairt.gen_ai_api.configs.workflow.WorkflowGraph)*, *containers: Mapping[str, [GenAIContainerable](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-containers.html#qairt.gen_ai_api.containers.gen_ai_containerable.GenAIContainerable)]*, *backend: [BackendType](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-api-configs.html#qairt.api.configs.common.BackendType)*, *device: Optional[[Device](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-api-configs.html#qairt.api.configs.device.Device)] = None*, *backend\_extensions\_config: Optional[Dict] = None*, *engine\_config: Optional[EngineConfig] = None*, *qairt\_sdk\_root: Optional[Union[str, PathLike]] = None*, *clean\_up: bool = True*)

    - Bases: [`GenAIExecutable`](https://docs.qualcomm.com/doc/80-87189-2/topic/qairt-gen-ai-api-executors.html#qairt.gen_ai_api.executors.gen_ai_executable.GenAIExecutable)

Handles Large Multimodal Model execution on target via Genie pipeline using Genie App.

Supports both text and vision inputs and coordinates their processing.

- clean\_environment() → Self

    - Removes artifacts from target environment.

- Returns

    - The executor instance.

- Return type

    - Self

- evaluate\_perplexity(*dataset\_path: Union[str, PathLike]*, *\**, *engine\_convert\_to\_basic: bool = False*, *engine\_role: str = 'target'*) → PerplexityResult

    - Not yet implemented for multimodal models.

Multimodal perplexity requires pipeline-node-based accuracy
(`accuracy create ... node`), which is not yet wired.

- Raises

    - **NotImplementedError** – Always.

- generate(*prompt: GenerationRequest*, *\**, *generation\_config: Optional[GenerationConfig] = None*) → GenerationExecutionResult

    - Generates a response from text and image inputs.

The formatted prompt is split into its semantic parts so that the Genie
pipeline receives inputs in the correct order, matching the structure:

<|im_start|>system\n{system}\n<|im_end|>\n          → text encoder (system turn)
    <|im_start|>user\n<|vision_start|>                    → text encoder (user pre-image)
    {image}                                                 → image encoder
    <|vision_end|>\n{user_text}<|im_end|>\n              → text encoder (user post-image)
    <|im_start|>assistant\n                               → text encoder (assistant turn)
    Copy to clipboard

The vision boundary token IDs are read from the image-encoder container’s
`VisionEncoderConfig`
and decoded to strings using the tokenizer.

- Parameters

    - **prompt** – Generation request whose `messages` field may contain
text-only or multimodal (text + image) content. Image paths
are extracted from content parts with `{"type": "image"}`.

- Returns

    - Result containing the generated text and execution metadata.

- prepare\_environment() → Self

    - Prepares artifacts for Genie App execution on target.

Writes the backend extensions config to a temporary directory, then delegates
pipeline-config construction and runner creation to
`GenieRunnerFactory`.

- Returns

    - The executor instance.

- Return type

    - Self

Last Published: Aug 19, 2026

[Previous Topic
GenAIContainerable.save()](https://docs.qualcomm.com/bundle/publicresource/80-87189-2/topics/qairt-gen-ai-api-containers.md)