@arizeai/phoenix-evals 0.8.0 → 0.9.0

package/src/__generated__/default_templates/TOOL_RESPONSE_HANDLING_CLASSIFICATION_EVALUATOR_CONFIG.ts

@@ -0,0 +1,88 @@
+// This file is generated. Do not edit by hand.
+
+import type { ClassificationEvaluatorConfig } from "../types";
+
+export const TOOL_RESPONSE_HANDLING_CLASSIFICATION_EVALUATOR_CONFIG: ClassificationEvaluatorConfig = {
+  name: "tool_response_handling",
+  description: "For determining if an AI agent properly handled a tool's response, including error handling, data extraction, transformation, and safe information disclosure. Requires conversation context, the tool call(s), the tool result(s), and the agent's output.",
+  optimizationDirection: "MAXIMIZE",
+  template: [
+    {
+      role: "user",
+      content: `
+You are an impartial judge evaluating an AI agent's handling of a tool's response. Your task is to determine whether the agent correctly processed the tool result to produce an appropriate output.
+
+IMPORTANT - Scope of Evaluation:
+- You are ONLY evaluating how the agent handled the tool response, NOT whether the right tool was selected or whether the tool was invoked correctly.
+- This evaluation focuses on what happens AFTER the tool returns a result.
+
+IMPORTANT - Multi-Tool Handling:
+- The agent may make MULTIPLE tool calls in a single interaction. This is valid and expected.
+- When multiple tools are called, evaluate how the agent handled ALL tool results together.
+- Return "correct" only if the agent properly handled ALL tool results.
+- Return "incorrect" if the agent mishandled ANY tool result.
+
+IMPORTANT - Error Response Handling:
+- Tool results may contain errors (rate limits, timeouts, not found, invalid arguments, etc.).
+- The agent's output may include retries, follow-up tool calls, or a final response to the user.
+- Evaluate the ENTIRE handling sequence, not just the final message.
+- Appropriate error handling includes:
+  - Retrying on transient errors (rate limits, timeouts)
+  - Correcting arguments after invalid argument errors
+  - Informing the user appropriately when errors are not recoverable
+  - NOT making repeated identical calls that continue to fail
+
+Criteria for CORRECT handling:
+- Data is extracted accurately from the tool result (no hallucination of data that wasn't returned)
+- Dates, numbers, and structured fields are properly transformed and formatted
+- Results are accurately summarized to address the user's original query
+- Error responses are handled appropriately (retries for transient errors, corrections for invalid arguments)
+- No repeated identical calls after non-retryable errors
+- No disclosure of sensitive/internal information (database credentials, internal URLs, PII, API keys, etc.)
+- The agent's response actually uses the tool result rather than ignoring it
+
+Criteria for INCORRECT handling:
+- Hallucinated data: The output includes information not present in the tool result
+- Misinterpretation: The meaning of the tool result is misrepresented or reversed
+- Improper transformation: Dates, numbers, or structured data are incorrectly converted
+- Missing retry: Failed to retry on retryable errors (rate limits, timeouts)
+- Missing correction: Failed to correct arguments after invalid argument errors
+- Futile retries: Repeated identical calls that continue to fail
+- Information disclosure: Leaked sensitive information (credentials, internal URLs, PII)
+- Ignored results: The agent's response doesn't incorporate the tool result
+- Incomplete handling: Only some tool results are used when multiple tools were called
+
+Before providing your final judgment, explain your reasoning and consider:
+- Does the output accurately reflect what the tool returned?
+- Are there any fabricated details not in the tool result?
+- Were errors handled appropriately?
+- Is sensitive information properly protected?
+- Does the output actually address the user's query using the tool data?
+
+<data>
+<input>
+{{input}}
+</input>
+
+<tool_call>
+{{toolCall}}
+</tool_call>
+
+<tool_result>
+{{toolResult}}
+</tool_result>
+
+<output>
+{{output}}
+</output>
+</data>
+
+Given the above data, did the agent handle the tool response correctly or incorrectly?
+`,
+    },
+  ],
+  choices: {
+  "correct": 1,
+  "incorrect": 0
+},
+};

package/src/__generated__/default_templates/index.ts

@@ -5,4 +5,5 @@ export { DOCUMENT_RELEVANCE_CLASSIFICATION_EVALUATOR_CONFIG } from "./DOCUMENT_R
 export { FAITHFULNESS_CLASSIFICATION_EVALUATOR_CONFIG } from "./FAITHFULNESS_CLASSIFICATION_EVALUATOR_CONFIG";
 export { HALLUCINATION_CLASSIFICATION_EVALUATOR_CONFIG } from "./HALLUCINATION_CLASSIFICATION_EVALUATOR_CONFIG";
 export { TOOL_INVOCATION_CLASSIFICATION_EVALUATOR_CONFIG } from "./TOOL_INVOCATION_CLASSIFICATION_EVALUATOR_CONFIG";
+export { TOOL_RESPONSE_HANDLING_CLASSIFICATION_EVALUATOR_CONFIG } from "./TOOL_RESPONSE_HANDLING_CLASSIFICATION_EVALUATOR_CONFIG";
 export { TOOL_SELECTION_CLASSIFICATION_EVALUATOR_CONFIG } from "./TOOL_SELECTION_CLASSIFICATION_EVALUATOR_CONFIG";

package/src/llm/createToolResponseHandlingEvaluator.ts

@@ -0,0 +1,109 @@
+import { TOOL_RESPONSE_HANDLING_CLASSIFICATION_EVALUATOR_CONFIG } from "../__generated__/default_templates";
+import { CreateClassificationEvaluatorArgs } from "../types/evals";
+
+import { ClassificationEvaluator } from "./ClassificationEvaluator";
+import { createClassificationEvaluator } from "./createClassificationEvaluator";
+
+export interface ToolResponseHandlingEvaluatorArgs<
+  RecordType extends Record<string, unknown> =
+    ToolResponseHandlingEvaluationRecord,
+> extends Omit<
+  CreateClassificationEvaluatorArgs<RecordType>,
+  "promptTemplate" | "choices" | "optimizationDirection" | "name"
+> {
+  optimizationDirection?: CreateClassificationEvaluatorArgs<RecordType>["optimizationDirection"];
+  name?: CreateClassificationEvaluatorArgs<RecordType>["name"];
+  choices?: CreateClassificationEvaluatorArgs<RecordType>["choices"];
+  promptTemplate?: CreateClassificationEvaluatorArgs<RecordType>["promptTemplate"];
+}
+
+/**
+ * A record to be evaluated by the tool response handling evaluator.
+ */
+export type ToolResponseHandlingEvaluationRecord = {
+  /**
+   * The user query or conversation context.
+   */
+  input: string;
+  /**
+   * The tool invocation(s) made by the agent, including arguments.
+   */
+  toolCall: string;
+  /**
+   * The tool's response (data, errors, or partial results).
+   */
+  toolResult: string;
+  /**
+   * The agent's handling after receiving the tool result
+   * (may include retries, follow-ups, or final response).
+   */
+  output: string;
+};
+
+/**
+ * Creates a tool response handling evaluator function.
+ *
+ * This function returns an evaluator that determines whether an AI agent properly
+ * handled a tool's response, including error handling, data extraction,
+ * transformation, and safe information disclosure.
+ *
+ * @param args - The arguments for creating the tool response handling evaluator.
+ * @param args.model - The model to use for classification.
+ * @param args.choices - The possible classification choices (defaults to correct/incorrect).
+ * @param args.promptTemplate - The prompt template to use.
+ * @param args.telemetry - The telemetry to use for the evaluator.
+ *
+ * @returns An evaluator function that takes a {@link ToolResponseHandlingEvaluationRecord}
+ * and returns a classification result indicating whether the tool response handling
+ * is correct or incorrect.
+ *
+ * @example
+ * ```ts
+ * const evaluator = createToolResponseHandlingEvaluator({ model: openai("gpt-4o-mini") });
+ *
+ * // Example: Correct extraction from tool result
+ * const result = await evaluator.evaluate({
+ *   input: "What's the weather in Seattle?",
+ *   toolCall: 'get_weather(location="Seattle")',
+ *   toolResult: JSON.stringify({
+ *     temperature: 58,
+ *     unit: "fahrenheit",
+ *     conditions: "partly cloudy"
+ *   }),
+ *   output: "The weather in Seattle is 58°F and partly cloudy."
+ * });
+ * console.log(result.label); // "correct"
+ *
+ * // Example: Hallucinated data (incorrect)
+ * const resultHallucinated = await evaluator.evaluate({
+ *   input: "What restaurants are nearby?",
+ *   toolCall: 'search_restaurants(location="downtown")',
+ *   toolResult: JSON.stringify({
+ *     results: [{ name: "Cafe Luna", rating: 4.2 }]
+ *   }),
+ *   output: "I found Cafe Luna (4.2 stars) and Mario's Italian (4.8 stars) nearby."
+ * });
+ * console.log(resultHallucinated.label); // "incorrect" - Mario's was hallucinated
+ * ```
+ */
+export function createToolResponseHandlingEvaluator<
+  RecordType extends Record<string, unknown> =
+    ToolResponseHandlingEvaluationRecord,
+>(
+  args: ToolResponseHandlingEvaluatorArgs<RecordType>
+): ClassificationEvaluator<RecordType> {
+  const {
+    choices = TOOL_RESPONSE_HANDLING_CLASSIFICATION_EVALUATOR_CONFIG.choices,
+    promptTemplate = TOOL_RESPONSE_HANDLING_CLASSIFICATION_EVALUATOR_CONFIG.template,
+    optimizationDirection = TOOL_RESPONSE_HANDLING_CLASSIFICATION_EVALUATOR_CONFIG.optimizationDirection,
+    name = TOOL_RESPONSE_HANDLING_CLASSIFICATION_EVALUATOR_CONFIG.name,
+    ...rest
+  } = args;
+  return createClassificationEvaluator<RecordType>({
+    ...rest,
+    promptTemplate,
+    choices,
+    optimizationDirection,
+    name,
+  });
+}

package/src/llm/createToolSelectionEvaluator.ts

@@ -0,0 +1,93 @@
+import { TOOL_SELECTION_CLASSIFICATION_EVALUATOR_CONFIG } from "../__generated__/default_templates";
+import { CreateClassificationEvaluatorArgs } from "../types/evals";
+
+import { ClassificationEvaluator } from "./ClassificationEvaluator";
+import { createClassificationEvaluator } from "./createClassificationEvaluator";
+
+export interface ToolSelectionEvaluatorArgs<
+  RecordType extends Record<string, unknown> = ToolSelectionEvaluationRecord,
+> extends Omit<
+  CreateClassificationEvaluatorArgs<RecordType>,
+  "promptTemplate" | "choices" | "optimizationDirection" | "name"
+> {
+  optimizationDirection?: CreateClassificationEvaluatorArgs<RecordType>["optimizationDirection"];
+  name?: CreateClassificationEvaluatorArgs<RecordType>["name"];
+  choices?: CreateClassificationEvaluatorArgs<RecordType>["choices"];
+  promptTemplate?: CreateClassificationEvaluatorArgs<RecordType>["promptTemplate"];
+}
+
+/**
+ * A record to be evaluated by the tool selection evaluator.
+ */
+export type ToolSelectionEvaluationRecord = {
+  /**
+   * The input query or conversation context.
+   */
+  input: string;
+  /**
+   * The available tools that the LLM could use.
+   */
+  availableTools: string;
+  /**
+   * The tool or tools selected by the LLM.
+   */
+  toolSelection: string;
+};
+
+/**
+ * Creates a tool selection evaluator function.
+ *
+ * This function returns an evaluator that determines whether the correct tool
+ * was selected for a given context. Unlike the tool invocation evaluator which
+ * checks if the tool was called correctly with proper arguments, this evaluator
+ * focuses on whether the right tool was chosen in the first place.
+ *
+ * The evaluator checks for:
+ * - Whether the LLM chose the best available tool for the user query
+ * - Whether the tool name exists in the available tools list
+ * - Whether the correct number of tools were selected for the task
+ * - Whether the tool selection is safe and appropriate
+ *
+ * @param args - The arguments for creating the tool selection evaluator.
+ * @param args.model - The model to use for classification.
+ * @param args.choices - The possible classification choices (defaults to correct/incorrect).
+ * @param args.promptTemplate - The prompt template to use (defaults to TOOL_SELECTION_TEMPLATE).
+ * @param args.telemetry - The telemetry to use for the evaluator.
+ *
+ * @returns An evaluator function that takes a {@link ToolSelectionEvaluationRecord} and returns
+ * a classification result indicating whether the tool selection is correct or incorrect.
+ *
+ * @example
+ * ```ts
+ * const evaluator = createToolSelectionEvaluator({ model: openai("gpt-4o-mini") });
+ *
+ * const result = await evaluator.evaluate({
+ *   input: "User: What is the weather in San Francisco?",
+ *   availableTools: `WeatherTool: Get the current weather for a location.
+ * NewsTool: Stay connected to global events with our up-to-date news around the world.
+ * MusicTool: Create playlists, search for music, and check the latest music trends.`,
+ *   toolSelection: "WeatherTool"
+ * });
+ * console.log(result.label); // "correct" or "incorrect"
+ * ```
+ */
+export function createToolSelectionEvaluator<
+  RecordType extends Record<string, unknown> = ToolSelectionEvaluationRecord,
+>(
+  args: ToolSelectionEvaluatorArgs<RecordType>
+): ClassificationEvaluator<RecordType> {
+  const {
+    choices = TOOL_SELECTION_CLASSIFICATION_EVALUATOR_CONFIG.choices,
+    promptTemplate = TOOL_SELECTION_CLASSIFICATION_EVALUATOR_CONFIG.template,
+    optimizationDirection = TOOL_SELECTION_CLASSIFICATION_EVALUATOR_CONFIG.optimizationDirection,
+    name = TOOL_SELECTION_CLASSIFICATION_EVALUATOR_CONFIG.name,
+    ...rest
+  } = args;
+  return createClassificationEvaluator<RecordType>({
+    ...rest,
+    promptTemplate,
+    choices,
+    optimizationDirection,
+    name,
+  });
+}

package/src/llm/index.ts

@@ -6,5 +6,7 @@ export * from "./createDocumentRelevanceEvaluator";
 export * from "./createFaithfulnessEvaluator";
 export * from "./createHallucinationEvaluator"; // Deprecated: use createFaithfulnessEvaluator
 export * from "./createToolInvocationEvaluator";
+export * from "./createToolResponseHandlingEvaluator";
+export * from "./createToolSelectionEvaluator";
 export * from "./generateClassification";
 export * from "./LLMEvaluator";