@output.ai/core 0.0.15 → 0.1.0

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,24 +1,28 @@
 {
   "name": "@output.ai/core",
-  "version": "0.0.15",
+  "version": "0.1.0",
   "description": "The core module of the output framework",
   "type": "module",
-  "main": "src/index.js",
-  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./tracing": {
+      "types": "./src/tracing/index.d.ts",
+      "import": "./src/tracing/index.js"
+    }
+  },
   "files": [
     "./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,10 +33,13 @@
     "@temporalio/workflow": "1.13.0",
     "zod": "4.1.9"
   },
+  "license": "UNLICENSED",
   "imports": {
     "#consts": "./src/consts.js",
     "#configs": "./src/configs.js",
     "#errors": "./src/errors.js",
+    "#tracing": "./src/tracing/index.js",
+    "#async_storage": "./src/async_storage.js",
     "#internal_activities": "./src/internal_activities/index.js"
   }
 }

package/src/configs.js

@@ -7,8 +7,7 @@ const envVarSchema = z.object( {
   TEMPORAL_NAMESPACE: z.string().optional().default( 'default' ),
   TEMPORAL_API_KEY: z.string().optional(),
   CATALOG_ID: z.string().regex( /^[a-z0-9_.@-]+$/i ),
-  API_AUTH_KEY: z.string().optional(),
-  TRACING_ENABLED: z.stringbool().optional()
+  API_AUTH_KEY: z.string().optional()
 } );
 
 const { data: safeEnvVar, error } = envVarSchema.safeParse( process.env );
@@ -30,7 +29,3 @@ export const worker = {
 export const api = {
   authKey: safeEnvVar.API_AUTH_KEY
 };
-
-export const tracing = {
-  enabled: safeEnvVar.TRACING_ENABLED
-};

package/src/configs.spec.js

@@ -181,38 +181,6 @@ describe( 'configs', () => {
         const { api } = await import( './configs.js' );
         expect( api.authKey ).toBeUndefined();
       } );
-
-      it( 'should handle TRACING_ENABLED when true', async () => {
-        process.env = {
-          TEMPORAL_ADDRESS: 'http://localhost:7233',
-          CATALOG_ID: 'test-catalog',
-          TRACING_ENABLED: 'true'
-        };
-
-        const { tracing } = await import( './configs.js' );
-        expect( tracing.enabled ).toBe( true );
-      } );
-
-      it( 'should handle TRACING_ENABLED when false', async () => {
-        process.env = {
-          TEMPORAL_ADDRESS: 'http://localhost:7233',
-          CATALOG_ID: 'test-catalog',
-          TRACING_ENABLED: 'false'
-        };
-
-        const { tracing } = await import( './configs.js' );
-        expect( tracing.enabled ).toBe( false );
-      } );
-
-      it( 'should handle missing TRACING_ENABLED', async () => {
-        process.env = {
-          TEMPORAL_ADDRESS: 'http://localhost:7233',
-          CATALOG_ID: 'test-catalog'
-        };
-
-        const { tracing } = await import( './configs.js' );
-        expect( tracing.enabled ).toBeUndefined();
-      } );
     } );
   } );
 
@@ -253,20 +221,6 @@ describe( 'configs', () => {
       } );
     } );
 
-    it( 'should export tracing config', async () => {
-      process.env = {
-        TEMPORAL_ADDRESS: 'http://localhost:7233',
-        CATALOG_ID: 'test-catalog',
-        TRACING_ENABLED: 'true'
-      };
-
-      const { tracing } = await import( './configs.js' );
-
-      expect( tracing ).toEqual( {
-        enabled: true
-      } );
-    } );
-
     it( 'should have correct static worker config values', async () => {
       process.env = {
         TEMPORAL_ADDRESS: 'http://localhost:7233',
@@ -361,11 +315,10 @@ describe( 'configs', () => {
         TEMPORAL_NAMESPACE: 'production',
         TEMPORAL_API_KEY: 'prod-api-key-123',
         CATALOG_ID: 'prod.catalog@v1',
-        API_AUTH_KEY: 'secure-auth-key',
-        TRACING_ENABLED: 'true'
+        API_AUTH_KEY: 'secure-auth-key'
       };
 
-      const { worker, api, tracing } = await import( './configs.js' );
+      const { worker, api } = await import( './configs.js' );
 
       expect( worker.address ).toBe( 'https://temporal.cloud.example.com' );
       expect( worker.namespace ).toBe( 'production' );
@@ -373,7 +326,6 @@ describe( 'configs', () => {
       expect( worker.catalogId ).toBe( 'prod.catalog@v1' );
       expect( worker.taskQueue ).toBe( 'prod.catalog@v1' );
       expect( api.authKey ).toBe( 'secure-auth-key' );
-      expect( tracing.enabled ).toBe( true );
     } );
   } );
 } );

package/src/consts.js

@@ -1,11 +1,9 @@
-export const SEND_WEBHOOK_ACTIVITY_NAME = '__internal#sendWebhookPost';
-export const READ_TRACE_FILE = '__internal#readTraceFile';
+export const ACTIVITY_SEND_WEBHOOK = '__internal#sendWebhook';
+export const ACTIVITY_READ_TRACE_FILE = '__internal#readTraceFile';
 export const METADATA_ACCESS_SYMBOL = Symbol( '__metadata' );
 export const WORKFLOWS_INDEX_FILENAME = '__workflows_entrypoint.js';
-export const THIS_LIB_NAME = 'core';
-export const TraceEvent = {
-  WORKFLOW_START: 'workflow_start',
-  WORKFLOW_END: 'workflow_end',
-  STEP_START: 'step_start',
-  STEP_END: 'step_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.STEP } );
   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;