@arizeai/phoenix-evals 0.6.1 → 0.6.5

package/README.md

@@ -19,6 +19,7 @@
     <a href="https://arize-ai.github.io/phoenix/">
         <img src="https://img.shields.io/badge/docs-blue?logo=typescript&logoColor=white" alt="Documentation">
     </a>
+    <img referrerpolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=8e8e8b34-7900-43fa-a38f-1f070bd48c64&page=js/packages/phoenix-evals/README.md" />
 </p>
 
 This package provides a TypeScript evaluation library. It is vendor agnostic and can be used in isolation of any framework or platform. This package is still under active development and is subject to change.

package/dist/esm/core/FunctionEvaluator.d.ts

@@ -0,0 +1,16 @@
+import { CreateEvaluatorArgs, EvaluationResult, ObjectMapping } from "../types/index.js";
+import { EvaluatorBase } from "./EvaluatorBase.js";
+type FunctionEvaluatorArgs<RecordType extends Record<string, unknown>> = CreateEvaluatorArgs<RecordType> & {
+    evaluateFn: (args: RecordType) => Promise<EvaluationResult>;
+};
+/**
+ * A class that constructs an evaluator based on an evaluate function.
+ */
+export declare class FunctionEvaluator<RecordType extends Record<string, unknown>> extends EvaluatorBase<RecordType> {
+    readonly evaluateFn: (args: RecordType) => Promise<EvaluationResult>;
+    constructor({ evaluateFn, ...args }: FunctionEvaluatorArgs<RecordType>);
+    evaluate(args: RecordType): Promise<EvaluationResult>;
+    bindInputMapping(inputMapping: ObjectMapping<RecordType>): FunctionEvaluator<RecordType>;
+}
+export {};
+//# sourceMappingURL=FunctionEvaluator.d.ts.map

package/dist/esm/core/FunctionEvaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FunctionEvaluator.d.ts","sourceRoot":"","sources":["../../../src/core/FunctionEvaluator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEhF,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD,KAAK,qBAAqB,CAAC,UAAU,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IACnE,mBAAmB,CAAC,UAAU,CAAC,GAAG;IAChC,UAAU,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAC7D,CAAC;AACJ;;GAEG;AACH,qBAAa,iBAAiB,CAC5B,UAAU,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAC1C,SAAQ,aAAa,CAAC,UAAU,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;gBACzD,EAAE,UAAU,EAAE,GAAG,IAAI,EAAE,EAAE,qBAAqB,CAAC,UAAU,CAAC;IAIhE,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAG3D,gBAAgB,CACd,YAAY,EAAE,aAAa,CAAC,UAAU,CAAC,GACtC,iBAAiB,CAAC,UAAU,CAAC;CAGjC"}

package/dist/esm/core/FunctionEvaluator.js

@@ -0,0 +1,18 @@
+import { EvaluatorBase } from "./EvaluatorBase.js";
+/**
+ * A class that constructs an evaluator based on an evaluate function.
+ */
+export class FunctionEvaluator extends EvaluatorBase {
+    evaluateFn;
+    constructor({ evaluateFn, ...args }) {
+        super({ ...args });
+        this.evaluateFn = evaluateFn;
+    }
+    async evaluate(args) {
+        return this.evaluateFn(args);
+    }
+    bindInputMapping(inputMapping) {
+        return new FunctionEvaluator({ ...this, inputMapping });
+    }
+}
+//# sourceMappingURL=FunctionEvaluator.js.map

package/dist/esm/core/FunctionEvaluator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FunctionEvaluator.js","sourceRoot":"","sources":["../../../src/core/FunctionEvaluator.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAMhD;;GAEG;AACH,MAAM,OAAO,iBAEX,SAAQ,aAAyB;IACxB,UAAU,CAAkD;IACrE,YAAY,EAAE,UAAU,EAAE,GAAG,IAAI,EAAqC;QACpE,KAAK,CAAC,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;QACnB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;IACD,KAAK,CAAC,QAAQ,CAAC,IAAgB;QAC7B,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IACD,gBAAgB,CACd,YAAuC;QAEvC,OAAO,IAAI,iBAAiB,CAAC,EAAE,GAAG,IAAI,EAAE,YAAY,EAAE,CAAC,CAAC;IAC1D,CAAC;CACF"}

package/dist/esm/helpers/asEvaluatorFn.d.ts

@@ -0,0 +1,6 @@
+import { AnyFn, EvaluatorFn } from "../types/index.js";
+/**
+ * A function that converts a generic function into an evaluator function
+ */
+export declare function asEvaluatorFn<RecordType extends Record<string, unknown>>(fn: AnyFn): EvaluatorFn<RecordType>;
+//# sourceMappingURL=asEvaluatorFn.d.ts.map

package/dist/esm/helpers/asEvaluatorFn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asEvaluatorFn.d.ts","sourceRoot":"","sources":["../../../src/helpers/asEvaluatorFn.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAK9C;;GAEG;AACH,wBAAgB,aAAa,CAAC,UAAU,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACtE,EAAE,EAAE,KAAK,GACR,WAAW,CAAC,UAAU,CAAC,CAQzB"}

package/dist/esm/helpers/asEvaluatorFn.js

@@ -0,0 +1,15 @@
+import { isPromise } from "../utils/typeUtils.js";
+import { toEvaluationResult } from "./toEvaluationResult.js";
+/**
+ * A function that converts a generic function into an evaluator function
+ */
+export function asEvaluatorFn(fn) {
+    return async (...args) => {
+        let result = fn(...args);
+        if (isPromise(result)) {
+            result = await result;
+        }
+        return toEvaluationResult(result);
+    };
+}
+//# sourceMappingURL=asEvaluatorFn.js.map

package/dist/esm/helpers/asEvaluatorFn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asEvaluatorFn.js","sourceRoot":"","sources":["../../../src/helpers/asEvaluatorFn.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;GAEG;AACH,MAAM,UAAU,aAAa,CAC3B,EAAS;IAET,OAAO,KAAK,EAAE,GAAG,IAAI,EAAE,EAAE;QACvB,IAAI,MAAM,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;QACzB,IAAI,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;YACtB,MAAM,GAAG,MAAM,MAAM,CAAC;QACxB,CAAC;QACD,OAAO,kBAAkB,CAAC,MAAM,CAAC,CAAC;IACpC,CAAC,CAAC;AACJ,CAAC"}

package/dist/esm/helpers/createEvaluator.d.ts

@@ -0,0 +1,141 @@
+import { EvaluatorBase } from "../core/EvaluatorBase.js";
+import { EvaluationKind, OptimizationDirection, TelemetryConfig } from "../types/index.js";
+type AnyFn = (...args: any[]) => any;
+/**
+ * Options for creating a custom evaluator using {@link createEvaluator}.
+ *
+ * @public
+ */
+export type CreateEvaluatorOptions = {
+    /**
+     * The name of the evaluator / metric that it measures.
+     *
+     * If not provided, the function will attempt to infer the name from the function's `name` property.
+     * If the function has no name, a unique name will be generated.
+     *
+     * @example
+     * ```typescript
+     * const evaluator = createEvaluator(myFunction, { name: "custom-metric" });
+     * ```
+     */
+    name?: string;
+    /**
+     * The kind of the evaluation.
+     *
+     * - `"CODE"`: Code-based evaluator that runs custom logic
+     * - `"LLM"`: LLM-based evaluator that uses a language model
+     *
+     * @defaultValue `"CODE"`
+     *
+     * @example
+     * ```typescript
+     * const evaluator = createEvaluator(myFunction, { kind: "CODE" });
+     * ```
+     */
+    kind?: EvaluationKind;
+    /**
+     * The direction to optimize the numeric evaluation score.
+     *
+     * - `"MAXIMIZE"`: Higher scores are better (e.g., accuracy, F1 score)
+     * - `"MINIMIZE"`: Lower scores are better (e.g., error rate, latency)
+     *
+     * @defaultValue `"MAXIMIZE"`
+     *
+     * @example
+     * ```typescript
+     * const evaluator = createEvaluator(myFunction, {
+     *   optimizationDirection: "MAXIMIZE"
+     * });
+     * ```
+     */
+    optimizationDirection?: OptimizationDirection;
+    /**
+     * The telemetry configuration for the evaluator.
+     *
+     * When enabled, the evaluator will automatically create OpenTelemetry spans
+     * for tracing and observability. This allows you to track evaluator performance
+     * and debug issues in distributed systems.
+     *
+     * @defaultValue `{ isEnabled: true }`
+     *
+     * @example
+     * ```typescript
+     * const evaluator = createEvaluator(myFunction, {
+     *   telemetry: { isEnabled: true, tracer: myTracer }
+     * });
+     * ```
+     */
+    telemetry?: TelemetryConfig;
+};
+/**
+ * A factory function for creating a custom evaluator from any function.
+ *
+ * This function wraps a user-provided function into an evaluator that can be used
+ * with Phoenix experiments and evaluations. The function can be synchronous or
+ * asynchronous, and can return a number, an {@link EvaluationResult} object, or
+ * a value that will be automatically converted to an evaluation result.
+ *
+ * The evaluator will automatically:
+ * - Convert the function's return value to an {@link EvaluationResult}
+ * - Handle both sync and async functions
+ * - Wrap the function with OpenTelemetry spans if telemetry is enabled
+ * - Infer the evaluator name from the function name if not provided
+ *
+ * @typeParam RecordType - The type of the input record that the evaluator expects.
+ *   Must extend `Record<string, unknown>`.
+ * @typeParam Fn - The type of the function being wrapped. Must be a function that
+ *   accepts the record type and returns a value compatible with {@link EvaluationResult}.
+ *
+ * @param fn - The function to wrap as an evaluator. Can be synchronous or asynchronous.
+ *   The function should accept a record of type `RecordType` and return either:
+ *   - A number (will be converted to `{ score: number }`)
+ *   - An {@link EvaluationResult} object
+ *   - Any value that can be converted to an evaluation result
+ *
+ * @param options - Optional configuration for the evaluator. See {@link CreateEvaluatorOptions}
+ *   for details on available options.
+ *
+ * @returns An {@link EvaluatorInterface} that can be used with Phoenix experiments
+ *   and evaluation workflows.
+ *
+ * @example
+ * Basic usage with a simple scoring function:
+ * ```typescript
+ * const accuracyEvaluator = createEvaluator(
+ *   ({ output, expected }) => {
+ *     return output === expected ? 1 : 0;
+ *   },
+ *   {
+ *     name: "accuracy",
+ *     kind: "CODE",
+ *     optimizationDirection: "MAXIMIZE"
+ *   }
+ * );
+ *
+ * const result = await accuracyEvaluator.evaluate({
+ *   output: "correct answer",
+ *   expected: "correct answer"
+ * });
+ * // result: { score: 1 }
+ * ```
+ *
+ *
+ * @example
+ * Returning a full EvaluationResult:
+ * ```typescript
+ * const qualityEvaluator = createEvaluator(
+ *   ({ output }) => {
+ *     const score = calculateQuality(output);
+ *     return {
+ *       score,
+ *       label: score > 0.8 ? "high" : "low",
+ *       explanation: `Quality score: ${score}`
+ *     };
+ *   },
+ *   { name: "quality" }
+ * );
+ * ```
+ */
+export declare function createEvaluator<RecordType extends Record<string, unknown> = Record<string, unknown>, Fn extends AnyFn = AnyFn>(fn: Fn, options?: CreateEvaluatorOptions): EvaluatorBase<RecordType>;
+export {};
+//# sourceMappingURL=createEvaluator.d.ts.map

package/dist/esm/helpers/createEvaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createEvaluator.d.ts","sourceRoot":"","sources":["../../../src/helpers/createEvaluator.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEtD,OAAO,EACL,cAAc,EACd,qBAAqB,EACrB,eAAe,EAChB,MAAM,UAAU,CAAC;AAKlB,KAAK,KAAK,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC;AAMrC;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC;;;;;;;;;;OAUG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB;;;;;;;;;;;;;;OAcG;IACH,qBAAqB,CAAC,EAAE,qBAAqB,CAAC;IAC9C;;;;;;;;;;;;;;;OAeG;IACH,SAAS,CAAC,EAAE,eAAe,CAAC;CAC7B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AACH,wBAAgB,eAAe,CAC7B,UAAU,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpE,EAAE,SAAS,KAAK,GAAG,KAAK,EACxB,EAAE,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,sBAAsB,GAAG,aAAa,CAAC,UAAU,CAAC,CAyBrE"}

package/dist/esm/helpers/createEvaluator.js

@@ -0,0 +1,96 @@
+import { withSpan } from "@arizeai/openinference-core";
+import { FunctionEvaluator } from "../core/FunctionEvaluator.js";
+import { asEvaluatorFn } from "./asEvaluatorFn.js";
+function generateUniqueName() {
+    return `evaluator-${Math.random().toString(36).substring(2, 15)}`;
+}
+/**
+ * A factory function for creating a custom evaluator from any function.
+ *
+ * This function wraps a user-provided function into an evaluator that can be used
+ * with Phoenix experiments and evaluations. The function can be synchronous or
+ * asynchronous, and can return a number, an {@link EvaluationResult} object, or
+ * a value that will be automatically converted to an evaluation result.
+ *
+ * The evaluator will automatically:
+ * - Convert the function's return value to an {@link EvaluationResult}
+ * - Handle both sync and async functions
+ * - Wrap the function with OpenTelemetry spans if telemetry is enabled
+ * - Infer the evaluator name from the function name if not provided
+ *
+ * @typeParam RecordType - The type of the input record that the evaluator expects.
+ *   Must extend `Record<string, unknown>`.
+ * @typeParam Fn - The type of the function being wrapped. Must be a function that
+ *   accepts the record type and returns a value compatible with {@link EvaluationResult}.
+ *
+ * @param fn - The function to wrap as an evaluator. Can be synchronous or asynchronous.
+ *   The function should accept a record of type `RecordType` and return either:
+ *   - A number (will be converted to `{ score: number }`)
+ *   - An {@link EvaluationResult} object
+ *   - Any value that can be converted to an evaluation result
+ *
+ * @param options - Optional configuration for the evaluator. See {@link CreateEvaluatorOptions}
+ *   for details on available options.
+ *
+ * @returns An {@link EvaluatorInterface} that can be used with Phoenix experiments
+ *   and evaluation workflows.
+ *
+ * @example
+ * Basic usage with a simple scoring function:
+ * ```typescript
+ * const accuracyEvaluator = createEvaluator(
+ *   ({ output, expected }) => {
+ *     return output === expected ? 1 : 0;
+ *   },
+ *   {
+ *     name: "accuracy",
+ *     kind: "CODE",
+ *     optimizationDirection: "MAXIMIZE"
+ *   }
+ * );
+ *
+ * const result = await accuracyEvaluator.evaluate({
+ *   output: "correct answer",
+ *   expected: "correct answer"
+ * });
+ * // result: { score: 1 }
+ * ```
+ *
+ *
+ * @example
+ * Returning a full EvaluationResult:
+ * ```typescript
+ * const qualityEvaluator = createEvaluator(
+ *   ({ output }) => {
+ *     const score = calculateQuality(output);
+ *     return {
+ *       score,
+ *       label: score > 0.8 ? "high" : "low",
+ *       explanation: `Quality score: ${score}`
+ *     };
+ *   },
+ *   { name: "quality" }
+ * );
+ * ```
+ */
+export function createEvaluator(fn, options) {
+    const { name, kind, optimizationDirection, telemetry = { isEnabled: true }, } = options || {};
+    const evaluatorName = name || fn.name || generateUniqueName();
+    let evaluateFn = asEvaluatorFn(fn);
+    // Add OpenTelemetry span wrapping if telemetry is enabled
+    if (telemetry && telemetry.isEnabled) {
+        evaluateFn = withSpan(evaluateFn, {
+            tracer: telemetry.tracer,
+            name: evaluatorName,
+            kind: "EVALUATOR",
+        });
+    }
+    return new FunctionEvaluator({
+        evaluateFn,
+        name: evaluatorName,
+        kind: kind || "CODE",
+        optimizationDirection: optimizationDirection || "MAXIMIZE",
+        telemetry,
+    });
+}
+//# sourceMappingURL=createEvaluator.js.map

package/dist/esm/helpers/createEvaluator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createEvaluator.js","sourceRoot":"","sources":["../../../src/helpers/createEvaluator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAGvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAO9D,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAKhD,SAAS,kBAAkB;IACzB,OAAO,aAAa,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;AACpE,CAAC;AAqED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AACH,MAAM,UAAU,eAAe,CAG7B,EAAM,EAAE,OAAgC;IACxC,MAAM,EACJ,IAAI,EACJ,IAAI,EACJ,qBAAqB,EACrB,SAAS,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,GAChC,GAAG,OAAO,IAAI,EAAE,CAAC;IAClB,MAAM,aAAa,GAAG,IAAI,IAAI,EAAE,CAAC,IAAI,IAAI,kBAAkB,EAAE,CAAC;IAC9D,IAAI,UAAU,GAAG,aAAa,CAAa,EAAE,CAAC,CAAC;IAE/C,0DAA0D;IAC1D,IAAI,SAAS,IAAI,SAAS,CAAC,SAAS,EAAE,CAAC;QACrC,UAAU,GAAG,QAAQ,CAAC,UAAU,EAAE;YAChC,MAAM,EAAE,SAAS,CAAC,MAAM;YACxB,IAAI,EAAE,aAAa;YACnB,IAAI,EAAE,WAAW;SAClB,CAAC,CAAC;IACL,CAAC;IACD,OAAO,IAAI,iBAAiB,CAAa;QACvC,UAAU;QACV,IAAI,EAAE,aAAa;QACnB,IAAI,EAAE,IAAI,IAAI,MAAM;QACpB,qBAAqB,EAAE,qBAAqB,IAAI,UAAU;QAC1D,SAAS;KACV,CAAC,CAAC;AACL,CAAC"}

package/dist/esm/helpers/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./asEvaluatorFn.js";
+export * from "./createEvaluator.js";
+export * from "./toEvaluationResult.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/helpers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/helpers/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC"}

package/dist/esm/helpers/index.js

@@ -0,0 +1,4 @@
+export * from "./asEvaluatorFn.js";
+export * from "./createEvaluator.js";
+export * from "./toEvaluationResult.js";
+//# sourceMappingURL=index.js.map

package/dist/esm/helpers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/helpers/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC"}

package/dist/esm/helpers/toEvaluationResult.d.ts

@@ -0,0 +1,67 @@
+import { EvaluationResult } from "../types/index.js";
+/**
+ * Converts an unknown value to an {@link EvaluationResult}.
+ *
+ * This function provides a flexible way to normalize various return types from
+ * evaluator functions into a standardized `EvaluationResult` format. It handles
+ * multiple input types:
+ *
+ * - **Numbers**: Converted to `{ score: number }`
+ * - **Strings**: Converted to `{ label: string }`
+ * - **Objects**: Extracts `score`, `label`, and `explanation` properties if present
+ * - **Other types**: Returns an empty `EvaluationResult` object
+ *
+ * This is particularly useful when creating evaluators from functions that may
+ * return different types, ensuring consistent evaluation result formatting.
+ *
+ * @param result - The value to convert to an EvaluationResult. Can be:
+ *   - A number (converted to score)
+ *   - A string (converted to label)
+ *   - An object with optional `score`, `label`, and/or `explanation` properties
+ *   - Any other value (returns empty object)
+ *
+ * @returns An {@link EvaluationResult} object with extracted properties
+ *
+ * @example
+ * Convert a number to an EvaluationResult:
+ * ```typescript
+ * const result = toEvaluationResult(0.95);
+ * // Returns: { score: 0.95 }
+ * ```
+ *
+ * @example
+ * Convert a string to an EvaluationResult:
+ * ```typescript
+ * const result = toEvaluationResult("correct");
+ * // Returns: { label: "correct" }
+ * ```
+ *
+ * @example
+ * Convert an object with all properties:
+ * ```typescript
+ * const result = toEvaluationResult({
+ *   score: 0.9,
+ *   label: "high",
+ *   explanation: "High quality output"
+ * });
+ * // Returns: { score: 0.9, label: "high", explanation: "High quality output" }
+ * ```
+ *
+ * @example
+ * Convert an object with partial properties:
+ * ```typescript
+ * const result = toEvaluationResult({ score: 0.8 });
+ * // Returns: { score: 0.8 }
+ * ```
+ *
+ * @example
+ * Handle null or undefined:
+ * ```typescript
+ * const result = toEvaluationResult(null);
+ * // Returns: {}
+ * ```
+ *
+ * @public
+ */
+export declare function toEvaluationResult(result: unknown): EvaluationResult;
+//# sourceMappingURL=toEvaluationResult.d.ts.map

package/dist/esm/helpers/toEvaluationResult.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toEvaluationResult.d.ts","sourceRoot":"","sources":["../../../src/helpers/toEvaluationResult.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAuD5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,OAAO,GAAG,gBAAgB,CAyBpE"}

package/dist/esm/helpers/toEvaluationResult.js

@@ -0,0 +1,133 @@
+/**
+ * Type guard to check if a value has a score property.
+ *
+ * @param result - The value to check
+ * @returns True if the value is an object with a numeric score property
+ *
+ * @internal
+ */
+function resultHasScore(result) {
+    return (typeof result === "object" &&
+        result !== null &&
+        "score" in result &&
+        typeof result.score === "number");
+}
+/**
+ * Type guard to check if a value has a label property.
+ *
+ * @param result - The value to check
+ * @returns True if the value is an object with a string label property
+ *
+ * @internal
+ */
+function resultHasLabel(result) {
+    return (typeof result === "object" &&
+        result !== null &&
+        "label" in result &&
+        typeof result.label === "string");
+}
+/**
+ * Type guard to check if a value has an explanation property.
+ *
+ * @param result - The value to check
+ * @returns True if the value is an object with a string explanation property
+ *
+ * @internal
+ */
+function resultHasExplanation(result) {
+    return (typeof result === "object" &&
+        result !== null &&
+        "explanation" in result &&
+        typeof result.explanation === "string");
+}
+/**
+ * Converts an unknown value to an {@link EvaluationResult}.
+ *
+ * This function provides a flexible way to normalize various return types from
+ * evaluator functions into a standardized `EvaluationResult` format. It handles
+ * multiple input types:
+ *
+ * - **Numbers**: Converted to `{ score: number }`
+ * - **Strings**: Converted to `{ label: string }`
+ * - **Objects**: Extracts `score`, `label`, and `explanation` properties if present
+ * - **Other types**: Returns an empty `EvaluationResult` object
+ *
+ * This is particularly useful when creating evaluators from functions that may
+ * return different types, ensuring consistent evaluation result formatting.
+ *
+ * @param result - The value to convert to an EvaluationResult. Can be:
+ *   - A number (converted to score)
+ *   - A string (converted to label)
+ *   - An object with optional `score`, `label`, and/or `explanation` properties
+ *   - Any other value (returns empty object)
+ *
+ * @returns An {@link EvaluationResult} object with extracted properties
+ *
+ * @example
+ * Convert a number to an EvaluationResult:
+ * ```typescript
+ * const result = toEvaluationResult(0.95);
+ * // Returns: { score: 0.95 }
+ * ```
+ *
+ * @example
+ * Convert a string to an EvaluationResult:
+ * ```typescript
+ * const result = toEvaluationResult("correct");
+ * // Returns: { label: "correct" }
+ * ```
+ *
+ * @example
+ * Convert an object with all properties:
+ * ```typescript
+ * const result = toEvaluationResult({
+ *   score: 0.9,
+ *   label: "high",
+ *   explanation: "High quality output"
+ * });
+ * // Returns: { score: 0.9, label: "high", explanation: "High quality output" }
+ * ```
+ *
+ * @example
+ * Convert an object with partial properties:
+ * ```typescript
+ * const result = toEvaluationResult({ score: 0.8 });
+ * // Returns: { score: 0.8 }
+ * ```
+ *
+ * @example
+ * Handle null or undefined:
+ * ```typescript
+ * const result = toEvaluationResult(null);
+ * // Returns: {}
+ * ```
+ *
+ * @public
+ */
+export function toEvaluationResult(result) {
+    if (typeof result === "number") {
+        return {
+            score: result,
+        };
+    }
+    if (typeof result === "string") {
+        return {
+            label: result,
+        };
+    }
+    if (typeof result === "object" && result !== null) {
+        const evaluationResult = {};
+        if (resultHasScore(result)) {
+            evaluationResult.score = result.score;
+        }
+        if (resultHasLabel(result)) {
+            evaluationResult.label = result.label;
+        }
+        if (resultHasExplanation(result)) {
+            evaluationResult.explanation = result.explanation;
+        }
+        return evaluationResult;
+    }
+    return {};
+}
+//# sourceMappingURL=toEvaluationResult.js.map

package/dist/esm/helpers/toEvaluationResult.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toEvaluationResult.js","sourceRoot":"","sources":["../../../src/helpers/toEvaluationResult.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,SAAS,cAAc,CAAC,MAAe;IACrC,OAAO,CACL,OAAO,MAAM,KAAK,QAAQ;QAC1B,MAAM,KAAK,IAAI;QACf,OAAO,IAAI,MAAM;QACjB,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,CACjC,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,cAAc,CAAC,MAAe;IACrC,OAAO,CACL,OAAO,MAAM,KAAK,QAAQ;QAC1B,MAAM,KAAK,IAAI;QACf,OAAO,IAAI,MAAM;QACjB,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,CACjC,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,oBAAoB,CAC3B,MAAe;IAEf,OAAO,CACL,OAAO,MAAM,KAAK,QAAQ;QAC1B,MAAM,KAAK,IAAI;QACf,aAAa,IAAI,MAAM;QACvB,OAAO,MAAM,CAAC,WAAW,KAAK,QAAQ,CACvC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAe;IAChD,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,OAAO;YACL,KAAK,EAAE,MAAM;SACd,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,OAAO;YACL,KAAK,EAAE,MAAM;SACd,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QAClD,MAAM,gBAAgB,GAAqB,EAAE,CAAC;QAC9C,IAAI,cAAc,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3B,gBAAgB,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;QACxC,CAAC;QACD,IAAI,cAAc,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3B,gBAAgB,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;QACxC,CAAC;QACD,IAAI,oBAAoB,CAAC,MAAM,CAAC,EAAE,CAAC;YACjC,gBAAgB,CAAC,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC;QACpD,CAAC;QACD,OAAO,gBAAgB,CAAC;IAC1B,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/dist/esm/index.d.ts

@@ -2,4 +2,5 @@ export * from "./llm/index.js";
 export * from "./template/index.js";
 export * from "./types/index.js";
 export * from "./utils/index.js";
+export * from "./helpers/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,OAAO,CAAC;AACtB,cAAc,YAAY,CAAC;AAC3B,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,OAAO,CAAC;AACtB,cAAc,YAAY,CAAC;AAC3B,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC"}

package/dist/esm/index.js

@@ -2,4 +2,5 @@ export * from "./llm/index.js";
 export * from "./template/index.js";
 export * from "./types/index.js";
 export * from "./utils/index.js";
+export * from "./helpers/index.js";
 //# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,OAAO,CAAC;AACtB,cAAc,YAAY,CAAC;AAC3B,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,OAAO,CAAC;AACtB,cAAc,YAAY,CAAC;AAC3B,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC"}