@ax-llm/ax 13.0.8 → 13.0.9

package/index.d.cts

@@ -4332,7 +4332,7 @@ interface AxFlowBranchContext {
     currentBranchValue?: unknown;
 }
 interface AxFlowExecutionStep {
-    type: 'execute' | 'map' | 'merge' | 'parallel-map' | 'parallel';
+    type: 'execute' | 'map' | 'merge' | 'parallel-map' | 'parallel' | 'derive';
     nodeName?: string;
     dependencies: string[];
     produces: string[];
@@ -4391,10 +4391,34 @@ declare class AxFlowExecutionPlanner {
      * @param mapTransform - Transformation function (for map steps)
      * @param mergeOptions - Options for merge operations (result key, merge function)
      */
-    addExecutionStep(stepFunction: AxFlowStepFunction, nodeName?: string, mapping?: (state: any) => any, stepType?: 'execute' | 'map' | 'merge' | 'parallel-map' | 'parallel', mapTransform?: (state: any) => any, mergeOptions?: {
+    addExecutionStep(stepFunction: AxFlowStepFunction, nodeName?: string, mapping?: (state: any) => any, stepType?: 'execute' | 'map' | 'merge' | 'parallel-map' | 'parallel' | 'derive', mapTransform?: (state: any) => any, mergeOptions?: {
         resultKey?: string;
         mergeFunction?: (...args: any[]) => any;
+    }, deriveOptions?: {
+        inputFieldName: string;
+        outputFieldName: string;
+        batchSize?: number;
     }): void;
+    /**
+     * Analyzes a step function to determine what fields it produces.
+     *
+     * This method analyzes the step function to understand what new fields
+     * it adds to the state. It uses a mock state approach:
+     * 1. Creates a mock state with sample data
+     * 2. Runs the step function on the mock state
+     * 3. Compares the result to see what fields were added
+     *
+     * @param stepFunction - The step function to analyze
+     * @returns Array of field names that the step function produces
+     */
+    private analyzeStepFunctionProduction;
+    /**
+     * Analyzes step function source code to determine what fields it produces.
+     *
+     * @param stepFunction - The step function to analyze
+     * @returns Array of field names that the step function produces
+     */
+    private analyzeStepFunctionSource;
     /**
      * Analyzes a map transformation function to determine what fields it produces.
      *
@@ -4551,7 +4575,7 @@ declare class AxFlowExecutionPlanner {
  * providing compile-time type safety and superior IntelliSense.
  *
  * @example
- * ```typescript
+ * ```
  * const flow = new AxFlow<{ topic: string }, { finalAnswer: string }>()
  *   .node('summarizer', 'text:string -> summary:string')
  *   .node('critic', 'summary:string -> critique:string')
@@ -4656,7 +4680,7 @@ TState extends AxFlowState = IN> implements AxFlowable<IN, OUT> {
      * @returns New AxFlow instance with updated TNodes type
      *
      * @example
-     * ```typescript
+     * ```
      * flow.node('summarizer', 'text:string -> summary:string')
      * flow.node('analyzer', 'text:string -> analysis:string, confidence:number', { debug: true })
      * ```
@@ -4675,7 +4699,7 @@ TState extends AxFlowState = IN> implements AxFlowable<IN, OUT> {
      * @returns New AxFlow instance with updated TNodes type
      *
      * @example
-     * ```typescript
+     * ```
      * const sig = new AxSignature('text:string -> summary:string')
      * flow.node('summarizer', sig, { temperature: 0.1 })
      * ```
@@ -4693,7 +4717,7 @@ TState extends AxFlowState = IN> implements AxFlowable<IN, OUT> {
      * @returns New AxFlow instance with updated TNodes type
      *
      * @example
-     * ```typescript
+     * ```
      * class CustomProgram extends AxProgram<{ input: string }, { output: string }> {
      *   async forward(ai, values) { return { output: values.input.toUpperCase() } }
      * }
@@ -4739,7 +4763,7 @@ TState extends AxFlowState = IN> implements AxFlowable<IN, OUT> {
      * @returns New AxFlow instance with updated TState type
      *
      * @example
-     * ```typescript
+     * ```
      * flow.map(state => ({ ...state, processedText: state.text.toLowerCase() }))
      * ```
      */
@@ -4754,7 +4778,7 @@ TState extends AxFlowState = IN> implements AxFlowable<IN, OUT> {
      * @returns New AxFlow instance with updated TState type
      *
      * @example
-     * ```typescript
+     * ```
      * // Parallel map with multiple transforms
      * flow.map([
      *   state => ({ ...state, result1: processA(state.data) }),
@@ -4975,6 +4999,31 @@ TState extends AxFlowState = IN> implements AxFlowable<IN, OUT> {
      * Short alias for endWhile()
      */
     end(): this;
+    /**
+     * Derives a new field from an existing field by applying a transform function.
+     *
+     * If the input field contains an array, the transform function is applied to each
+     * array element in parallel with batch size control. If the input field contains
+     * a scalar value, the transform function is applied directly.
+     *
+     * @param outputFieldName - Name of the field to store the result
+     * @param inputFieldName - Name of the existing field to transform
+     * @param transformFn - Function to apply to each element (for arrays) or the value directly (for scalars)
+     * @param options - Options including batch size for parallel processing
+     * @returns this (for chaining)
+     *
+     * @example
+     * ```typescript
+     * // Parallel processing of array items
+     * flow.derive('processedItems', 'items', (item, index) => processItem(item), { batchSize: 5 })
+     *
+     * // Direct transformation of scalar value
+     * flow.derive('upperText', 'text', (text) => text.toUpperCase())
+     * ```
+     */
+    derive<T>(outputFieldName: string, inputFieldName: string, transformFn: (value: any, index?: number, state?: TState) => T, options?: {
+        batchSize?: number;
+    }): this;
     /**
      * Gets execution plan information for debugging automatic parallelization
      *

package/index.d.ts

@@ -4332,7 +4332,7 @@ interface AxFlowBranchContext {
     currentBranchValue?: unknown;
 }
 interface AxFlowExecutionStep {
-    type: 'execute' | 'map' | 'merge' | 'parallel-map' | 'parallel';
+    type: 'execute' | 'map' | 'merge' | 'parallel-map' | 'parallel' | 'derive';
     nodeName?: string;
     dependencies: string[];
     produces: string[];
@@ -4391,10 +4391,34 @@ declare class AxFlowExecutionPlanner {
      * @param mapTransform - Transformation function (for map steps)
      * @param mergeOptions - Options for merge operations (result key, merge function)
      */
-    addExecutionStep(stepFunction: AxFlowStepFunction, nodeName?: string, mapping?: (state: any) => any, stepType?: 'execute' | 'map' | 'merge' | 'parallel-map' | 'parallel', mapTransform?: (state: any) => any, mergeOptions?: {
+    addExecutionStep(stepFunction: AxFlowStepFunction, nodeName?: string, mapping?: (state: any) => any, stepType?: 'execute' | 'map' | 'merge' | 'parallel-map' | 'parallel' | 'derive', mapTransform?: (state: any) => any, mergeOptions?: {
         resultKey?: string;
         mergeFunction?: (...args: any[]) => any;
+    }, deriveOptions?: {
+        inputFieldName: string;
+        outputFieldName: string;
+        batchSize?: number;
     }): void;
+    /**
+     * Analyzes a step function to determine what fields it produces.
+     *
+     * This method analyzes the step function to understand what new fields
+     * it adds to the state. It uses a mock state approach:
+     * 1. Creates a mock state with sample data
+     * 2. Runs the step function on the mock state
+     * 3. Compares the result to see what fields were added
+     *
+     * @param stepFunction - The step function to analyze
+     * @returns Array of field names that the step function produces
+     */
+    private analyzeStepFunctionProduction;
+    /**
+     * Analyzes step function source code to determine what fields it produces.
+     *
+     * @param stepFunction - The step function to analyze
+     * @returns Array of field names that the step function produces
+     */
+    private analyzeStepFunctionSource;
     /**
      * Analyzes a map transformation function to determine what fields it produces.
      *
@@ -4551,7 +4575,7 @@ declare class AxFlowExecutionPlanner {
  * providing compile-time type safety and superior IntelliSense.
  *
  * @example
- * ```typescript
+ * ```
  * const flow = new AxFlow<{ topic: string }, { finalAnswer: string }>()
  *   .node('summarizer', 'text:string -> summary:string')
  *   .node('critic', 'summary:string -> critique:string')
@@ -4656,7 +4680,7 @@ TState extends AxFlowState = IN> implements AxFlowable<IN, OUT> {
      * @returns New AxFlow instance with updated TNodes type
      *
      * @example
-     * ```typescript
+     * ```
      * flow.node('summarizer', 'text:string -> summary:string')
      * flow.node('analyzer', 'text:string -> analysis:string, confidence:number', { debug: true })
      * ```
@@ -4675,7 +4699,7 @@ TState extends AxFlowState = IN> implements AxFlowable<IN, OUT> {
      * @returns New AxFlow instance with updated TNodes type
      *
      * @example
-     * ```typescript
+     * ```
      * const sig = new AxSignature('text:string -> summary:string')
      * flow.node('summarizer', sig, { temperature: 0.1 })
      * ```
@@ -4693,7 +4717,7 @@ TState extends AxFlowState = IN> implements AxFlowable<IN, OUT> {
      * @returns New AxFlow instance with updated TNodes type
      *
      * @example
-     * ```typescript
+     * ```
      * class CustomProgram extends AxProgram<{ input: string }, { output: string }> {
      *   async forward(ai, values) { return { output: values.input.toUpperCase() } }
      * }
@@ -4739,7 +4763,7 @@ TState extends AxFlowState = IN> implements AxFlowable<IN, OUT> {
      * @returns New AxFlow instance with updated TState type
      *
      * @example
-     * ```typescript
+     * ```
      * flow.map(state => ({ ...state, processedText: state.text.toLowerCase() }))
      * ```
      */
@@ -4754,7 +4778,7 @@ TState extends AxFlowState = IN> implements AxFlowable<IN, OUT> {
      * @returns New AxFlow instance with updated TState type
      *
      * @example
-     * ```typescript
+     * ```
      * // Parallel map with multiple transforms
      * flow.map([
      *   state => ({ ...state, result1: processA(state.data) }),
@@ -4975,6 +4999,31 @@ TState extends AxFlowState = IN> implements AxFlowable<IN, OUT> {
      * Short alias for endWhile()
      */
     end(): this;
+    /**
+     * Derives a new field from an existing field by applying a transform function.
+     *
+     * If the input field contains an array, the transform function is applied to each
+     * array element in parallel with batch size control. If the input field contains
+     * a scalar value, the transform function is applied directly.
+     *
+     * @param outputFieldName - Name of the field to store the result
+     * @param inputFieldName - Name of the existing field to transform
+     * @param transformFn - Function to apply to each element (for arrays) or the value directly (for scalars)
+     * @param options - Options including batch size for parallel processing
+     * @returns this (for chaining)
+     *
+     * @example
+     * ```typescript
+     * // Parallel processing of array items
+     * flow.derive('processedItems', 'items', (item, index) => processItem(item), { batchSize: 5 })
+     *
+     * // Direct transformation of scalar value
+     * flow.derive('upperText', 'text', (text) => text.toUpperCase())
+     * ```
+     */
+    derive<T>(outputFieldName: string, inputFieldName: string, transformFn: (value: any, index?: number, state?: TState) => T, options?: {
+        batchSize?: number;
+    }): this;
     /**
      * Gets execution plan information for debugging automatic parallelization
      *