AxFlow

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L79

AxFlow - A fluent, chainable API for building and orchestrating complex, stateful AI programs.

Now with advanced type-safe chaining where each method call evolves the type information, providing compile-time type safety and superior IntelliSense.

Example

const flow = new AxFlow<{ topic: string }, { finalAnswer: string }>()
  .node('summarizer', 'text:string -> summary:string')
  .node('critic', 'summary:string -> critique:string')
  .execute('summarizer', state => ({ text: `About ${state.topic}` })) // state is { topic: string }
  .execute('critic', state => ({ summary: state.summarizerResult.summary })) // state evolves!
  .map(state => ({ finalAnswer: state.criticResult.critique })) // fully typed!

const result = await flow.forward(ai, { topic: "AI safety" })

Type Parameters

Implements

• AxFlowable<IN, OUT>

Constructors

Constructor

new AxFlow<IN, OUT, TNodes, TState>(options?: object): AxFlow<IN, OUT, TNodes, TState>;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L598

Parameters

Returns

AxFlow<IN, OUT, TNodes, TState>

Methods

applyOptimization()

applyOptimization(optimizedProgram: AxOptimizedProgram<any>): void;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L1702

Apply optimized configuration to this flow and all node programs.

Parameters

Returns

void

Implementation of

AxFlowable.applyOptimization

b()

b(predicate: (_state: TState) => unknown): this;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L1772

Short alias for branch()

Parameters

Returns

this

branch()

branch(predicate: (_state: TState) => unknown): this;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L1755

Starts a conditional branch based on a predicate function.

Example

flow.branch(state => state.qualityResult.needsMoreInfo)
  .when(true)
    .execute('queryGen', ...)
  .when(false)
    .execute('answer', ...)
  .merge()

Parameters

Returns

this

this (for chaining)

derive()

derive<T>(
   outputFieldName: string, 
   inputFieldName: string, 
   transformFn: (value: any, index?: number, state?: TState) => T, 
   options?: object): this;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L2320

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.

Example

// 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())

Type Parameters

Parameters

Returns

this

this (for chaining)

e()

e<TNodeName, TAI>(
   nodeName: TNodeName, 
   mapping: (_state: TState) => GetGenIn<TNodes[TNodeName]>, 
dynamicContext?: AxFlowDynamicContext<TAI>): AxFlow<IN, OUT, TNodes, AddNodeResult<TState, TNodeName, GetGenOut<TNodes[TNodeName]>>>;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L1723

Short alias for execute()

Type Parameters

Parameters

Returns

AxFlow<IN, OUT, TNodes, AddNodeResult<TState, TNodeName, GetGenOut<TNodes[TNodeName]>>>

end()

end(): this;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L2294

Short alias for endWhile()

Returns

this

endWhile()

endWhile(): this;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L2228

Marks the end of a loop block.

Returns

this

this (for chaining)

execute()

execute<TNodeName, TAI>(
   nodeName: TNodeName, 
   mapping: (_state: TState) => GetGenIn<TNodes[TNodeName]>, 
dynamicContext?: AxFlowDynamicContext<TAI>): AxFlow<IN, OUT, TNodes, AddNodeResult<TState, TNodeName, GetGenOut<TNodes[TNodeName]>>>;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L1570

Executes a previously defined node with full type safety. The node name must exist in TNodes, and the mapping function is typed based on the node’s signature.

Example

flow.execute('summarizer', state => ({ text: state.originalText }), { ai: cheapAI })

Type Parameters

Parameters

Returns

AxFlow<IN, OUT, TNodes, AddNodeResult<TState, TNodeName, GetGenOut<TNodes[TNodeName]>>>

New AxFlow instance with TState augmented with the node’s result

fb()

fb(
   condition: (_state: TState) => boolean, 
   targetLabel: string, 
   maxIterations: number): this;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L2159

Short alias for feedback()

Parameters

Returns

this

feedback()

feedback(
   condition: (_state: TState) => boolean, 
   targetLabel: string, 
   maxIterations: number): this;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L2103

Creates a feedback loop that jumps back to a labeled step if a condition is met.

Example

flow.label('retry-point')
  .execute('answer', ...)
  .execute('qualityCheck', ...)
  .feedback(state => state.qualityCheckResult.confidence < 0.7, 'retry-point')

Parameters

Returns

this

this (for chaining)

forward()

forward<T>(
   ai: T, 
   values: IN | AxMessage<IN>[], 
options?: Readonly<AxAIServiceOptions & object & object>): Promise<OUT>;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L831

Executes the flow with the given AI service and input values.

This is the main execution method that orchestrates the entire flow execution. It handles several complex aspects:

1. Dynamic Signature Inference: If the flow was created with a default signature but has nodes defined, it will infer the actual signature from the flow structure.

2. Execution Mode Selection: Chooses between optimized parallel execution (when auto-parallel is enabled) or sequential execution based on configuration.

3. State Management: Maintains the evolving state object as it flows through each step, accumulating results and transformations.

4. Performance Optimization: Uses the execution planner to identify independent operations that can run in parallel, reducing total execution time.

Execution Flow:

• Initialize state with input values
• Infer signature if needed (based on nodes and current signature)
• Choose execution strategy (parallel vs sequential)
• Execute all steps while maintaining state consistency
• Return final state cast to expected output type

Type Parameters

Parameters

Returns

Promise<OUT>

Promise that resolves to the final output

Implementation of

AxFlowable.forward

getExecutionPlan()

getExecutionPlan(): object;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L2408

Gets execution plan information for debugging automatic parallelization

Returns

object

Object with execution plan details

getSignature()

getSignature(): AxSignature;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L2427

Returns

AxSignature

Implementation of

AxFlowable.getSignature

getTraces()

getTraces(): AxProgramTrace<IN, OUT>[];

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L699

Returns

AxProgramTrace<IN, OUT>[]

Implementation of

AxFlowable.getTraces

getTracesReport()

getTracesReport(): Record<string, AxProgramTrace<any, any>[]>;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L773

Gets a detailed trace report broken down by node name. This provides visibility into the execution traces for each node.

Returns

Record<string, AxProgramTrace<any, any>[]>

Object mapping node names to their trace data

getUsage()

getUsage(): AxModelUsage & object[];

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L716

Returns

AxModelUsage & object[]

Implementation of

AxFlowable.getUsage

getUsageReport()

getUsageReport(): Record<string, AxProgramUsage[]>;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L757

Gets a detailed usage report broken down by node name. This provides visibility into which nodes are consuming the most tokens.

Returns

Record<string, AxProgramUsage[]>

Object mapping node names to their usage statistics

l()

l(label: string): this;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L1552

Short alias for label()

Parameters

Returns

this

label()

label(label: string): this;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L1541

Labels a step for later reference (useful for feedback loops).

Example

flow.label('retry-point')
  .execute('queryGen', ...)

Parameters

Returns

this

this (for chaining, no type change)

m()

Call Signature

m<TNewState>(transform: (_state: TState) => TNewState): AxFlow<IN, OUT, TNodes, TNewState>;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L1430

Short alias for map() - supports parallel option and async functions

Type Parameters

Parameters

Returns

AxFlow<IN, OUT, TNodes, TNewState>

Call Signature

m<TNewState>(transform: (_state: TState) => Promise<TNewState>): AxFlow<IN, OUT, TNodes, TNewState>;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L1434

Short alias for map() - supports parallel option and async functions

Type Parameters

Parameters

Returns

AxFlow<IN, OUT, TNodes, TNewState>

Call Signature

m<TNewState>(transforms: (_state: TState) => TNewState[], options: object): AxFlow<IN, OUT, TNodes, TNewState>;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L1438

Short alias for map() - supports parallel option and async functions

Type Parameters

Parameters

Returns

AxFlow<IN, OUT, TNodes, TNewState>

Call Signature

m<TNewState>(transforms: (_state: TState) => Promise<TNewState>[], options: object): AxFlow<IN, OUT, TNodes, TNewState>;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L1443

Short alias for map() - supports parallel option and async functions

Type Parameters

Parameters

Returns

AxFlow<IN, OUT, TNodes, TNewState>

map()

Call Signature

map<TNewState>(transform: (_state: TState) => TNewState): AxFlow<IN, OUT, TNodes, TNewState>;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L1252

Applies a synchronous transformation to the state object. Returns a new AxFlow type with the evolved state.

Example

flow.map(state => ({ ...state, processedText: state.text.toLowerCase() }))

Type Parameters

Parameters

Returns

AxFlow<IN, OUT, TNodes, TNewState>

New AxFlow instance with updated TState type

Call Signature

map<TNewState>(transform: (_state: TState) => Promise<TNewState>): AxFlow<IN, OUT, TNodes, TNewState>;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L1271

Applies an asynchronous transformation to the state object. Returns a new AxFlow type with the evolved state.

Example

flow.map(async state => ({
  ...state,
  apiResult: await fetchDataFromAPI(state.query)
}))

Type Parameters

Parameters

Returns

AxFlow<IN, OUT, TNodes, TNewState>

New AxFlow instance with updated TState type

Call Signature

map<TNewState>(transforms: (_state: TState) => TNewState[], options: object): AxFlow<IN, OUT, TNodes, TNewState>;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L1294

Applies a transformation to the state object with optional parallel execution. When parallel is enabled, the transform function should prepare data for parallel processing. The actual parallel processing happens with the array of transforms provided.

Example

// Parallel map with multiple transforms
flow.map([
  state => ({ ...state, result1: processA(state.data) }),
  state => ({ ...state, result2: processB(state.data) }),
  state => ({ ...state, result3: processC(state.data) })
], { parallel: true })

Type Parameters

Parameters

Returns

AxFlow<IN, OUT, TNodes, TNewState>

New AxFlow instance with updated TState type

Call Signature

map<TNewState>(transforms: (_state: TState) => Promise<TNewState>[], options: object): AxFlow<IN, OUT, TNodes, TNewState>;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L1317

Applies async transformations to the state object with optional parallel execution. When parallel is enabled, all async transforms are executed concurrently.

Example

// Parallel async map with multiple transforms
flow.map([
  async state => ({ ...state, result1: await apiCall1(state.data) }),
  async state => ({ ...state, result2: await apiCall2(state.data) }),
  async state => ({ ...state, result3: await apiCall3(state.data) })
], { parallel: true })

Type Parameters

Parameters

Returns

AxFlow<IN, OUT, TNodes, TNewState>

New AxFlow instance with updated TState type

Call Signature

map<TNewState>(transform: (_state: TState) => TNewState | Promise<TNewState>, options?: object): AxFlow<IN, OUT, TNodes, TNewState>;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L1322

Applies a synchronous transformation to the state object. Returns a new AxFlow type with the evolved state.

Example

flow.map(state => ({ ...state, processedText: state.text.toLowerCase() }))

Type Parameters

Parameters

Returns

AxFlow<IN, OUT, TNodes, TNewState>

New AxFlow instance with updated TState type

mapOutput()

mapOutput<TOutput>(transform: (_state: TState) => TOutput): AxFlow<IN, TOutput, TNodes, TOutput & TState>;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L2554

Applies a final transformation to the state object that updates both state and output type. This is specifically designed for terminal transformations that shape the final output.

Example

const result = await flow
  .node('analyzer', 'userQuestion:string -> analysisResult:string')
  .execute('analyzer', state => ({ userQuestion: state.userQuestion }))
  .mapOutput(state => ({
    // Note: Node results are typed as AxFieldValue, so you may need to cast
    finalAnswer: state.analyzerResult.analysisResult as string
  }))
  .forward(ai, { userQuestion: 'test' });

// result is typed as { finalAnswer: string }

Type Parameters

Parameters

Returns

AxFlow<IN, TOutput, TNodes, TOutput & TState>

New AxFlow instance with updated OUT and TState types

merge()

merge<TMergedState>(): AxFlow<IN, OUT, TNodes, TMergedState>;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L1831

Merges the results of conditional branches into a single execution path.

This method is called after defining conditional branches with branch() and when() methods. It creates a merge point where the flow continues with the results from whichever branch was executed based on the branch condition.

How conditional merging works:

1. The branch predicate is evaluated against the current state
2. The matching branch’s steps are executed sequentially
3. If no branch matches, the state is returned unchanged
4. The merged result becomes the new state for subsequent steps

Type safety note: The TMergedState generic allows for type-level tracking of what fields will be available after the merge, though runtime behavior depends on which branch actually executes.

Example

flow
  .branch(state => state.complexity > 0.5)
  .when(true)
    .execute('complexProcessor', state => ({ input: state.text }))
  .when(false)
    .execute('simpleProcessor', state => ({ input: state.text }))
  .merge() // Combines results from either branch

Type Parameters

Returns

AxFlow<IN, OUT, TNodes, TMergedState>

AxFlow with updated state type reflecting the merged result

mg()

mg<TMergedState>(): AxFlow<IN, OUT, TNodes, TMergedState>;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L1903

Short alias for merge()

Type Parameters

Returns

AxFlow<IN, OUT, TNodes, TMergedState>

mo()

mo<TOutput>(transform: (_state: TState) => TOutput): AxFlow<IN, TOutput, TNodes, TOutput & TState>;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L2600

Short alias for mapOutput()

Type Parameters

Parameters

Returns

AxFlow<IN, TOutput, TNodes, TOutput & TState>

n()

Call Signature

n<TName, TSig>(name: TName, signature: TSig): AxFlow<IN, OUT, TNodes & { [K in string]: InferAxGen<TSig> }, TState>;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L1201

Short alias for node() - supports signature strings, AxSignature instances, AxGen instances, and program classes

Type Parameters

Parameters

Returns

AxFlow<IN, OUT, TNodes & { [K in string]: InferAxGen<TSig> }, TState>

Call Signature

n<TName>(name: TName, signature: AxSignature): AxFlow<IN, OUT, TNodes & { [K in string]: AxGen<AxGenIn, AxGenOut> }, TState>;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L1206

Short alias for node() - supports signature strings, AxSignature instances, AxGen instances, and program classes

Type Parameters

Parameters

Returns

AxFlow<IN, OUT, TNodes & { [K in string]: AxGen<AxGenIn, AxGenOut> }, TState>

Call Signature

n<TName, TProgram>(name: TName, programClass: TProgram): AxFlow<IN, OUT, TNodes & { [K in string]: InstanceType<TProgram> }, TState>;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L1216

Short alias for node() - supports signature strings, AxSignature instances, AxGen instances, and program classes

Type Parameters

Parameters

Returns

AxFlow<IN, OUT, TNodes & { [K in string]: InstanceType<TProgram> }, TState>

Call Signature

n<TName, TProgram>(name: TName, programInstance: TProgram): AxFlow<IN, OUT, TNodes & { [K in string]: TProgram }, TState>;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L1224

Short alias for node() - supports signature strings, AxSignature instances, AxGen instances, and program classes

Type Parameters

Parameters

Returns

AxFlow<IN, OUT, TNodes & { [K in string]: TProgram }, TState>

node()

Call Signature

node<TName, TSig>(name: TName, signature: TSig): AxFlow<IN, OUT, TNodes & { [K in string]: InferAxGen<TSig> }, TState>;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L1035

Declares a reusable computational node using a signature string. Returns a new AxFlow type that tracks this node in the TNodes registry.

Example

flow.node('summarizer', 'text:string -> summary:string')
flow.node('analyzer', 'text:string -> analysis:string, confidence:number', { debug: true })

Type Parameters

Parameters

Returns

AxFlow<IN, OUT, TNodes & { [K in string]: InferAxGen<TSig> }, TState>

New AxFlow instance with updated TNodes type

Call Signature

node<TName>(name: TName, signature: AxSignature): AxFlow<IN, OUT, TNodes & { [K in string]: AxGen<AxGenIn, AxGenOut> }, TState>;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L1059

Declares a reusable computational node using an AxSignature instance. This allows using pre-configured signatures in the flow.

Example

const sig = s('text:string -> summary:string')
flow.node('summarizer', sig, { temperature: 0.1 })

Type Parameters

Parameters

Returns

AxFlow<IN, OUT, TNodes & { [K in string]: AxGen<AxGenIn, AxGenOut> }, TState>

New AxFlow instance with updated TNodes type

Call Signature

node<TName, TProgram>(name: TName, programClass: TProgram): AxFlow<IN, OUT, TNodes & { [K in string]: InstanceType<TProgram> }, TState>;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L1085

Declares a reusable computational node using a class that extends AxProgram. This allows using custom program classes in the flow.

Example

class CustomProgram extends AxProgram<{ input: string }, { output: string }> {
  async forward(ai, values) { return { output: values.input.toUpperCase() } }
}
flow.node('custom', CustomProgram)

Type Parameters

Parameters

Returns

AxFlow<IN, OUT, TNodes & { [K in string]: InstanceType<TProgram> }, TState>

New AxFlow instance with updated TNodes type

Call Signature

node<TName, TProgram>(name: TName, programInstance: TProgram): AxFlow<IN, OUT, TNodes & { [K in string]: TProgram }, TState>;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L1106

Declares a reusable computational node using an AxProgrammable instance. This allows using pre-configured AxGen instances or other programmable objects in the flow.

Type Parameters

Parameters

Returns

AxFlow<IN, OUT, TNodes & { [K in string]: TProgram }, TState>

New AxFlow instance with updated TNodes type

nodeExtended()

nodeExtended<TName>(
   name: TName, 
   baseSignature: 
  | string
  | AxSignature<Record<string, any>, Record<string, any>>, 
extensions: object): AxFlow<IN, OUT, TNodes & { [K in string]: AxGen<AxGenIn, AxGenOut> }, TState>;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L2456

Creates a new AxFlow node from an existing signature by extending it with additional fields.

Example

// Create a chain-of-thought node
flow.nodeExtended('reasoner', 'question:string -> answer:string', {
  prependOutputs: [
    { name: 'reasoning', type: f.internal(f.string('Step-by-step reasoning')) }
  ]
})

// Create a node with context and confidence
flow.nodeExtended('analyzer', 'input:string -> output:string', {
  appendInputs: [{ name: 'context', type: f.optional(f.string('Context')) }],
  appendOutputs: [{ name: 'confidence', type: f.number('Confidence score') }]
})

Type Parameters

Parameters

Returns

AxFlow<IN, OUT, TNodes & { [K in string]: AxGen<AxGenIn, AxGenOut> }, TState>

New AxFlow instance with the extended node

nx()

nx<TName>(
   name: TName, 
   baseSignature: 
  | string
  | AxSignature<Record<string, any>, Record<string, any>>, 
extensions: object): AxFlow<IN, OUT, TNodes & { [K in string]: AxGen<AxGenIn, AxGenOut> }, TState>;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L2515

Short alias for nodeExtended() - creates nodes with extended signatures

Type Parameters

Parameters

Returns

AxFlow<IN, OUT, TNodes & { [K in string]: AxGen<AxGenIn, AxGenOut> }, TState>

p()

p(branches: (
  | AxFlowParallelBranch
  | AxFlowTypedParallelBranch<TNodes, TState>)[]): object;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L2073

Short alias for parallel()

Parameters

Returns

object

parallel()

parallel(branches: (
  | AxFlowParallelBranch
  | AxFlowTypedParallelBranch<TNodes, TState>)[]): object;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L1944

Executes multiple operations in parallel and provides a merge method for combining results.

This method enables true parallel execution of independent operations, which is particularly useful for operations like:

• Multiple document retrievals
• Parallel processing of different data sources
• Independent LLM calls that can run simultaneously

How parallel execution works:

1. Each branch function receives a sub-context for defining operations
2. All branches are executed simultaneously using Promise.all()
3. Results are stored in _parallelResults for the merge operation
4. The merge function combines the results into a single field

Performance benefits:

• Reduces total execution time for independent operations
• Maximizes throughput for I/O-bound operations (like LLM calls)
• Maintains type safety through the merge operation

Example

flow.parallel([
  subFlow => subFlow.execute('retrieve1', state => ({ query: state.query1 })),
  subFlow => subFlow.execute('retrieve2', state => ({ query: state.query2 })),
  subFlow => subFlow.execute('retrieve3', state => ({ query: state.query3 }))
]).merge('documents', (docs1, docs2, docs3) => [...docs1, ...docs2, ...docs3])

Parameters

Returns

object

Object with merge method for combining results

r()

r<TNewOut>(transform: (_state: TState) => TNewOut): AxFlow<IN, TNewOut, TNodes, TState>;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L1523

Short alias for returns() - r() is to returns() as m() is to map()

Type Parameters

Parameters

Returns

AxFlow<IN, TNewOut, TNodes, TState>

A new flow with the output type set to the transform result

resetTraces()

resetTraces(): void;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L743

Resets trace tracking for the flow. This is called automatically on each forward/streamingForward call.

Returns

void

resetUsage()

resetUsage(): void;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L727

Returns

void

Implementation of

AxFlowable.resetUsage

returns()

returns<TNewOut>(transform: (_state: TState) => TNewOut): AxFlow<IN, TNewOut, TNodes, TState>;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L1473

Terminal transformation that sets the final output type of the flow. Use this as the last transformation to get proper type inference for the flow result.

Example

const flow = flow<{ input: string }>()
  .map(state => ({ ...state, processed: true }))
  .returns(state => ({
    result: state.processed ? "done" : "pending"
  })) // TypeScript now knows the output is { result: string }

Type Parameters

Parameters

Returns

AxFlow<IN, TNewOut, TNodes, TState>

A new flow with the output type set to the transform result

setDemos()

setDemos(demos: readonly AxProgramDemos<IN, OUT>[]): void;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L711

Parameters

Returns

void

Implementation of

AxFlowable.setDemos

setExamples()

setExamples(examples: Readonly<AxProgramExamples<IN, OUT>>, options?: Readonly<AxSetExamplesOptions>): void;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L681

Parameters

Returns

void

Implementation of

AxFlowable.setExamples

setId()

setId(id: string): void;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L689

Parameters

Returns

void

Implementation of

AxFlowable.setId

setParentId()

setParentId(parentId: string): void;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L694

Parameters

Returns

void

Implementation of

AxFlowable.setParentId

streamingForward()

streamingForward<T>(
   ai: T, 
   values: IN | AxMessage<IN>[], 
options?: Readonly<AxProgramStreamingForwardOptionsWithModels<T>>): AxGenStreamingOut<OUT>;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L783

Type Parameters

Parameters

Returns

AxGenStreamingOut<OUT>

Implementation of

AxFlowable.streamingForward

w()

w(value: unknown): this;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L1796

Short alias for when()

Parameters

Returns

this

wh()

wh(condition: (_state: TState) => boolean, maxIterations: number): this;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L2219

Short alias for while()

Parameters

Returns

this

when()

when(value: unknown): this;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L1782

Defines a branch case for the current branch context.

Parameters

Returns

this

this (for chaining)

while()

while(condition: (state: TState) => boolean, maxIterations: number): this;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L2181

Marks the beginning of a loop block.

Example

flow.while(state => state.iterations < 3, 10)
  .map(state => ({ ...state, iterations: (state.iterations || 0) + 1 }))
  .endWhile()

Parameters

Returns

this

this (for chaining)

create()

static create<IN, OUT, TNodes, TState>(options?: object): AxFlow<IN, OUT, TNodes, TState>;

Defined in: https://github.com/ax-llm/ax/blob/8dfd0ce02b8cb386fb2c93fa280a2ec0da2d6011/src/ax/flow/flow.ts#L649

Static factory method to create a new AxFlow instance with proper type safety

Type Parameters

Parameters

Returns

AxFlow<IN, OUT, TNodes, TState>

New AxFlow instance with type-safe defaults