> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baserun.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Automatic Evaluators

Automatic evaluators can be rule-based or graded by large language models (LLMs), and they can programmatically run on LLM input or output.
Baserun offers a number of pre-built automatic evaluators (see below), as well as the ability to perform custom evals with your own prompt or your own function.

### Complete Reference

<Tabs>
  <Tab title="Python">
    <AccordionGroup>
      <Accordion title="match(name: str, submission: str, expected: Union[str, List[str]]) -> bool">
        Checks if the `submission` starts with any of the `expected` values.

        Returns `true` if the `submission` starts with any of the `expected` values, otherwise `false`.

        <ParamField path="name" type="str">
          Name of the evaluation.
        </ParamField>

        <ParamField path="submission" type="str">
          The input string.
        </ParamField>

        <ParamField path="expected" type="Union[str, List[str]]">
          A string or a list of strings to check against.
        </ParamField>
      </Accordion>

      <Accordion title="includes(name: str, submission: str, expected: Union[str, List[str]]) -> bool">
        Checks if the `submission` contains any of the `expected` values within it.

        Returns `true` if the `submission` includes any of the `expected` values, otherwise `false`.

        <ParamField path="name" type="str">
          Name of the evaluation.
        </ParamField>

        <ParamField path="submission" type="str">
          The input string.
        </ParamField>

        <ParamField path="expected" type="Union[str, List[str]]">
          A string or a list of strings to check against.
        </ParamField>
      </Accordion>

      <Accordion title="fuzzy_match(name: str, submission: str, expected: Union[str, List[str]]) -> bool">
        Checks if the `submission` contains any of the `expected` values or if any of the `expected` values contain the `submission`.

        Returns `true` if there's a fuzzy match, otherwise `false`.

        <ParamField path="name" type="str">
          Name of the evaluation.
        </ParamField>

        <ParamField path="submission" type="str">
          The input string.
        </ParamField>

        <ParamField path="expected" type="Union[str, List[str]]">
          A string or a list of strings to check against.
        </ParamField>
      </Accordion>

      <Accordion title="not_match(name: str, submission: str, expected: Union[str, List[str]]) -> bool">
        Checks if the `submission` does not start with any of the `expected` values.

        Returns `true` if the `submission` does not start with any of the `expected` values, otherwise `false`.

        <ParamField path="name" type="str">
          Name of the evaluation.
        </ParamField>

        <ParamField path="submission" type="str">
          The input string.
        </ParamField>

        <ParamField path="expected" type="Union[str, List[str]]">
          A string or a list of strings to check against.
        </ParamField>
      </Accordion>

      <Accordion title="not_includes(name: str, submission: str, expected: Union[str, List[str]]) -> bool">
        Checks if the `submission` does not contain any of the `expected` values.

        Returns `true` if the `submission` does not include any of the `expected` values, otherwise `false`.

        <ParamField path="name" type="str">
          Name of the evaluation.
        </ParamField>

        <ParamField path="submission" type="str">
          The input string.
        </ParamField>

        <ParamField path="expected" type="Union[str, List[str]]">
          A string or a list of strings to check against.
        </ParamField>
      </Accordion>

      <Accordion title="not_fuzzy_match(name: str, submission: str, expected: Union[str, List[str]]) -> bool">
        Checks if the `submission` neither contains any of the `expected` values nor is contained by any of the `expected` values.

        Returns `true` if there's no fuzzy match, otherwise `false`.

        <ParamField path="name" type="str">
          Name of the evaluation.
        </ParamField>

        <ParamField path="submission" type="str">
          The input string.
        </ParamField>

        <ParamField path="expected" type="Union[str, List[str]]">
          A string or a list of strings to check against.
        </ParamField>
      </Accordion>

      <Accordion title="valid_json(name: str, submission: str) -> bool">
        Checks if the `submission` is a valid JSON string.

        Returns `true` if the `submission` is a valid JSON string, otherwise `false`.

        <ParamField path="name" type="str">
          Name of the evaluation.
        </ParamField>

        <ParamField path="submission" type="str">
          The input string.
        </ParamField>
      </Accordion>

      <Accordion title="check_injection(name: str, submission: str) -> bool">
        Checks if the `submission` includes injection.

        Returns `true` if the `submission` includes injection, otherwise `false`.

        <ParamField path="name" type="str">
          Name of the evaluation.
        </ParamField>

        <ParamField path="submission" type="str">
          The input string.
        </ParamField>
      </Accordion>

      <Accordion title="custom(name: str, submission: str, fn: Callable[[str], bool]) -> bool">
        Checks the `submission` using a custom function.

        Returns the result of the custom function.

        <ParamField path="name" type="str">
          Name of the evaluation.
        </ParamField>

        <ParamField path="submission" type="str">
          The input string.
        </ParamField>

        <ParamField path="fn" type="Callable[[str], bool]">
          A custom function that takes the `submission` and returns a boolean.
        </ParamField>
      </Accordion>

      <Accordion title="custom_async(name: str, submission: str, fn: Callable[[str], Awaitable[bool]]) -> bool">
        Checks the `submission` using an asynchronous custom function.

        Returns the result of the custom function.

        <ParamField path="name" type="str">
          Name of the evaluation.
        </ParamField>

        <ParamField path="submission" type="str">
          The input string.
        </ParamField>

        <ParamField path="fn" type="Callable[[str], Awaitable[bool]]">
          A custom function that takes the `submission` and returns a promise that resolves to a boolean.
        </ParamField>
      </Accordion>

      <Accordion title="model_graded_custom(name: str, prompt: str, choices: dict[str, float], model: str, metadata: Optional[Dict[str, Any]], **variables) -> str">
        Evaluates the model's response based on a prompt and a set of choices.

        Returns the choice given by the model.

        Example:

        <CodeGroup>
          ```python python theme={null}
          result = Baserun.evals.model_graded_custom(
              name="Truthiness",
              prompt="How true is this statement? {statement}.",
              choices={"True": 1, "Somewhat true": 0.5, "Not true": 0},
              statement=statement,
          )
          ```
        </CodeGroup>

        <ParamField path="name" type="str">
          Name of the evaluation.
        </ParamField>

        <ParamField path="prompt" type="str">
          The prompt passed to the model.
        </ParamField>

        <ParamField path="choices" type="dict[str, float]">
          A dictionary of choices and their scores.
        </ParamField>

        <ParamField path="model" type="str" default="gpt-4-0125-preview">
          OpenAI model that you want to use for the evaluation.
        </ParamField>

        <ParamField path="metadata" type="Optional[dict[str, Any]]" default="None">
          Any metadata that might be useful for you.
        </ParamField>

        <ParamField path="variables" type="dict[str, str]">
          Variables that will be substituted in the formatted prompt.
        </ParamField>
      </Accordion>

      <Accordion title="model_graded_fact(name: str, question: str, expert: str, submission: str) -> str">
        Checks a submitted answer against an expert answer for factual consistency using gpt-4-0613.

        Returns one of:

        * "A": The output is a subset of the expert answer and fully consistent with it.
        * "B": The output is a superset of the expert answer and fully consistent with it.
        * "C": The submitted answer contains all of the same details as the expert answer.
        * "D": There is disagreement between the submitted answer and the expert answer.
        * "E": The answers differ, but these differences don't matter from the perspective of factuality.

        <ParamField path="name" type="str">
          Name of the evaluation.
        </ParamField>

        <ParamField path="question" type="str">
          The question.
        </ParamField>

        <ParamField path="expert" type="str">
          The expert answer.
        </ParamField>

        <ParamField path="submission" type="str">
          The submitted answer.
        </ParamField>
      </Accordion>

      <Accordion title="model_graded_closed_qa(name: str, task: str, submission: str, criterion: str) -> str">
        Checks a submitted answer based on a specific criterion for relevance, conciseness, and correctness using gpt-4-0613.

        Returns "Yes" if the submission meets the criteria, "No" if it does not, and "Unsure" if it cannot be determined.

        <ParamField path="name" type="str">
          Name of the evaluation.
        </ParamField>

        <ParamField path="task" type="str">
          The task.
        </ParamField>

        <ParamField path="submission" type="str">
          The submitted answer.
        </ParamField>

        <ParamField path="criterion" type="str">
          The criterion.
        </ParamField>
      </Accordion>

      <Accordion title="model_graded_security(name: str, submission: str) -> str">
        Checks the submitted string for potential malicious content using gpt-4-0613.

        Returns "Yes" if the submission is malicious, "No" if it is not malicious, and "Unsure" if it cannot be determined.

        <ParamField path="name" type="str">
          Name of the evaluation.
        </ParamField>

        <ParamField path="submission" type="str">
          The input string.
        </ParamField>
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Typescript">
    <AccordionGroup>
      <Accordion title="equals(name: string, submission: string, expected: string | string[]): boolean">
        Checks if the `submission` equals `expected`.

        Returns `true` if the `submission` equals `expected` value, otherwise `false`.

        <ParamField path="name" type="string">
          Name of the evaluation.
        </ParamField>

        <ParamField path="submission" type="string">
          The input string.
        </ParamField>

        <ParamField path="expected" type="string | string[]">
          A string to check against.
        </ParamField>
      </Accordion>

      <Accordion title="eq(name: string, submission: string, expected: string | string[]): boolean">
        Short version of `equals`.
      </Accordion>

      <Accordion title="match(name: string, submission: string, expected: string | string[]): boolean">
        Checks if the `submission` starts with any of the `expected` values.

        Returns `true` if the `submission` starts with any of the `expected` values, otherwise `false`.

        <ParamField path="name" type="string">
          Name of the evaluation.
        </ParamField>

        <ParamField path="submission" type="string">
          The input string.
        </ParamField>

        <ParamField path="expected" type="string | string[]">
          A string or an array of strings to check against.
        </ParamField>
      </Accordion>

      <Accordion title="includes(name: string, submission: string, expected: string | string[]): boolean">
        Checks if the `submission` contains any of the `expected` values within it.

        Returns `true` if the `submission` includes any of the `expected` values, otherwise `false`.

        <ParamField path="name" type="string">
          Name of the evaluation.
        </ParamField>

        <ParamField path="submission" type="string">
          The input string.
        </ParamField>

        <ParamField path="expected" type="string | string[]">
          A string or an array of strings to check against.
        </ParamField>
      </Accordion>

      <Accordion title="fuzzyMatch(name: string, submission: string, expected: string | string[]): boolean">
        Checks if the `submission` contains any of the `expected` values or if any of the `expected` values contain the `submission`.

        Returns `true` if there's a fuzzy match, otherwise `false`.

        <ParamField path="name" type="string">
          Name of the evaluation.
        </ParamField>

        <ParamField path="submission" type="string">
          The input string.
        </ParamField>

        <ParamField path="expected" type="string | string[]">
          A string or an array of strings to check against.
        </ParamField>
      </Accordion>

      <Accordion title="notMatch(name: string, submission: string, expected: string | string[]): boolean">
        Checks if the `submission` does not start with any of the `expected` values.

        Returns `true` if the `submission` does not start with any of the `expected` values, otherwise `false`.

        <ParamField path="name" type="string">
          Name of the evaluation.
        </ParamField>

        <ParamField path="submission" type="string">
          The input string.
        </ParamField>

        <ParamField path="expected" type="string | string[]">
          A string or an array of strings to check against.
        </ParamField>
      </Accordion>

      <Accordion title="notIncludes(name: string, submission: string, expected: string | string[]): boolean">
        Checks if the `submission` does not contain any of the `expected` values.

        Returns `true` if the `submission` does not include any of the `expected` values, otherwise `false`.

        <ParamField path="name" type="string">
          Name of the evaluation.
        </ParamField>

        <ParamField path="submission" type="string">
          The input string.
        </ParamField>

        <ParamField path="expected" type="string | string[]">
          A string or an array of strings to check against.
        </ParamField>
      </Accordion>

      <Accordion title="notFuzzyMatch(name: string, submission: string, expected: string | string[]): boolean">
        Checks if the `submission` neither contains any of the `expected` values nor is contained by any of the `expected` values.

        Returns `true` if there's no fuzzy match, otherwise `false`.

        <ParamField path="name" type="string">
          Name of the evaluation.
        </ParamField>

        <ParamField path="submission" type="string">
          The input string.
        </ParamField>

        <ParamField path="expected" type="string | string[]">
          A string or an array of strings to check against.
        </ParamField>
      </Accordion>

      <Accordion title="validJson(name: string, submission: string): boolean">
        Checks if the `submission` is a valid JSON string.

        Returns `true` if the `submission` is a valid JSON string, otherwise `false`.

        <ParamField path="name" type="string">
          Name of the evaluation.
        </ParamField>

        <ParamField path="submission" type="string">
          The input string.
        </ParamField>
      </Accordion>

      <Accordion title="custom(name: string, submission: string, fn: (submission: string) => boolean): boolean">
        Checks the `submission` using a custom function.

        Returns the result of the custom function.

        <ParamField path="name" type="string">
          Name of the evaluation.
        </ParamField>

        <ParamField path="submission" type="string">
          The input string.
        </ParamField>

        <ParamField path="fn" type="(submission: string) => boolean">
          A custom function that takes the `submission` and returns a boolean.
        </ParamField>
      </Accordion>

      <Accordion title="customAsync(name: string, submission: string, fn: (submission: string) => Promise<boolean>): Promise<boolean>">
        Checks the `submission` using an asynchronous custom function.

        Returns the result of the custom function.

        <ParamField path="name" type="string">
          Name of the evaluation.
        </ParamField>

        <ParamField path="submission" type="string">
          The input string.
        </ParamField>

        <ParamField path="fn" type="(submission: string) => Promise<boolean>">
          A custom function that takes the `submission` and returns a promise that resolves to a boolean.
        </ParamField>
      </Accordion>

      <Accordion title="modelGradedCustom(name: str, prompt: string, choices: Record<string, number>, model: string = 'gpt-4-0125-preview', metadata?: Record<string, any>): Promise<string>">
        Evaluates the model's response based on a prompt and a set of choices.

        Returns the choice given by the model.

        Example:

        <CodeGroup>
          ```typescript typescript theme={null}
          const result = await baserun.evals.modelGradedCustom(
              "Truthiness",
              `How true is this statement? ${statement}.`,
              {"True": 1, "Somewhat true": 0.5, "Not true": 0},
          )
          ```
        </CodeGroup>

        <ParamField path="name" type="string">
          Name of the evaluation.
        </ParamField>

        <ParamField path="prompt" type="string">
          The prompt passed to the model.
        </ParamField>

        <ParamField path="choices" type="Record<string, number>">
          A dictionary of choices and their scores.
        </ParamField>

        <ParamField path="model" type="string" default="gpt-4-0125-preview">
          OpenAI model that you want to use for the evaluation.
        </ParamField>

        <ParamField path="metadata" type="Record<string, any>">
          Any metadata that might be useful for you.
        </ParamField>
      </Accordion>

      <Accordion title="modelGradedFact(name: string, question: string, expert: string, submission: string): Promise<string>">
        Checks a submitted answer against an expert answer for factual consistency using gpt-4-0613.

        Returns one of:

        * "A": The output is a subset of the expert answer and fully consistent with it.
        * "B": The output is a superset of the expert answer and fully consistent with it.
        * "C": The submitted answer contains all of the same details as the expert answer.
        * "D": There is disagreement between the submitted answer and the expert answer.
        * "E": The answers differ, but these differences don't matter from the perspective of factuality.

        <ParamField path="name" type="string">
          Name of the evaluation.
        </ParamField>

        <ParamField path="question" type="string">
          The question.
        </ParamField>

        <ParamField path="expert" type="string">
          The expert answer.
        </ParamField>

        <ParamField path="submission" type="string">
          The submitted answer.
        </ParamField>
      </Accordion>

      <Accordion title="modelGradedClosedQA(name: string, task: string, submission: string, criterion: string): Promise<string>">
        Checks a submitted answer based on a specific criterion for relevance, conciseness, and correctness using gpt-4-0613.

        Returns "Yes" if the submission is malicious, "No" if it is not malicious, and "Unsure" if it cannot be determined.

        <ParamField path="name" type="string">
          Name of the evaluation.
        </ParamField>

        <ParamField path="task" type="string">
          The task.
        </ParamField>

        <ParamField path="submission" type="string">
          The submitted answer.
        </ParamField>

        <ParamField path="criterion" type="string">
          The criterion.
        </ParamField>
      </Accordion>

      <Accordion title="modelGradedSecurity(name: string, submission: string): Promise<string>">
        Checks the submitted string for potential malicious content using gpt-4-0613.

        Returns "Yes" if the submission is malicious, "No" if it is not malicious, and "Unsure" if it cannot be determined.

        <ParamField path="name" type="string">
          Name of the evaluation.
        </ParamField>

        <ParamField path="submission" type="string">
          The input string.
        </ParamField>
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>
