kernelfoundry.algorithm.prompts.optimization_aware¶

Optimization-aware prompting that adds direct, actionable guidance for LLMs.

This module provides direct, actionable guidance for LLMs to generate high-performance GPU kernels. The prompts focus on WHAT TO DO rather than abstract taxonomy.

Design Philosophy: - Give specific, actionable instructions - Lead with concrete code patterns - Minimize classification overhead - Focus the LLM on the transformation task

Backend Support: - SYCL: Intel oneAPI DPC++ with ESIMD extensions - CUDA: NVIDIA CUDA with Tensor Cores and CUB/CUTLASS - OpenCL: Khronos OpenCL C with local memory/sub-group optimizations - Triton: OpenAI Triton (future support)

The backend parameter controls which set of optimization instructions to use. When backend is None, it defaults to SYCL for backward compatibility.

Functions

`build_exploration_prompt`(base_prompt, ...[, ...])	Build a prompt that explores underexplored optimization strategies.
`get_compute_optimization_instructions`(level)	Get compute optimization instructions for the specified backend.
`get_explicit_simd_instructions`([backend])	Get explicit SIMD/Tensor Core instructions for the specified backend.
`get_memory_optimization_instructions`(level)	Get memory optimization instructions for the specified backend.
`get_optimization_guidance_for_parent`(...[, ...])	Compute the target optimization coordinates to explore next.
`get_optimization_taxonomy_prompt`([...])	Get optimization taxonomy/instructions for the requested dimensions.
`get_parallelism_optimization_instructions`(level)	Get parallelism optimization instructions for the specified backend.
`parse_llm_full_response`(llm_output)	Parse complete structured response from LLM.
`parse_llm_optimization_response`(llm_output)	Parse optimization profile from LLM response.

Classes

`Backend`(value)	Supported GPU backends for kernel generation.
`ComputeOptLevel`(value)	An enumeration.
`EsimdOptLevel`(value)	An enumeration.
`MemoryOptLevel`(value)	An enumeration.
`OptimizationProfile`(memory_opt, compute_opt, ...)	Optimization profile for tracking kernel characteristics.
`ParallelismOptLevel`(value)	An enumeration.

class kernelfoundry.algorithm.prompts.optimization_aware.Backend(value)[source]¶

Supported GPU backends for kernel generation.

SYCL = 1¶

CUDA = 2¶

OPENCL = 3¶

TRITON = 4¶

classmethod from_string(s: str | None) → Backend[source]¶

Convert a string to Backend enum.

Parameters:: s – Backend name string (case-insensitive). None defaults to SYCL.
Returns:: Backend enum value
Raises:: ValueError – If string doesn’t match any known backend

property supports_explicit_simd: bool¶: Whether this backend supports explicit SIMD extensions (like ESIMD).

property has_tensor_cores: bool¶: Whether this backend supports tensor core operations.

property display_name: str¶: Human-readable backend name for prompts.

class kernelfoundry.algorithm.prompts.optimization_aware.OptimizationProfile(memory_opt: int, compute_opt: int, parallelism_opt: int, esimd_opt: int = 0)[source]¶

Optimization profile for tracking kernel characteristics.

memory_opt: int¶

compute_opt: int¶

parallelism_opt: int¶

esimd_opt: int = 0¶

to_dict() → Dict[str, int][source]¶

classmethod from_dict(d: Dict[str, int]) → OptimizationProfile[source]¶

property uses_esimd: bool¶

property is_high_opt: bool¶

property total_level: int¶

__init__(memory_opt: int, compute_opt: int, parallelism_opt: int, esimd_opt: int = 0) → None¶

class kernelfoundry.algorithm.prompts.optimization_aware.MemoryOptLevel(value)[source]¶

An enumeration.

NAIVE = 0¶

COALESCED = 1¶

SLM_CACHED = 2¶

MULTI_LEVEL = 3¶

class kernelfoundry.algorithm.prompts.optimization_aware.ComputeOptLevel(value)[source]¶

An enumeration.

MULTI_PASS = 0¶

FUSED = 1¶

STREAMING = 2¶

ADVANCED = 3¶

class kernelfoundry.algorithm.prompts.optimization_aware.ParallelismOptLevel(value)[source]¶

An enumeration.

THREAD_ONLY = 0¶

WORKGROUP = 1¶

SUBGROUP = 2¶

HIERARCHICAL = 3¶

class kernelfoundry.algorithm.prompts.optimization_aware.EsimdOptLevel(value)[source]¶

An enumeration.

DISABLED = 0¶

BASIC = 1¶

OPTIMIZED = 2¶

EXPERT = 3¶

kernelfoundry.algorithm.prompts.optimization_aware.build_exploration_prompt(base_prompt: str, underexplored_regions: List[Dict[str, int]], include_taxonomy: bool = True, exploration_temperature: float = 0.7, random_seed: int | None = None, include_esimd: bool = True, backend: Backend | str | None = None) → str[source]¶

Build a prompt that explores underexplored optimization strategies.

Generates concise, actionable optimization directives that integrate cleanly with the main prompt structure.

Parameters:

base_prompt – The base prompt to augment
underexplored_regions – List of optimization profiles to explore
include_taxonomy – Whether to include full taxonomy (unused, kept for compatibility)
exploration_temperature – Temperature for sampling (unused, kept for compatibility)
random_seed – Random seed for reproducibility
include_esimd – Whether to include ESIMD/Tensor Core techniques
backend – Target backend (SYCL, CUDA). Defaults to SYCL.

Returns:

Augmented prompt with exploration directives

kernelfoundry.algorithm.prompts.optimization_aware.get_optimization_taxonomy_prompt(include_antipatterns: bool = False, include_performance_hints: bool = True, dimensions: List[str] | None = None, include_esimd: bool = True, backend: Backend | str | None = None) → str[source]¶

Get optimization taxonomy/instructions for the requested dimensions.

Parameters:

include_antipatterns – Whether to include common antipatterns section
include_performance_hints – Whether to include performance hints section
dimensions – List of dimensions to include (memory, compute, parallelism, esimd/tensor_core)
include_esimd – Whether to include ESIMD/Tensor Core section (for backward compatibility)
backend – Target backend (SYCL, CUDA). Defaults to SYCL.

Returns:

Formatted optimization taxonomy prompt for the specified backend

kernelfoundry.algorithm.prompts.optimization_aware.get_optimization_guidance_for_parent(parent_profile: Dict[str, int], strategy: str = 'mutate', parent_performance: Dict[str, float] | None = None, target_dimension: str | None = None, random_seed: int | None = None, include_esimd: bool = True, backend: Backend | str | None = None) → Dict[str, int][source]¶

Compute the target optimization coordinates to explore next.

Parameters:

parent_profile – Current optimization profile of the parent kernel
strategy – Evolution strategy (mutate, intensify, diversify, specialize, balance, esimd_upgrade)
parent_performance – Performance metrics of parent kernel (unused, kept for compatibility)
target_dimension – Specific dimension to target for mutation
random_seed – Random seed for reproducibility
include_esimd – Whether to include ESIMD/Tensor Core upgrades
backend – Target backend (SYCL, CUDA). Defaults to SYCL.

Returns:

Target optimization profile coordinates

kernelfoundry.algorithm.prompts.optimization_aware.get_memory_optimization_instructions(level: int, backend: Backend | str | None = None) → str[source]¶

Get memory optimization instructions for the specified backend.

Parameters:

level – Optimization level (0-3)
backend – Target backend (SYCL, CUDA, or string). Defaults to SYCL.

Returns:

Formatted instruction string for the specified backend and level

kernelfoundry.algorithm.prompts.optimization_aware.get_compute_optimization_instructions(level: int, backend: Backend | str | None = None) → str[source]¶

Get compute optimization instructions for the specified backend.

Parameters:

level – Optimization level (0-3)
backend – Target backend (SYCL, CUDA, or string). Defaults to SYCL.

Returns:

Formatted instruction string for the specified backend and level

kernelfoundry.algorithm.prompts.optimization_aware.get_parallelism_optimization_instructions(level: int, backend: Backend | str | None = None) → str[source]¶

Get parallelism optimization instructions for the specified backend.

Parameters:

level – Optimization level (0-3)
backend – Target backend (SYCL, CUDA, or string). Defaults to SYCL.

Returns:

Formatted instruction string for the specified backend and level

kernelfoundry.algorithm.prompts.optimization_aware.get_explicit_simd_instructions(backend: Backend | str | None = None) → str[source]¶

Get explicit SIMD/Tensor Core instructions for the specified backend.

Parameters:

backend – Target backend (SYCL, CUDA, or string). Defaults to SYCL.

Returns:

SYCL: Intel ESIMD instructions
CUDA: NVIDIA Tensor Core instructions

Return type:

Formatted instruction string

kernelfoundry.algorithm.prompts.optimization_aware.parse_llm_optimization_response(llm_output: str, strict: bool = False) → Dict[str, int] | None[source]¶

Parse optimization profile from LLM response.

Looks for JSON with optimization levels.

kernelfoundry.algorithm.prompts.optimization_aware.parse_llm_full_response(llm_output: str) → Dict[source]¶: Parse complete structured response from LLM.