@output.ai/core 0.1.16 → 0.1.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@output.ai/core",
-  "version": "0.1.16",
+  "version": "0.1.17",
   "description": "The core module of the output framework",
   "type": "module",
   "exports": {

package/src/index.d.ts

@@ -1,52 +1,189 @@
-// Import Zod types for dual schema support
 import type { z } from 'zod';
 import type { ActivityOptions } from '@temporalio/workflow';
 
-// Re-export Zod for consumers to use
+/**
+ * Expose z from Zod as a convenience.
+ */
 export { z } from 'zod';
 
+/*
+╭─────────────────────────╮
+│ C O M M O N  T Y P E S  │╮
+╰─────────────────────────╯│
+ ╰─────────────────────────╯
+*/
+
 /**
  * Type alias for any Zod schema type.
+ */
+export type AnyZodSchema = z.ZodType<any, any, any>; // eslint-disable-line @typescript-eslint/no-explicit-any
+
+/**
+ * Native Temporal configurations for activities.
  *
- * Note: The use of `any` here is intentional and necessary. Zod's ZodType has three
- * generic parameters (Output, Def, Input) that vary based on the specific schema type.
- * When we want to accept ANY Zod schema (string, number, object, etc.), we must use
- * `any` for these parameters. Using `unknown` would be too restrictive and would
- * break Zod's type inference system.
+ * All native options are accepted except 'versioningIntent', 'taskQueue', 'allowEagerDispatch'.
  *
- * This is a common pattern in TypeScript when dealing with highly generic types,
- * and Zod itself uses this pattern internally.
+ * @see {@link https://typescript.temporal.io/api/interfaces/common.ActivityOptions}
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-type AnyZodSchema = z.ZodType<any, any, any>;
+export type TemporalActivityOptions = Omit<ActivityOptions, 'versioningIntent' | 'taskQueue' | 'allowEagerDispatch'>;
+
+/*
+╭─────────╮
+│ S T E P │╮
+╰─────────╯│
+ ╰─────────╯
+*/
 
 /**
- * Activity options accepted by step/evaluator/workflow definitions.
- * Exposes supported Temporal ActivityOptions.
+ * The handler function of a step.
+ *
+ * @param input - The step input; it matches the schema defined by `inputSchema`.
+ *
+ * @returns A value matching the schema defined by `outputSchema`.
+ */
+export type StepFunction<
+  InputSchema extends AnyZodSchema | undefined = undefined,
+  OutputSchema extends AnyZodSchema | undefined = undefined
+> = InputSchema extends AnyZodSchema ?
+  ( input: z.infer<InputSchema> ) => Promise<OutputSchema extends AnyZodSchema ? z.infer<OutputSchema> : void> :
+  () => Promise<OutputSchema extends AnyZodSchema ? z.infer<OutputSchema> : void>;
+
+/**
+ * A wrapper around the user defined `fn` handler function.
+ *
+ * It accepts the same input and returns the same value, calling the user function inside.
+ *
+ * It adds input and output validation based on the `inputSchema`, `outputSchema`.
+ *
+ * @param input - The Step input; it matches the schema defined by `inputSchema`.
+ * @returns A value matching the schema defined by `outputSchema`.
+ */
+export type StepFunctionWrapper<StepFunction> =
+  Parameters<StepFunction> extends [infer Input] ?
+    ( input: Input ) => ReturnType<StepFunction> :
+    () => ReturnType<StepFunction>;
+
+/**
+ * Creates a step.
+ *
+ * A step is a logical unit of work that can perform I/O. It is translated to a Temporal Activity.
+ *
+ * The step logic is defined in the `fn` handler function.
+ *
+ * The schema of the input that the function receives as the first argument is defined by the `inputSchema` option.
+ *
+ * The output of the `fn` handler must match the schema defined by `outputSchema`; otherwise, a validation error is raised.
+ *
+ * @example
+ * ```
+ * step( {
+ *   name: 'process',
+ *   description: 'A generic process',
+ *   inputSchema: z.object( {
+ *     value: z.number()
+ *   } ),
+ *   outputSchema: z.string(),
+ *   fn: async input => {
+ *     const result = await ai.call( input.value );
+ *     return result as string;
+ *   }
+ * } )
+ * ```
+ *
+ * @example Step without outputSchema
+ * ```
+ * step( {
+ *   name: 'process',
+ *   description: 'A generic process',
+ *   inputSchema: z.object( {
+ *     value: z.number()
+ *   } ),
+ *   fn: async input => {
+ *     await ai.call( input.value );
+ *   }
+ * } )
+ * ```
+ *
+ * @example Step without inputSchema
+ * ```
+ * step( {
+ *   name: 'process',
+ *   description: 'A generic process',
+ *   outputSchema: z.string(),
+ *   fn: async () => {
+ *     const result = await ai.call();
+ *     return result as string;
+ *   }
+ * } )
+ * ```
+ *
+ * @example Step without inputSchema and outputSchema
+ * ```
+ * step( {
+ *   name: 'process',
+ *   description: 'A generic process',
+ *   fn: async () => {
+ *     await ai.call();
+ *   }
+ * } )
+ * ```
+ *
+ * @remarks
+ * - Never call another step from within a step.
+ * - Never call a workflow from within a step.
  *
- * @description Exposes supported Temporal ActivityOptions
+ * @typeParam InputSchema - Zod schema for the step input
+ * @typeParam OutputSchema - Zod schema for the step output
+ *
+ * @param params - Step parameters
+ * @param params.name - Human-readable step name (must start with a letter or underscore, followed by letters, numbers, or underscores)
+ * @param params.description - Description of the step
+ * @param params.inputSchema - Zod schema for the `fn` input
+ * @param params.outputSchema - Zod schema for the `fn` output
+ * @param params.fn - A handler function containing the step code
+ * @param params.options - Temporal Activity options
+ * @returns The same handler function set at `fn`
  */
-export type Options = Omit<ActivityOptions, 'versioningIntent' | 'taskQueue' | 'allowEagerDispatch'>;
+export declare function step<
+  InputSchema extends AnyZodSchema | undefined = undefined,
+  OutputSchema extends AnyZodSchema | undefined = undefined
+>( params: {
+  name: string;
+  description?: string;
+  inputSchema?: InputSchema;
+  outputSchema?: OutputSchema;
+  fn: StepFunction<InputSchema, OutputSchema>;
+  options?: TemporalActivityOptions;
+} ): StepFunctionWrapper<StepFunction<InputSchema, OutputSchema>>;
+
+/*
+╭─────────────────╮
+│ W O R K F L O W │╮
+╰─────────────────╯│
+ ╰─────────────────╯
+*/
 
 /**
- * The last argument when calling workflows is used to configure it
+ * Configuration for workflow invocations.
+ *
+ * Allows overriding Temporal Activity options for this workflow.
  */
-export type WorkflowCallConfig = {
+export type WorkflowInvocationConfiguration = {
 
   /**
-   * Temporal Activity Options
+   * Native Temporal Activity options
    */
-  options?: Options,
+  options?: TemporalActivityOptions,
 
   /**
-   * Whether this workflow will run detached or not.
-   * Detached workflows called without explicitly awaiting for the result will be "fire-an-forget", outliving the parent.
+   * Configures whether this workflow runs detached.
+   * Detached workflows called without explicitly awaiting the result are "fire-and-forget" and may outlive the parent.
    */
   detached?: boolean
 };
 
 /**
- * The second argument for the workflow's fn function
+ * The second argument passed to the workflow's `fn` function.
  */
 export type WorkflowContext<
   InputSchema extends AnyZodSchema | undefined = undefined,
@@ -58,25 +195,28 @@ export type WorkflowContext<
    */
   control: {
     /**
-     * Lets Workflow Execution close successfully and creates a new Workflow Execution.
+     * Closes the current workflow execution successfully and creates a new workflow execution.
      *
-     * The new Workflow Execution is in the same chain as previous workflow but it will generate another trace file.
+     * The new workflow execution is in the same chain as the previous workflow, but it generates another trace file.
      *
-     * It is akin to a checkpoint for when the Workflow gets too long or approaches certain scaling limits.
+     * It acts as a checkpoint when the workflow gets too long or approaches certain scaling limits.
      *
      * It accepts input with the same schema as the parent workflow function (`inputSchema`).
      *
-     * Calling the function needs to be the last statement for the workflow, accompanied by a `return`:
+     * Calling this function must be the last statement in the workflow, accompanied by a `return`:
+     *
+     * @example
      * ```js
      *   return control.continueAsNew();
      * ```
-     * Upon returning it, the parent workflow execution is closed without any output and the new execution takes its place.
+     * Upon returning, the parent workflow execution closes without any output, and the new execution takes its place.
      *
-     * The function return type respects the `outputSchema` although no values are ever returned, the execution is just replaced.
+     * The function's return type matches `outputSchema`; although no value is returned, the execution is replaced.
      *
      * @see {@link https://docs.temporal.io/develop/typescript/continue-as-new}
-     * @param {z.infer<InputSchema>|undefined} input - The input for the new run. Omit when the workflow has no input schema.
-     * @returns {z.infer<OutputSchema>|void} The workflow output type for type-checking; never returns at runtime.
+     *
+     * @param input - The input for the new run. Omit when the workflow has no input schema.
+     * @returns The workflow output type for type-checking; never returns at runtime.
      */
     continueAsNew: InputSchema extends AnyZodSchema ?
       ( input: z.infer<InputSchema> ) => ( OutputSchema extends AnyZodSchema ? z.infer<OutputSchema> : void ) :
@@ -88,206 +228,170 @@ export type WorkflowContext<
      * Prefer returning the `continueAsNew(...)` call immediately when this becomes `true`.
      *
      * @see {@link https://docs.temporal.io/develop/typescript/continue-as-new#how-to-test}
-     * @returns {boolean} True if a continue-as-new is suggested for the current run; otherwise false.
+     *
+     * @returns True if a continue-as-new is suggested for the current run; otherwise false.
      */
     isContinueAsNewSuggested: () => boolean
   }
 };
 
-/*
-╭─────────╮
-│ S T E P │╮
-╰─────────╯│
- ╰─────────╯
-*/
-
-/*
- * There are 4 overloads of the "step" function:
- * - with fn receiving input and returning output;
- * - with fn receiving input and returning void;
- * - with fn receiving void and returning output;
- * - with fn receiving void and returning void;
- */
-
-/**
- * Creates logical unit of work defined schema for both input and output.
- *
- * @param {object} options - Step options
- * @param {string} options.name - Human-readable step name (only letters, numbers and "_")
- * @param {string} [options.description] - Description of the step
- * @param {z.ZodType} options.inputSchema - Zod schema for the fn input
- * @param {z.ZodType} options.outputSchema - Zod schema for the fn output
- * @param {function} options.fn - The function logic: `(input: z.infer<InputSchema>) => Promise<z.infer<OutputSchema>>`
- * @param {Options} [options.options] - Activity retry options
- * @returns {function} Function with signature: `(input: z.infer<InputSchema>) => Promise<z.infer<OutputSchema>>`
- */
-export async function step<
-  InputSchema extends AnyZodSchema,
-  OutputSchema extends AnyZodSchema
->( options: {
-  name: string;
-  description?: string;
-  inputSchema: InputSchema;
-  outputSchema: OutputSchema;
-  fn: ( input: z.infer<InputSchema> ) => Promise<z.infer<OutputSchema>>;
-  options?: Options;
-} ): ( input: z.infer<InputSchema> ) => Promise<z.infer<OutputSchema>>;
-
 /**
- * Creates logical unit of work with defined schema for input only.
- *
- * @param {object} options - Step options
- * @param {string} options.name - Human-readable step name (only letters, numbers and "_")
- * @param {string} [options.description] - Description of the step
- * @param {z.ZodType} options.inputSchema - Zod schema for the fn input
- * @param {function} options.fn - The function logic: `(input: z.infer<InputSchema>) => Promise<void>`
- * @param {Options} [options.options] - Activity retry options
- * @returns {function} Function with signature: `(input: z.infer<InputSchema>) => Promise<void>`
+ * The handler function of a workflow.
+ *
+ * @param input - The workflow input; it matches the schema defined by `inputSchema`.
+ * @param context - A context object with tools and information.
+ *
+ * @returns A value matching the schema defined by `outputSchema`.
  */
-export async function step<
-  InputSchema extends AnyZodSchema
->( options: {
-  name: string;
-  description?: string;
-  inputSchema: InputSchema;
-  fn: ( input: z.infer<InputSchema> ) => Promise<void>;
-  options?: Options;
-} ): ( input: z.infer<InputSchema> ) => Promise<void>;
+export type WorkflowFunction<
+  InputSchema extends AnyZodSchema | undefined = undefined,
+  OutputSchema extends AnyZodSchema | undefined = undefined
+> = InputSchema extends AnyZodSchema ?
+  ( input: z.infer<InputSchema>, context: WorkflowContext<InputSchema, OutputSchema> ) =>
+  Promise<OutputSchema extends AnyZodSchema ? z.infer<OutputSchema> : void> :
+  ( input?: undefined | null, context: WorkflowContext<InputSchema, OutputSchema> ) =>
+  Promise<OutputSchema extends AnyZodSchema ? z.infer<OutputSchema> : void>;
 
 /**
- * Creates logical unit of work with defined schema for output only.
- *
- * @param {object} options - Step options
- * @param {string} options.name - Human-readable step name (only letters, numbers and "_")
- * @param {string} [options.description] - Description of the step
- * @param {z.ZodType} options.outputSchema - Zod schema for the fn output
- * @param {function} options.fn - The function logic: `() => Promise<z.infer<OutputSchema>>`
- * @param {Options} [options.options] - Activity retry options
- * @returns {function} Function with signature: `() => Promise<z.infer<OutputSchema>>`
+ * A wrapper around the user defined `fn` handler function.
+ *
+ * It accepts the same input and returns the same value, calling the user function inside.
+ *
+ * The second argument is a WorkflowInvocationConfiguration object, allowing workflows configuration overwrite.
+ *
+ * It adds input and output validation based on the `inputSchema`, `outputSchema`.
+ *
+ * @param input - The workflow input; it matches the schema defined by `inputSchema`.
+ * @param config - Additional configuration for the invocation.
+ * @returns A value matching the schema defined by `outputSchema`.
  */
-export async function step<
-  OutputSchema extends AnyZodSchema
->( options: {
-  name: string;
-  description?: string;
-  outputSchema: OutputSchema;
-  fn: () => Promise<z.infer<OutputSchema>>;
-  options?: Options;
-} ): () => Promise<z.infer<OutputSchema>>;
+export type WorkflowFunctionWrapper<WorkflowFunction> =
+  [Parameters<WorkflowFunction>[0]] extends [undefined | null] ?
+    ( input?: undefined | null, config?: WorkflowInvocationConfiguration ) => ReturnType<WorkflowFunction> :
+    ( input: Parameters<WorkflowFunction>[0], config?: WorkflowInvocationConfiguration ) => ReturnType<WorkflowFunction>;
 
 /**
- * Creates logical unit of work without schemas.
- *
- * @param {object} options - Step options
- * @param {string} options.name - Human-readable step name (only letters, numbers and "_")
- * @param {string} [options.description] - Description of the step
- * @param {function} options.fn - The function logic: `() => Promise<void>`
- * @param {Options} [options.options] - Activity retry options
- * @returns {function} Function with signature: `() => Promise<void>`
+ * Creates a workflow.
+ *
+ * A workflow is an orchestration of one or more steps. It is translated to a Temporal Workflow.
+ *
+ * The workflow logic is defined in the `fn` handler function.
+ *
+ * The schema of the input that the function receives as the first argument is defined by `inputSchema`.
+ *
+ * The output of the `fn` handler must match `outputSchema`; otherwise, a validation error is raised.
+ *
+ * @remarks
+ * - Workflows should respect the same limitations as Temporal workflows.
+ * - Workflows can invoke steps or evaluators and cannot perform I/O directly.
+ * - The workflow `name` needs to be unique across all workflows in the project.
+ *
+ * @example
+ * ```
+ * import { step } from './my_steps.ts';
+ *
+ * workflow( {
+ *   name: 'main',
+ *   description: 'A generic workflow',
+ *   inputSchema: z.object( {
+ *     value: z.number()
+ *   } ),
+ *   outputSchema: z.string(),
+ *   fn: async input => {
+ *     const result = await step( input.value );
+ *     return result as string;
+ *   }
+ * } )
+ * ```
+ *
+ * @example Workflow without outputSchema
+ * ```
+ * import { step } from './my_steps.ts';
+ *
+ * workflow( {
+ *   name: 'main',
+ *   description: 'A generic workflow',
+ *   inputSchema: z.object( {
+ *     value: z.number()
+ *   } ),
+ *   fn: async input => {
+ *     await step( input.value );
+ *   }
+ * } )
+ * ```
+ *
+ * @example Workflow without inputSchema
+ * ```
+ * import { step } from './my_steps.ts';
+ *
+ * workflow( {
+ *   name: 'main',
+ *   description: 'A generic workflow',
+ *   outputSchema: z.string(),
+ *   fn: async () => {
+ *     const result = await step();
+ *     return result as string;
+ *   }
+ * } )
+ * ```
+ *
+ * @example Workflow without inputSchema and outputSchema
+ * ```
+ * import { step } from './my_steps.ts';
+ *
+ * workflow( {
+ *   name: 'main',
+ *   description: 'A generic workflow',
+ *   fn: async () => {
+ *     await step();
+ *   }
+ * } )
+ * ```
+ *
+ * @example Using continueAsNew
+ * The function `continueAsNew` (same as Temporal) can be used to create a new workflow with the same ID and pass different input.
+ *
+ * ```
+ * import { step } from './my_steps.ts';
+ *
+ * workflow( {
+ *   name: 'main',
+ *   description: 'A generic workflow',
+ *   inputSchema: z.object( {
+ *     value: z.number()
+ *   } ),
+ *   outputSchema: z.string(),
+ *   fn: async ( input, context ) => {
+ *     const result = await step( input.value );
+ *     if ( context.control.isContinueAsNewSuggested() ) {
+ *       return context.control.continueAsNew( input );
+ *     }
+ *
+ *     return result as string;
+ *   }
+ * } )
+ * ```
+ *
+ * @param params - Workflow parameters
+ * @param params.name - Human-readable workflow name (must start with a letter or underscore, followed by letters, numbers, or underscores).
+ * @param params.description - Description of the workflow
+ * @param params.inputSchema - Zod schema for workflow input
+ * @param params.outputSchema - Zod schema for workflow output
+ * @param params.fn - A function containing the workflow code
+ * @param params.options - Temporal Activity options
+ * @returns The same handler function set at `fn` with a different signature
  */
-export async function step( options: {
+export declare function workflow<
+  InputSchema extends AnyZodSchema | undefined = undefined,
+  OutputSchema extends AnyZodSchema | undefined = undefined
+>( params: {
   name: string;
   description?: string;
-  fn: () => Promise<void>;
-  options?: Options;
-} ): () => Promise<void>;
-
-/*
-╭─────────────────╮
-│ W O R K F L O W │╮
-╰─────────────────╯│
- ╰─────────────────╯
-*/
-/*
- * There are 4 overloads of the "workflow" function:
- * - with fn receiving input and returning output;
- * - with fn receiving input and returning void;
- * - with fn receiving void and returning output;
- * - with fn receiving void and returning void;
- */
-
-/**
- * Creates a workflow orchestrator with defined schema for both input and output.
- *
- * @param {object} options - Workflow options
- * @param {string} options.name - Unique workflow name
- * @param {string} [options.description] - Description of the workflow
- * @param {z.ZodType} options.inputSchema - Zod schema for workflow input
- * @param {z.ZodType} options.outputSchema - Zod schema for workflow output
- * @param {function} options.fn - Workflow logic
- * @param {Options} [options.options] - Activity retry options
- * @returns {function} Callable workflow function
- */
-export function workflow<
-  InputSchema extends AnyZodSchema,
-  OutputSchema extends AnyZodSchema
->( options : {
-  name: string,
-  description?: string,
-  inputSchema: InputSchema,
-  outputSchema: OutputSchema,
-  fn: ( input: z.infer<InputSchema>, context: WorkflowContext<InputSchema, OutputSchema> ) => Promise<z.infer<OutputSchema>>,
-  options?: Options
-} ): ( input: z.infer<InputSchema>, extra?: WorkflowCallConfig ) => Promise<z.infer<OutputSchema>>;
-
-/**
- * Creates a workflow orchestrator with defined schema for input only.
- *
- * @param {object} options - Workflow options
- * @param {string} options.name - Unique workflow name
- * @param {string} [options.description] - Description of the workflow
- * @param {z.ZodType} options.inputSchema - Zod schema for workflow input
- * @param {function} options.fn - Workflow logic
- * @param {Options} [options.options] - Activity retry options
- * @returns {function} Callable workflow function
- */
-export function workflow<
-  InputSchema extends AnyZodSchema
->( options : {
-  name: string,
-  description?: string,
-  inputSchema: InputSchema,
-  fn: ( input: z.infer<InputSchema>, context: WorkflowContext<InputSchema, undefined> ) => Promise<void>,
-  options?: Options
-} ): ( input: z.infer<InputSchema>, extra?: WorkflowCallConfig ) => Promise<void>;
-
-/**
- * Creates a workflow orchestrator with defined schema for output only.
- *
- * @param {object} options - Workflow options
- * @param {string} options.name - Unique workflow name
- * @param {string} [options.description] - Description of the workflow
- * @param {z.ZodType} options.outputSchema - Zod schema for workflow output
- * @param {function} options.fn - Workflow logic
- * @param {Options} [options.options] - Activity retry options
- * @returns {function} Callable workflow function
- */
-export function workflow<
-  OutputSchema extends AnyZodSchema
->( options : {
-  name: string,
-  description?: string,
-  outputSchema: OutputSchema,
-  fn: ( input?: undefined | null, context: WorkflowContext<undefined, OutputSchema> ) => Promise<z.infer<OutputSchema>>,
-  options?: Options
-} ): ( input?: undefined | null, extra?: WorkflowCallConfig ) => Promise<z.infer<OutputSchema>>;
-
-/**
- * Creates a workflow orchestrator without defined schemas.
- *
- * @param {object} options - Workflow options
- * @param {string} options.name - Unique workflow name
- * @param {string} [options.description] - Description of the workflow
- * @param {function} options.fn - Workflow logic
- * @param {Options} [options.options] - Activity retry options
- * @returns {function} Callable workflow function
- */
-export function workflow( options : {
-  name: string,
-  description?: string,
-  fn: ( input?: undefined | null, context: WorkflowContext<undefined, undefined> ) => Promise<void>,
-  options?: Options
-} ): ( input?: undefined | null, extra?: WorkflowCallConfig ) => Promise<void>;
+  inputSchema?: InputSchema;
+  outputSchema?: OutputSchema;
+  fn: WorkflowFunction<InputSchema, OutputSchema>;
+  options?: TemporalActivityOptions;
+} ): WorkflowFunctionWrapper<WorkflowFunction<InputSchema, OutputSchema>>;
 
 /*
 ╭───────────────────╮
@@ -297,31 +401,32 @@ export function workflow( options : {
 */
 
 /**
- * Generic EvaluationResult class, represents the result of an evaluation
+ * Represents the result of an evaluation.
+ *
+ * Generic base class; evaluators must return an instance of an EvaluationResult subclass.
  */
-class EvaluationResult {
+export class EvaluationResult {
   /**
    * @constructor
-   * @param {object} args
-   * @param {any} args.value - The value of the evaluation
-   * @param {number} args.confidence - The confidence on the evaluation
-   * @param {string} [args.reasoning] - The reasoning behind the result
+   * @param args
+   * @param args.value - The value of the evaluation
+   * @param args.confidence - The confidence in the evaluation
+   * @param args.reasoning - The reasoning behind the result
    */
   constructor( args: { value: any; confidence: number; reasoning?: string } ); // eslint-disable-line @typescript-eslint/no-explicit-any
 
   /**
-   * @returns {any} The evaluation result value
+   * @returns The evaluation result value
    */
-
   get value(): any; // eslint-disable-line @typescript-eslint/no-explicit-any
 
   /**
-   * @returns {number} The evaluation result confidence
+   * @returns The evaluation result confidence
    */
   get confidence(): number;
 
   /**
-   * @returns {string} The evaluation result reasoning
+   * @returns The evaluation result reasoning
    */
   get reasoning(): string;
 }
@@ -333,15 +438,15 @@ class EvaluationResult {
 export class EvaluationStringResult extends EvaluationResult {
   /**
    * @constructor
-   * @param {object} args
-   * @param {string} args.value - The value of the evaluation
-   * @param {number} args.confidence - The confidence on the evaluation
-   * @param {string} [args.reasoning] - The reasoning behind the result
+   * @param args
+   * @param args.value - The value of the evaluation
+   * @param args.confidence - The confidence on the evaluation
+   * @param args.reasoning - The reasoning behind the result
    */
   constructor( args: { value: string; confidence: number; reasoning?: string } );
 
   /**
-   * @returns {string} The evaluation result value
+   * @returns The evaluation result value
    */
   get value(): string;
 }
@@ -353,15 +458,15 @@ export class EvaluationStringResult extends EvaluationResult {
 export class EvaluationNumberResult extends EvaluationResult {
   /**
    * @constructor
-   * @param {object} args
-   * @param {number} args.value - The value of the evaluation
-   * @param {number} args.confidence - The confidence on the evaluation
-   * @param {string} [args.reasoning] - The reasoning behind the result
+   * @param args
+   * @param args.value - The value of the evaluation
+   * @param args.confidence - The confidence on the evaluation
+   * @param args.reasoning - The reasoning behind the result
    */
   constructor( args: { value: number; confidence: number; reasoning?: string } );
 
   /**
-   * @returns {number} The evaluation result value
+   * @returns The evaluation result value
    */
   get value(): number;
 }
@@ -373,71 +478,72 @@ export class EvaluationNumberResult extends EvaluationResult {
 export class EvaluationBooleanResult extends EvaluationResult {
   /**
    * @constructor
-   * @param {object} args
-   * @param {boolean} args.value - The value of the evaluation
-   * @param {number} args.confidence - The confidence on the evaluation
-   * @param {string} [args.reasoning] - The reasoning behind the result
+   * @param args
+   * @param args.value - The value of the evaluation
+   * @param args.confidence - The confidence on the evaluation
+   * @param args.reasoning - The reasoning behind the result
    */
   constructor( args: { value: boolean; confidence: number; reasoning?: string } );
 
   /**
-   * @returns {boolean} The evaluation result value
+   * @returns The evaluation result value
    */
   get value(): boolean;
 }
 
-/*
- * There are 2 overloads of the "evaluator" function:
- * - with fn receiving input;
- * - with fn receiving void;
+/**
+ * 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>;
 
 /**
- * Creates workflow evaluation of work defined schema for input.
- *
- * @param {object} options - Evaluator options
- * @param {string} options.name - Human-readable evaluator name (only letters, numbers and "_")
- * @param {string} [options.description] - Description of the evaluator
- * @param {z.ZodType} options.inputSchema - Zod schema for the fn input
- * @param {function} options.fn - The function logic: `(input: z.infer<InputSchema>) => Promise<z.infer<OutputSchema>>`
- * @param {Options} [options.options] - Activity retry options
- * @returns {function} Function with signature: `(input: z.infer<InputSchema>) => Promise<z.infer<OutputSchema>>`
+ * 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 async function evaluator<
-  InputSchema extends AnyZodSchema,
-  Result extends EvaluationResult
->( options: {
-  name: string;
-  description?: string;
-  inputSchema: InputSchema;
-  fn: ( input: z.infer<InputSchema> ) => Promise<Result>;
-  options?: Options;
-} ): ( input: z.infer<InputSchema> ) => Promise<Result>;
+export type EvaluatorFunctionWrapper<EvaluatorFunction> =
+  Parameters<EvaluatorFunction> extends [infer Input] ?
+    ( input: Input ) => ReturnType<EvaluatorFunction> :
+    () => ReturnType<EvaluatorFunction>;
 
 /**
- * Creates workflow evaluation without a defined input schema.
- *
- * @param {object} options - Evaluator options
- * @param {string} options.name - Human-readable evaluator name (only letters, numbers and "_")
- * @param {string} [options.description] - Description of the evaluator
- * @param {z.ZodType} options.inputSchema - Zod schema for the fn input
- * @param {function} options.fn - The function logic: `(input: z.infer<InputSchema>) => Promise<z.infer<OutputSchema>>`
- * @param {Options} [options.options] - Activity retry options
- * @returns {function} Function with signature: `(input: z.infer<InputSchema>) => Promise<z.infer<OutputSchema>>`
+ * Creates an evaluation function. It is similar to a step, but must return an EvaluationResult.
+ *
+ * It is translated to a Temporal Activity.
+ *
+ * @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 - Temporal Activity options
+ * @returns A wrapper function around the `fn` function
  */
-export async function evaluator<
+export declare function evaluator<
   InputSchema extends AnyZodSchema,
   Result extends EvaluationResult
->( options: {
+>( params: {
   name: string;
   description?: string;
-  fn: ( input: z.infer<InputSchema> ) => Promise<Result>;
-  options?: Options;
-} ): ( input: z.infer<InputSchema> ) => Promise<Result>;
+  inputSchema: InputSchema;
+  fn: EvaluatorFunction<InputSchema, Result>;
+  options?: TemporalActivityOptions;
+} ): EvaluatorFunctionWrapper<EvaluatorFunction<InputSchema, Result>>;
 
 /*
 ╭───────────╮
-│ O T H E R │╮
+│ T O O L S │╮
 ╰───────────╯│
  ╰───────────╯
 */
@@ -448,23 +554,32 @@ export async function evaluator<
  * Sends a request via an activity; the workflow will await a corresponding
  * resume signal to continue and return the response payload.
  *
- * @param {object} options - Webhook request options
- * @param {string} options.url - Webhook request url (POST)
- * @param {object} [options.payload] - Webhook request payload
- * @returns {Promise<object>} Resolves with the response payload when resumed
+ * @param params - Webhook request parameters
+ * @param params.url - Webhook request URL (POST)
+ * @param params.payload - Webhook request payload
+ * @returns Resolves with the response payload when resumed
  */
-export function createWebhook( options: { url: string; payload?: object } ): Promise<object>;
+export declare function createWebhook( params: { url: string; payload?: object } ): Promise<object>;
+
+/*
+╭─────────────╮
+│ E R R O R S │╮
+╰─────────────╯│
+ ╰─────────────╯
+*/
 
 /**
  * Error indicating a non-recoverable failure.
  *
- * Use for failures that should not be retried by the workflow runtime.
+ * Throw this error to end the workflow execution altogether without retries.
  */
 export class FatalError extends Error {}
 
 /**
  * Error indicating invalid input or schema validation issues.
  *
- * Use for problems detected during input validation or contract checks.
+ * This error is thrown when there are validation errors, either in the input or output, for steps, evaluators, and workflows.
+ *
+ * It will end the workflow execution without retries.
  */
 export class ValidationError extends Error {}