kiln_ai.adapters.eval.base_eval

  1import json
  2from abc import abstractmethod
  3from typing import Dict
  4
  5from kiln_ai.adapters.adapter_registry import adapter_for_task
  6from kiln_ai.adapters.ml_model_list import ModelProviderName
  7from kiln_ai.adapters.model_adapters.base_adapter import AdapterConfig
  8from kiln_ai.datamodel.eval import Eval, EvalConfig, EvalScores
  9from kiln_ai.datamodel.json_schema import validate_schema_with_value_error
 10from kiln_ai.datamodel.task import RunConfigProperties, TaskOutputRatingType, TaskRun
 11from kiln_ai.utils.exhaustive_error import raise_exhaustive_enum_error
 12
 13
 14class BaseEval:
 15    """
 16    Base class for all evals/evaluators.
 17
 18    Should be subclassed, and the run_eval method implemented.
 19    """
 20
 21    def __init__(self, eval_config: EvalConfig, run_config: RunConfigProperties | None):
 22        self.eval_config = eval_config
 23        eval = eval_config.parent_eval()
 24        if not eval:
 25            raise ValueError("Eval config must have a parent eval")
 26        self.eval = eval
 27        task = self.eval.parent_task()
 28        if not task:
 29            raise ValueError("Eval must have a parent task")
 30        self.target_task = task
 31        self.score_schema = BaseEval.build_score_schema(eval, allow_float_scores=True)
 32        self.run_config = run_config
 33
 34    def model_and_provider(self) -> tuple[str, ModelProviderName]:
 35        model_name = self.eval_config.model_name
 36        provider = self.eval_config.model_provider
 37        if (
 38            not model_name
 39            or not provider
 40            or not isinstance(model_name, str)
 41            or not isinstance(provider, str)
 42            or provider not in ModelProviderName.__members__
 43        ):
 44            raise ValueError(
 45                "Model name and provider must be set in the eval config model properties"
 46            )
 47
 48        return model_name, ModelProviderName(provider)
 49
 50    async def run_task_and_eval(
 51        self, eval_job_item: TaskRun
 52    ) -> tuple[TaskRun, EvalScores, Dict[str, str] | None]:
 53        """
 54        Runs the task on the provided run_config to generate fresh output, then runs the eval on that output.
 55        """
 56        input = eval_job_item.input
 57        if self.run_config is None:
 58            raise ValueError("Run config is required for run_task_and_eval")
 59
 60        run_adapter = adapter_for_task(
 61            self.target_task,
 62            self.run_config,
 63            base_adapter_config=AdapterConfig(allow_saving=False),
 64        )
 65
 66        # Parse structured input if needed
 67        parsed_input = input
 68        if self.target_task.input_json_schema is not None:
 69            parsed_input = json.loads(input)
 70
 71        # we don't save by default here. We'll save manually after validating the output
 72        run_output = await run_adapter.invoke(parsed_input)
 73
 74        eval_output, intermediate_outputs = await self.run_eval(
 75            run_output, eval_job_item
 76        )
 77
 78        validate_schema_with_value_error(
 79            eval_output, self.score_schema, "Eval output does not match score schema."
 80        )
 81
 82        return run_output, eval_output, intermediate_outputs
 83
 84    @abstractmethod
 85    async def run_eval(
 86        self, task_run: TaskRun, eval_job_item: TaskRun | None = None
 87    ) -> tuple[EvalScores, Dict[str, str] | None]:
 88        """
 89        Runs the eval on the given task run.
 90
 91        Returns a dictionary of scores which should conform to the score schema, and a dictionary of intermediate outputs (eval thinking).
 92        """
 93        pass
 94
 95    @classmethod
 96    def build_score_schema(cls, eval: Eval, allow_float_scores: bool = False) -> str:
 97        """
 98        Build a JSON schema for the scoring output of the task requirements
 99
100        We allow 2 modes: allow_float_scores=True and allow_float_scores=False.
101
102        allow_float_scores=False is used for the call to the model, and forces the model into selecting into discrete rating options (int 1-5, pass-fail, etc).
103        allow_float_scores=True is used for final score output (for example, after we take a g-eval weighting of the model's logprobs). A pass/fail rating might return 0.75 for likely pass (as opposed to 0.99 for near certain pass), or a 1-5 score might return 3.75.
104        """
105
106        # Note: python maintains order, which is good as we want the user defined order, and overall last
107        properties = {}
108        for output_score in eval.output_scores:
109            output_score_json_key = output_score.json_key()
110
111            if len(output_score_json_key) == 0:
112                raise ValueError(
113                    f"Invalid output score name: {output_score.name}. Can not be used as JSON schema key."
114                )
115            property: dict[str, str | int | float | list[str] | list[int]] = {
116                "title": output_score.name,
117            }
118            match output_score.type:
119                case TaskOutputRatingType.five_star:
120                    if allow_float_scores:
121                        property["type"] = "number"
122                        property["minimum"] = 1
123                        property["maximum"] = 5
124                    else:
125                        property["type"] = "integer"
126                        property["minimum"] = 1
127                        property["maximum"] = 5
128
129                    property["description"] = (
130                        f"{output_score.instruction}\n\nThe rating should be between 1 and 5, with 1 being the worst and 5 being the best."
131                    )
132                case TaskOutputRatingType.pass_fail:
133                    if allow_float_scores:
134                        property["type"] = "number"
135                        property["minimum"] = 0
136                        property["maximum"] = 1
137                        property["description"] = (
138                            f"{output_score.instruction}\n\nThe rating should be between 0 and 1, with 0 being a failure and 1 being a pass."
139                        )
140                    else:
141                        property["enum"] = ["pass", "fail"]
142                        property["type"] = "string"
143                        property["description"] = (
144                            f"{output_score.instruction}\n\nThe rating should be either 'pass' or 'fail'."
145                        )
146                case TaskOutputRatingType.pass_fail_critical:
147                    if allow_float_scores:
148                        property["type"] = "number"
149                        property["minimum"] = -1
150                        property["maximum"] = 1
151                        property["description"] = (
152                            f"{output_score.instruction}\n\nThe rating should be between -1 and 1, with 1 being a pass, 0 being a failure, and -1 being a critical failure (very severe failure)."
153                        )
154                    else:
155                        property["enum"] = ["pass", "fail", "critical"]
156                        property["type"] = "string"
157                        property["description"] = (
158                            f"{output_score.instruction}\n\nThe rating should be either 'pass', 'fail', or 'critical' where critical a very severe failure."
159                        )
160                case TaskOutputRatingType.custom:
161                    # Skip custom rating types in evals
162                    continue
163                case _:
164                    raise_exhaustive_enum_error(output_score.type)
165
166            properties[output_score_json_key] = property
167
168        schema = {
169            "type": "object",
170            "properties": properties,
171            "required": list(properties.keys()),
172        }
173        return json.dumps(schema, ensure_ascii=False)