@output.ai/core 0.5.0 → 0.5.2

package/src/index.js

@@ -1,29 +1,4 @@
-import { evaluator, EvaluationStringResult, EvaluationNumberResult, EvaluationBooleanResult, EvaluationFeedback } from './interface/evaluator.js';
-import { step } from './interface/step.js';
-import { workflow } from './interface/workflow.js';
-import { executeInParallel } from './interface/workflow_utils.js';
-import { sendHttpRequest, sendPostRequestAndAwaitWebhook } from './interface/webhook.js';
-import { FatalError, ValidationError } from './errors.js';
+export * from './interface/index.js';
+export * from './errors.js';
+export { z } from 'zod';
 export { continueAsNew, sleep } from '@temporalio/workflow';
-import { z } from 'zod';
-
-export {
-  // base building blocks
-  evaluator,
-  step,
-  workflow,
-  // Evaluation results
-  EvaluationNumberResult,
-  EvaluationStringResult,
-  EvaluationBooleanResult,
-  EvaluationFeedback,
-  // tools
-  executeInParallel,
-  sendHttpRequest,
-  sendPostRequestAndAwaitWebhook,
-  // errors
-  FatalError,
-  ValidationError,
-  // zod
-  z
-};

package/src/interface/evaluation_result.d.ts

@@ -0,0 +1,160 @@
+import type { z } from 'zod';
+
+/**
+ * A single feedback for an EvaluationResult
+ */
+export class EvaluationFeedback {
+  /**
+   * Issue found
+   */
+  issue: string;
+
+  /**
+   * Improvement suggestion
+   */
+  suggestion?: string;
+
+  /**
+   * Reference for the issue
+   */
+  reference?: string;
+
+  /**
+   * Issue priority
+   */
+  priority?: 'low' | 'medium' | 'high' | 'critical';
+
+  /**
+   * @constructor
+   * @param args
+   * @param args.issue
+   * @param args.suggestion
+   * @param args.reference
+   * @param args.priority
+   */
+  constructor( args: {
+    issue: string;
+    suggestion?: string;
+    reference?: string;
+    priority?: 'low' | 'medium' | 'high' | 'critical';
+  } );
+
+  /**
+   * @returns The zod schema for this class
+   */
+  static get schema(): z.ZodType;
+}
+
+/**
+ * Base constructor arguments for EvaluationResult classes
+ */
+export type EvaluationResultArgs<TValue = any> = { // eslint-disable-line @typescript-eslint/no-explicit-any
+  /**
+   * The value of the evaluation
+   */
+  value: TValue;
+  /**
+   * The confidence in the evaluation
+   */
+  confidence: number;
+  /**
+   * The name of the evaluation
+   */
+  name?: string;
+  /**
+   * The reasoning behind the result
+   */
+  reasoning?: string;
+  /**
+   * Feedback for this evaluation
+   */
+  feedback?: EvaluationFeedback[];
+  /**
+   * Dimensions of this evaluation
+   */
+  dimensions?: Array<EvaluationStringResult | EvaluationNumberResult | EvaluationBooleanResult>;
+};
+
+/**
+ * Represents the result of an evaluation.
+ *
+ * Generic base class; evaluators must return an instance of an EvaluationResult subclass.
+ */
+export class EvaluationResult {
+  /**
+   * The name of the evaluation result
+   */
+  name?: string;
+
+  /**
+   * The evaluation result value
+   */
+  value: any; // eslint-disable-line @typescript-eslint/no-explicit-any
+
+  /**
+   * The evaluation result confidence
+   */
+  confidence: number;
+
+  /**
+   * The evaluation result reasoning
+   */
+  reasoning?: string;
+
+  /**
+   * Feedback for this evaluation
+   */
+  feedback: EvaluationFeedback[];
+
+  /**
+   * Dimensions of this evaluation
+   */
+  dimensions: Array<EvaluationStringResult | EvaluationNumberResult | EvaluationBooleanResult>;
+
+  /**
+   * @constructor
+   * @param args
+   */
+  constructor( args: EvaluationResultArgs );
+
+  /**
+   * @returns The zod schema for this class
+   */
+  static get schema(): z.ZodType;
+}
+
+/**
+ * An evaluation result where the value is a string
+ * @extends EvaluationResult
+ */
+export class EvaluationStringResult extends EvaluationResult {
+  /**
+   * @constructor
+   * @param args
+   */
+  constructor( args: EvaluationResultArgs<string> );
+}
+
+/**
+ * An evaluation result where the value is a number
+ * @extends EvaluationResult
+ */
+export class EvaluationNumberResult extends EvaluationResult {
+  /**
+   * @constructor
+   * @param args
+   */
+  constructor( args: EvaluationResultArgs<number> );
+}
+
+/**
+ * An evaluation result where the value is a boolean
+ * @extends EvaluationResult
+ */
+export class EvaluationBooleanResult extends EvaluationResult {
+  /**
+   * @constructor
+   * @param args
+   */
+  constructor( args: EvaluationResultArgs<boolean> );
+}

package/src/interface/evaluation_result.js

@@ -0,0 +1,202 @@
+import { ValidationError } from '#errors';
+import * as z from 'zod';
+
+/**
+ * Error for when EvaluationResult are invalid
+ */
+export class EvaluationResultValidationError extends ValidationError {};
+
+/**
+ * A single feedback for an EvaluationResult
+ */
+export class EvaluationFeedback {
+
+  /**
+   * Issue found
+   * @type {string}
+   */
+  issue;
+
+  /**
+   * Improvement suggestion
+   * @type {string}
+   */
+  suggestion;
+
+  /**
+   * Reference for the issue
+   * @type {string}
+   */
+  reference;
+
+  /**
+   * Issue priority
+   * @type {'low' | 'medium' | 'high' | 'critical' | undefined}
+   */
+  priority;
+
+  /**
+   * The zod schema for this class
+   * @type {z.ZodType}
+   */
+  static get schema() {
+    return z.object( {
+      issue: z.string(),
+      suggestion: z.string().optional(),
+      reference: z.string().optional(),
+      priority: z.enum( [ 'low', 'medium', 'high', 'critical' ] ).optional()
+    } );
+  };
+
+  /**
+   * @constructor
+   * @param {object} args
+   * @param {string} args.issue
+   * @param {string} [args.suggestion]
+   * @param {string} [args.reference]
+   * @param {'low' | 'medium' | 'high' | 'critical'} [args.priority]
+   */
+  constructor( { issue, suggestion = undefined, reference = undefined, priority = undefined } ) {
+    const result = this.constructor.schema.safeParse( { issue, suggestion, reference, priority } );
+    if ( result.error ) {
+      throw new EvaluationResultValidationError( z.prettifyError( result.error ) );
+    }
+    this.issue = issue;
+    this.suggestion = suggestion;
+    this.reference = reference;
+    this.priority = priority;
+  }
+}
+
+/**
+ * Generic EvaluationResult class, represents the result of an evaluation.
+ */
+export class EvaluationResult {
+
+  /**
+   * The name of the evaluation result
+   * @type {string}
+   */
+  name;
+
+  /**
+   * The evaluation result value
+   * @type {any}
+   */
+  value = null;
+
+  /**
+   * The confidence value, between 0 and 1
+   * @type {number}
+   */
+  confidence;
+
+  /**
+   * The reasoning value
+   * @type {string}
+   */
+  reasoning;
+
+  /**
+   * Feedback for this evaluation
+   * @type {EvaluationFeedback[]}
+   */
+  feedback = [];
+
+  /**
+   * Dimensions of this evaluation
+   * @type {EvaluationResult[]}
+   */
+  dimensions = [];
+
+  /**
+   * The schema main field
+   * @type {z.ZodAny}
+   */
+  static valueSchema = z.any();
+
+  /**
+   * The zod schema for this class
+   * @type {z.ZodType}
+   */
+  static get schema() {
+    const baseSchema = z.object( {
+      value: this.valueSchema,
+      confidence: z.number(),
+      reasoning: z.string().optional(),
+      name: z.string().optional(),
+      feedback: z.array( EvaluationFeedback.schema ).optional()
+    } );
+
+    // Adds dimension but keep it only one level deep
+    return baseSchema.extend( {
+      dimensions: z.array(
+        baseSchema.extend( {
+          value: z.union( [ z.string(), z.number(), z.boolean() ] )
+        } )
+      ).optional()
+    } );
+  };
+
+  /**
+   * @constructor
+   * @param {object} args
+   * @param {any} args.value
+   * @param {number} args.confidence
+   * @param {string} [args.name]
+   * @param {EvaluationResult[]} [args.dimensions]
+   * @param {EvaluationFeedback[]} [args.feedback]
+   * @param {string} [args.reasoning]
+   */
+  constructor( { value, confidence, dimensions = [], feedback = [], name = undefined, reasoning = undefined } ) {
+    const result = this.constructor.schema.safeParse( { value, confidence, dimensions, feedback, name, reasoning } );
+    if ( result.error ) {
+      throw new EvaluationResultValidationError( z.prettifyError( result.error ) );
+    }
+    this.confidence = confidence;
+    this.value = value;
+    this.dimensions = dimensions;
+    this.feedback = feedback;
+    this.name = name;
+    this.reasoning = reasoning;
+  }
+};
+
+/**
+ * An evaluation result that uses a string value
+ * @extends EvaluationResult
+ * @property {string} value - The evaluation result value
+ * @constructor
+ * @param {object} args
+ * @param {string} args.value - The value of the evaluation (must be a string)
+ * @see EvaluationResult#constructor for other parameters (confidence, reasoning)
+ */
+export class EvaluationStringResult extends EvaluationResult {
+  static valueSchema = z.string();
+};
+
+/**
+ * An evaluation result that uses a boolean value
+ * @extends EvaluationResult
+ * @property {boolean} value - The evaluation result value
+ * @constructor
+ * @param {object} args
+ * @param {boolean} args.value - The value of the evaluation (must be a boolean)
+ * @see EvaluationResult#constructor for other parameters (confidence, reasoning)
+ */
+export class EvaluationBooleanResult extends EvaluationResult {
+  static valueSchema = z.boolean();
+};
+
+/**
+ * An evaluation result that uses a number value
+ * @extends EvaluationResult
+ * @property {number} value - The evaluation result value
+ * @constructor
+ * @param {object} args
+ * @param {number} args.value - The value of the evaluation (must be a number)
+ * @see EvaluationResult#constructor for other parameters (confidence, reasoning)
+ */
+export class EvaluationNumberResult extends EvaluationResult {
+  static valueSchema = z.number();
+};

package/src/interface/evaluator.d.ts

@@ -0,0 +1,70 @@
+import type { z } from 'zod';
+import type { AnyZodSchema, TemporalActivityOptions } from './types.d.ts';
+import type { EvaluationResult } from './evaluation_result.d.ts';
+
+/**
+ * Options for an evaluator.
+ */
+export type EvaluatorOptions = {
+
+  /**
+   * Temporal activity options for this evaluator.
+   */
+  activityOptions?: TemporalActivityOptions
+};
+
+/**
+ * The handler function of an evaluator.
+ *
+ * @param input - The evaluator input; it matches the schema defined by `inputSchema`.
+ *
+ * @returns The result of the evaluation.
+ */
+export type EvaluatorFunction<
+  InputSchema extends AnyZodSchema | undefined = undefined,
+  Result extends EvaluationResult
+> = InputSchema extends AnyZodSchema ?
+  ( input: z.infer<InputSchema> ) => Promise<Result> :
+  () => Promise<Result>;
+
+/**
+ * A wrapper around the user defined `fn` handler function.
+ *
+ * It has the same signature and returns the same value, calling the user function inside.
+ *
+ * It adds input validation based on the `inputSchema`.
+ */
+export type EvaluatorFunctionWrapper<EvaluatorFunction> =
+  Parameters<EvaluatorFunction> extends [infer Input] ?
+    ( input: Input ) => ReturnType<EvaluatorFunction> :
+    () => ReturnType<EvaluatorFunction>;
+
+/**
+ * Creates an evaluation function. It is similar to a step, but must return an EvaluationResult.
+ *
+ * It is translated to a Temporal Activity.
+ *
+ * @typeParam InputSchema - Zod schema of the fn's input.
+ * @typeParam Result - Return type of the fn, extends EvaluationResult.
+ *
+ * @throws {@link ValidationError}
+ * @throws {@link FatalError}
+ *
+ * @param params - Evaluator parameters
+ * @param params.name - Human-readable evaluator name (must start with a letter or underscore, followed by letters, numbers, or underscores)
+ * @param params.description - Description of the evaluator
+ * @param params.inputSchema - Zod schema for the `fn` input
+ * @param params.fn - A function containing the evaluator code
+ * @param params.options - Optional evaluator options.
+ * @returns A wrapper function around the `fn` function
+ */
+export declare function evaluator<
+  InputSchema extends AnyZodSchema,
+  Result extends EvaluationResult
+>( params: {
+  name: string;
+  description?: string;
+  inputSchema: InputSchema;
+  fn: EvaluatorFunction<InputSchema, Result>;
+  options?: EvaluatorOptions;
+} ): EvaluatorFunctionWrapper<EvaluatorFunction<InputSchema, Result>>;

package/src/interface/evaluator.js

@@ -3,208 +3,7 @@ import { validateWithSchema } from './validations/runtime.js';
 import { setMetadata } from '#utils';
 import { ValidationError } from '#errors';
 import { ComponentType } from '#consts';
-import * as z from 'zod';
-
-/**
- * Error for when EvaluationResult are invalid
- */
-class EvaluationResultValidationError extends ValidationError {};
-
-/**
- * A single feedback for an EvaluationResult
- */
-export class EvaluationFeedback {
-
-  /**
-   * Issue found
-   * @type {string}
-   */
-  issue;
-
-  /**
-   * Improvement suggestion
-   * @type {string}
-   */
-  suggestion;
-
-  /**
-   * Reference for the issue
-   * @type {string}
-   */
-  reference;
-
-  /**
-   * Issue priority
-   * @type {'low' | 'medium' | 'high' | 'critical' | undefined}
-   */
-  priority;
-
-  /**
-   * The zod schema for this class
-   * @type {z.ZodType}
-   */
-  static get schema() {
-    return z.object( {
-      issue: z.string(),
-      suggestion: z.string().optional(),
-      reference: z.string().optional(),
-      priority: z.enum( [ 'low', 'medium', 'high', 'critical' ] ).optional()
-    } );
-  };
-
-  /**
-   * @constructor
-   * @param {object} args
-   * @param {string} args.issue
-   * @param {string} [args.suggestion]
-   * @param {string} [args.reference]
-   * @param {'low' | 'medium' | 'high' | 'critical'} [args.priority]
-   */
-  constructor( { issue, suggestion = undefined, reference = undefined, priority = undefined } ) {
-    const result = this.constructor.schema.safeParse( { issue, suggestion, reference, priority } );
-    if ( result.error ) {
-      throw new EvaluationResultValidationError( z.prettifyError( result.error ) );
-    }
-    this.issue = issue;
-    this.suggestion = suggestion;
-    this.reference = reference;
-    this.priority = priority;
-  }
-}
-
-/**
- * Generic EvaluationResult class, represents the result of an evaluation.
- */
-export class EvaluationResult {
-
-  /**
-   * The name of the evaluation result
-   * @type {string}
-   */
-  name;
-
-  /**
-   * The evaluation result value
-   * @type {any}
-   */
-  value = null;
-
-  /**
-   * The confidence value, between 0 and 1
-   * @type {number}
-   */
-  confidence;
-
-  /**
-   * The reasoning value
-   * @type {string}
-   */
-  reasoning;
-
-  /**
-   * Feedback for this evaluation
-   * @type {EvaluationFeedback[]}
-   */
-  feedback = [];
-
-  /**
-   * Dimensions of this evaluation
-   * @type {EvaluationResult[]}
-   */
-  dimensions = [];
-
-  /**
-   * The schema main field
-   * @type {z.ZodAny}
-   */
-  static valueSchema = z.any();
-
-  /**
-   * The zod schema for this class
-   * @type {z.ZodType}
-   */
-  static get schema() {
-    const baseSchema = z.object( {
-      value: this.valueSchema,
-      confidence: z.number(),
-      reasoning: z.string().optional(),
-      name: z.string().optional(),
-      feedback: z.array( EvaluationFeedback.schema ).optional()
-    } );
-
-    // Adds dimension but keep it only one level deep
-    return baseSchema.extend( {
-      dimensions: z.array(
-        baseSchema.extend( {
-          value: z.union( [ z.string(), z.number(), z.boolean() ] )
-        } )
-      ).optional()
-    } );
-  };
-
-  /**
-   * @constructor
-   * @param {object} args
-   * @param {any} args.value
-   * @param {number} args.confidence
-   * @param {string} [args.name]
-   * @param {EvaluationResult[]} [args.dimensions]
-   * @param {EvaluationFeedback[]} [args.feedback]
-   * @param {string} [args.reasoning]
-   */
-  constructor( { value, confidence, dimensions = [], feedback = [], name = undefined, reasoning = undefined } ) {
-    const result = this.constructor.schema.safeParse( { value, confidence, dimensions, feedback, name, reasoning } );
-    if ( result.error ) {
-      throw new EvaluationResultValidationError( z.prettifyError( result.error ) );
-    }
-    this.confidence = confidence;
-    this.value = value;
-    this.dimensions = dimensions;
-    this.feedback = feedback;
-    this.name = name;
-    this.reasoning = reasoning;
-  }
-};
-
-/**
- * An evaluation result that uses a string value
- * @extends EvaluationResult
- * @property {string} value - The evaluation result value
- * @constructor
- * @param {object} args
- * @param {string} args.value - The value of the evaluation (must be a string)
- * @see EvaluationResult#constructor for other parameters (confidence, reasoning)
- */
-export class EvaluationStringResult extends EvaluationResult {
-  static valueSchema = z.string();
-};
-
-/**
- * An evaluation result that uses a boolean value
- * @extends EvaluationResult
- * @property {boolean} value - The evaluation result value
- * @constructor
- * @param {object} args
- * @param {boolean} args.value - The value of the evaluation (must be a boolean)
- * @see EvaluationResult#constructor for other parameters (confidence, reasoning)
- */
-export class EvaluationBooleanResult extends EvaluationResult {
-  static valueSchema = z.boolean();
-};
-
-/**
- * An evaluation result that uses a number value
- * @extends EvaluationResult
- * @property {number} value - The evaluation result value
- * @constructor
- * @param {object} args
- * @param {number} args.value - The value of the evaluation (must be a number)
- * @see EvaluationResult#constructor for other parameters (confidence, reasoning)
- */
-export class EvaluationNumberResult extends EvaluationResult {
-  static valueSchema = z.number();
-};
-
+import { EvaluationResult } from './evaluation_result.js';
 /**
  * Expose the function to create a new evaluator
  * @param {object} opts

package/src/interface/evaluator.spec.js

@@ -5,7 +5,7 @@ import {
   EvaluationNumberResult,
   EvaluationBooleanResult,
   EvaluationFeedback
-} from './evaluator.js';
+} from './evaluation_result.js';
 import { ValidationError } from '#errors';
 
 describe( 'interface/evaluator - EvaluationResult classes', () => {

package/src/interface/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Exports all public methods from the interface
+ */
+export * from './webhook.d.ts';
+export * from './workflow_utils.d.ts';
+export * from './step.d.ts';
+export * from './evaluator.d.ts';
+export * from './workflow.d.ts';
+export * from './evaluation_result.d.ts';

package/src/interface/index.js

@@ -0,0 +1,19 @@
+import { EvaluationStringResult, EvaluationNumberResult, EvaluationBooleanResult, EvaluationFeedback } from './evaluation_result.js';
+import { evaluator } from './evaluator.js';
+import { step } from './step.js';
+import { workflow } from './workflow.js';
+import { executeInParallel } from './workflow_utils.js';
+import { sendHttpRequest, sendPostRequestAndAwaitWebhook } from './webhook.js';
+
+export {
+  evaluator,
+  step,
+  workflow,
+  EvaluationNumberResult,
+  EvaluationStringResult,
+  EvaluationBooleanResult,
+  EvaluationFeedback,
+  executeInParallel,
+  sendHttpRequest,
+  sendPostRequestAndAwaitWebhook
+};