AxFlow

Defined in: https://github.com/ax-llm/ax/blob/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L85

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L607

Parameters

Returns

AxFlow<IN, OUT, TNodes, TState>

Methods

applyOptimization()

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

Defined in: https://github.com/ax-llm/ax/blob/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L1940

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L2010

Short alias for branch()

Parameters

Returns

this

branch()

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

Defined in: https://github.com/ax-llm/ax/blob/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L1993

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L2558

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)

description()

description(name: string, description: string): this;

Defined in: https://github.com/ax-llm/ax/blob/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L725

Parameters

Returns

this

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L1961

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L2532

Short alias for endWhile()

Returns

this

endWhile()

endWhile(): this;

Defined in: https://github.com/ax-llm/ax/blob/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L2466

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L1808

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L2397

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L2341

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L996

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L2646

Gets execution plan information for debugging automatic parallelization

Returns

object

Object with execution plan details

getNodePrograms()

getNodePrograms(): readonly object[];

Defined in: https://github.com/ax-llm/ax/blob/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L823

Expose node programs for system-level operations (optimization, inspection)

Returns

readonly object[]

getSignature()

getSignature(): AxSignature;

Defined in: https://github.com/ax-llm/ax/blob/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L2665

Returns

AxSignature

Implementation of

AxFlowable.getSignature

getTraces()

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

Defined in: https://github.com/ax-llm/ax/blob/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L708

Returns

AxProgramTrace<IN, OUT>[]

Implementation of

AxFlowable.getTraces

getTracesReport()

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

Defined in: https://github.com/ax-llm/ax/blob/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L867

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L769

Returns

AxModelUsage & object[]

Implementation of

AxFlowable.getUsage

getUsageReport()

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

Defined in: https://github.com/ax-llm/ax/blob/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L810

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L1790

Short alias for label()

Parameters

Returns

this

label()

label(label: string): this;

Defined in: https://github.com/ax-llm/ax/blob/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L1779

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L1668

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L1672

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L1676

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L1681

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L1490

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L1509

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L1532

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L1555

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L1560

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L2792

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L2069

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L2141

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L2838

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L1439

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L1444

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L1454

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L1462

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L1273

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L1297

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L1323

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L1344

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L2694

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L2753

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L2311

Short alias for parallel()

Parameters

Returns

object

parallel()

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

Defined in: https://github.com/ax-llm/ax/blob/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L2182

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L1761

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L796

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L780

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L1711

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

setAllNodeInstructions()

setAllNodeInstructions(map: Readonly<Record<string, string>>): void;

Defined in: https://github.com/ax-llm/ax/blob/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L855

Bulk-apply instructions to nodes; ignores names that don’t exist or nodes without instruction setter

Parameters

Returns

void

setDemos()

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

Defined in: https://github.com/ax-llm/ax/blob/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L720

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L690

Parameters

Returns

void

Implementation of

AxFlowable.setExamples

setId()

setId(id: string): void;

Defined in: https://github.com/ax-llm/ax/blob/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L698

Parameters

Returns

void

Implementation of

AxFlowable.setId

setNodeInstruction()

setNodeInstruction(name: string, instruction: string): boolean;

Defined in: https://github.com/ax-llm/ax/blob/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L837

Attempt to set instruction on a node if supported (AxGen. setInstruction is optional; returns true if applied)

Parameters

Returns

boolean

setParentId()

setParentId(parentId: string): void;

Defined in: https://github.com/ax-llm/ax/blob/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L703

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L877

Type Parameters

Parameters

Returns

AxGenStreamingOut<OUT>

Implementation of

AxFlowable.streamingForward

toFunction()

toFunction(): AxFunction;

Defined in: https://github.com/ax-llm/ax/blob/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L732

Returns

AxFunction

w()

w(value: unknown): this;

Defined in: https://github.com/ax-llm/ax/blob/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L2034

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L2457

Short alias for while()

Parameters

Returns

this

when()

when(value: unknown): this;

Defined in: https://github.com/ax-llm/ax/blob/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L2020

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L2419

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/d2df625e2c2fd70a090d6321c042579c2819f0d1/src/ax/flow/flow.ts#L658

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