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, input: str
 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        if self.run_config is None:
 57            raise ValueError("Run config is required for run_task_and_eval")
 58
 59        run_adapter = adapter_for_task(
 60            self.target_task,
 61            self.run_config,
 62            base_adapter_config=AdapterConfig(allow_saving=False),
 63        )
 64
 65        # Parse structured input if needed
 66        parsed_input = input
 67        if self.target_task.input_json_schema is not None:
 68            parsed_input = json.loads(input)
 69
 70        # we don't save by default here. We'll save manually after validating the output
 71        run_output = await run_adapter.invoke(parsed_input)
 72
 73        eval_output, intermediate_outputs = await self.run_eval(run_output)
 74
 75        validate_schema_with_value_error(
 76            eval_output, self.score_schema, "Eval output does not match score schema."
 77        )
 78
 79        return run_output, eval_output, intermediate_outputs
 80
 81    @abstractmethod
 82    async def run_eval(
 83        self, task_run: TaskRun
 84    ) -> tuple[EvalScores, Dict[str, str] | None]:
 85        """
 86        Runs the eval on the given task run.
 87
 88        Returns a dictionary of scores which should conform to the score schema, and a dictionary of intermediate outputs (eval thinking).
 89        """
 90        pass
 91
 92    @classmethod
 93    def build_score_schema(cls, eval: Eval, allow_float_scores: bool = False) -> str:
 94        """
 95        Build a JSON schema for the scoring output of the task requirements
 96
 97        We allow 2 modes: allow_float_scores=True and allow_float_scores=False.
 98
 99        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).
100        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.
101        """
102
103        # Note: python maintains order, which is good as we want the user defined order, and overall last
104        properties = {}
105        for output_score in eval.output_scores:
106            output_score_json_key = output_score.json_key()
107
108            if len(output_score_json_key) == 0:
109                raise ValueError(
110                    f"Invalid output score name: {output_score.name}. Can not be used as JSON schema key."
111                )
112            property: dict[str, str | int | float | list[str] | list[int]] = {
113                "title": output_score.name,
114            }
115            match output_score.type:
116                case TaskOutputRatingType.five_star:
117                    if allow_float_scores:
118                        property["type"] = "number"
119                        property["minimum"] = 1
120                        property["maximum"] = 5
121                    else:
122                        property["type"] = "integer"
123                        property["minimum"] = 1
124                        property["maximum"] = 5
125
126                    property["description"] = (
127                        f"{output_score.instruction}\n\nThe rating should be between 1 and 5, with 1 being the worst and 5 being the best."
128                    )
129                case TaskOutputRatingType.pass_fail:
130                    if allow_float_scores:
131                        property["type"] = "number"
132                        property["minimum"] = 0
133                        property["maximum"] = 1
134                        property["description"] = (
135                            f"{output_score.instruction}\n\nThe rating should be between 0 and 1, with 0 being a failure and 1 being a pass."
136                        )
137                    else:
138                        property["enum"] = ["pass", "fail"]
139                        property["type"] = "string"
140                        property["description"] = (
141                            f"{output_score.instruction}\n\nThe rating should be either 'pass' or 'fail'."
142                        )
143                case TaskOutputRatingType.pass_fail_critical:
144                    if allow_float_scores:
145                        property["type"] = "number"
146                        property["minimum"] = -1
147                        property["maximum"] = 1
148                        property["description"] = (
149                            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)."
150                        )
151                    else:
152                        property["enum"] = ["pass", "fail", "critical"]
153                        property["type"] = "string"
154                        property["description"] = (
155                            f"{output_score.instruction}\n\nThe rating should be either 'pass', 'fail', or 'critical' where critical a very severe failure."
156                        )
157                case TaskOutputRatingType.custom:
158                    # Skip custom rating types in evals
159                    continue
160                case _:
161                    raise_exhaustive_enum_error(output_score.type)
162
163            properties[output_score_json_key] = property
164
165        schema = {
166            "type": "object",
167            "properties": properties,
168            "required": list(properties.keys()),
169        }
170        return json.dumps(schema, ensure_ascii=False)