Live Execution Engine

Relevant source files

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

• src/components/features/ExecutionWorkspace.tsx
• server.ts
• README.md
• ORIGINAL_REQUEST.md
• ABOUT.md
• src/App.tsx

The Live Execution Engine is a core module of Olive Studio designed to bridge the gap between high-level visual recipe building and the low-level execution of Microsoft Olive optimization workflows. It provides a real-time interface for triggering, monitoring, and managing local optimization jobs directly from the web application.

The engine automates environmental setup, including the creation of Python virtual environments and the installation of olive-ai and hardware-specific dependencies (such as CUDA or TensorRT packages). It utilizes Server-Sent Events (SSE) to stream live CLI output from the backend process to the frontend, ensuring that developers have immediate visibility into the optimization progress, setup logs, and potential errors.

Sources: ABOUT.md, README.md, ORIGINAL_REQUEST.md:12-23

Architecture and Data Flow

The Live Execution Engine operates through a client-server architecture where the frontend initiates execution and the backend manages the lifecycle of the Python process.

Execution Lifecycle

1. Trigger: The user clicks "Execute Live" in the ExecutionWorkspace.
2. Request: The frontend sends the generated recipe JSON to the /api/olive/run endpoint.
3. Venv Management: The backend checks for a .venv. If missing, it creates one and installs required packages, streaming this progress via SSE.
4. Process Spawn: The engine spawns a Python process running python -m olive run.
5. Streaming: Logs are captured and pushed to the client via a persistent SSE connection.
6. Completion: The process exits, and the backend sends a final done event with the exit code.

Sources: src/components/features/ExecutionWorkspace.tsx:327-375, ORIGINAL_REQUEST.md:12-23

Logical Flow Diagram

The following diagram illustrates the interaction between the UI components and the backend execution services.

The diagram shows the sequence from user trigger to live log streaming and status tracking.

Sources: src/components/features/ExecutionWorkspace.tsx:340-385, ORIGINAL_REQUEST.md:12-25

Key Backend Components

The backend implementation, primarily located in server.ts, handles job tracking and process management.

Job Tracking and API Endpoints

The engine maintains a server-side Map of active jobs to allow status queries and log streaming.

Endpoint	Method	Purpose
/api/olive/run	POST	Receives recipe JSON, initializes environment, and starts the Olive process.
/api/olive/stream/:jobId	GET	Establishes an SSE connection to stream line-by-line logs.
/api/olive/status/:jobId	GET	Returns the current state of a specific job without a persistent connection.

Sources: ORIGINAL_REQUEST.md:12-25, src/components/features/ExecutionWorkspace.tsx:340-360

Environment and Dependency Management

On the first execution, the engine performs a "Preflight" check. If python is not found on the system PATH, it returns an HTTP 503 error. Otherwise, it creates a local .venv and installs:

• olive-ai
• Hardware-specific pins (e.g., onnxruntime-gpu, nvidia-cudnn-cu12)
• TensorRT packages (if required by the recipe provider)

Sources: README.md, ORIGINAL_REQUEST.md:12-16

Frontend Integration

The ExecutionWorkspace component serves as the primary interface for the engine. It manages the local state for logs, job IDs, and execution status.

Component Logic

The handleExecuteLive function is responsible for the transition from "Idle" to "Running". It manages the EventSource object and listens for specific events:

• onmessage: Parses incoming JSON strings to append lines to the executionLogs array.
• addEventListener("done"): Captures the final exit code to update the UI status to completed or failed.

Sources: src/components/features/ExecutionWorkspace.tsx:327-385

Sequence Diagram: Live Run

This diagram visualizes the synchronous request followed by asynchronous log streaming.

Sources: src/components/features/ExecutionWorkspace.tsx:340-385, ORIGINAL_REQUEST.md:12-25

Job States and UI Indicators

The engine tracks several states to provide user feedback through various UI indicators.

State	UI Representation	Description
idle	Execute Live Button (Enabled)	System is ready for a new optimization run.
running	Spinner + "Olive running..."	Process is active; logs are being streamed to the console view.
completed	CheckCircle + "Done"	Process exited with code 0.
failed	AlertCircle + "Failed"	Process exited with non-zero code or SSE connection was lost.

Sources: src/components/features/ExecutionWorkspace.tsx:68-71, src/components/features/ExecutionWorkspace.tsx:490-505

Error Handling and Validation

Before execution, the engine checks the isRunnable property derived from recipePipeline. If the recipe is invalid or has critical compatibility issues (e.g., trying to run a GPU-only pass on a CPU provider), execution is blocked, and errors are displayed in the log window.

if (!isRunnable) {
  setExecutionLogs([
    schema.valid
      ? `[ERROR] Cannot execute: ${validation.criticalCount} blocking compatibility issue(s).`
      : `[ERROR] Cannot execute: recipe schema invalid.`,
    // ... lists specific issues
  ]);
  setExecutionStatus("failed");
  return;
}

Sources: src/components/features/ExecutionWorkspace.tsx:329-338

The Live Execution Engine ensures that users can iteratively optimize models with real-time feedback, moving from local files or Hugging Face sources to hardware-specific targets like CUDA, OpenVINO, or QNN.