flowcraft 1.0.0-beta.1

package/sandbox/5.distributed/data/4.content-moderation/401.json

@@ -0,0 +1,47 @@
+{
+	"nodes": [
+		{
+			"id": "api_call_ban_user",
+			"type": "llm-process",
+			"data": {
+				"promptTemplate": "Simulate a database update to ban a user. Respond with a simulated SQL command.\n\nUPDATE users SET status='banned' WHERE id={{userId}};",
+				"inputs": {
+					"userId": "userId"
+				}
+			}
+		},
+		{
+			"id": "log_ban_event",
+			"type": "llm-process",
+			"data": {
+				"promptTemplate": "Simulate writing to a security log. Respond with a simulated log entry.\n\nEVENT: UserBanned\nUSER_ID: {{userId}}\nREASON: {{reason}}\nSEVERITY: critical",
+				"inputs": {
+					"userId": "userId",
+					"reason": "reason"
+				}
+			}
+		},
+		{
+			"id": "output_ban_summary",
+			"type": "output",
+			"data": {
+				"outputKey": "ban_summary",
+				"promptTemplate": "User Banned Successfully.\n--- DB Action ---\n{{db_update}}\n\n--- Log Entry ---\n{{log_entry}}",
+				"inputs": {
+					"db_update": "api_call_ban_user",
+					"log_entry": "log_ban_event"
+				}
+			}
+		}
+	],
+	"edges": [
+		{
+			"source": "api_call_ban_user",
+			"target": "output_ban_summary"
+		},
+		{
+			"source": "log_ban_event",
+			"target": "output_ban_summary"
+		}
+	]
+}

package/sandbox/5.distributed/data/4.content-moderation/402.json

@@ -0,0 +1,46 @@
+{
+	"nodes": [
+		{
+			"id": "redact_pii",
+			"type": "llm-process",
+			"data": {
+				"promptTemplate": "Find any Personally Identifiable Information (PII) in the following text and replace it with '[REDACTED]'.\n\nOriginal Text: \"{{userPost}}\"",
+				"inputs": {
+					"userPost": "userPost"
+				}
+			}
+		},
+		{
+			"id": "generate_warning",
+			"type": "llm-process",
+			"data": {
+				"promptTemplate": "Write a polite, templated warning message to user {{userId}} explaining that their post was edited to remove personal information and reminding them not to share PII.",
+				"inputs": {
+					"userId": "userId"
+				}
+			}
+		},
+		{
+			"id": "output_redaction_summary",
+			"type": "output",
+			"data": {
+				"outputKey": "redaction_summary",
+				"promptTemplate": "Post Edited for PII.\n--- Redacted Post ---\n{{redacted_post}}\n\n--- User Warning Message ---\n{{warning_message}}",
+				"inputs": {
+					"redacted_post": "redact_pii",
+					"warning_message": "generate_warning"
+				}
+			}
+		}
+	],
+	"edges": [
+		{
+			"source": "redact_pii",
+			"target": "output_redaction_summary"
+		},
+		{
+			"source": "generate_warning",
+			"target": "output_redaction_summary"
+		}
+	]
+}

package/sandbox/5.distributed/data/4.content-moderation/403.json

@@ -0,0 +1,31 @@
+{
+	"nodes": [
+		{
+			"id": "delete_and_flag_user",
+			"type": "llm-process",
+			"data": {
+				"promptTemplate": "Simulate the actions of deleting a spam post and flagging the user. Respond with a summary of actions taken for user ID {{userId}}.",
+				"inputs": {
+					"userId": "userId"
+				}
+			}
+		},
+		{
+			"id": "output_spam_summary",
+			"type": "output",
+			"data": {
+				"outputKey": "spam_deletion_summary",
+				"promptTemplate": "{{result}}",
+				"inputs": {
+					"result": "delete_and_flag_user"
+				}
+			}
+		}
+	],
+	"edges": [
+		{
+			"source": "delete_and_flag_user",
+			"target": "output_spam_summary"
+		}
+	]
+}

package/sandbox/5.distributed/data/4.content-moderation/README.md

@@ -0,0 +1,83 @@
+# Use Case 4: Content Moderation
+
+This workflow demonstrates a sophisticated "router" pattern. It performs multiple parallel analyses on a piece of content and then uses a central LLM-powered router node to decide which of several distinct moderation actions to take.
+
+## Main Workflow ID: 400
+
+### Description
+
+1. **Parallel Analysis**: The workflow begins by performing three independent checks on the `userPost` in parallel:
+    - `check_for_pii`: Looks for Personally Identifiable Information.
+    - `check_for_hate_speech`: Analyzes the severity of any hate speech.
+    - `check_for_spam`: Detects if the post is commercial spam.
+2. **Router Node**: All three analysis results are fed into the `triage_post` node. This special `llm-router` node uses an LLM to evaluate the combined inputs against a set of rules and returns a single action string (e.g., `action_ban`, `action_redact`).
+3. **Multi-Way Branching**: The action string from the router determines which of the four possible paths is executed.
+    - `action_ban` -> Sub-Workflow 401 (Ban User)
+    - `action_redact` -> Sub-Workflow 402 (Redact Post)
+    - `action_delete_spam` -> Sub-Workflow 403 (Delete Spam)
+    - `action_approve` -> A simple node to log the approval.
+4. **Convergence**: The result from the chosen moderation path is captured in the `final_log` node.
+
+### Visual Graph
+
+```mermaid
+graph TD
+    subgraph "Content Moderation (ID: 400)"
+        A(User Post) --> B[check_for_pii]
+        A --> C[check_for_hate_speech]
+        A --> D[check_for_spam]
+
+        B --> E{triage_post}
+        C --> E
+        D --> E
+
+        E -- action_ban --> F["Sub-Workflow: Ban User (401)"]
+        E -- action_redact --> G["Sub-Workflow: Redact Post (402)"]
+        E -- action_delete_spam --> H["Sub-Workflow: Delete Spam (403)"]
+        E -- action_approve --> I[approve_post_branch]
+
+        F --> Z[final_log]
+        G --> Z
+        H --> Z
+        I --> Z
+    end
+```
+
+---
+
+## Sub-Workflows
+
+### Sub-Workflow ID: 401 (Ban User)
+
+This workflow simulates banning a user by performing a database update and creating a security log entry in parallel.
+
+```mermaid
+graph TD
+    subgraph "Ban User Actions (ID: 401)"
+        A[api_call_ban_user] --> C[output_ban_summary]
+        B[log_ban_event] --> C
+    end
+```
+
+### Sub-Workflow ID: 402 (Redact Post)
+
+This workflow redacts PII from the user's post and generates a warning message for the user, with both actions running in parallel.
+
+```mermaid
+graph TD
+    subgraph "Redact Post Actions (ID: 402)"
+        A[redact_pii] --> C[output_redaction_summary]
+        B[generate_warning] --> C
+    end
+```
+
+### Sub-Workflow ID: 403 (Delete Spam)
+
+A simple, linear workflow that simulates deleting a spam post and flagging the user.
+
+```mermaid
+graph TD
+    subgraph "Delete Spam Action (ID: 403)"
+        A[delete_and_flag_user] --> B[output_spam_summary]
+    end
+```

package/sandbox/5.distributed/package.json

@@ -0,0 +1,20 @@
+{
+	"name": "distributed-workflow",
+	"type": "module",
+	"scripts": {
+		"start": "tsx src/client.ts",
+		"worker": "tsx src/worker.ts"
+	},
+	"dependencies": {
+		"bullmq": "^5.10.1",
+		"dotenv": "^16.4.5",
+		"flowcraft": "workspace:*",
+		"ioredis": "^5.4.1",
+		"openai": "^4.52.7"
+	},
+	"devDependencies": {
+		"@types/node": "^24.0.13",
+		"tsx": "^4.16.2",
+		"typescript": "^5.5.4"
+	}
+}

package/sandbox/5.distributed/src/client.ts

@@ -0,0 +1,124 @@
+import path from 'node:path'
+import process from 'node:process'
+import { ConsoleLogger, TypedContext } from 'flowcraft'
+import IORedis from 'ioredis'
+import { BullMQExecutor } from './executor'
+import { WorkflowRegistry } from './registry'
+import { RUN_ID } from './types'
+import { waitForWorkflow } from './utils'
+
+const config = {
+	'1.blog-post': {
+		mainWorkflowId: 100,
+		getInitialContext: () => new TypedContext([
+			['topic', 'The rise of AI-powered workflow automation in modern software development.'],
+		]),
+	},
+	'2.job-application': {
+		mainWorkflowId: 200,
+		getInitialContext: () => new TypedContext([
+			['applicantName', 'Jane Doe'],
+			['resume', 'Experienced developer with a background in TypeScript, Node.js, and building complex DAG workflow systems. Also proficient in React and SQL.'],
+			['coverLetter', 'To Whom It May Concern, I am writing to express my interest in the Senior Developer position. My skills and experience align perfectly with the requirements of the role.'],
+		]),
+	},
+	'3.customer-review': {
+		mainWorkflowId: 300,
+		getInitialContext: () => new TypedContext([
+			['initial_review', 'The new dashboard is a huge improvement, but I noticed that the export-to-PDF feature is really slow and sometimes crashes the app on large datasets. It would be great if you could look into this.'],
+		]),
+	},
+	'4.content-moderation': {
+		mainWorkflowId: 400,
+		getInitialContext: () => new TypedContext([
+			['userId', 'user-456'],
+			// Try different posts to test different paths
+			// Path 1: PII detection
+			['userPost', 'Hi, I need help with my account. My email is test@example.com and my phone is 555-123-4567.'],
+			// Path 2: Spam
+			// ['userPost', '!!!BUY NOW!!! Visit my-scam-site.com for a FREE PRIZE! Limited time offer!'],
+			// Path 3: Severe hate speech
+			// ['userPost', `I don't want any dirty immigrants in my country, stealing, raping, and killing my people. They should all be eradicated!`],
+			// Path 4: Moderate hate speech (approve)
+			// ['userPost', `I don't want any illegal immigrants in my country.`],
+			// Path 5: Approved post
+			// ['userPost', 'I really enjoy using this platform. The new features are great and very helpful.'],
+		]),
+	},
+} as const
+
+type UseCase = keyof typeof config
+
+// --- CONFIGURATION ---
+const QUEUE_NAME = 'distributed-flowcraft-queue'
+const ACTIVE_USE_CASE: UseCase = '2.job-application'
+const WORKFLOW_ID = config[ACTIVE_USE_CASE].mainWorkflowId
+
+async function main() {
+	const logger = new ConsoleLogger()
+	logger.info('--- Distributed Workflow Client ---')
+
+	const runId = Math.random().toString(36).substring(2, 4)
+	const redisConnection = new IORedis({ maxRetriesPerRequest: null })
+	const useCaseDirectory = path.join(process.cwd(), 'data', ACTIVE_USE_CASE)
+
+	const registry = await WorkflowRegistry.create([useCaseDirectory])
+
+	const flow = await registry.getFlow(WORKFLOW_ID)
+	const context = config[ACTIVE_USE_CASE].getInitialContext()
+	context.set(RUN_ID, runId) // Add runId to the context
+
+	const executor = new BullMQExecutor(QUEUE_NAME, redisConnection)
+
+	console.log('🚀 Starting Workflow and awaiting result...')
+
+	const initialJobsOrJob = await flow.run(context, {
+		logger,
+		executor,
+		params: { runId, workflowId: WORKFLOW_ID },
+	})
+
+	if (!initialJobsOrJob) {
+		logger.error('Workflow did not produce any initial jobs.')
+		await redisConnection.quit()
+		return
+	}
+
+	const firstJob = Array.isArray(initialJobsOrJob)
+		? initialJobsOrJob[0]
+		: initialJobsOrJob
+
+	try {
+		const finalStatus = await waitForWorkflow(redisConnection, runId, 30000)
+
+		console.log('\n=============================================================')
+
+		switch (finalStatus.status) {
+			case 'completed':
+				logger.info(`✅ Workflow Run ID: ${runId} COMPLETED.`)
+				console.log('=============================================================\n')
+				console.log('Final Result from Worker:\n')
+				console.log(finalStatus.payload.result)
+				break
+			case 'cancelled':
+				logger.warn(`🛑 Workflow Run ID: ${runId} was successfully CANCELLED.`)
+				console.log(`   Reason: ${finalStatus.reason}`)
+				console.log('=============================================================')
+				break
+			case 'failed':
+				logger.error(`❌ Workflow Run ID: ${runId} FAILED or timed out.`)
+				console.log(`   Reason: ${finalStatus.reason}`)
+				console.log('=============================================================')
+				break
+		}
+	}
+	catch (error: any) {
+		logger.error(`Error waiting for job to complete for Run ID ${runId}`, error)
+		const jobState = await firstJob.getState()
+		logger.error(`Job state is: ${jobState}`)
+	}
+
+	await redisConnection.quit()
+}
+
+main().catch(console.error)

package/sandbox/5.distributed/src/executor.ts

@@ -0,0 +1,69 @@
+import type { Job } from 'bullmq'
+import type { Context, IExecutor, RunOptions } from 'flowcraft'
+import type IORedis from 'ioredis'
+import type { NodeJobPayload } from './types'
+import { Queue } from 'bullmq'
+import { Flow } from 'flowcraft'
+
+export class BullMQExecutor implements IExecutor {
+	public readonly queue: Queue<NodeJobPayload>
+
+	constructor(
+		queueName: string,
+		private connection: IORedis,
+	) {
+		this.queue = new Queue(queueName, { connection })
+	}
+
+	async run(flow: Flow, context: Context, options?: RunOptions): Promise<any> {
+		const logger = options?.logger
+		const runId = options?.params?.runId as string
+		const workflowId = options?.params?.workflowId as number
+
+		if (!runId || !workflowId) {
+			throw new Error('BullMQExecutor requires a `runId` and `workflowId` to be passed in `options.params`.')
+		}
+		if (!flow.startNode) {
+			logger?.warn(`Executing a flow with no startNode: ${flow.constructor.name}. Nothing to do.`)
+			return
+		}
+
+		const serializedContext = Object.fromEntries(context.entries())
+		const combinedParams = { ...flow.params, ...options?.params }
+
+		// The GraphBuilder creates a special Flow to handle parallel start nodes.
+		// We need to look inside it to enqueue the actual start nodes.
+		const isParallelStart = flow.startNode instanceof Flow
+		const nodesToEnqueue = isParallelStart
+			? (flow.startNode as any).nodesToRun
+			: [flow.startNode]
+
+		if (!nodesToEnqueue || nodesToEnqueue.length === 0) {
+			logger?.warn('Flow start node has no executable children.')
+			return
+		}
+
+		logger?.info(`[Executor] Enqueuing ${nodesToEnqueue.length} start node(s) for workflow ${workflowId}`)
+		logger?.info(`[Executor] Starting Run ID: ${runId}`)
+
+		const jobs: Job[] = []
+		for (const node of nodesToEnqueue) {
+			const nodeId = node.id!
+			const jobPayload: NodeJobPayload = {
+				runId,
+				workflowId,
+				nodeId,
+				context: serializedContext,
+				params: combinedParams,
+			}
+			const job = await this.queue.add(nodeId, jobPayload)
+			jobs.push(job)
+		}
+
+		if (jobs.length === 0)
+			return undefined
+		if (jobs.length === 1)
+			return jobs[0]
+		return jobs
+	}
+}

package/sandbox/5.distributed/src/nodes.ts

@@ -0,0 +1,136 @@
+import type { DEFAULT_ACTION, NodeArgs, NodeOptions } from 'flowcraft'
+import type { WorkflowRegistry } from './registry'
+import type { AgentNodeTypeMap } from './types'
+import { Node } from 'flowcraft'
+import { FINAL_ACTION } from './types'
+import { callLLM, resolveTemplate } from './utils'
+
+interface AiNodeOptions<T extends keyof AgentNodeTypeMap> extends NodeOptions {
+	data: AgentNodeTypeMap[T] & { nodeId: string }
+	registry?: WorkflowRegistry
+}
+
+/**
+ * A generic node that executes an LLM prompt.
+ * The prompt is a template that gets resolved with inputs from the context.
+ */
+export class LLMProcessNode extends Node<string, string> {
+	private data: AiNodeOptions<'llm-process'>['data']
+
+	constructor(options: AiNodeOptions<'llm-process'>) {
+		super(options)
+		this.data = options.data
+	}
+
+	prep(args: NodeArgs): Promise<string> {
+		const template = this.data.promptTemplate
+		const inputMappings = this.data.inputs
+		const templateData: Record<string, any> = {}
+
+		for (const [templateKey, sourcePathOrPaths] of Object.entries(inputMappings)) {
+			const sourcePaths = Array.isArray(sourcePathOrPaths) ? sourcePathOrPaths : [sourcePathOrPaths]
+			let value: any
+
+			for (const sourcePath of sourcePaths) {
+				value = args.ctx.get(sourcePath)
+				if (value !== undefined)
+					break
+			}
+
+			if (value === undefined)
+				args.logger.warn(`[Node: ${this.data.nodeId}] Template variable '{{${templateKey}}}' could not be resolved from any source: [${sourcePaths.join(', ')}].`)
+
+			templateData[templateKey] = value
+		}
+
+		const resolvedPrompt = resolveTemplate(template, templateData)
+		return Promise.resolve(resolvedPrompt)
+	}
+
+	exec(args: NodeArgs<string>): Promise<string> {
+		args.logger.info(`[Node: ${this.data.nodeId}] Executing LLM process...`)
+		return callLLM(args.prepRes)
+	}
+
+	async post(args: NodeArgs<string, string>) {
+		args.ctx.set(this.data.nodeId, args.execRes)
+		args.logger.info(`[Node: ${this.data.nodeId}] ✓ Process complete.`)
+	}
+}
+
+/**
+ * An LLM-powered node that evaluates a condition and returns 'true' or 'false'.
+ */
+export class LLMConditionNode extends Node<string, string, 'true' | 'false'> {
+	private data: AiNodeOptions<'llm-condition'>['data']
+
+	constructor(options: AiNodeOptions<'llm-condition'>) {
+		super(options)
+		this.data = options.data
+	}
+
+	prep = LLMProcessNode.prototype.prep
+
+	exec(args: NodeArgs<string>): Promise<string> {
+		args.logger.info(`[Node: ${this.data.nodeId}] Evaluating condition...`)
+		return callLLM(args.prepRes)
+	}
+
+	async post(args: NodeArgs<string, string>): Promise<'true' | 'false'> {
+		const result = args.execRes.toLowerCase().includes('true') ? 'true' : 'false'
+		args.ctx.set(this.data.nodeId, result)
+		args.logger.info(`[Node: ${this.data.nodeId}] ✓ Condition evaluated to: ${result}`)
+		return result
+	}
+}
+
+/**
+ * An LLM-powered node that returns its raw output as an action for dynamic routing.
+ */
+export class LLMRouterNode extends Node<string, string, string> {
+	private data: AiNodeOptions<'llm-router'>['data']
+
+	constructor(options: AiNodeOptions<'llm-router'>) {
+		super(options)
+		this.data = options.data
+	}
+
+	prep = LLMProcessNode.prototype.prep
+	exec = LLMProcessNode.prototype.exec
+
+	async post(args: NodeArgs<string, string>): Promise<string> {
+		const result = args.execRes.trim()
+		args.ctx.set(this.data.nodeId, result)
+		args.logger.info(`[Node: ${this.data.nodeId}] ✓ Routing decision is: '${result}'`)
+		return result
+	}
+}
+
+/**
+ * Aggregates inputs and sets a final value in the context.
+ */
+export class OutputNode extends Node<string, void, typeof FINAL_ACTION | string | typeof DEFAULT_ACTION> {
+	private data: AiNodeOptions<'output'>['data']
+
+	constructor(options: AiNodeOptions<'output'>) {
+		super(options)
+		this.data = options.data
+	}
+
+	prep = LLMProcessNode.prototype.prep
+
+	async post(args: NodeArgs<string, void>): Promise<any> {
+		const finalResult = args.prepRes
+		const outputKey = this.data.outputKey || 'final_output'
+		args.ctx.set(outputKey, finalResult)
+
+		// The payload needs to be the *entire context* for sub-workflow output mapping.
+		args.ctx.set('__final_payload', {
+			result: finalResult,
+			context: Object.fromEntries(args.ctx.entries()),
+		})
+
+		args.logger.info(`[Output] Workflow branch finished. Final value set to context key '${outputKey}'.`)
+		return FINAL_ACTION
+	}
+}

package/sandbox/5.distributed/src/registry.ts

@@ -0,0 +1,101 @@
+import type { AbstractNode, Flow, TypedWorkflowGraph } from 'flowcraft'
+import type { AgentNodeTypeMap } from './types'
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import { ConsoleLogger, createNodeRegistry, GraphBuilder } from 'flowcraft'
+import {
+	LLMConditionNode,
+	LLMProcessNode,
+	LLMRouterNode,
+	OutputNode,
+} from './nodes'
+
+export const nodeRegistry = createNodeRegistry({
+	'llm-process': LLMProcessNode,
+	'llm-condition': LLMConditionNode,
+	'llm-router': LLMRouterNode,
+	'output': OutputNode,
+})
+
+export class WorkflowRegistry {
+	private flowCache = new Map<number, Flow>()
+	private nodeMapCache = new Map<number, Map<string, AbstractNode>>()
+	private predecessorCountCache = new Map<number, Map<string, number>>()
+	private graphDatabase = new Map<number, TypedWorkflowGraph<AgentNodeTypeMap>>()
+	private builder: GraphBuilder<AgentNodeTypeMap>
+
+	private constructor() {
+		this.builder = new GraphBuilder(
+			nodeRegistry,
+			{ registry: this },
+			{ subWorkflowNodeTypes: ['sub-workflow'] },
+			new ConsoleLogger(),
+		)
+	}
+
+	public static async create(useCaseDirectories: string[]): Promise<WorkflowRegistry> {
+		const registry = new WorkflowRegistry()
+		for (const dir of useCaseDirectories) {
+			await registry.initialize(dir)
+		}
+		return registry
+	}
+
+	private async initialize(useCaseDirectory: string): Promise<void> {
+		try {
+			const files = await fs.readdir(useCaseDirectory)
+			for (const file of files) {
+				if (path.extname(file) === '.json') {
+					const workflowId = Number.parseInt(path.basename(file, '.json'), 10)
+					if (!Number.isNaN(workflowId)) {
+						const filePath = path.join(useCaseDirectory, file)
+						const fileContent = await fs.readFile(filePath, 'utf-8')
+						const graphData: TypedWorkflowGraph<AgentNodeTypeMap> = JSON.parse(fileContent)
+						this.graphDatabase.set(workflowId, graphData)
+						console.log(`[Registry] Loaded workflow ${workflowId} from ${file}`)
+					}
+				}
+			}
+		}
+		catch (error) {
+			console.error(`[Registry] Failed to initialize from directory ${useCaseDirectory}`, error)
+			throw error
+		}
+	}
+
+	public getGraph(workflowId: number): TypedWorkflowGraph<AgentNodeTypeMap> | undefined {
+		return this.graphDatabase.get(workflowId)
+	}
+
+	private async buildAndCache(workflowId: number): Promise<void> {
+		const graphData = this.graphDatabase.get(workflowId)
+		if (!graphData)
+			throw new Error(`Workflow with id ${workflowId} not found in the database.`)
+
+		const { flow, nodeMap, predecessorCountMap } = this.builder.build(graphData)
+		this.flowCache.set(workflowId, flow)
+		this.nodeMapCache.set(workflowId, nodeMap)
+		this.predecessorCountCache.set(workflowId, predecessorCountMap)
+	}
+
+	async getFlow(workflowId: number): Promise<Flow> {
+		if (!this.flowCache.has(workflowId))
+			await this.buildAndCache(workflowId)
+
+		return this.flowCache.get(workflowId)!
+	}
+
+	async getNode(workflowId: number, nodeId: string): Promise<AbstractNode | undefined> {
+		if (!this.nodeMapCache.has(workflowId))
+			await this.buildAndCache(workflowId)
+
+		return this.nodeMapCache.get(workflowId)?.get(nodeId)
+	}
+
+	async getPredecessorCount(workflowId: number, nodeId: string): Promise<number> {
+		if (!this.predecessorCountCache.has(workflowId))
+			await this.buildAndCache(workflowId)
+
+		return this.predecessorCountCache.get(workflowId)?.get(nodeId) ?? 0
+	}
+}