Recipe Builder Logic

Relevant source files

The following files were used as context for generating this wiki page:

• src/lib/recipePipeline.ts
• src/lib/oliveRecipeSchema.ts
• src/components/features/ExecutionWorkspace.tsx
• src/components/features/InputEnvironmentPanel.tsx
• src/lib/tests/recipePipeline.test.ts
• README.md

The Recipe Builder Logic serves as the core transformation engine within Olive Studio, responsible for converting high-level UI configurations into valid, executable Microsoft Olive JSON recipes. This logic ensures that optimization pipelines—consisting of model conversion, quantization, pruning, and hardware-specific transforms—adhere to the strict structural and compatibility requirements of the Olive engine.

The system operates as a "single source of truth" pipeline where user intent (expressed via the UIState) is sanitized, validated against hardware constraints, and finally serialized into a JSON artifact. This process enables local execution, batch queuing, and cross-platform export for ONNX Runtime (OWR) targets.
Sources: src/lib/recipePipeline.ts:16-24, README.md:100-110, ABOUT.md:7-15

Core Transformation Pipeline

The transformation of UI state into a runnable recipe follows a structured sequence of sanitization, building, and validation. This is primarily handled by the buildRecipeFromState function.

The pipeline first sanitizes the state to resolve immediate conflicts (e.g., ensuring conversion formats match execution providers) before generating the raw recipe object.
Sources: src/lib/recipePipeline.ts:26-38, src/lib/tests/recipePipeline.test.ts:50-55

Key Pipeline Components

Component	Description	Source File
sanitizePipelineState	Adjusts UI selections to ensure basic validity before building.	src/lib/recipePipeline.ts:30
buildOliveRecipe	Maps the internal UIState to the Olive-compliant JSON structure.	src/lib/recipePipeline.ts:31
getPipelineValidation	Assesses if the selected passes are compatible with the hardware execution provider.	src/lib/recipePipeline.ts:33
validateOliveRecipeStructure	Performs a schema check against the generated object.	src/lib/oliveRecipeSchema.ts:31

Recipe Structure and Validation

Olive recipes must follow a specific top-level schema involving input_model, systems, passes, and engine configurations. The builder logic enforces these requirements through strict type checking and structural validation.

Structural Requirements

The validateOliveRecipeStructure function checks for the following mandatory sections:

1. input_model: Defines the source (e.g., PyTorchModel) and its configuration.
2. systems: Defines the execution environments (e.g., LocalSystem) and available accelerators.
3. passes: An object where each key represents an optimization step (e.g., OnnxQuantization).
4. engine: Configures the host, target, and directory paths for execution.

Sources: src/lib/oliveRecipeSchema.ts:31-90, src/lib/tests/oliveRecipeSchema.test.ts:10-35

System and Accelerator Validation

A critical part of the builder logic is ensuring that the engine correctly references valid entries in the systems object. Each system must define a non-empty array of accelerators, each specifying a device and a list of execution_providers.

Integration with Execution and Export

The builder logic is utilized in several high-level UI workflows to provide immediate feedback and artifacts for execution.

Live Execution Flow

When a user clicks "Execute Live," the workspace invokes the builder logic to generate a temporary JSON recipe, which is then posted to the backend Olive runner.

OWR Export Logic

The builder logic is also extended to generate deployment bundles for ONNX Runtime Web/Mobile (OWR). This involves deriving platform-specific session_options (like WebGPUExecutionProvider for Web or NNAPI for Mobile) based on the optimized model's architecture and the user's performance/memory constraints.
Sources: src/components/features/ExecutionWorkspace.tsx:90-135

Batch Job Logic

For batch processing, the system uses buildOliveRecipeFromBatchJob. This function attempts to use a pre-stored recipeJson if it is valid; otherwise, it falls back to rebuilding the recipe from the current state using the job's specific model identifiers and providers.
Sources: src/lib/recipePipeline.ts:63-88, src/lib/tests/recipePipeline.test.ts:184-210

Implementation Example: Validation Assertion

export function assertRunnableRecipe(state: UIState): RecipePipelineResult {
  const pipeline = buildRecipeFromState(state);
  if (!pipeline.schema.valid) {
    throw new Error(`Recipe schema invalid:\n- ${pipeline.schema.errors.join("\n- ")}`);
  }
  if (pipeline.validation.isBlocked) {
    throw new Error(
      `Pipeline blocked: ${pipeline.validation.criticalCount} compatibility issue(s) remain after sanitization`,
    );
  }
  return pipeline;
}

Sources: src/lib/recipePipeline.ts:110-121

The Recipe Builder Logic ensures that every optimization attempt in Olive Studio is grounded in structural correctness and hardware compatibility. By centralizing the mapping from UI intent to Olive schema, the project provides a robust foundation for both novice users following curated presets and expert engineers designing custom edge-deployment pipelines.