LLM-as-a-judge

LLM-as-a-judge is an evaluation technique in which a large language model assesses the quality of an output from another model against predefined criteria by assigning scores (e.g. overall score, correctness, relevance or completeness). It also provides reasoning for the scores.

Toor provides 2 types of LLM judges:

• binary which returns a boolean value (pass or fail) and reasoning for the decision
• scalar which returns a numeric score and reasoning for the score

Example

Let's suppose we want to test two prompts for a customer-support chat agent. The agent answers a user question:

How can I reset my password?

The first agent generated the following response:

Click "Forgot Password" on the login page, enter your email address, and follow the instructions sent to your inbox.

We run evaluation over the prompt and response. The LLM judge might return the following:

{
  "correctness": 10,
  "completeness": 9,
  "helpfulness": 10,
  "overall": 9,
  "reasoning": "Provides accurate steps and enough detail for the user to proceed."
}

The second agent replied with:

Contact support.

The LLM judge might return the following:

{
  "correctness": 6,
  "completeness": 2,
  "helpfulness": 3,
  "overall": 3,
  "reasoning": "The response may be valid in some cases but does not explain how to reset the password."
}

Binary

The binary judge is run using the function binary.

async function binary(input: BinaryInput): Promise<BinaryOutput>;

It takes an object of type BinaryInput as argument with the following properties:

• modelName: The name of the model to use for the evaluation.
• modelProvider (optional): The model provider to use for the evaluation. If not provided, the default model provider will be used. See Model provider.
• modelParameters (optional): The model parameters to use for the evaluation. See ModelParameters.
• prompt: The prompt to evaluate.
• response: The response to the prompt.
• evalPrompt (optional): The prompt to use for the evaluation. If not provided, the default prompt will be used. See Binary evalPrompt.

The function returns an object of type BinaryOutput with the following properties:

• result: The result of the evaluation, a boolean value indicating whether the answer satisfies the prompt.
• reasoning: The reasoning for the evaluation.
• usage: The LLM usage LLMUsage for the evaluation.

Example

import { binary } from '@gettoor/core';

const result = await binary({
  modelName: 'openai:gpt-4o',
  prompt: 'What is the capital of France?',
  response: 'Paris',
});

console.log(
  `   Result: ${result.result ? 'Passed' : 'Failed'}\n` +
  `Reasoning: ${result.reasoning}`
);

Binary evalPrompt

The field evalPrompt can be used to provide a custom evaluation prompt. The prompt must contain the placeholders:

• <<prompt>> replaced with the prompt to evaluate,
• <<response>> replaced with the response to the prompt.

The evaluation will fail if any of the placeholders are not provided.

const result = await binary({
  modelName: 'openai:gpt-4o',
  prompt: 'What is the capital of France?',
  response: 'Paris',
  evalPrompt: `
You are an evaluator. Does the response correctly satisfy the prompt?

Prompt:
<<prompt>>

Response:
<<response>>
`,
});

Scalar

The scalar judge is run using the function scalar.

async function scalar(input: ScalarInput): Promise<ScalarOutput>;

It takes an object of type ScalarInput as argument with the following properties:

• modelName: The name of the model to use for the evaluation.
• modelProvider (optional): The model provider to use for the evaluation. If not provided, the default model provider will be used. See Model provider.
• modelParameters (optional): The model parameters to use for the evaluation. See ModelParameters.
• prompt: The prompt to evaluate.
• response: The response to the prompt.
• scoringScale (optional): The scoring scale to use for the evaluation. If not provided, the default scoring SCALAR_SCORING_DEFAULT scale will be used. See Scales and ScalarScoringScale.
• metrics (optional): The metrics to use for the evaluation. See ScalarMetric.
• evalPrompt (optional): The prompt to use for the evaluation. If not provided, the default prompt will be used. See Scalar evalPrompt.

The function returns an object of type ScalarOutput with the following properties:

• result: The result of the evaluation, numeric scores indicating how well the response satisfies the prompt.
• reasoning: The reasoning for the evaluation.
• usage: The LLM usage LLMUsage for the evaluation.

Example

Try the response Exercise is good for you. instead of the one given below.

import { scalar, ScalarOutput } from '@gettoor/core';

const result = await scalar({
  modelName: 'openai:gpt-4o',
  prompt: 'Summarize the benefits of regular exercise.',
  response: [
    'Regular exercise improves cardiovascular health, ',
    'helps maintain a healthy weight, ',
    'strengthens muscles and bones, ',
    'improves mood, ',
    'and reduces the risk of many chronic diseases.',
  ].join(''),
});

console.log(
  `   Result: ${result.result.score}\n` +
  `Reasoning: ${result.reasoning}`
);

Scales

There are 3 predefined scoring scales (score 1 is the lowest score):

• Coarse-grained scale SCALAR_SCORING_1_3 with score range 1-3
• Likert scale SCALAR_SCORING_1_5 with score range 1-5
• Fine-grained scale SCALAR_SCORING_1_10 with score range 1-10

Custom scale

You will need to provide an object of type ScalarScoringScale to build your own scoring scale. The prompt in the field prompt is injected into the evaluation prompt as <<scoring_scale>>. The fields min and max are used to normalize the score to the range [0, 1].

See the below example for a custom scoring scale.

const scoringScale: ScalarScoringScale = {
  min: 0,
  max: 1,
  prompt: `
    0 = Incorrect or irrelevant
    1 = Correct
  `,
};

const result = await scalar({
  modelName: 'openai:gpt-4o',
  prompt: 'What is the capital of France?',
  response: 'Paris',
  scoringScale,
});

console.log(
  `   Result: ${result.result.score}\n` +
  `Reasoning: ${result.reasoning}`
);

Metrics

The field metrics can be used to provide custom metrics to use for the evaluation. The metrics must be an array of objects of type ScalarMetric.

const result = await scalar({
  modelName: 'openai:gpt-4o',
  prompt: 'Summarize the benefits of regular exercise.',
  metrics: [
    SCALAR_METRIC_CORRECTNESS,
    SCALAR_METRIC_COMPLETENESS,
    SCALAR_METRIC_RELEVANCE,
  ],
  response: 'Exercise is good for you.',
});

The result will contain the scores and reasoning for each metric in the field metrics. See MetricResult for the structure of the result.

Toor provides the following predefined metrics:

• SCALAR_METRIC_CORRECTNESS - Is the answer factually accurate?
• SCALAR_METRIC_COMPLETENESS - Does it cover everything important?
• SCALAR_METRIC_RELEVANCE - Does it address the user's request?
• SCALAR_METRIC_CLARITY - Is it easy to understand?
• SCALAR_METRIC_CONCISENESS - Is it appropriately brief without unnecessary content?
• SCALAR_METRIC_GRAMMAR - Is it free of spelling, grammar, and punctuation errors?
• SCALAR_METRIC_COHERENCE - Does it flow logically and remain internally consistent?
• SCALAR_METRIC_HELPFULNESS - Does it actually help the user accomplish their goal?
• SCALAR_METRIC_SAFETY - Does it avoid harmful or policy-violating content?
• SCALAR_METRIC_REASONING_QUALITY - Is the reasoning clear and logical?
• SCALAR_METRIC_ACTIONABILITY - Can the user act on the answer?
• SCALAR_METRIC_INSTRUCTION_FOLLOWING - Does it follow the instructions provided?

Scalar evalPrompt

The field evalPrompt can be used to provide a custom evaluation prompt. The prompt must contain the placeholders:

• <<prompt>> replaced with the prompt to evaluate,
• <<response>> replaced with the response to the prompt,
• <<scoring_scale>> replaced with the scoring scale to use for the evaluation,
• <<metrics>> replaced with the metrics to use for the evaluation.

The evaluation will fail if any of the placeholders is not provided.

const result = await scalar({
  modelName: 'openai:gpt-4o',
  prompt: 'What is the capital of France?',
  response: 'Paris',
  evalPrompt: `
You are an evaluator. Does the response correctly satisfy the prompt?

PROMPT:
<<prompt>>

RESPONSE:
<<response>>

SCORING_SCALE:
<<scoring_scale>>

METRICS:
<<metrics>>
`,
});