kernelfoundry.algorithm.schemas

Interfaces and schemas for kernel Program objects and evaluation results.

Classes

CompilationResult(idx, binary, ...[, error, ...])	Results from compiling a kernel.
EvalResult(*[, compiled, correctness, ...])	Results from evaluating a single kernel.
Program(id, code, is_program0, raw_llm_code, ...)	Represents a kernel program candidate in the optimization database.

class kernelfoundry.algorithm.schemas.EvalResult(*, compiled: bool = False, correctness: bool = False, metadata: dict = {}, runtime: float = -1.0, runtime_stats: dict = {}, runtime_improvement: float = -1.0, improve_over_compile: float = -1.0, perf_score: int = -1, profiler_data: dict = {}, template_results: dict = {}, eval_log: str = '')

Results from evaluating a single kernel.

This class stores comprehensive evaluation metrics for a kernel execution, including compilation status, correctness results, performance data, and profiling information. It also provides unified performance scoring and status reporting.

compiled: bool

correctness: bool

metadata: dict

runtime: float

runtime_stats: dict

runtime_improvement: float

improve_over_compile: float

perf_score: int

profiler_data: dict

template_results: dict

eval_log: str

static compute_performance_score(eval_result: EvalResult) → float

Compute unified performance score for a kernel evaluation result.

This is the single source of truth for performance scoring, used consistently across: - MAP-Elites elite selection (combined_score in metrics) - Best kernel selection for next iteration - Prompt evolution fitness tracking

Fitness calculation:

• Base: perf_score (0-5, discrete quality indicator)

• If runtime_improvement > 0: add actual speedup (when test_reference=True)

• Else if runtime_improvement == -1 (test_reference=False) and kernel is correct: add 1/runtime to prefer faster kernels

Parameters:

eval_result – EvalResult object with perf_score, runtime_improvement, correctness, runtime

Returns:

Composite performance score (higher is better)

Return type:

float

static get_eval_status(compiled: bool, correctness: bool, for_prompt=False) → str

Convert correctness and compilation variables into a string status variable

get_status()

format_for_prompt()

to_dict()

Convert exec result to dictionary

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class kernelfoundry.algorithm.schemas.Program(id: str, code: str, is_program0: bool = False, raw_llm_code: str | None = None, language: str = 'python', parent_id: str | None = None, generation: int = 0, timestamp: float = <factory>, iteration_found: int = 0, metrics: ~typing.Dict[str, float] = <factory>, complexity: float = 0.0, diversity: float = 0.0, is_templated: bool = False, template_parameter_combinations: list | None = None, metadata: ~typing.Dict[str, ~typing.Any] = <factory>, kernel_exec_result: ~kernelfoundry.algorithm.schemas.EvalResult | None = None, feedback: str | None = None, task: ~kernelfoundry.eval_pipeline.task.Task | None = None)

Represents a kernel program candidate in the optimization database.

This class encapsulates a kernel implementation along with its metadata, evaluation results, and evolutionary history. Programs are the core units tracked through the kernel optimization pipeline.

id: str

code: str

is_program0: bool = False

raw_llm_code: str | None = None

language: str = 'python'

parent_id: str | None = None

generation: int = 0

timestamp: float

iteration_found: int = 0

metrics: Dict[str, float]

complexity: float = 0.0

diversity: float = 0.0

is_templated: bool = False

template_parameter_combinations: list = None

metadata: Dict[str, Any]

kernel_exec_result: EvalResult = None

feedback: str = None

task: Task | None = None

to_dict() → Dict[str, Any]

Convert to dictionary representation

get_artifact() → str

Get artifact from here or EvalResult

add_eval_results(exec_result: EvalResult, artifact_path: str | None = None, artifact_str: str | None = None)

Add evaluation results to the program

static populate_kernel_from_exec_result(kernel: Kernel, exec_result: EvalResult)

update_Kernel(kernel: Kernel)

Populate a Kernel database object from this Program

classmethod from_dict(data: Dict[str, Any]) → Program

Create from dictionary representation

__init__(id: str, code: str, is_program0: bool = False, raw_llm_code: str | None = None, language: str = 'python', parent_id: str | None = None, generation: int = 0, timestamp: float = <factory>, iteration_found: int = 0, metrics: ~typing.Dict[str, float] = <factory>, complexity: float = 0.0, diversity: float = 0.0, is_templated: bool = False, template_parameter_combinations: list | None = None, metadata: ~typing.Dict[str, ~typing.Any] = <factory>, kernel_exec_result: ~kernelfoundry.algorithm.schemas.EvalResult | None = None, feedback: str | None = None, task: ~kernelfoundry.eval_pipeline.task.Task | None = None) → None

class kernelfoundry.algorithm.schemas.CompilationResult(idx: int, binary: object | None, kernel_exec_result: object | None, compile_success: bool, error: str | None = None, worker_info: dict | None = None)

Results from compiling a kernel.

idx: int

binary: object | None

kernel_exec_result: object | None

compile_success: bool

error: str | None = None

__init__(idx: int, binary: object | None, kernel_exec_result: object | None, compile_success: bool, error: str | None = None, worker_info: dict | None = None) → None

worker_info: dict | None = None