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, list[str]] =, is_program0, ...)	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 = '')[source]#

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[source]#

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[source]#: Convert correctness and compilation variables into a string status variable

get_status()[source]#

format_for_prompt()[source]#

to_dict()[source]#: 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: dict[str, list[str]] = <factory>, 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)[source]#

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: dict[str, list[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#

property code_as_str: str#: Flattened string of all code blocks, for use in prompts, regex, and DB storage.

to_dict() → Dict[str, Any][source]#: Convert to dictionary representation

get_artifact() → str[source]#: Get artifact from here or EvalResult

add_eval_results(exec_result: EvalResult, artifact_path: str | None = None, artifact_str: str | None = None)[source]#: Add evaluation results to the program

static populate_kernel_from_exec_result(kernel: Kernel, exec_result: EvalResult)[source]#

update_Kernel(kernel: Kernel)[source]#: Populate a Kernel database object from this Program

classmethod from_dict(data: Dict[str, Any]) → Program[source]#: Create from dictionary representation

__init__(id: str, code: dict[str, list[str]] = <factory>, 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)[source]#

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#