types

types

Core data types for the optimization framework.

Classes

SearchDimension dataclass

SearchDimension(
    name: str,
    dim_type: str,
    values: List[Any] = list(),
    low: Optional[float] = None,
    high: Optional[float] = None,
    description: str = "",
    primitive: str = "",
)

One tunable dimension in the config space.

SearchSpace dataclass

SearchSpace(
    dimensions: List[SearchDimension] = list(),
    fixed: Dict[str, Any] = dict(),
    constraints: List[str] = list(),
)

The full space of configs the optimizer can propose.

Methods:

to_prompt_description

to_prompt_description() -> str

Render search space as structured text for the LLM optimizer.

Source code in src/diapason/learning/optimize/types.py

def to_prompt_description(self) -> str:
    """Render search space as structured text for the LLM optimizer."""
    lines: List[str] = []
    lines.append("# Search Space")
    lines.append("")

    # Group dimensions by primitive
    by_primitive: Dict[str, List[SearchDimension]] = {}
    for dim in self.dimensions:
        key = dim.primitive or "other"
        by_primitive.setdefault(key, []).append(dim)

    for primitive, dims in sorted(by_primitive.items()):
        lines.append(f"## {primitive.title()}")
        for dim in dims:
            lines.append(f"- **{dim.name}** ({dim.dim_type})")
            if dim.description:
                lines.append(f"  Description: {dim.description}")
            if dim.dim_type in ("categorical", "subset"):
                lines.append(f"  Options: {dim.values}")
            elif dim.dim_type in ("continuous", "integer"):
                lines.append(f"  Range: [{dim.low}, {dim.high}]")
            elif dim.dim_type == "text":
                lines.append("  Free-form text")
        lines.append("")

    if self.fixed:
        lines.append("## Fixed Parameters")
        for k, v in sorted(self.fixed.items()):
            lines.append(f"- {k} = {v}")
        lines.append("")

    if self.constraints:
        lines.append("## Constraints")
        for c in self.constraints:
            lines.append(f"- {c}")
        lines.append("")

    return "\n".join(lines)

BenchmarkScore dataclass

BenchmarkScore(
    benchmark: str,
    accuracy: float = 0.0,
    mean_latency_seconds: float = 0.0,
    total_cost_usd: float = 0.0,
    total_energy_joules: float = 0.0,
    total_tokens: int = 0,
    samples_evaluated: int = 0,
    errors: int = 0,
    weight: float = 1.0,
    summary: Optional[Any] = None,
    sample_scores: List["SampleScore"] = list(),
)

Per-benchmark metrics from a multi-benchmark evaluation trial.

SampleScore dataclass

SampleScore(
    record_id: str,
    is_correct: Optional[bool] = None,
    score: Optional[float] = None,
    latency_seconds: float = 0.0,
    prompt_tokens: int = 0,
    completion_tokens: int = 0,
    cost_usd: float = 0.0,
    error: Optional[str] = None,
    ttft: float = 0.0,
    energy_joules: float = 0.0,
    power_watts: float = 0.0,
    gpu_utilization_pct: float = 0.0,
    throughput_tok_per_sec: float = 0.0,
    mfu_pct: float = 0.0,
    mbu_pct: float = 0.0,
    ipw: float = 0.0,
    ipj: float = 0.0,
    energy_per_output_token_joules: float = 0.0,
    throughput_per_watt: float = 0.0,
    mean_itl_ms: float = 0.0,
)

Per-sample metrics from an evaluation trial.

TrialFeedback dataclass

TrialFeedback(
    summary_text: str = "",
    failure_patterns: List[str] = list(),
    primitive_ratings: Dict[str, str] = dict(),
    suggested_changes: List[str] = list(),
    target_primitive: str = "",
)

Structured feedback from trial analysis.

ObjectiveSpec dataclass

ObjectiveSpec(
    metric: str, direction: str, weight: float = 1.0
)

A single optimization objective.

TrialConfig dataclass

TrialConfig(
    trial_id: str,
    params: Dict[str, Any] = dict(),
    reasoning: str = "",
)

A single candidate configuration proposed by the optimizer.

Methods:

to_recipe

to_recipe() -> Recipe

Map params back to Recipe fields.

Source code in src/diapason/learning/optimize/types.py

def to_recipe(self) -> Recipe:
    """Map params back to Recipe fields."""
    kwargs: Dict[str, Any] = {}
    for dotted_key, value in self.params.items():
        recipe_field = _PARAM_TO_RECIPE.get(dotted_key)
        if recipe_field is not None:
            kwargs[recipe_field] = value

    return Recipe(
        name=f"trial-{self.trial_id}",
        **kwargs,
    )

TrialResult dataclass

TrialResult(
    trial_id: str,
    config: TrialConfig,
    accuracy: float = 0.0,
    mean_latency_seconds: float = 0.0,
    total_cost_usd: float = 0.0,
    total_energy_joules: float = 0.0,
    total_tokens: int = 0,
    samples_evaluated: int = 0,
    analysis: str = "",
    failure_modes: List[str] = list(),
    per_sample_feedback: List[Dict[str, Any]] = list(),
    summary: Optional[RunSummary] = None,
    sample_scores: List[SampleScore] = list(),
    structured_feedback: Optional[TrialFeedback] = None,
    per_benchmark: List[BenchmarkScore] = list(),
)

Result of evaluating a trial, with both scalar and textual feedback.

OptimizationRun dataclass

OptimizationRun(
    run_id: str,
    search_space: SearchSpace,
    trials: List[TrialResult] = list(),
    best_trial: Optional[TrialResult] = None,
    best_recipe_path: Optional[str] = None,
    status: str = "running",
    optimizer_model: str = "",
    benchmark: str = "",
    benchmarks: List[str] = list(),
    pareto_frontier: List[TrialResult] = list(),
    objectives: List[ObjectiveSpec] = (
        lambda: list(DEFAULT_OBJECTIVES)
    )(),
)

Complete optimization session.