README

A graph-based workflow orchestration engine for PHP 8.3+. Define directed workflow graphs of nodes: AI calls, tool executions, conditionals, loops, parallel branches, waits, and sub-workflows. Run them with middleware, guards, persistence stores, resumable execution, and observability.

Built on top of NexusAI for seamless LLM integration.

Features

Fluent WorkflowBuilder: declarative, chainable API for constructing workflow graphs
8 node types: ActionNode, AINode, ToolNode, ConditionNode, LoopNode, ParallelNode, WaitNode, SubWorkflowNode
WorkflowRunner: executes graphs following transitions until completion, failure, or suspension
Resumable execution: WaitNode suspends a workflow and resume() continues from the suspended node without re-running previous steps
Transition guards: ExpressionGuard closures and AIGuard LLM-based decisions
Middleware pipeline: onion architecture for cross-cutting concerns per step
Persistence stores: FileWorkflowStore, CacheWorkflowStore, and InMemoryWorkflowStore for workflow snapshots
Observability: EventBus integration with typed workflow event DTOs
FakeWorkflowRunner: testing without HTTP calls, with assertion helpers
Immutable context: thread-safe WorkflowContext that flows through nodes

Installation

composer require token27/nexus-ai-workflows

Requires nexus-ai as a dependency:

composer require token27/nexus-ai guzzlehttp/guzzle

Quick Start

use Token27\NexusAI\Driver\DriverRegistry;
use Token27\NexusAI\Workflows\Engine\WorkflowBuilder;
use Token27\NexusAI\Workflows\Engine\WorkflowContext;
use Token27\NexusAI\Workflows\Runner\WorkflowRunner;

// 1. Register your LLM drivers.
$registry = new DriverRegistry();
$registry->register('openai', fn () => /* your OpenAI driver */);

// 2. Build a workflow.
$workflow = WorkflowBuilder::named('research-pipeline')
    ->addAINode('analyze', 'openai', 'gpt-4o', 'Analyze this topic: {{_input}}')
    ->addActionNode('format', fn ($ctx) => $ctx->with('output', strtoupper($ctx->get('output'))))
    ->addTransition('analyze', 'format')
    ->build();

// 3. Run it.
$runner = new WorkflowRunner($registry);
$result = $runner->run($workflow, WorkflowContext::from(['_input' => 'PHP async']));

echo $result->output['output'];
echo $result->elapsedMs;

Examples

Runnable examples are available in examples/:

01-basic-action-workflow.php: pure PHP workflow without AI calls
02-fake-ai-workflow.php: test an AI workflow with FakeWorkflowRunner
03-suspend-resume-tasks.php: CakePHP-style multi-task suspend/resume flow
04-branch-loop-workflow.php: branching and loops

Run one locally after composer install:

php examples/03-suspend-resume-tasks.php

Documentation

Full documentation is available in the docs/ directory:

Architecture

WorkflowBuilder::named('my-flow')     <- Define the graph
    ->addAINode(...)                  <- Add nodes
    ->addTransition(...)              <- Connect with transitions
    ->build()                         <- Immutable Workflow

WorkflowRunner::run(workflow, ctx)    <- Execute the graph
    +-- Middleware pipeline           <- Cross-cutting concerns
    +-- Node::execute(ctx) -> ctx     <- Each node transforms context
    +-- TransitionEvaluator           <- Guards + priority routing
    +-- EventBus                      <- Observability events

Requirements

PHP 8.3 or higher
token27/nexus-ai ^1.0

License

MIT. Please see LICENSE for more information.

token27 / nexus-ai-workflows

Maintainers

Package info

Statistics

Security