/** * Workflow control-flow patterns (Python parity). * * Python reference: praisonaiagents/workflows/workflows.py * - Route (decision-based branching on the previous output) * - Parallel (fan-out with a worker cap and three failure modes) * - Include (run another recipe/workflow as a step) * - If / when / if_ (conditional branching on a "{{var}} > 80" string) * - MAX_NESTING_DEPTH * * These classes are plain step descriptors, exactly like the Python * dataclasses. Execution lives in `AgentFlow.run()` (./index.ts), which walks * the step list and interprets each pattern. * * @example * ```typescript * import { AgentFlow, when, Parallel, Route } from 'praisonai'; * * const flow = new AgentFlow({ * name: 'review', * variables: { score: 90 }, * steps: [ * new Parallel([summariser, factChecker], 2, 'partial_ok'), * when('{{score}} > 80', [approve], [reject]), * new Route({ approve: [publish], reject: [revise] }), * ], * }); * ``` */ import type { StepResult, WorkflowContext, Task } from './index'; import type { Loop } from './loop'; import type { Repeat } from './repeat'; /** Maximum nesting depth for patterns (prevents runaway recursion). Python: MAX_NESTING_DEPTH = 5 */ export declare const MAX_NESTING_DEPTH = 5; /** Default cap on concurrent parallel branches. Python: DEFAULT_MAX_PARALLEL_WORKERS = 3 */ export declare const DEFAULT_MAX_PARALLEL_WORKERS = 3; /** Failure strategies accepted by {@link Parallel}. */ export type ParallelOnFailure = 'partial_ok' | 'fail_fast' | 'fail_all'; export declare const PARALLEL_ON_FAILURE_MODES: readonly ParallelOnFailure[]; /** Anything with a `chat()` method (an Agent) can be used directly as a step. */ export interface AgentLikeStep { chat: (prompt: string, ...rest: any[]) => Promise | any; name?: string; } /** * Minimal surface a workflow needs in order to be nested via {@link Include}. * `AgentFlow` satisfies it; so can any user object. */ export interface IncludableWorkflow { name?: string; id?: string; run(input: any, options?: { variables?: Record; includeChain?: Set; }): Promise<{ output: any; results: StepResult[]; context: WorkflowContext; }>; } /** * A single entry in an `AgentFlow` step list: a leaf (`Task`, function or * agent) or a control-flow pattern. The `Task`/`Loop`/`Repeat` references are * type-only imports, so this module has no runtime dependency on ./index. */ export type FlowStep = Task | Loop | Repeat | If | Parallel | Route | Include | AgentLikeStep | ((input: any, context: WorkflowContext) => any); /** One failed branch of a {@link Parallel} block. */ export interface ParallelBranchError { /** Index of the branch in `Parallel.steps`. */ step: number; error: unknown; } /** * Raised when a workflow step fails in a way that must abort the run * (`Parallel` with `fail_fast` / `fail_all`). * Python: WorkflowStepError(message, cause=None, errors=None) */ export declare class WorkflowStepError extends Error { readonly cause?: unknown; readonly errors: ParallelBranchError[]; constructor(message: string, cause?: unknown, errors?: ParallelBranchError[]); } /** * Raised when patterns nest deeper than {@link MAX_NESTING_DEPTH}. Unlike an * ordinary branch failure this always aborts the run — a `Parallel` block * never records it as a partial result. */ export declare class NestingDepthError extends Error { constructor(message?: string); } /** * Decision-based branching. Routes to different steps based on the previous * step's output (word-boundary, case-insensitive key match; `default` otherwise). * * Python: Route(routes, default=None) */ export declare class Route { readonly routes: Record; /** Steps taken when no key matches. Falls back to `routes.default`, then `[]`. */ readonly default: FlowStep[]; constructor(routes: Record, defaultSteps?: FlowStep[] | null); } /** * Execute multiple steps concurrently and combine their outputs. * * Failure strategies (Python parity): * - `partial_ok` (default): keep going; failed branches contribute `null` * - `fail_fast`: stop scheduling new branches and throw on the first failure * - `fail_all`: wait for every branch, then throw if any failed * * Python: Parallel(steps, max_workers=None, on_failure="partial_ok") */ export declare class Parallel { readonly steps: FlowStep[]; /** Cap on concurrent branches. `null` = min(DEFAULT_MAX_PARALLEL_WORKERS, steps.length). */ readonly maxWorkers: number | null; readonly onFailure: ParallelOnFailure; constructor(steps: FlowStep[], maxWorkers?: number | null, onFailure?: ParallelOnFailure); } /** * Include another recipe or workflow as a workflow step. * * A `recipe` string is resolved through the resolver registered with * {@link setRecipeResolver}; a `workflow` instance is run directly. * * Python: Include(recipe=None, workflow=None, input=None) */ export declare class Include { readonly recipe: string | null; readonly workflow: IncludableWorkflow | null; /** Input override; supports `{{var}}`, `{{previous_output}}` and `{{input}}`. */ readonly input: string | null; constructor(recipe?: string | null, workflow?: IncludableWorkflow | null, input?: string | null); } /** * Resolves a recipe name to a runnable workflow. Return `null`/`undefined` * when the recipe is unknown. */ export type RecipeResolver = (recipe: string) => IncludableWorkflow | null | undefined | Promise; /** * Register the resolver used by {@link Include} steps that name a `recipe`. * Pass `null` to clear it. Without a resolver, running such a step throws. */ export declare function setRecipeResolver(resolver: RecipeResolver | null): void; /** The currently registered recipe resolver, if any. */ export declare function getRecipeResolver(): RecipeResolver | null; /** * Conditional branching. Evaluates `condition` (a string with `{{var}}` * placeholders) against the workflow variables and runs `thenSteps` or * `elseSteps`. * * Supported condition formats (see {@link evaluateWorkflowCondition}): * - Numeric comparison: "{{var}} > 80", "{{var}} >= 50", "{{var}} < 10" * - String equality: "{{var}} == approved", "{{var}} != rejected" * - Contains check: "error in {{message}}", "{{status}} contains success" * - Boolean: "{{flag}}" (truthy check) * - Nested property: "{{item.score}} >= 60" * * Python: If(condition, then_steps, else_steps=None) */ export declare class If { readonly condition: string; readonly thenSteps: FlowStep[]; readonly elseSteps: FlowStep[]; constructor(condition: string, thenSteps: FlowStep[], elseSteps?: FlowStep[] | null); } /** Create a routing decision point. Python: route(routes, default=None) */ export declare function routePattern(routes: Record, defaultSteps?: FlowStep[] | null): Route; /** Execute steps in parallel. Python: parallel(steps, max_workers=None, on_failure="partial_ok") */ export declare function parallelPattern(steps: FlowStep[], maxWorkers?: number | null, onFailure?: ParallelOnFailure): Parallel; /** Include another recipe or workflow as a step. Python: include(recipe=None, workflow=None, input=None) */ export declare function include(recipe?: string | null, workflow?: IncludableWorkflow | null, input?: string | null): Include; /** * Create a conditional branching step (preferred spelling). * Python: when(condition, then_steps, else_steps=None) */ export declare function when(condition: string, thenSteps: FlowStep[], elseSteps?: FlowStep[] | null): If; /** Alias for {@link when}. Python: if_(condition, then_steps, else_steps=None) */ export declare function if_(condition: string, thenSteps: FlowStep[], elseSteps?: FlowStep[] | null): If; /** Alias for {@link if_} with a JS-friendly name. */ export declare const ifStep: typeof if_; /** * Evaluate a workflow condition string with `{{var}}` substitution. * * Python: praisonaiagents.conditions.evaluator.evaluate_condition(condition, variables, previous_output) * * Returns `false` (fail-safe) when the condition cannot be evaluated. */ export declare function evaluateWorkflowCondition(condition: string, variables: Record, previousOutput?: any): boolean; /** * Substitute `{{var}}`, `{{nested.path}}`, `{{previous_output}}` and `{{input}}` * in a template string. Unknown placeholders are left untouched (Python parity: * only keys present in `variables` are replaced). */ export declare function substituteWorkflowVariables(template: string, variables: Record, previousOutput?: any, input?: any): string; /** True when `step` is one of the pattern descriptors defined in this module. */ export declare function isControlFlowPattern(step: unknown): step is If | Parallel | Route | Include;