@output.ai/core 0.0.8 → 0.0.10

package/README.md

@@ -1,64 +1,100 @@
 # Core
 
-Provides tools to run a workflow, which is a well defined logical unit of work.
+Provides tools to develop and run a workflow, which is a well defined logical unit of work.
 
-## step()
+## Structure
 
-Defines a step, which is a enclosed unit of work which can import external dependencies.
+Workflows are defined using core functions "workflow" and "step", separate files:
 
-```ts
-import { step } from 'flow-core';
+```
+└ workflows
+  └ example
+    ├ workflow.ts|js <- workflow entry point
+    ├ steps.ts|js <- file with each step of this workflow
+    └ prompt.prompt <- a prompt file
+  └ other-example
 
-export const aSingleStep = step( {
-  name: 'aSingleStep',
-  fn: async (): Promise<string> => {
-    // do stuff
-  }
-} );
 ```
 
-All step needs a name, and the name will be used in the context of the workflow (see below).
+Think that workflows is the orchestrator and steps are executors. So the workflow only call the steps and the steps call the IO operations, like APIs, DBs, LLMs, etc.
 
-## workflow()
+## Workflow code
 
-Defines a logical structure of step invocations. No external dependencies can be imported in the file containing the workflow.
+### workflow.js
 
-```ts
-import { workflow } from 'flow-core';
-import type { WorkflowContext } from 'flow-core';
-import type { PromptWorkflowInput, PromptWorkflowOutput } from './types';
+```js
+import { workflow } from '@output.ai/workflow';
+import { guessByName } from './steps.js';
 
 export default workflow( {
-  name: 'prompt',
-  description: 'A workflow to demonstrate the prompt feature',
-  fn: async ( input: PromptWorkflowInput, context: WorkflowContext ): Promise<PromptWorkflowOutput> => {
-    const result = await context.steps.aSingleStep();
-
-    return { result };
+  name: 'guessMyProfession',
+  description: 'Guess a person profession by its name',
+  inputSchema: {
+    type: 'object',
+    required: [ 'name' ],
+    properties: {
+      name: { type: 'string'}
+    }
+  },
+  outputSchema: {
+    type: 'object',
+    required: [ 'profession' ],
+    properties: {
+      profession: { type: 'string'}
+    }
+  },
+  fn: async input => {
+    const profession = await guessByName( input.name );
+    return { profession };
   }
-} );
+})
 ```
 
-The workflow Context has the following properties:
+### steps.js
 
-### .steps.*()
+```js
+import { api } from './api.js'
 
-Each step defined in the step file is available here as js function with the "name" it was defined there. The input arguments are the input arguments of its `fn` function.
+export const guessByName = step( {
+  name: 'guessByName',
+  inputSchema: {
+    type: 'string'
+  },
+  outputSchema: {
+    type: 'string'
+  },
+  fn: async name => {
+    const res = await api.consumer( name );
+    return res.body;
+  }
+} )
+```
 
-### .tools.webhook()
+## webhooks
 
-Provides a webhook feature where a POST is made to a given url and the workflow is stopped until another POST is made back to the workflows API:
+workflows can call webhooks that will stop their execution until an answer is given back.
 
 ```js
-const result = await context.tools.webhook( {
-  name: 'needFeedback',
-  description: 'Get a feedback',
-  url: 'http://xxx.xxx/feedback',
-  payload: { /* a given payload */ }
-} );
+import { workflow, createWebhook } from '@output.ai/workflow';
+import { guessByName } from './steps.js';
+
+export default workflow( {
+  ...
+  fn: async input => {
+    ...
+
+    const result = await createWebhook( {
+      url: 'http://xxx.xxx/feedback',
+      payload: {
+        progressSoFar: 'plenty'
+      }
+    } );
+
+  }
+})
 ```
 
-the url will receive the following payload:
+The url of the example will receive the payload, plus the workflowId:
 
 ```js
 {
@@ -67,38 +103,39 @@ the url will receive the following payload:
 }
 ```
 
-To resume the workflow, a POST has to be made to a given url, with a response payload and the workflowId.
+To resume the workflow, a POST has to be made with a response payload and the workflowId.
 
-The host is localhost:3001 if running locally, there is not remote host yet.
+- Production: `https://output-api-production.onrender.com/workflow/feedback`
+- Staging: `https://output-api-staging.onrender.com/workflow/feedback`
+- Local: `http://localhost:3001/workflow/feedback`
 
-The format is:
-```
-POST https://locahost:3001/workflow/feedback
+Example:
+
+```bash
+POST http://locahost:3001/workflow/feedback
   {
     workflowId,
     payload: {}
   }
 ```
 
-## Folder structure:
+## Developing
 
-```
-└ workflows
-  └ my workflow
-    ├ index.ts // contains the workflow()
-    ├ types.ts // contains input, output types, and other misc types
-    └ steps.ts // contains all steps
-```
-
-## Booting
+To develop workflows you need the code, which will be called the worker, the API and the engine (Temporal).
 
-The project with workflows will be a "worker", meaning its workflows can be invoked individually by their names. To do so it has to be started using a npx command.
+After having the API and the engine running, to start the worker just run:
 
-_package.json_
 ```js
-...
-  "scripts": {
-    "start": "npx flow-worker"
-  },
-...
+`npm run outputai`
 ```
+
+## Env variables
+
+Necessary env variables to run the worker locally:
+
+- `TEMPORAL_ADDRESS`: The temporal backend address, prefer the remote;
+- `TEMPORAL_NAMESPACE`: The name of the namespace, if using remote, use: "output-staging.i0jzq";
+- `TEMPORAL_API_KEY`: The API key to access remote temporal. If using local temporal, leave it blank;
+- `CATALOG_ID`: The name of the local catalog, always set this. Use your email;
+- `API_AUTH_KEY`: The API key to access the Framework API. Local can be blank, remote use the proper API Key;
+- `TRACING_ENABLED`: A "stringbool" value indicating if traces should be generated or note;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@output.ai/core",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "description": "The core module of the output framework",
   "type": "module",
   "main": "src/index.js",
@@ -13,19 +13,22 @@
     "worker": "node ./src/worker/index.js"
   },
   "bin": {
-    "flow-worker": "./bin/worker.sh"
+    "flow-worker": "./bin/worker.sh",
+    "outputai": "./bin/worker.sh"
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/growthxai/flow-sdk"
   },
   "dependencies": {
-    "@babel/generator": "7.26.5",
-    "@babel/parser": "7.26.7",
-    "@babel/traverse": "7.25.9",
-    "@babel/types": "7.26.7",
+    "@babel/generator": "7.28.3",
+    "@babel/parser": "7.28.4",
+    "@babel/traverse": "7.28.4",
+    "@babel/types": "7.28.4",
     "@temporalio/worker": "1.13.0",
-    "@temporalio/workflow": "1.13.0"
+    "@temporalio/workflow": "1.13.0",
+    "ajv": "8.17.1",
+    "zod": "4.1.9"
   },
   "imports": {
     "#consts": "./src/consts.js",

package/src/configs.js

@@ -1,17 +1,39 @@
+import * as z from 'zod';
+
+class InvalidEnvVarsErrors extends Error {}
+
+const envVarSchema = z.object( {
+  TEMPORAL_ADDRESS: z.union( [
+    z.httpUrl(),
+    z.string().regex( /^[a-z0-9_-]+:\d{2,5}$/i ) // local docker container name like worker:7233
+  ] ),
+  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()
+} );
+
+const { data: safeEnvVar, error } = envVarSchema.safeParse( process.env );
+if ( error ) {
+  throw new InvalidEnvVarsErrors( z.prettifyError( error ) );
+}
+
 export const worker = {
-  address: process.env.TEMPORAL_ADDRESS,
-  apiKey: process.env.TEMPORAL_API_KEY,
+  address: safeEnvVar.TEMPORAL_ADDRESS,
+  apiKey: safeEnvVar.TEMPORAL_API_KEY,
   executionTimeout: '1m',
   maxActivities: 100,
   maxWorkflows: 100,
-  namespace: process.env.TEMPORAL_NAMESPACE ?? 'default',
-  taskQueue: process.env.TEMPORAL_TASK_QUEUE
+  namespace: safeEnvVar.TEMPORAL_NAMESPACE ?? 'default',
+  taskQueue: safeEnvVar.CATALOG_ID,
+  catalogId: safeEnvVar.CATALOG_ID
 };
 
 export const api = {
-  authKey: process.env.API_AUTH_KEY
+  authKey: safeEnvVar.API_AUTH_KEY
 };
 
 export const tracing = {
-  enabled: [ '1', 'true' ].includes( process.env.TRACING_ENABLED )
+  enabled: safeEnvVar.TRACING_ENABLED
 };

package/src/consts.js

@@ -1,3 +1,4 @@
 export const SEND_WEBHOOK_ACTIVITY_NAME = '__internal#sendWebhookPost';
 export const METADATA_ACCESS_SYMBOL = Symbol( '__metadata' );
 export const WORKFLOWS_INDEX_FILENAME = '__workflows_entrypoint.js';
+export const THIS_LIB_NAME = 'core';

package/src/errors.js

@@ -1,3 +1,14 @@
+/**
+ * These are errors exposed as tools for the user to break their flow
+ * They work in both steps and workflows
+ */
+
+/**
+ * Any generic fatal errors
+ */
 export class FatalError extends Error { }
 
+/**
+ * Any validation error
+ */
 export class ValidationError extends Error { }

package/src/interface/step.js

@@ -1,6 +1,20 @@
 import { setMetadata } from './metadata.js';
+import { validateStep } from './validations/static.js';
+import { validateStepInput, validateStepOutput } from './validations/runtime.js';
+import { invokeFnAndValidateOutputPreservingExecutionModel } from './utils.js';
 
 export function step( { name, description, inputSchema, outputSchema, fn } ) {
-  setMetadata( fn, { name, description, inputSchema, outputSchema } );
-  return fn;
+  validateStep( { name, description, inputSchema, outputSchema, fn } );
+  const wrapper = input => {
+    if ( inputSchema ) {
+      validateStepInput( name, inputSchema, input );
+    }
+    if ( !outputSchema ) {
+      return fn( input );
+    }
+    return invokeFnAndValidateOutputPreservingExecutionModel( fn, input, validateStepOutput.bind( null, name, outputSchema ) );
+  };
+
+  setMetadata( wrapper, { name, description, inputSchema, outputSchema } );
+  return wrapper;
 };

package/src/interface/utils.js

@@ -1,9 +1,46 @@
-// This is rigged to return which folder had the source of calls for both interface methods (step workflow) functions
-// Important, if to refactor, pay attention to the depth in the stack trace to extract the info
-// now is 3 cause (1 line is name, 2 line is this function, 3 line is step/workflow, 4 line is caller)
-export const getInvocationDir = _ => new Error()
+/**
+ * Function rigged to return the folder path of the source of calls for the interface methods (step/workflow)
+ *
+ * IMPORTANT!!!
+ * If to refactor this, pay attention to the depth in the stack trace to extract the info.
+ * Currently it is 3:
+ * - 1st line is the name of the function;
+ * - 2nd line is this function;
+ * - 3rd line is step/workflow;
+ * - 4th line is caller;
+ *
+ * @returns {string} The folder path of the caller
+ */
+export const getInvocationDir = () => new Error()
   .stack.split( '\n' )[3]
   .split( ' ' )
   .at( -1 )
   .replace( /\((.+):\d+:\d+\)/, '$1' )
   .split( '/' ).slice( 0, -1 ).join( '/' );
+
+/**
+ * This mouthful function will invoke a function with given arguments, and validate its return
+ * using a given validator.
+ *
+ * It will preserver the execution model (asynchronous vs synchronous), so if the function is
+ * sync the validation happens here, if it is async (returns Promise) the validation is attached
+ * to a .then().
+ *
+ *
+ * @param {Function} fn - The function to execute
+ * @param {any} input - The payload to call the function
+ * @param {Function} validate - The validator function
+ * @returns {any} Function result (Promise or not)
+ */
+export const invokeFnAndValidateOutputPreservingExecutionModel = ( fn, input, validate ) => {
+  const uniformReturn = output => {
+    validate( output );
+    return output;
+  };
+
+  const output = fn( input );
+  if ( output?.constructor === Promise ) {
+    return output.then( resolvedOutput => uniformReturn( resolvedOutput ) );
+  }
+  return uniformReturn( output );
+};

package/src/interface/utils.spec.js

@@ -0,0 +1,71 @@
+import { describe, it, expect, vi } from 'vitest';
+import { getInvocationDir, invokeFnAndValidateOutputPreservingExecutionModel } from './utils.js';
+
+describe( 'interface/utils', () => {
+  describe( 'getInvocationDir', () => {
+    it( 'returns the caller directory from stack trace', () => {
+      const fakeCaller = '/tmp/project/src/caller/file.js';
+      const OriginalError = Error;
+      // Provide a deterministic stack shape for the function under test
+      // Lines: 1) Error, 2) getInvocationDir, 3) step/workflow, 4) actual caller
+      // Include typical V8 formatting with leading spaces and without function name
+      // for the caller line
+
+      Error = class extends OriginalError {
+        constructor( ...args ) {
+          super( ...args );
+          this.stack = [
+            'Error',
+            '    at getInvocationDir (a:1:1)',
+            '    at step (b:1:1)',
+            `    at ${fakeCaller}:10:20`
+          ].join( '\n' );
+        }
+      };
+      try {
+        const dir = getInvocationDir();
+        expect( dir ).toBe( '/tmp/project/src/caller' );
+      } finally {
+
+        Error = OriginalError;
+      }
+    } );
+  } );
+
+  describe( 'invokeFnAndValidateOutputPreservingExecutionModel', () => {
+    it( 'validates and returns sync output', () => {
+      const fn = vi.fn( x => x * 2 );
+      const validate = vi.fn();
+      const result = invokeFnAndValidateOutputPreservingExecutionModel( fn, 3, validate );
+      expect( result ).toBe( 6 );
+      expect( validate ).toHaveBeenCalledWith( 6 );
+    } );
+
+    it( 'validates and returns async output preserving promise', async () => {
+      const fn = vi.fn( async x => x + 1 );
+      const validate = vi.fn();
+      const resultPromise = invokeFnAndValidateOutputPreservingExecutionModel( fn, 4, validate );
+      expect( resultPromise ).toBeInstanceOf( Promise );
+      const result = await resultPromise;
+      expect( result ).toBe( 5 );
+      expect( validate ).toHaveBeenCalledWith( 5 );
+    } );
+
+    it( 'propagates validator errors (sync)', () => {
+      const fn = vi.fn( x => x );
+      const validate = vi.fn( () => {
+        throw new Error( 'invalid' );
+      } );
+      expect( () => invokeFnAndValidateOutputPreservingExecutionModel( fn, 'a', validate ) ).toThrow( 'invalid' );
+    } );
+
+    it( 'propagates validator errors (async)', async () => {
+      const fn = vi.fn( async x => x );
+      const validate = vi.fn( () => {
+        throw new Error( 'invalid' );
+      } );
+      await expect( invokeFnAndValidateOutputPreservingExecutionModel( fn, 'a', validate ) ).rejects.toThrow( 'invalid' );
+    } );
+  } );
+} );
+

package/src/interface/validations/ajv_provider.js

@@ -0,0 +1,3 @@
+import Ajv from 'ajv';
+
+export const ajv = new Ajv();

package/src/interface/validations/runtime.js

@@ -0,0 +1,69 @@
+import { FatalError } from '#errors';
+import { ajv } from './ajv_provider.js';
+
+/**
+ * Error type for when the input/output of a step/workflow doesn't match its input/output schema, respectively
+ */
+export class MismatchSchemaError extends FatalError {}
+/**
+ * Error type for when the input of a step/workflow doesn't match its input schema
+ * @extends MismatchSchemaError
+ */
+export class InvalidInputError extends MismatchSchemaError {}
+/**
+ * Error type for when the output of a step/workflow doesn't match its output schema
+ * @extends MismatchSchemaError
+ */
+export class InvalidOutputError extends MismatchSchemaError {}
+
+const validate = ( ErrorClass, type, name, schema, payload ) => {
+  const validate = ajv.compile( schema );
+  const valid = validate( payload );
+
+  if ( !valid ) {
+    throw new ErrorClass( `Invalid input at ${type} "${name}": ${ajv.errorsText( validate.errors )}` );
+  }
+};
+
+const validateInput = validate.bind( null, InvalidInputError );
+const validateOutput = validate.bind( null, InvalidOutputError );
+
+/**
+ * Validates step input
+ *
+ * @param {name} name - step's name
+ * @param {object} schema - step's input schema
+ * @param {any} - the input to validate
+ * @throws InvalidInputError
+ */
+export const validateStepInput = validateInput.bind( null, 'step' );
+
+/**
+ * Validates step output
+ *
+ * @param {name} name - step's name
+ * @param {object} schema - step's output schema
+ * @param {any} - the output to validate
+ * @throws InvalidOutputError
+ */
+export const validateStepOutput = validateOutput.bind( null, 'step' );
+
+/**
+ * Validates workflow input
+ *
+ * @param {name} name - workflow's name
+ * @param {object} schema - workflow's input schema
+ * @param {any} - the input to validate
+ * @throws InvalidInputError
+ */
+export const validateWorkflowInput = validateInput.bind( null, 'workflow' );
+
+/**
+ * Validates workflow output
+ *
+ * @param {name} name - workflow's name
+ * @param {object} schema - workflow's output schema
+ * @param {any} - the output to validate
+ * @throws InvalidOutputError
+ */
+export const validateWorkflowOutput = validateOutput.bind( null, 'workflow' );

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

@@ -0,0 +1,50 @@
+import { describe, it, expect } from 'vitest';
+import { validateStepInput, validateWorkflowInput, InvalidInputError } from './runtime.js';
+
+describe( 'Runtime validations spec', () => {
+  describe( 'validateStepInput', () => {
+    it( 'passes with matching payload', () => {
+      const schema = {
+        type: 'object',
+        properties: { id: { type: 'string' }, count: { type: 'integer', minimum: 0 } },
+        required: [ 'id' ],
+        additionalProperties: false
+      };
+      expect( () => validateStepInput( 'myStep', schema, { id: 'x', count: 2 } ) ).not.toThrow();
+    } );
+
+    it( 'rejects invalid payload', () => {
+      const schema = {
+        type: 'object',
+        properties: { id: { type: 'string' }, count: { type: 'integer', minimum: 0 } },
+        required: [ 'id' ],
+        additionalProperties: false
+      };
+      const error = new InvalidInputError( 'Invalid input at step "myStep": data must have required property \'id\'' );
+      expect( () => validateStepInput( 'myStep', schema, { count: -1 } ) ).toThrow( error );
+    } );
+  } );
+
+  describe( 'validateWorkflowInput', () => {
+    it( 'passes with matching payload', () => {
+      const schema = {
+        type: 'object',
+        properties: { name: { type: 'string' }, enabled: { type: 'boolean' } },
+        required: [ 'name' ],
+        additionalProperties: false
+      };
+      expect( () => validateWorkflowInput( 'myWorkflow', schema, { name: 'wf', enabled: true } ) ).not.toThrow();
+    } );
+
+    it( 'rejects invalid payload', () => {
+      const schema = {
+        type: 'object',
+        properties: { name: { type: 'string' }, enabled: { type: 'boolean' } },
+        required: [ 'name' ],
+        additionalProperties: false
+      };
+      const error = new InvalidInputError( 'Invalid input at workflow "myWorkflow": data must have required property \'name\'' );
+      expect( () => validateWorkflowInput( 'myWorkflow', schema, { enabled: 'yes' } ) ).toThrow( error );
+    } );
+  } );
+} );

package/src/interface/validations/static.js

@@ -0,0 +1,67 @@
+import { ajv } from './ajv_provider.js';
+import * as z from 'zod';
+
+/**
+ * Error is thrown when the definition of a step/workflow has problems
+ */
+export class StaticValidationError extends Error {};
+
+// Custom validation for zod, to be used when validating JSONSchema def with ajv
+const refineJsonSchema = ( value, ctx ) => {
+  if ( value && !ajv.validateSchema( value ) ) {
+    ctx.addIssue( {
+      code: 'invalid_format',
+      message: ajv.errorsText( ajv.errors )
+    } );
+  }
+};
+
+const stepAndWorkflowSchema = z.object( {
+  name: z.string().regex( /^[a-z_][a-z0-9_]*$/i ),
+  description: z.string().optional(),
+  inputSchema: z.looseObject( {} ).optional().superRefine( refineJsonSchema ),
+  outputSchema: z.looseObject( {} ).optional().superRefine( refineJsonSchema ),
+  fn: z.function()
+} );
+
+const webhookSchema = z.object( {
+  url: z.url( { protocol: /^https?$/ } ),
+  payload: z.any().optional()
+} );
+
+const validateAgainstSchema = ( schema, args ) => {
+  const result = schema.safeParse( args );
+  if ( !result.success ) {
+    throw new StaticValidationError( z.prettifyError( result.error ) );
+  }
+};
+
+/**
+ * Validate step payload
+ *
+ * @param {object} args - The step arguments
+ * @throws {StaticValidationError} Throws if args are invalid
+ */
+export function validateStep( args ) {
+  validateAgainstSchema( stepAndWorkflowSchema, args );
+};
+
+/**
+ * Validate workflow payload
+ *
+ * @param {object} args - The workflow arguments
+ * @throws {StaticValidationError} Throws if args are invalid
+ */
+export function validateWorkflow( args ) {
+  validateAgainstSchema( stepAndWorkflowSchema, args );
+};
+
+/**
+ * Validate createWebhook payload
+ *
+ * @param {object} args - The createWebhook arguments
+ * @throws {StaticValidationError} Throws if args are invalid
+ */
+export function validateCreateWebhook( args ) {
+  validateAgainstSchema( webhookSchema, args );
+};