@output.ai/core 0.3.0 → 0.3.2

package/README.md

@@ -3,96 +3,9 @@
 Workflow orchestration and worker runtime for building durable LLM applications with Temporal.
 
 [![npm version](https://img.shields.io/npm/v/@output.ai/core)](https://www.npmjs.com/package/@output.ai/core)
-[![Documentation](https://img.shields.io/badge/docs-docs.output.ai-blue)](https://docs.output.ai/packages/core)
-
-## Installation
-
-```bash
-npm install @output.ai/core
-```
-
-## Quick Start
-
-```typescript
-// workflow.ts
-import { workflow, z } from '@output.ai/core';
-import { processData } from './steps.js';
-
-export default workflow({
-  name: 'myWorkflow',
-  inputSchema: z.object({ text: z.string() }),
-  outputSchema: z.object({ result: z.string() }),
-  fn: async (input) => {
-    const result = await processData(input.text);
-    return { result };
-  }
-});
-```
-
-```typescript
-// steps.ts
-import { step, z } from '@output.ai/core';
-
-export const processData = step({
-  name: 'processData',
-  inputSchema: z.string(),
-  outputSchema: z.string(),
-  fn: async (text) => {
-    return text.toUpperCase();
-  }
-});
-```
-
-## Key Exports
-
-| Export | Description |
-|--------|-------------|
-| `workflow` | Define orchestration logic that coordinates steps |
-| `step` | Define reusable units of work that handle I/O |
-| `evaluator` | Define steps that return evaluation results |
-| `createWebhook` | Pause workflow execution until external input |
-| `z` | Zod schema library for input/output validation |
-
-## File Structure
-
-Each workflow lives in its own directory:
-
-```text
-src/workflows/
-└── my-workflow/
-    ├── workflow.ts           # Workflow definition
-    ├── steps.ts              # Step implementations
-    ├── evaluators.ts         # Evaluators (optional)
-    ├── prompts/              # LLM prompt templates
-    │   └── prompt@v1.prompt
-    └── scenarios/            # Test scenarios
-        └── test_input.json
-```
-
-## Environment Variables
-
-The worker reads these environment variables:
-
-| Variable | Description |
-|----------|-------------|
-| `TEMPORAL_ADDRESS` | Temporal backend address |
-| `TEMPORAL_NAMESPACE` | Temporal namespace name |
-| `TEMPORAL_API_KEY` | API key for remote Temporal (leave blank for local) |
-| `CATALOG_ID` | **Required.** Name of the local catalog (use your email) |
-| `API_AUTH_KEY` | API key for Framework API (blank for local, required for remote) |
-| `TRACE_LOCAL_ON` | Enable local trace saving (requires `REDIS_URL`) |
-| `TRACE_REMOTE_ON` | Enable remote trace saving (requires `REDIS_URL` and AWS secrets) |
-| `REDIS_URL` | Redis address (required when tracing is enabled) |
-| `TRACE_REMOTE_S3_BUCKET` | AWS S3 bucket for traces (required for remote tracing) |
-| `AWS_REGION` | AWS region matching the S3 bucket (required for remote tracing) |
-| `AWS_ACCESS_KEY_ID` | AWS key ID (required for remote tracing) |
-| `AWS_SECRET_ACCESS_KEY` | AWS secret key (required for remote tracing) |
 
 ## Documentation
+- [README](https://docs.output.ai/packages/core)
+- [API Reference](https://output-ai-reference-code-docs.onrender.com/modules/core_src.html)
 
-For comprehensive documentation, visit:
-
-- [Package Reference](https://docs.output.ai/packages/core)
-- [Workflows Guide](https://docs.output.ai/core/workflows)
-- [Steps Guide](https://docs.output.ai/core/steps)
-- [Getting Started](https://docs.output.ai/quickstart)
+<!-- Internal Dev Note: The documentation for this package is found at docs/guides/packages/core.mdx -->

package/package.json

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

package/src/index.d.ts

@@ -79,6 +79,15 @@ export type HttpMethod = 'HEAD' | 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
  */
 export type TemporalActivityOptions = Omit<ActivityOptions, 'versioningIntent' | 'taskQueue' | 'allowEagerDispatch'>;
 
+/**
+ * Result of a single job executed by `executeInParallel`.
+ *
+ * @typeParam T - The return type of the job function
+ */
+export type ParallelJobResult<T> =
+  | { ok: true; result: T; index: number } |
+  { ok: false; error: unknown; index: number };
+
 /*
 ╭─────────╮
 │ S T E P │╮
@@ -480,6 +489,81 @@ export declare function workflow<
  ╰───────────────────╯
 */
 
+/**
+ * A single feedback for an EvaluationResult
+ */
+export class EvaluationFeedback {
+  /**
+   * Issue found
+   */
+  issue: string;
+
+  /**
+   * Improvement suggestion
+   */
+  suggestion?: string;
+
+  /**
+   * Reference for the issue
+   */
+  reference?: string;
+
+  /**
+   * Issue priority
+   */
+  priority?: 'low' | 'medium' | 'high' | 'critical';
+
+  /**
+   * @constructor
+   * @param args
+   * @param args.issue
+   * @param args.suggestion
+   * @param args.reference
+   * @param args.priority
+   */
+  constructor( args: {
+    issue: string;
+    suggestion?: string;
+    reference?: string;
+    priority?: 'low' | 'medium' | 'high' | 'critical';
+  } );
+
+  /**
+   * @returns The zod schema for this class
+   */
+  static get schema(): z.ZodType;
+}
+
+/**
+ * Base constructor arguments for EvaluationResult classes
+ */
+export type EvaluationResultArgs<TValue = any> = { // eslint-disable-line @typescript-eslint/no-explicit-any
+  /**
+   * The value of the evaluation
+   */
+  value: TValue;
+  /**
+   * The confidence in the evaluation
+   */
+  confidence: number;
+  /**
+   * The name of the evaluation
+   */
+  name?: string;
+  /**
+   * The reasoning behind the result
+   */
+  reasoning?: string;
+  /**
+   * Feedback for this evaluation
+   */
+  feedback?: EvaluationFeedback[];
+  /**
+   * Dimensions of this evaluation
+   */
+  dimensions?: Array<EvaluationStringResult | EvaluationNumberResult | EvaluationBooleanResult>;
+};
+
 /**
  * Represents the result of an evaluation.
  *
@@ -487,33 +571,45 @@ export declare function workflow<
  */
 export class EvaluationResult {
   /**
-   * @constructor
-   * @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
+   * The name of the evaluation result
+   */
+  name?: string;
+
+  /**
+   * The evaluation result value
+   */
+  value: any; // eslint-disable-line @typescript-eslint/no-explicit-any
+
+  /**
+   * The evaluation result confidence
    */
-  constructor( args: { value: any; confidence: number; reasoning?: string } ); // eslint-disable-line @typescript-eslint/no-explicit-any
+  confidence: number;
 
   /**
-   * @returns The evaluation result value
+   * The evaluation result reasoning
    */
-  get value(): any; // eslint-disable-line @typescript-eslint/no-explicit-any
+  reasoning?: string;
 
   /**
-   * @returns The evaluation result confidence
+   * Feedback for this evaluation
    */
-  get confidence(): number;
+  feedback: EvaluationFeedback[];
 
   /**
-   * @returns The evaluation result reasoning
+   * Dimensions of this evaluation
    */
-  get reasoning(): string;
+  dimensions: Array<EvaluationStringResult | EvaluationNumberResult | EvaluationBooleanResult>;
 
   /**
-   * @returns A zod schema representing this class
+   * @constructor
+   * @param args
+   */
+  constructor( args: EvaluationResultArgs );
+
+  /**
+   * @returns The zod schema for this class
    */
-  get schema(): string;
+  static get schema(): z.ZodType;
 }
 
 /**
@@ -524,16 +620,8 @@ export class EvaluationStringResult extends EvaluationResult {
   /**
    * @constructor
    * @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 The evaluation result value
-   */
-  get value(): string;
+  constructor( args: EvaluationResultArgs<string> );
 }
 
 /**
@@ -544,16 +632,8 @@ export class EvaluationNumberResult extends EvaluationResult {
   /**
    * @constructor
    * @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 The evaluation result value
    */
-  get value(): number;
+  constructor( args: EvaluationResultArgs<number> );
 }
 
 /**
@@ -564,16 +644,8 @@ export class EvaluationBooleanResult extends EvaluationResult {
   /**
    * @constructor
    * @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 The evaluation result value
-   */
-  get value(): boolean;
+  constructor( args: EvaluationResultArgs<boolean> );
 }
 
 /**
@@ -717,6 +789,51 @@ export declare function sendHttpRequest( params: {
   headers?: Record<string, string>;
 } ): Promise<SerializedFetchResponse>;
 
+/**
+ * Execute jobs in parallel with optional concurrency limit.
+ *
+ * Returns all job results (successes and failures) sorted by original job index.
+ * Each result contains `ok` (boolean), `index` (original position), and either
+ * `result` (on success) or `error` (on failure).
+ *
+ * Jobs must be wrapped in arrow functions—do not pass promises directly.
+ *
+ * @example
+ * ```ts
+ * const results = await executeInParallel( {
+ *   jobs: [
+ *     () => myStep( data1 ),
+ *     () => myStep( data2 ),
+ *     () => myStep( data3 )
+ *   ],
+ *   concurrency: 2
+ * } );
+ *
+ * // Handle the discriminated union (result only exists when ok is true)
+ * const successfulResults = results.filter( r => r.ok ).map( r => r.result );
+ *
+ * // Or handle each result individually
+ * for ( const r of results ) {
+ *   if ( r.ok ) {
+ *     console.log( `Job ${r.index} succeeded:`, r.result );
+ *   } else {
+ *     console.log( `Job ${r.index} failed:`, r.error );
+ *   }
+ * }
+ * ```
+ *
+ * @param params - Parameters object
+ * @param params.jobs - Array of arrow functions returning step/activity calls (not promises directly)
+ * @param params.concurrency - Max concurrent jobs (default: Infinity)
+ * @param params.onJobCompleted - Optional callback invoked as each job completes (in completion order)
+ * @returns Array of results sorted by original job index
+ */
+export declare function executeInParallel<T>( params: {
+  jobs: Array<() => Promise<T> | T>;
+  concurrency?: number;
+  onJobCompleted?: ( result: ParallelJobResult<T> ) => void;
+} ): Promise<Array<ParallelJobResult<T>>>;
+
 /*
 ╭─────────────╮
 │ E R R O R S │╮

package/src/index.js

@@ -1,6 +1,7 @@
 import { evaluator, EvaluationStringResult, EvaluationNumberResult, EvaluationBooleanResult } from './interface/evaluator.js';
 import { step } from './interface/step.js';
 import { workflow } from './interface/workflow.js';
+import { executeInParallel } from './interface/workflow_utils.js';
 import { sendHttpRequest, sendPostRequestAndAwaitWebhook } from './interface/webhook.js';
 import { FatalError, ValidationError } from './errors.js';
 export { continueAsNew, sleep } from '@temporalio/workflow';
@@ -16,6 +17,7 @@ export {
   EvaluationStringResult,
   EvaluationBooleanResult,
   // webhook tools
+  executeInParallel,
   sendHttpRequest,
   sendPostRequestAndAwaitWebhook,
   // errors

package/src/interface/evaluator.js

@@ -11,56 +11,158 @@ import * as z from 'zod';
 class EvaluationResultValidationError extends ValidationError {};
 
 /**
- * Generic EvaluationResult class, represents the result
- * of an evaluation
+ * A single feedback for an EvaluationResult
+ */
+export class EvaluationFeedback {
+
+  /**
+   * Issue found
+   * @type {string}
+   */
+  issue;
+
+  /**
+   * Improvement suggestion
+   * @type {string}
+   */
+  suggestion;
+
+  /**
+   * Reference for the issue
+   * @type {string}
+   */
+  reference;
+
+  /**
+   * Issue priority
+   * @type {'low' | 'medium' | 'high' | 'critical' | undefined}
+   */
+  priority;
+
+  /**
+   * The zod schema for this class
+   * @type {z.ZodType}
+   */
+  static get schema() {
+    return z.object( {
+      issue: z.string(),
+      suggestion: z.string().optional(),
+      reference: z.string().optional(),
+      priority: z.enum( [ 'low', 'medium', 'high', 'critical' ] ).optional()
+    } );
+  };
+
+  /**
+   * @constructor
+   * @param {object} args
+   * @param {string} args.issue
+   * @param {string} [args.suggestion]
+   * @param {string} [args.reference]
+   * @param {'low' | 'medium' | 'high' | 'critical'} [args.priority]
+   */
+  constructor( { issue, suggestion = undefined, reference = undefined, priority = undefined } ) {
+    const result = this.constructor.schema.safeParse( { issue, suggestion, reference, priority } );
+    if ( result.error ) {
+      throw new EvaluationResultValidationError( z.prettifyError( result.error ) );
+    }
+    this.issue = issue;
+    this.suggestion = suggestion;
+    this.reference = reference;
+    this.priority = priority;
+  }
+}
+
+/**
+ * Generic EvaluationResult class, represents the result of an evaluation.
  */
 export class EvaluationResult {
 
   /**
-   * Returns the evaluation result value
+   * The name of the evaluation result
+   * @type {string}
+   */
+  name;
+
+  /**
+   * The evaluation result value
    * @type {any}
    */
   value = null;
 
   /**
-   * Returns the confidence value, between 0 and 1.
+   * The confidence value, between 0 and 1
    * @type {number}
    */
-  confidence = undefined;
+  confidence;
 
   /**
-   * Returns the reasoning value.
+   * The reasoning value
    * @type {string}
    */
-  reasoning = undefined;
+  reasoning;
 
-  static get valueSchema() {
-    return z.any();
-  };
+  /**
+   * Feedback for this evaluation
+   * @type {EvaluationFeedback[]}
+   */
+  feedback = [];
+
+  /**
+   * Dimensions of this evaluation
+   * @type {EvaluationResult[]}
+   */
+  dimensions = [];
 
+  /**
+   * The schema main field
+   * @type {z.ZodAny}
+   */
+  static valueSchema = z.any();
+
+  /**
+   * The zod schema for this class
+   * @type {z.ZodType}
+   */
   static get schema() {
-    return z.object( {
+    const baseSchema = z.object( {
       value: this.valueSchema,
       confidence: z.number(),
-      reasoning: z.string().optional()
+      reasoning: z.string().optional(),
+      name: z.string().optional(),
+      feedback: z.array( EvaluationFeedback.schema ).optional()
+    } );
+
+    // Adds dimension but keep it only one level deep
+    return baseSchema.extend( {
+      dimensions: z.array(
+        baseSchema.extend( {
+          value: z.union( [ z.string(), z.number(), z.boolean() ] )
+        } )
+      ).optional()
     } );
   };
 
   /**
    * @constructor
    * @param {object} args
-   * @param {any} args.value - The value of the evaluation
-   * @param {number} args.confidence - The confidence on the evaluation
-   * @param {string} [args.reasoning] - The reasoning behind the result
+   * @param {any} args.value
+   * @param {number} args.confidence
+   * @param {string} [args.name]
+   * @param {EvaluationResult[]} [args.dimensions]
+   * @param {EvaluationFeedback[]} [args.feedback]
+   * @param {string} [args.reasoning]
    */
-  constructor( args ) {
-    const result = this.constructor.schema.safeParse( args );
+  constructor( { value, confidence, dimensions = [], feedback = [], name = undefined, reasoning = undefined } ) {
+    const result = this.constructor.schema.safeParse( { value, confidence, dimensions, feedback, name, reasoning } );
     if ( result.error ) {
       throw new EvaluationResultValidationError( z.prettifyError( result.error ) );
     }
-    this.value = args.value;
-    this.confidence = args.confidence;
-    this.reasoning = args.reasoning;
+    this.confidence = confidence;
+    this.value = value;
+    this.dimensions = dimensions;
+    this.feedback = feedback;
+    this.name = name;
+    this.reasoning = reasoning;
   }
 };
 
@@ -68,71 +170,51 @@ export class EvaluationResult {
  * An evaluation result that uses a string value
  * @extends EvaluationResult
  * @property {string} value - The evaluation result value
+ * @constructor
+ * @param {object} args
+ * @param {string} args.value - The value of the evaluation (must be a string)
+ * @see EvaluationResult#constructor for other parameters (confidence, reasoning)
  */
 export class EvaluationStringResult extends EvaluationResult {
-  static get valueSchema() {
-    return 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
-   */
-  // eslint-disable-next-line no-useless-constructor
-  constructor( args ) {
-    super( args );
-  }
+  static valueSchema = z.string();
 };
 
 /**
  * An evaluation result that uses a boolean value
  * @extends EvaluationResult
  * @property {boolean} value - The evaluation result value
+ * @constructor
+ * @param {object} args
+ * @param {boolean} args.value - The value of the evaluation (must be a boolean)
+ * @see EvaluationResult#constructor for other parameters (confidence, reasoning)
  */
 export class EvaluationBooleanResult extends EvaluationResult {
-  static get valueSchema() {
-    return 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
-   */
-  // eslint-disable-next-line no-useless-constructor
-  constructor( args ) {
-    super( args );
-  }
+  static valueSchema = z.boolean();
 };
 
 /**
  * An evaluation result that uses a number value
  * @extends EvaluationResult
  * @property {number} value - The evaluation result value
+ * @constructor
+ * @param {object} args
+ * @param {number} args.value - The value of the evaluation (must be a number)
+ * @see EvaluationResult#constructor for other parameters (confidence, reasoning)
  */
 export class EvaluationNumberResult extends EvaluationResult {
-  static get valueSchema() {
-    return 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
-   */
-  // eslint-disable-next-line no-useless-constructor
-  constructor( args ) {
-    super( args );
-  }
+  static valueSchema = z.number();
 };
 
+/**
+ * Expose the function to create a new evaluator
+ * @param {object} opts
+ * @param {string} opts.name
+ * @param {string} opts.description
+ * @param {z.ZodType} opts.inputSchema
+ * @param {Function} opts.fn
+ * @param {object} opts.options
+ * @returns {Function}
+ */
 export function evaluator( { name, description, inputSchema, fn, options } ) {
   validateEvaluator( { name, description, inputSchema, fn, options } );