flowcraft 1.0.0-beta.1

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

@@ -0,0 +1,45 @@
+import { contextKey } from 'flowcraft'
+
+// A generic structure for the `inputs` object in our node data.
+// It maps a template key to a context key (or an array of fallback keys).
+type NodeInputMap = Record<string, string | string[]>
+
+export interface AgentNodeTypeMap {
+	'llm-process': {
+		promptTemplate: string
+		inputs: NodeInputMap
+	}
+	'llm-condition': {
+		promptTemplate: string
+		inputs: NodeInputMap
+	}
+	'llm-router': {
+		promptTemplate: string
+		inputs: NodeInputMap
+	}
+	'output': {
+		promptTemplate: string
+		inputs: NodeInputMap
+		outputKey?: string // defaults to 'final_output'
+		returnAction?: string
+	}
+}
+
+// A unique ID for an entire workflow execution.
+export const RUN_ID = contextKey<string>('run_id')
+
+export interface NodeJobPayload {
+	runId: string
+	workflowId: number
+	nodeId: string
+	context: Record<string, any>
+	params: Record<string, any>
+}
+
+export const FINAL_ACTION = Symbol('final_action')
+
+export interface WorkflowStatus {
+	status: 'completed' | 'failed' | 'cancelled'
+	payload?: any
+	reason?: string
+}

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

@@ -0,0 +1,69 @@
+import type Redis from 'ioredis'
+import type { WorkflowStatus } from './types'
+import OpenAI from 'openai'
+import 'dotenv/config'
+
+const openaiClient = new OpenAI()
+
+/**
+ * Calls the OpenAI Chat Completions API.
+ * @param prompt The user prompt to send to the LLM.
+ * @returns The content of the LLM's response as a string.
+ */
+export async function callLLM(prompt: string): Promise<string> {
+	try {
+		console.log(`\n--- Sending to LLM ---\n${prompt.substring(0, 300)}...\n---------------------\n`)
+		const response = await openaiClient.chat.completions.create({
+			model: 'gpt-4o-mini',
+			messages: [{ role: 'user', content: prompt }],
+			temperature: 0.2,
+		})
+		const result = response.choices[0].message.content || ''
+		console.log(`--- Received from LLM ---\n${result}\n-----------------------\n`)
+		return result
+	}
+	catch (error: any) {
+		console.error('Error calling OpenAI API:', error)
+		throw new Error(`OpenAI API call failed: ${error.message}`)
+	}
+}
+
+/**
+ * Resolves a template string by replacing {{key}} with values from a data object.
+ * This is crucial for dynamically constructing prompts.
+ */
+export function resolveTemplate(template: string, data: Record<string, any>): string {
+	return template.replace(/\{\{(.*?)\}\}/g, (_, key) => {
+		const value = data[key.trim()]
+		if (value === undefined || value === null) {
+			console.warn(`Template variable '{{${key.trim()}}}' not found in data.`)
+			return `{{${key.trim()}}}`
+		}
+		return String(value)
+	})
+}
+
+/**
+ * Polls Redis for the final status of a workflow run.
+ * @param redis The IORedis client instance.
+ * @param runId The unique ID of the workflow run to wait for.
+ * @param timeoutMs The maximum time to wait in milliseconds.
+ * @returns A promise that resolves with the final WorkflowStatus.
+ */
+export async function waitForWorkflow(redis: Redis, runId: string, timeoutMs: number): Promise<WorkflowStatus> {
+	const statusKey = `workflow:status:${runId}`
+	const startTime = Date.now()
+
+	while (Date.now() - startTime < timeoutMs) {
+		const statusJson = await redis.get(statusKey)
+		if (statusJson) {
+			await redis.del(statusKey) // Clean up the key
+			return JSON.parse(statusJson) as WorkflowStatus
+		}
+		// Wait a bit before polling again
+		await new Promise(resolve => setTimeout(resolve, 500))
+	}
+
+	// If the loop finishes, it's a timeout.
+	return { status: 'failed', reason: `Timeout: Workflow did not complete within ${timeoutMs}ms.` }
+}

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

@@ -0,0 +1,217 @@
+import type { NodeJobPayload } from './types'
+import path from 'node:path'
+import process from 'node:process'
+import readline from 'node:readline'
+import { Queue, Worker } from 'bullmq'
+import { AbortError, ConsoleLogger, Flow, TypedContext } from 'flowcraft'
+import IORedis from 'ioredis'
+import { WorkflowRegistry } from './registry'
+import { FINAL_ACTION, RUN_ID } from './types'
+import 'dotenv/config'
+
+const QUEUE_NAME = 'distributed-flowcraft-queue'
+const CANCELLATION_KEY_PREFIX = 'workflow:cancel:'
+
+function getCancellationKey(runId: string) {
+	return `${CANCELLATION_KEY_PREFIX}${runId}`
+}
+
+async function setupCancellationListener(redis: IORedis, logger: ConsoleLogger) {
+	readline.emitKeypressEvents(process.stdin)
+	if (process.stdin.isTTY)
+		process.stdin.setRawMode(true)
+
+	logger.info('... Press \'c\' to cancel a running workflow ...')
+
+	process.stdin.on('keypress', (_str, key) => {
+		if (key.ctrl && key.name === 'c') {
+			process.exit()
+		}
+
+		if (key.name === 'c') {
+			const rl = readline.createInterface({
+				input: process.stdin,
+				output: process.stdout,
+			})
+
+			readline.clearLine(process.stdout, 0)
+			readline.cursorTo(process.stdout, 0)
+
+			rl.question('Enter Run ID to cancel: ', async (runId) => {
+				if (runId) {
+					logger.warn(`Signaling cancellation for Run ID: ${runId}`)
+					await redis.set(getCancellationKey(runId), 'true', 'EX', 3600)
+				}
+				rl.close()
+			})
+		}
+	})
+}
+
+async function main() {
+	const logger = new ConsoleLogger()
+	logger.info('--- Distributed Workflow Worker ---')
+
+	const redisConnection = new IORedis({ maxRetriesPerRequest: null })
+	const queue = new Queue(QUEUE_NAME, { connection: redisConnection })
+
+	// Define all use-case directories the worker should be aware of.
+	const useCaseDirectories = [
+		'1.blog-post',
+		'2.job-application',
+		'3.customer-review',
+		'4.content-moderation',
+	].map(dir => path.join(process.cwd(), 'data', dir))
+
+	// Create and initialize the registry from all directories in one clean call.
+	const masterRegistry = await WorkflowRegistry.create(useCaseDirectories)
+
+	setupCancellationListener(redisConnection, logger)
+	logger.info(`Worker listening on queue: "${QUEUE_NAME}"`)
+
+	const worker = new Worker<NodeJobPayload>(QUEUE_NAME, async (job) => {
+		const { runId, workflowId, nodeId, params } = job.data
+		const statusKey = `workflow:status:${runId}`
+		const contextKey = `workflow:context:${runId}`
+
+		logger.info(`[Worker] Processing job: ${job.name} (Workflow: ${workflowId}, Run: ${runId})`)
+
+		const controller = new AbortController()
+		const pollInterval = setInterval(async () => {
+			if (await redisConnection.get(getCancellationKey(runId)) === 'true') {
+				logger.warn(`[Worker] Abort signal received for Run ID ${runId}. Aborting...`)
+				controller.abort()
+				clearInterval(pollInterval)
+			}
+		}, 500)
+
+		try {
+			if (controller.signal.aborted)
+				throw new AbortError(`Job for Run ID ${runId} was cancelled before starting.`)
+
+			const node = await masterRegistry.getNode(workflowId, nodeId)
+			if (!node)
+				throw new Error(`Node '${nodeId}' in workflow '${workflowId}' not found.`)
+
+			// Load the most up-to-date context from the Redis hash.
+			const contextData = await redisConnection.hgetall(contextKey)
+			const context = new TypedContext()
+
+			if (Object.keys(contextData).length === 0 && Object.keys(job.data.context).length > 0) {
+				// This is the first node for this run. Persist the initial context from the job payload.
+				const initialContextObject = job.data.context
+				for (const [key, value] of Object.entries(initialContextObject))
+					context.set(key, value)
+
+				const serializedInitialContext = Object.entries(initialContextObject).flatMap(([key, value]) => [key, JSON.stringify(value)])
+				if (serializedInitialContext.length > 0)
+					await redisConnection.hset(contextKey, ...serializedInitialContext)
+			}
+			else {
+				// For subsequent nodes, hydrate the context from the Redis hash.
+				for (const [key, value] of Object.entries(contextData)) {
+					try {
+						context.set(key, JSON.parse(value))
+					}
+					catch {
+						context.set(key, value) // Fallback for non-JSON strings
+					}
+				}
+			}
+
+			context.set(RUN_ID, runId)
+
+			const action = await node._run({
+				ctx: context,
+				params,
+				signal: controller.signal,
+				logger,
+			})
+
+			// Persist the entire updated context back to Redis for the next job.
+			const updatedContextObject = Object.fromEntries(context.entries())
+			const serializedUpdatedContext = Object.entries(updatedContextObject).flatMap(([key, value]) => {
+				if (typeof key === 'symbol')
+					return [] // Symbols cannot be keys in Redis hashes
+				return [key, JSON.stringify(value)]
+			})
+
+			if (serializedUpdatedContext.length > 0)
+				await redisConnection.hset(contextKey, ...serializedUpdatedContext)
+
+			if (action === FINAL_ACTION) {
+				logger.info(`[Worker] Final node executed for Run ID ${runId}. Reporting 'completed' status...`)
+				const finalPayload = context.get('__final_payload')
+				const statusPayload = { status: 'completed', payload: finalPayload ?? null }
+				await redisConnection.set(statusKey, JSON.stringify(statusPayload), 'EX', 3600)
+				await redisConnection.del(contextKey) // Clean up context hash
+				return
+			}
+
+			if (controller.signal.aborted)
+				throw new AbortError('Job cancelled after execution, before enqueueing next step.')
+
+			const successor = node.successors.get(action)
+			if (!successor) {
+				logger.info(`[Worker] Branch complete for run ${runId}. Node '${nodeId}' has no successor for action '${String(action)}'.`)
+				return
+			}
+
+			const nodesToEnqueue = (successor instanceof Flow) ? (successor as any).nodesToRun : [successor]
+
+			for (const nextNode of nodesToEnqueue) {
+				const nextNodeId = nextNode.id!
+				const predecessorCount = await masterRegistry.getPredecessorCount(workflowId, nextNodeId)
+
+				if (predecessorCount <= 1) {
+					logger.info(`[Worker] Enqueuing successor: ${nextNodeId} for run ${runId}.`)
+					await queue.add(nextNodeId, { runId, workflowId, nodeId: nextNodeId, context: {}, params })
+				}
+				else {
+					const joinKey = `workflow:join:${runId}:${nextNodeId}`
+					const completedCount = await redisConnection.incr(joinKey)
+					await redisConnection.expire(joinKey, 3600)
+
+					logger.info(`[Worker] Predecessor ${nodeId} completed for fan-in node ${nextNodeId}. (${completedCount}/${predecessorCount})`)
+
+					if (completedCount >= predecessorCount) {
+						logger.info(`[Worker] All ${predecessorCount} predecessors for ${nextNodeId} have completed. Enqueuing join node.`)
+						await queue.add(nextNodeId, { runId, workflowId, nodeId: nextNodeId, context: {}, params })
+						await redisConnection.del(joinKey)
+					}
+				}
+			}
+		}
+		catch (error) {
+			if (error instanceof AbortError) {
+				logger.warn(`[Worker] Job for Run ID ${runId} was aborted. Reporting 'cancelled' status.`)
+				const statusPayload = { status: 'cancelled', reason: error.message }
+				if (await redisConnection.setnx(statusKey, JSON.stringify(statusPayload))) {
+					await redisConnection.expire(statusKey, 3600)
+					await redisConnection.del(contextKey)
+				}
+			}
+			else {
+				logger.error(`[Worker] Job for Run ID ${runId} failed. Reporting 'failed' status.`, { error })
+				const statusPayload = { status: 'failed', reason: (error as Error).message }
+				if (await redisConnection.setnx(statusKey, JSON.stringify(statusPayload))) {
+					await redisConnection.expire(statusKey, 3600)
+					await redisConnection.del(contextKey)
+				}
+				throw error
+			}
+		}
+		finally {
+			clearInterval(pollInterval)
+		}
+	}, {
+		connection: redisConnection,
+		concurrency: 5,
+	})
+
+	worker.on('failed', (job, err) => {
+		logger.error(`Job ${job?.id} failed with error: ${err.message}`, { job, err })
+	})
+}
+
+main().catch(console.error)

package/sandbox/5.distributed/tsconfig.json

@@ -0,0 +1,3 @@
+{
+	"extends": "../tsconfig.json"
+}

package/sandbox/6.rag/.env.example

@@ -0,0 +1 @@
+OPENAI_API_KEY="your-api-key-here"

package/sandbox/6.rag/README.md

@@ -0,0 +1,60 @@
+# Advanced RAG Agent with Document Analysis
+
+This example demonstrates a sophisticated Retrieval-Augmented Generation (RAG) agent built with Flowcraft. The workflow ingests and analyzes a document, uses embeddings to find relevant information, and generates a precise answer to a user's question.
+
+This project serves two main purposes:
+
+1. To provide a practical, real-world example of a complex, multi-step AI workflow.
+2. To illustrate the importance of robust state serialization (`superjson`) when passing complex data structures (like `Map`, `Date`, and custom class instances) through a workflow's `Context`.
+
+## Features
+
+- **RAG Pipeline**: Implements a full RAG pipeline: document loading, chunking, embedding generation, vector search, and final answer synthesis.
+- **Complex Data Structures**: The workflow creates and manages `Map` objects, `Date` objects, and custom `DocumentChunk` and `SearchResult` class instances.
+- **Robust Serialization**: At the end of the workflow, it demonstrates how `superjson` can correctly serialize the entire final context, preserving all complex data types that would be lost with `JSON.stringify`.
+- **Declarative & Modular**: The entire workflow is defined in a single `rag.json` file, and the logic is broken down into reusable, single-responsibility nodes.
+
+## How to Run
+
+1. **Install dependencies**:
+
+    ```bash
+    npm install
+    ```
+
+2. **Set your OpenAI API key**:
+    Create a `.env` file in this project's root directory:
+
+    ```
+    OPENAI_API_KEY="your-api-key-here"
+    ```
+
+3. **Run the application**:
+
+    ```bash
+    npm start
+    ```
+
+    The application will process the `documents/sample-flowcraft.txt` file and answer a hard-coded question. You can change the question in `src/main.ts`.
+
+## How It Works
+
+The workflow is defined in `data/rag.json` and executed by the `InMemoryExecutor`.
+
+```mermaid
+graph TD
+    subgraph "Advanced RAG Agent"
+        A[Load & Chunk Document] --> B[Generate Embeddings in Parallel]
+        B --> C[Store in Vector DB]
+        C --> D[Vector Search for Question]
+        D --> E[Generate Final Answer]
+    end
+```
+
+1. **`LoadAndChunkNode`**: Reads the source document and splits it into smaller text chunks, creating `DocumentChunk` class instances which include an `ingestedAt: Date`.
+2. **`GenerateEmbeddingsNode`**: A `ParallelBatchFlow` that concurrently generates a vector embedding for each document chunk.
+3. **`StoreInVectorDBNode`**: Simulates storing the chunks and their embeddings in a vector database (represented as a `Map` in the context).
+4. **`VectorSearchNode`**: Takes a user's question, generates an embedding for it, and performs a cosine similarity search to find the most relevant chunks from the "database".
+5. **`LLMProcessNode`**: Takes the original question and the retrieved chunks (the "context") and passes them to an LLM to generate a final, synthesized answer.
+
+At the conclusion, `main.ts` prints the final answer and then logs the entire `Context` object, serialized with `superjson`, to show that all the rich data types were preserved throughout the workflow's execution.

package/sandbox/6.rag/data/README.md

@@ -0,0 +1,31 @@
+# Advanced RAG Agent Workflow
+
+This workflow demonstrates a complete Retrieval-Augmented Generation (RAG) pipeline. It ingests a document, processes it into a searchable format, retrieves relevant context based on a question, and synthesizes a final answer.
+
+This is a powerful example of a linear, data-processing workflow where each step enriches the `Context` for the subsequent step, culminating in a sophisticated AI-powered response.
+
+## Workflow ID: (Implicit, from file name `rag.json`)
+
+### Description
+
+1. **`load_and_chunk`**: Reads a source document from a file path. It splits the content into smaller, manageable text chunks, creating `DocumentChunk` objects that include metadata like an ID and ingestion timestamp.
+
+2. **`generate_embeddings`**: Takes the document chunks and, using a `ParallelBatchFlow`, calls an embedding API for each chunk concurrently. This efficiently transforms the text into numerical vector representations.
+
+3. **`store_in_db`**: Simulates the process of upserting the chunks and their corresponding embedding vectors into a vector database. The combined data is stored in the `Context` for the next step.
+
+4. **`vector_search`**: Performs the "retrieval" step. It generates an embedding for the user's question, calculates the similarity against all document chunks in the "database", and returns the top `k` most relevant chunks.
+
+5. **`generate_final_answer`**: The final "generation" step. It constructs a prompt containing the user's original question and the retrieved text chunks as context, then asks an LLM to synthesize a comprehensive answer based only on the provided information.
+
+### Visual Graph
+
+```mermaid
+graph TD
+    subgraph "Advanced RAG Agent"
+        A[load_and_chunk] --> B[generate_embeddings]
+        B --> C[store_in_db]
+        C --> D[vector_search]
+        D --> E[generate_final_answer]
+    end
+```

package/sandbox/6.rag/data/rag.json

@@ -0,0 +1,58 @@
+{
+	"nodes": [
+		{
+			"id": "load_and_chunk",
+			"type": "load-and-chunk",
+			"data": {
+				"filePath": "./documents/sample-flowcraft.txt"
+			}
+		},
+		{
+			"id": "generate_embeddings",
+			"type": "generate-embeddings",
+			"data": {}
+		},
+		{
+			"id": "store_in_db",
+			"type": "store-in-db",
+			"data": {}
+		},
+		{
+			"id": "vector_search",
+			"type": "vector-search",
+			"data": {
+				"question": "How does Flowcraft handle conditional branching?",
+				"topK": 2
+			}
+		},
+		{
+			"id": "generate_final_answer",
+			"type": "llm-process",
+			"data": {
+				"promptTemplate": "Based on the following context, please provide a clear and concise answer to the user's question.\n\n**CONTEXT**\n\n{{context}}\n\n**QUESTION**\n\n{{question}}\n\n**ANSWER**",
+				"inputs": {
+					"context": "search_results",
+					"question": "question"
+				}
+			}
+		}
+	],
+	"edges": [
+		{
+			"source": "load_and_chunk",
+			"target": "generate_embeddings"
+		},
+		{
+			"source": "generate_embeddings",
+			"target": "store_in_db"
+		},
+		{
+			"source": "store_in_db",
+			"target": "vector_search"
+		},
+		{
+			"source": "vector_search",
+			"target": "generate_final_answer"
+		}
+	]
+}

package/sandbox/6.rag/documents/sample-cascade.txt

@@ -0,0 +1,11 @@
+Flowcraft is a lightweight, zero-dependency TypeScript framework for building complex, multi-step processes. It empowers you to model everything from simple sequential tasks to dynamic, graph-driven AI agents with a clear and composable API.
+
+The Node is the most fundamental building block. It represents a single, atomic unit of work in your process. Every Node has a well-defined, three-phase lifecycle that separates data preparation (prep), core logic (exec), and result processing (post). This separation makes nodes highly testable and reusable.
+
+A Flow is a special type of Node that acts as an orchestrator. It doesn't have its own business logic; instead, its purpose is to manage the execution of a graph of other nodes. The Executor is the engine that runs the Flow, traversing the graph and executing each node.
+
+An action is a string returned by a node's post() method. The Executor uses this string to determine which path to take next in the workflow graph. If a node returns the default action, the flow proceeds linearly. However, if a node returns a custom string like 'user_is_valid' or 'error_occurred', the Executor will look for a successor connected to that specific action. This is the primary mechanism for implementing conditional branching and creating dynamic, responsive workflows.
+
+The Context is the shared memory of a running workflow. It is a type-safe, Map-like object that is passed to every single node, allowing different steps in the process to communicate and share state with each other. For example, an early node might fetch user data and place it in the context, while a later node reads that data to make a decision.
+
+Flowcraft also supports advanced features like middleware for cross-cutting concerns, automatic retries with fallback logic for resilience, and robust cancellation support via standard AbortControllers. This makes it suitable for building production-grade applications.

package/sandbox/6.rag/package.json

@@ -0,0 +1,18 @@
+{
+	"name": "rag-workflow",
+	"type": "module",
+	"scripts": {
+		"start": "npx tsx src/main.ts"
+	},
+	"dependencies": {
+		"dotenv": "^16.4.5",
+		"flowcraft": "workspace:*",
+		"openai": "^4.52.7",
+		"superjson": "^2.2.1"
+	},
+	"devDependencies": {
+		"@types/node": "^24.0.13",
+		"tsx": "^4.16.2",
+		"typescript": "^5.5.4"
+	}
+}

package/sandbox/6.rag/src/main.ts

@@ -0,0 +1,52 @@
+import type { TypedWorkflowGraph } from 'flowcraft'
+import type { RagNodeTypeMap } from './types'
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import process from 'node:process'
+import { ConsoleLogger, TypedContext } from 'flowcraft'
+import SuperJSON from 'superjson'
+import { DOCUMENT_PATH, FINAL_ANSWER, keyRegistry, QUESTION } from './nodes'
+import { ragGraphBuilder } from './registry'
+
+async function main() {
+	console.log('--- RAG Agent Workflow ---')
+
+	// 1. Load the declarative workflow graph from the JSON file.
+	const graphPath = path.join(process.cwd(), 'data', 'rag.json')
+	const graphContent = await fs.readFile(graphPath, 'utf-8')
+	const graph: TypedWorkflowGraph<RagNodeTypeMap> = JSON.parse(graphContent)
+
+	// 2. Build the executable flow from the graph definition.
+	const { flow } = ragGraphBuilder.build(graph)
+
+	// 3. Set up the initial context for the workflow run.
+	const documentPath = path.join(process.cwd(), 'documents', 'sample-flowcraft.txt')
+	const context = new TypedContext()
+	context.set(DOCUMENT_PATH, documentPath)
+	context.set(QUESTION, 'How does Flowcraft handle conditional branching?')
+
+	// 4. Run the workflow.
+	await flow.run(context, { logger: new ConsoleLogger() })
+
+	console.log('\n--- Workflow Complete ---\n')
+
+	// 5. Inspect the final state of the context.
+	const finalAnswer = context.get(FINAL_ANSWER)
+	console.log('Final Answer:\n', finalAnswer)
+
+	// 6. Demonstrate robust serialization of the final context.
+	console.log('\n\n--- Final Context State (Serialized with SuperJSON) ---')
+
+	// maps the symbol to its string description for superjson
+	keyRegistry.forEach((symbolValue, stringKey) => SuperJSON.registerSymbol(symbolValue, stringKey))
+	const finalContextMap = new Map(context.entries())
+	const outputFilePath = path.join(process.cwd(), 'tmp', 'final-context.json')
+	const serializedObject = SuperJSON.serialize(finalContextMap)
+
+	// Save the full, untruncated data to a file for detailed inspection.
+	await fs.mkdir(path.dirname(outputFilePath), { recursive: true })
+	await fs.writeFile(outputFilePath, JSON.stringify(serializedObject, null, 2), 'utf-8')
+	console.log(`Full context saved to: ${outputFilePath}\n`)
+}
+
+main().catch(console.error)

package/sandbox/6.rag/src/nodes/GenerateEmbeddingsNode.ts

@@ -0,0 +1,54 @@
+import type { AbstractNode, NodeArgs } from 'flowcraft'
+import { Node, ParallelBatchFlow } from 'flowcraft'
+import { getEmbedding } from '../utils'
+import { CHUNKS, EMBEDDINGS } from './index'
+
+// The "worker" node that processes a single item from the batch.
+class GetSingleEmbeddingNode extends Node<{ chunkId: string, text: string }, { chunkId: string, vector: number[] }> {
+	async exec({ params }: NodeArgs) {
+		const vector = await getEmbedding(params.text)
+		return { chunkId: params.chunkId, vector }
+	}
+
+	async post({ execRes }: NodeArgs) {
+		return execRes
+	}
+}
+
+// This is the main orchestrator node for this step.
+export class GenerateEmbeddingsNode extends ParallelBatchFlow {
+	protected nodeToRun: AbstractNode = new GetSingleEmbeddingNode()
+
+	// The `prep` phase gathers the items to be processed in parallel.
+	async prep({ ctx }: NodeArgs) {
+		const chunks = ctx.get(CHUNKS)
+		if (!chunks)
+			return []
+
+		// Return an array of parameter objects for the batch processor.
+		return Array.from(chunks.values()).map(chunk => ({
+			chunkId: chunk.id,
+			text: chunk.text,
+		}))
+	}
+
+	// The `post` phase runs after all parallel jobs are complete to aggregate the results.
+	async post({ ctx, execRes, logger }: NodeArgs) {
+		const embeddings = new Map<string, number[]>()
+		const batchResults = execRes as PromiseSettledResult<{ chunkId: string, vector: number[] }>[] | undefined
+
+		if (batchResults) {
+			for (const result of batchResults) {
+				if (result.status === 'fulfilled' && result.value) {
+					embeddings.set(result.value.chunkId, result.value.vector)
+				}
+				else if (result.status === 'rejected') {
+					logger?.error('[GenerateEmbeddingsNode] A batch embedding generation failed.', { error: result.reason })
+				}
+			}
+		}
+
+		ctx.set(EMBEDDINGS, embeddings)
+		logger?.info(`[GenerateEmbeddingsNode] Generated ${embeddings.size} embeddings.`)
+	}
+}

package/sandbox/6.rag/src/nodes/LLMProcessNode.ts

@@ -0,0 +1,48 @@
+import type { NodeArgs } from 'flowcraft'
+import type { RagNodeOptions, SearchResult } from '../types'
+import { Node } from 'flowcraft'
+import { callLLM, resolveTemplate } from '../utils'
+import { FINAL_ANSWER, keyRegistry, SEARCH_RESULTS } from './index'
+
+export class LLMProcessNode extends Node<string, string> {
+	private data: RagNodeOptions<'llm-process'>['data']
+
+	constructor(options: RagNodeOptions<'llm-process'>) {
+		super(options)
+		this.data = options.data
+	}
+
+	prep(args: NodeArgs): Promise<string> {
+		const template = this.data.promptTemplate
+		const templateData: Record<string, any> = {}
+
+		for (const [templateKey, contextKeyString] of Object.entries(this.data.inputs)) {
+			const keySymbol = keyRegistry.get(contextKeyString)
+			if (keySymbol) {
+				let value = args.ctx.get(keySymbol as any)
+
+				if (keySymbol === SEARCH_RESULTS) {
+					const searchResults = value as SearchResult[] | undefined
+					value = searchResults
+						?.map(result => result.chunk.text)
+						.join('\n\n---\n\n') ?? ''
+				}
+
+				templateData[templateKey] = value
+			}
+			else {
+				args.logger.warn(`[LLMProcessNode] Unknown context key '${contextKeyString}' in graph definition.`)
+			}
+		}
+
+		return Promise.resolve(resolveTemplate(template, templateData))
+	}
+
+	exec(args: NodeArgs<string>): Promise<string> {
+		return callLLM(args.prepRes)
+	}
+
+	async post(args: NodeArgs<string, string>) {
+		args.ctx.set(FINAL_ANSWER, args.execRes)
+	}
+}