README

A graph-based workflow orchestration engine for PHP 8.2+. Define directed acyclic graphs of nodes — AI calls, tool executions, conditionals, loops, parallel branches — and run them with built-in persistence, middleware, guards, 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 a terminal state
• Transition guards — ExpressionGuard (closure) and AIGuard (LLM-based decisions)
• Middleware pipeline — onion architecture for cross-cutting concerns per step
• Persistence — FileWorkflowStore and CacheWorkflowStore for suspend/resume
• Observability — EventBus integration with 9 typed 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']; // AI-generated analysis
echo $result->elapsedMs;        // Execution time in ms

Documentation

Full documentation is available in the docs/ directory:

• Getting Started
• WorkflowBuilder
• Node Types
• Transitions & Guards
• WorkflowRunner
• Context & State
• Persistence
• Observability
• Testing

Architecture

WorkflowBuilder::named('my-flow')     ← Define the graph
    ->addAINode(...)                  ← Add nodes (8 types)
    ->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.2 or higher
• token27/nexus-ai ^1.0

License

MIT. Please see LICENSE for more information.