@output.ai/core 0.0.14 → 0.0.16

package/bin/worker.sh

@@ -18,7 +18,7 @@ fi
 # Get the real script directory (should be node_modules/<pkg>/bin)
 script_dir="$(cd "$(dirname "$real_script")" && pwd)"
 
-# SDK dir is the parent (node_modules/flow-core)
+# SDK dir is the parent (node_modules/output-core)
 sdk_dir="$(dirname "$script_dir")"
 
 cd ${sdk_dir}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@output.ai/core",
-  "version": "0.0.14",
+  "version": "0.0.16",
   "description": "The core module of the output framework",
   "type": "module",
   "main": "src/index.js",
@@ -9,16 +9,12 @@
     "./src",
     "./bin"
   ],
-  "scripts": {
-    "worker": "node ./src/worker/index.js"
-  },
   "bin": {
-    "flow-worker": "./bin/worker.sh",
+    "output-worker": "./bin/worker.sh",
     "outputai": "./bin/worker.sh"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/growthxai/flow-sdk"
+  "scripts": {
+    "worker": "node ./src/worker/index.js"
   },
   "dependencies": {
     "@babel/generator": "7.28.3",
@@ -29,6 +25,7 @@
     "@temporalio/workflow": "1.13.0",
     "zod": "4.1.9"
   },
+  "license": "UNLICENSED",
   "imports": {
     "#consts": "./src/consts.js",
     "#configs": "./src/configs.js",

package/src/consts.js

@@ -7,5 +7,12 @@ export const TraceEvent = {
   WORKFLOW_START: 'workflow_start',
   WORKFLOW_END: 'workflow_end',
   STEP_START: 'step_start',
-  STEP_END: 'step_end'
+  STEP_END: 'step_end',
+  EVALUATOR_START: 'evaluator_start',
+  EVALUATOR_END: 'evaluator_end'
+};
+export const ComponentType = {
+  EVALUATOR: 'evaluator',
+  INTERNAL_STEP: 'internal_step',
+  STEP: 'step'
 };

package/src/index.d.ts

@@ -19,6 +19,13 @@ export { z } from 'zod';
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type AnyZodSchema = z.ZodType<any, any, any>;
 
+/*
+╭─────────╮
+│ S T E P │╮
+╰─────────╯│
+ ╰─────────╯
+*/
+
 /*
  * There are 4 overloads of the "step" function:
  * - with fn receiving input and returning output;
@@ -28,7 +35,7 @@ type AnyZodSchema = z.ZodType<any, any, any>;
  */
 
 /**
- * Creates logical unit of work with Zod schemas for both input and output.
+ * 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 "_")
@@ -50,7 +57,7 @@ export async function step<
 } ): ( input: z.infer<InputSchema> ) => Promise<z.infer<OutputSchema>>;
 
 /**
- * Creates logical unit of work with Zod schema for input only.
+ * 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 "_")
@@ -69,7 +76,7 @@ export async function step<
 } ): ( input: z.infer<InputSchema> ) => Promise<void>;
 
 /**
- * Creates logical unit of work with Zod schema for output only.
+ * 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 "_")
@@ -102,6 +109,12 @@ export async function step( options: {
   fn: () => Promise<void>;
 } ): () => 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;
@@ -111,7 +124,7 @@ export async function step( options: {
  */
 
 /**
- * Creates a workflow orchestrator with Zod schemas for both input and output.
+ * Creates a workflow orchestrator defined schema for both input and output.
  *
  * @param {object} options - Workflow options
  * @param {string} options.name - Unique workflow name
@@ -133,7 +146,7 @@ export function workflow<
 } ): ( input: z.infer<InputSchema> ) => Promise<z.infer<OutputSchema>>;
 
 /**
- * Creates a workflow orchestrator with Zod schema for input only.
+ * Creates a workflow orchestrator with defined schema for input only.
  *
  * @param {object} options - Workflow options
  * @param {string} options.name - Unique workflow name
@@ -152,7 +165,7 @@ export function workflow<
 } ): ( input: z.infer<InputSchema> ) => Promise<void>;
 
 /**
- * Creates a workflow orchestrator with Zod schema for output only.
+ * Creates a workflow orchestrator with defined schema for output only.
  *
  * @param {object} options - Workflow options
  * @param {string} options.name - Unique workflow name
@@ -171,7 +184,7 @@ export function workflow<
 } ): () => Promise<z.infer<OutputSchema>>;
 
 /**
- * Creates a workflow orchestrator without schemas.
+ * Creates a workflow orchestrator without defined schemas.
  *
  * @param {object} options - Workflow options
  * @param {string} options.name - Unique workflow name
@@ -185,6 +198,155 @@ export function workflow( options : {
   fn: () => Promise<void>
 } ): () => Promise<void>;
 
+/*
+╭───────────────────╮
+│ E V A L U A T O R │╮
+╰───────────────────╯│
+ ╰───────────────────╯
+*/
+
+/**
+ * Generic EvaluationResult class, represents the result of an evaluation
+ */
+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
+   */
+  constructor( args: { value: any; confidence: number; reasoning?: string } ); // eslint-disable-line @typescript-eslint/no-explicit-any
+
+  /**
+   * @returns {any} The evaluation result value
+   */
+
+  get value(): any; // eslint-disable-line @typescript-eslint/no-explicit-any
+
+  /**
+   * @returns {number} The evaluation result confidence
+   */
+  get confidence(): number;
+
+  /**
+   * @returns {string} The evaluation result reasoning
+   */
+  get reasoning(): string;
+}
+
+/**
+ * An evaluation result where the value is a string
+ * @extends 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
+   */
+  constructor( args: { value: string; confidence: number; reasoning?: string } );
+
+  /**
+   * @returns {string} The evaluation result value
+   */
+  get value(): string;
+}
+
+/**
+ * An evaluation result where the value is a number
+ * @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
+   */
+  constructor( args: { value: number; confidence: number; reasoning?: string } );
+
+  /**
+   * @returns {number} The evaluation result value
+   */
+  get value(): number;
+}
+
+/**
+ * An evaluation result where the value is a boolean
+ * @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
+   */
+  constructor( args: { value: boolean; confidence: number; reasoning?: string } );
+
+  /**
+   * @returns {boolean} The evaluation result value
+   */
+  get value(): boolean;
+}
+
+/*
+ * There are 2 overloads of the "evaluator" function:
+ * - with fn receiving input;
+ * - with fn receiving void;
+ */
+
+/**
+ * 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>>`
+ * @returns {function} Function with signature: `(input: z.infer<InputSchema>) => Promise<z.infer<OutputSchema>>`
+ */
+export async function evaluator<
+  InputSchema extends AnyZodSchema,
+  Result extends EvaluationResult
+>( options: {
+  name: string;
+  description?: string;
+  inputSchema: InputSchema;
+  fn: ( input: z.infer<InputSchema> ) => Promise<Result>;
+} ): ( input: z.infer<InputSchema> ) => Promise<Result>;
+
+/**
+ * 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>>`
+ * @returns {function} Function with signature: `(input: z.infer<InputSchema>) => Promise<z.infer<OutputSchema>>`
+ */
+export async function evaluator<
+  InputSchema extends AnyZodSchema,
+  Result extends EvaluationResult
+>( options: {
+  name: string;
+  description?: string;
+  fn: ( input: z.infer<InputSchema> ) => Promise<Result>;
+} ): ( input: z.infer<InputSchema> ) => Promise<Result>;
+
+/*
+╭───────────╮
+│ O T H E R │╮
+╰───────────╯│
+ ╰───────────╯
+*/
+
 /**
  * Create a webhook call that pauses the workflow until resumed via signal.
  *

package/src/index.js

@@ -1,7 +1,24 @@
+import { evaluator, EvaluationStringResult, EvaluationNumberResult, EvaluationBooleanResult } from './interface/evaluator.js';
 import { step } from './interface/step.js';
 import { workflow } from './interface/workflow.js';
 import { createWebhook } from './interface/webhook.js';
 import { FatalError, ValidationError } from './errors.js';
 import { z } from 'zod';
 
-export { step, workflow, createWebhook, FatalError, ValidationError, z };
+export {
+  // base building blocks
+  evaluator,
+  step,
+  workflow,
+  // Evaluation results
+  EvaluationNumberResult,
+  EvaluationStringResult,
+  EvaluationBooleanResult,
+  // webhook tool
+  createWebhook,
+  // errors
+  FatalError,
+  ValidationError,
+  // zod
+  z
+};

package/src/interface/evaluator.js

@@ -0,0 +1,146 @@
+import { setMetadata } from './metadata.js';
+import { validateEvaluator } from './validations/static.js';
+import { validateWithSchema } from './validations/runtime.js';
+import { ValidationError } from '#errors';
+import { ComponentType } from '#consts';
+import * as z from 'zod';
+
+/**
+ * Error for when EvaluationResult are invalid
+ */
+class EvaluationResultValidationError extends ValidationError {};
+
+/**
+ * Generic EvaluationResult class, represents the result
+ * of an evaluation
+ */
+export class EvaluationResult {
+
+  /**
+   * Returns the evaluation result value
+   * @type {any}
+   */
+  value = null;
+
+  /**
+   * Returns the confidence value, between 0 and 1.
+   * @type {number}
+   */
+  confidence = undefined;
+
+  /**
+   * Returns the reasoning value.
+   * @type {string}
+   */
+  reasoning = undefined;
+
+  static #schema = z.object( {
+    value: z.any(),
+    confidence: z.number(),
+    reasoning: z.string().optional()
+  } );
+
+  /**
+   * @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
+   */
+  constructor( args ) {
+    if ( !EvaluationResult.#schema.safeParse( args ) ) {
+      throw new EvaluationResultValidationError( z.prettifyError( result.error ) );
+    }
+    this.value = args.value;
+    this.confidence = args.confidence;
+    this.reasoning = args.reasoning;
+  }
+};
+
+/**
+ * An evaluation result that uses a string value
+ * @extends EvaluationResult
+ * @property {string} value - The evaluation result value
+ */
+export class EvaluationStringResult extends EvaluationResult {
+  static #valueSchema = z.string();
+
+  /**
+   * @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
+   */
+  constructor( args ) {
+    if ( !EvaluationStringResult.#valueSchema.safeParse( args.value ) ) {
+      throw new EvaluationResultValidationError( z.prettifyError( result.error ) );
+    }
+    super( args );
+  }
+};
+
+/**
+ * An evaluation result that uses a boolean value
+ * @extends EvaluationResult
+ * @property {boolean} value - The evaluation result value
+ */
+export class EvaluationBooleanResult extends EvaluationResult {
+  static #valueSchema = z.boolean();
+
+  /**
+   * @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
+   */
+  constructor( args ) {
+    if ( !EvaluationBooleanResult.#valueSchema.safeParse( args.value ) ) {
+      throw new EvaluationResultValidationError( z.prettifyError( result.error ) );
+    }
+    super( args );
+  }
+};
+
+/**
+ * An evaluation result that uses a number value
+ * @extends EvaluationResult
+ * @property {number} value - The evaluation result value
+ */
+export class EvaluationNumberResult extends EvaluationResult {
+  static #valueSchema = z.number();
+
+  /**
+   * @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
+   */
+  constructor( args ) {
+    if ( !EvaluationNumberResult.#valueSchema.safeParse( args.value ) ) {
+      throw new EvaluationResultValidationError( z.prettifyError( result.error ) );
+    }
+    super( args );
+  }
+};
+
+export function evaluator( { name, description, inputSchema, fn } ) {
+  validateEvaluator( { name, description, inputSchema, fn } );
+
+  const wrapper = async input => {
+    validateWithSchema( inputSchema, input, `Evaluator ${name} input` );
+
+    const output = await fn( input );
+
+    if ( !output instanceof EvaluationResult ) {
+      throw new ValidationError( 'Evaluators must return an EvaluationResult' );
+    }
+
+    return output;
+  };
+
+  setMetadata( wrapper, { name, description, inputSchema, type: ComponentType.EVALUATOR } );
+  return wrapper;
+};

package/src/interface/step.js

@@ -1,15 +1,10 @@
 import { setMetadata } from './metadata.js';
 import { validateStep } from './validations/static.js';
-import { validateWithSchema } from './schema_utils.js';
+import { validateWithSchema } from './validations/runtime.js';
+import { ComponentType } from '#consts';
 
 export function step( { name, description, inputSchema, outputSchema, fn } ) {
-  validateStep( {
-    name,
-    description,
-    inputSchema,
-    outputSchema,
-    fn
-  } );
+  validateStep( { name, description, inputSchema, outputSchema, fn } );
 
   const wrapper = async input => {
     validateWithSchema( inputSchema, input, `Step ${name} input` );
@@ -21,6 +16,6 @@ export function step( { name, description, inputSchema, outputSchema, fn } ) {
     return output;
   };
 
-  setMetadata( wrapper, { name, description, inputSchema, outputSchema } );
+  setMetadata( wrapper, { name, description, inputSchema, outputSchema, type: ComponentType.EVALUATOR } );
   return wrapper;
 };

package/src/interface/{schema_utils.js → validations/runtime.js}

@@ -1,18 +1,5 @@
 import { ValidationError } from '#errors';
 
-/**
- * Detects if a schema is a Zod schema object
- * @param {unknown} schema - The schema to check
- * @returns {boolean} True if the schema is a Zod schema
- */
-export function isZodSchema( schema ) {
-  return schema &&
-         typeof schema === 'object' &&
-         '_def' in schema &&
-         typeof schema.parse === 'function' &&
-         typeof schema.parseAsync === 'function';
-}
-
 /**
  * Validates data against a Zod schema using safeParse
  * @param {unknown} schema - The Zod schema to validate against
@@ -31,4 +18,3 @@ export function validateWithSchema( schema, data, context ) {
     throw new ValidationError( `${context} validation failed: ${result.error.message}` );
   }
 }
-

package/src/interface/validations/runtime.spec.js

@@ -0,0 +1,29 @@
+import { describe, it, expect } from 'vitest';
+import { z } from 'zod';
+import { validateWithSchema } from './runtime.js';
+import { ValidationError } from '#errors';
+
+describe( 'runtime validations', () => {
+  describe( 'validateWithSchema', () => {
+    it( 'no-ops when schema is falsy', () => {
+      expect( () => validateWithSchema( undefined, { a: 1 }, 'X' ) ).not.toThrow();
+      expect( () => validateWithSchema( null, { a: 1 }, 'X' ) ).not.toThrow();
+    } );
+
+    it( 'passes on valid data', () => {
+      const schema = z.object( { a: z.string(), b: z.number().optional() } );
+      expect( () => validateWithSchema( schema, { a: 'ok' }, 'Test' ) ).not.toThrow();
+    } );
+
+    it( 'throws ValidationError on invalid data and prefixes context', () => {
+      const schema = z.object( { a: z.string() } );
+      const call = () => validateWithSchema( schema, { a: 1 }, 'MyCtx' );
+      expect( call ).toThrow( ValidationError );
+      try {
+        call();
+      } catch ( e ) {
+        expect( String( e.message ) ).toContain( 'MyCtx validation failed:' );
+      }
+    } );
+  } );
+} );

package/src/interface/validations/schema_utils.js

@@ -0,0 +1,8 @@
+import { ZodType } from 'zod';
+
+/**
+ * Detects if a schema is a ZodType instance
+ * @param {unknown} schema - The schema to check
+ * @returns {boolean} True if the schema is a Zod schema
+ */
+export const isZodSchema = schema => schema instanceof ZodType;

package/src/interface/validations/static.js

@@ -1,5 +1,5 @@
 import * as z from 'zod';
-import { isZodSchema } from '../schema_utils.js';
+import { isZodSchema } from './schema_utils.js';
 
 /**
  * Error is thrown when the definition of a step/workflow has problems
@@ -25,6 +25,8 @@ const stepAndWorkflowSchema = z.object( {
   fn: z.function()
 } );
 
+const evaluatorSchema = stepAndWorkflowSchema.omit( { outputSchema: true } );
+
 const webhookSchema = z.object( {
   url: z.url( { protocol: /^https?$/ } ),
   payload: z.any().optional()
@@ -47,6 +49,16 @@ export function validateStep( args ) {
   validateAgainstSchema( stepAndWorkflowSchema, args );
 };
 
+/**
+ * Validate evaluator payload
+ *
+ * @param {object} args - The evaluator arguments
+ * @throws {StaticValidationError} Throws if args are invalid
+ */
+export function validateEvaluator( args ) {
+  validateAgainstSchema( evaluatorSchema, args );
+};
+
 /**
  * Validate workflow payload
  *

package/src/interface/validations/static.spec.js

@@ -1,6 +1,6 @@
 import { describe, it, expect } from 'vitest';
 import { z } from 'zod';
-import { validateStep, validateWorkflow, validateCreateWebhook, StaticValidationError } from './static.js';
+import { validateStep, validateWorkflow, validateCreateWebhook, validateEvaluator, StaticValidationError } from './static.js';
 
 const validArgs = Object.freeze( {
   name: 'valid_name',
@@ -73,6 +73,34 @@ describe( 'interface/validator', () => {
     } );
   } );
 
+  describe( 'validateEvaluator', () => {
+    const base = Object.freeze( {
+      name: 'valid_name',
+      description: 'desc',
+      inputSchema: z.object( {} ),
+      fn: () => {}
+    } );
+
+    it( 'passes for valid args (no outputSchema)', () => {
+      expect( () => validateEvaluator( { ...base } ) ).not.toThrow();
+    } );
+
+    it( 'rejects invalid name pattern', () => {
+      const error = new StaticValidationError( '✖ Invalid string: must match pattern /^[a-z_][a-z0-9_]*$/i\n  → at name' );
+      expect( () => validateEvaluator( { ...base, name: '-bad' } ) ).toThrow( error );
+    } );
+
+    it( 'rejects non-Zod inputSchema', () => {
+      const error = new StaticValidationError( '✖ Schema must be a Zod schema\n  → at inputSchema' );
+      expect( () => validateEvaluator( { ...base, inputSchema: 'not-a-zod-schema' } ) ).toThrow( error );
+    } );
+
+    it( 'rejects missing fn', () => {
+      const error = new StaticValidationError( '✖ Invalid input: expected function, received undefined\n  → at fn' );
+      expect( () => validateEvaluator( { ...base, fn: undefined } ) ).toThrow( error );
+    } );
+  } );
+
   describe( 'validate webhook', () => {
     it( 'passes with valid http url', () => {
       expect( () => validateCreateWebhook( { url: 'http://example.com' } ) ).not.toThrow();

package/src/interface/workflow.js

@@ -4,8 +4,8 @@ import { getInvocationDir } from './utils.js';
 import { setMetadata } from './metadata.js';
 import { FatalError, ValidationError } from '#errors';
 import { validateWorkflow } from './validations/static.js';
+import { validateWithSchema } from './validations/runtime.js';
 import { READ_TRACE_FILE, TraceEvent } from '#consts';
-import { validateWithSchema } from './schema_utils.js';
 
 const temporalActivityConfigs = {
   startToCloseTimeout: '20 minute',
@@ -19,13 +19,7 @@ const temporalActivityConfigs = {
 };
 
 export function workflow( { name, description, inputSchema, outputSchema, fn } ) {
-  validateWorkflow( {
-    name,
-    description,
-    inputSchema,
-    outputSchema,
-    fn
-  } );
+  validateWorkflow( { name, description, inputSchema, outputSchema, fn } );
   const workflowPath = getInvocationDir();
 
   const steps = proxyActivities( temporalActivityConfigs );
@@ -53,6 +47,7 @@ export function workflow( { name, description, inputSchema, outputSchema, fn } )
       // binds the methods called in the code that  Webpack loader will add, they will exposed via "this"
       const output = await fn.call( {
         invokeStep: async ( stepName, input ) => steps[`${workflowPath}#${stepName}`]( input ),
+        invokeEvaluator: async ( evaluatorName, input ) => steps[`${workflowPath}#${evaluatorName}`]( input ),
 
         startWorkflow: async ( childName, input ) => {