@arizeai/phoenix-evals 0.6.1 → 0.6.2

package/dist/esm/utils/typeUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"typeUtils.js","sourceRoot":"","sources":["../../../src/utils/typeUtils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAc,KAAc;IACnD,OAAO,CACL,CAAC,CAAC,KAAK;QACP,8DAA8D;QAC9D,OAAQ,KAAa,EAAE,IAAI,KAAK,UAAU;QAC1C,8DAA8D;QAC9D,OAAQ,KAAa,EAAE,KAAK,KAAK,UAAU,CAC5C,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,16 @@
+import { CreateEvaluatorArgs, EvaluationResult, ObjectMapping } from "../types";
+import { EvaluatorBase } from "./EvaluatorBase";
+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/src/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/src/core/FunctionEvaluator.js

@@ -0,0 +1,33 @@
+"use strict";
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FunctionEvaluator = void 0;
+const EvaluatorBase_1 = require("./EvaluatorBase");
+/**
+ * A class that constructs an evaluator based on an evaluate function.
+ */
+class FunctionEvaluator extends EvaluatorBase_1.EvaluatorBase {
+    constructor(_a) {
+        var { evaluateFn } = _a, args = __rest(_a, ["evaluateFn"]);
+        super(Object.assign({}, args));
+        this.evaluateFn = evaluateFn;
+    }
+    async evaluate(args) {
+        return this.evaluateFn(args);
+    }
+    bindInputMapping(inputMapping) {
+        return new FunctionEvaluator(Object.assign(Object.assign({}, this), { inputMapping }));
+    }
+}
+exports.FunctionEvaluator = FunctionEvaluator;
+//# sourceMappingURL=FunctionEvaluator.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FunctionEvaluator.js","sourceRoot":"","sources":["../../../src/core/FunctionEvaluator.ts"],"names":[],"mappings":";;;;;;;;;;;;;;AAEA,mDAAgD;AAMhD;;GAEG;AACH,MAAa,iBAEX,SAAQ,6BAAyB;IAEjC,YAAY,EAA0D;YAA1D,EAAE,UAAU,OAA8C,EAAzC,IAAI,cAArB,cAAuB,CAAF;QAC/B,KAAK,mBAAM,IAAI,EAAG,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,iCAAM,IAAI,KAAE,YAAY,IAAG,CAAC;IAC1D,CAAC;CACF;AAhBD,8CAgBC"}

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

@@ -0,0 +1,6 @@
+import { AnyFn, EvaluatorFn } from "../types";
+/**
+ * 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/src/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/src/helpers/asEvaluatorFn.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.asEvaluatorFn = asEvaluatorFn;
+const typeUtils_1 = require("../utils/typeUtils");
+const toEvaluationResult_1 = require("./toEvaluationResult");
+/**
+ * A function that converts a generic function into an evaluator function
+ */
+function asEvaluatorFn(fn) {
+    return async (...args) => {
+        let result = fn(...args);
+        if ((0, typeUtils_1.isPromise)(result)) {
+            result = await result;
+        }
+        return (0, toEvaluationResult_1.toEvaluationResult)(result);
+    };
+}
+//# sourceMappingURL=asEvaluatorFn.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"asEvaluatorFn.js","sourceRoot":"","sources":["../../../src/helpers/asEvaluatorFn.ts"],"names":[],"mappings":";;AAQA,sCAUC;AAjBD,kDAA+C;AAE/C,6DAA0D;AAE1D;;GAEG;AACH,SAAgB,aAAa,CAC3B,EAAS;IAET,OAAO,KAAK,EAAE,GAAG,IAAI,EAAE,EAAE;QACvB,IAAI,MAAM,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;QACzB,IAAI,IAAA,qBAAS,EAAC,MAAM,CAAC,EAAE,CAAC;YACtB,MAAM,GAAG,MAAM,MAAM,CAAC;QACxB,CAAC;QACD,OAAO,IAAA,uCAAkB,EAAC,MAAM,CAAC,CAAC;IACpC,CAAC,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,141 @@
+import { EvaluatorBase } from "../core/EvaluatorBase";
+import { EvaluationKind, OptimizationDirection, TelemetryConfig } from "../types";
+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/src/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/src/helpers/createEvaluator.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEvaluator = createEvaluator;
+const openinference_core_1 = require("@arizeai/openinference-core");
+const FunctionEvaluator_1 = require("../core/FunctionEvaluator");
+const asEvaluatorFn_1 = require("./asEvaluatorFn");
+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" }
+ * );
+ * ```
+ */
+function createEvaluator(fn, options) {
+    const { name, kind, optimizationDirection, telemetry = { isEnabled: true }, } = options || {};
+    const evaluatorName = name || fn.name || generateUniqueName();
+    let evaluateFn = (0, asEvaluatorFn_1.asEvaluatorFn)(fn);
+    // Add OpenTelemetry span wrapping if telemetry is enabled
+    if (telemetry && telemetry.isEnabled) {
+        evaluateFn = (0, openinference_core_1.withSpan)(evaluateFn, {
+            tracer: telemetry.tracer,
+            name: evaluatorName,
+            kind: "EVALUATOR",
+        });
+    }
+    return new FunctionEvaluator_1.FunctionEvaluator({
+        evaluateFn,
+        name: evaluatorName,
+        kind: kind || "CODE",
+        optimizationDirection: optimizationDirection || "MAXIMIZE",
+        telemetry,
+    });
+}
+//# sourceMappingURL=createEvaluator.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"createEvaluator.js","sourceRoot":"","sources":["../../../src/helpers/createEvaluator.ts"],"names":[],"mappings":";;AA2JA,0CA4BC;AAvLD,oEAAuD;AAGvD,iEAA8D;AAO9D,mDAAgD;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,SAAgB,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,IAAA,6BAAa,EAAa,EAAE,CAAC,CAAC;IAE/C,0DAA0D;IAC1D,IAAI,SAAS,IAAI,SAAS,CAAC,SAAS,EAAE,CAAC;QACrC,UAAU,GAAG,IAAA,6BAAQ,EAAC,UAAU,EAAE;YAChC,MAAM,EAAE,SAAS,CAAC,MAAM;YACxB,IAAI,EAAE,aAAa;YACnB,IAAI,EAAE,WAAW;SAClB,CAAC,CAAC;IACL,CAAC;IACD,OAAO,IAAI,qCAAiB,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/src/helpers/index.d.ts

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

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

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

package/dist/src/helpers/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./createEvaluator"), exports);
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/helpers/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,oDAAkC"}

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

@@ -0,0 +1,67 @@
+import { EvaluationResult } from "../types";
+/**
+ * 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/src/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/src/helpers/toEvaluationResult.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toEvaluationResult = toEvaluationResult;
+/**
+ * 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
+ */
+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/src/helpers/toEvaluationResult.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toEvaluationResult.js","sourceRoot":"","sources":["../../../src/helpers/toEvaluationResult.ts"],"names":[],"mappings":";;AAuHA,gDAyBC;AA9ID;;;;;;;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,SAAgB,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/src/index.d.ts

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

package/dist/src/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/src/index.js

@@ -18,4 +18,5 @@ __exportStar(require("./llm"), exports);
 __exportStar(require("./template"), exports);
 __exportStar(require("./types"), exports);
 __exportStar(require("./utils"), exports);
+__exportStar(require("./helpers"), exports);
 //# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,wCAAsB;AACtB,6CAA2B;AAC3B,0CAAwB;AACxB,0CAAwB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,wCAAsB;AACtB,6CAA2B;AAC3B,0CAAwB;AACxB,0CAAwB;AACxB,4CAA0B"}

package/dist/src/types/base.d.ts

@@ -0,0 +1,2 @@
+export type AnyFn = (...args: any[]) => any;
+//# sourceMappingURL=base.d.ts.map

package/dist/src/types/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../src/types/base.ts"],"names":[],"mappings":"AACA,MAAM,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC"}

package/dist/src/types/base.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=base.js.map

package/dist/src/types/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../../src/types/base.ts"],"names":[],"mappings":""}

package/dist/src/types/index.d.ts

@@ -2,4 +2,5 @@ export * from "./evals";
 export * from "./templating";
 export * from "./otel";
 export * from "./data";
+export * from "./base";
 //# sourceMappingURL=index.d.ts.map

package/dist/src/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC"}

package/dist/src/types/index.js

@@ -18,4 +18,5 @@ __exportStar(require("./evals"), exports);
 __exportStar(require("./templating"), exports);
 __exportStar(require("./otel"), exports);
 __exportStar(require("./data"), exports);
+__exportStar(require("./base"), exports);
 //# sourceMappingURL=index.js.map

package/dist/src/types/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAwB;AACxB,+CAA6B;AAC7B,yCAAuB;AACvB,yCAAuB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAwB;AACxB,+CAA6B;AAC7B,yCAAuB;AACvB,yCAAuB;AACvB,yCAAuB"}