flowcraft 1.0.0-beta.1

package/sandbox/3.parallel/README.md

@@ -0,0 +1,65 @@
+# Parallel Batch Translation
+
+This project demonstrates using `flowcraft`'s `ParallelBatchFlow` to translate a document into multiple languages concurrently, showcasing significant performance improvements for I/O-bound tasks.
+
+## Goal
+
+Translate a source `README.md` file into multiple languages (Chinese, Spanish, etc.) in parallel and save each translation to the `translations/` directory.
+
+## How to Run
+
+1. **Install dependencies**:
+
+    ```bash
+    npm install
+    ```
+
+2. **Set your OpenAI API key**:
+    Create a `.env` file in this directory:
+
+    ```
+    OPENAI_API_KEY="your-api-key-here"
+    ```
+
+3. **Run the translation process**:
+
+    ```bash
+    npm start
+    ```
+
+## How It Works
+
+The implementation uses an `ParallelBatchFlow` to process translation requests for all languages at the same time.
+
+```mermaid
+graph TD
+    A[Load README.md] --> B["ParallelBatchFlow"]
+    subgraph "Concurrent Translation"
+        B -- "Chinese" --> T1[TranslateNode]
+        B -- "Spanish" --> T2[TranslateNode]
+        B -- "Japanese" --> T3[TranslateNode]
+        B -- "German" --> T4[TranslateNode]
+    end
+    T1 --> S1[Save Chinese.md]
+    T2 --> S2[Save Spanish.md]
+    T3 --> S3[Save Japanese.md]
+    T4 --> S4[Save German.md]
+```
+
+1. **`TranslateFlow` (extends `ParallelBatchFlow`)**: The `prep` method prepares a list of parameters, one for each language.
+
+    ```typescript
+    // prep returns: [{ language: 'Chinese' }, { language: 'Spanish' }, ...]
+    ```
+
+2. **`TranslateNode` (extends `Node`)**: This node is executed in parallel for each set of parameters. Its `exec` method calls the LLM for a single translation.
+3. **File I/O**: The results are written to disk asynchronously.
+
+## Performance Comparison
+
+Running translations in parallel dramatically reduces the total execution time compared to a one-by-one sequential approach.
+
+- **Sequential**: ~60 seconds
+- **Parallel (this example)**: ~10 seconds
+
+*(Actual times will vary based on API response speed and system.)*

package/sandbox/3.parallel/package.json

@@ -0,0 +1,16 @@
+{
+	"name": "parallel-workflow",
+	"type": "module",
+	"scripts": {
+		"start": "npx tsx src/main.ts"
+	},
+	"dependencies": {
+		"dotenv": "^16.4.5",
+		"flowcraft": "workspace:*",
+		"openai": "^4.52.7",
+		"yaml": "^2.5.0"
+	},
+	"devDependencies": {
+		"typescript": "^5.5.4"
+	}
+}

package/sandbox/3.parallel/src/main.ts

@@ -0,0 +1,45 @@
+import type { Context } from 'flowcraft'
+import * as fs from 'node:fs/promises'
+import * as path from 'node:path'
+import process from 'node:process'
+import dotenv from 'dotenv'
+import { ConsoleLogger, TypedContext } from 'flowcraft'
+import { TranslateFlow } from './nodes'
+
+dotenv.config()
+
+async function main() {
+	const sourceReadmePath = path.resolve(process.cwd(), '../../README.md')
+	const outputDir = path.resolve(process.cwd(), 'translations')
+	await fs.mkdir(outputDir, { recursive: true })
+
+	const text = await fs.readFile(sourceReadmePath, 'utf-8')
+	const languages = [
+		'Chinese',
+		'Spanish',
+		'Japanese',
+		'German',
+		// 'Russian',
+		// 'Portuguese',
+		// 'French',
+		// 'Korean',
+	]
+
+	const context: Context = new TypedContext([
+		['text', text],
+		['languages', languages],
+		['output_dir', outputDir],
+	])
+
+	const flow = new TranslateFlow()
+	console.log(`Starting parallel translation into ${languages.length} languages...`)
+	const startTime = Date.now()
+
+	await flow.run(context, { logger: new ConsoleLogger() })
+
+	const duration = (Date.now() - startTime) / 1000
+	console.log(`\nTotal parallel translation time: ${duration.toFixed(2)} seconds`)
+	console.log('\n=== Translation Complete ===')
+}
+
+main().catch(console.error)

package/sandbox/3.parallel/src/nodes.ts

@@ -0,0 +1,43 @@
+import type { AbstractNode, NodeArgs } from 'flowcraft'
+import * as fs from 'node:fs/promises'
+import * as path from 'node:path'
+import { Node, ParallelBatchFlow } from 'flowcraft'
+import { callLLM } from './utils'
+
+export class TranslateNode extends Node<void, { language: string, translation: string }> {
+	async exec({ params }: NodeArgs) {
+		const { text, language } = params
+		const prompt = `
+Translate the following markdown text into ${language}.
+Preserve markdown formatting, links, and code blocks.
+Return only the translated text.
+
+Original Text:
+${text}`
+		console.log(`Translating to ${language}...`)
+		const translation = await callLLM(prompt)
+		console.log(`✓ Finished ${language}`)
+		return { language, translation }
+	}
+
+	async post({ ctx, execRes }: NodeArgs<void, { language: string, translation: string }>) {
+		const { language, translation } = execRes
+		const outputDir = ctx.get('output_dir')!
+		const filename = path.join(outputDir, `README_${language.toUpperCase()}.md`)
+		await fs.writeFile(filename, translation, 'utf-8')
+		console.log(`Saved translation to ${filename}`)
+	}
+}
+
+export class TranslateFlow extends ParallelBatchFlow {
+	protected nodeToRun: AbstractNode = new TranslateNode()
+
+	async prep({ ctx }: NodeArgs): Promise<any[]> {
+		const languages = ctx.get('languages')!
+		const text = ctx.get('text')
+		return languages.map((language: string) => ({
+			language,
+			text,
+		}))
+	}
+}

package/sandbox/3.parallel/src/utils.ts

@@ -0,0 +1,25 @@
+import process from 'node:process'
+import OpenAI from 'openai'
+
+const client = new OpenAI({
+	apiKey: process.env.OPENAI_API_KEY,
+})
+
+/**
+ * Asynchronously 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 {
+		const response = await client.chat.completions.create({
+			model: 'gpt-4o-mini',
+			messages: [{ role: 'user', content: prompt }],
+		})
+		return response.choices[0].message.content || ''
+	}
+	catch (error: any) {
+		console.error('Error calling OpenAI API:', error)
+		return `Error: Could not get a response from the LLM. Details: ${error.message}`
+	}
+}

package/sandbox/3.parallel/tsconfig.json

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

package/sandbox/4.dag/README.md

@@ -0,0 +1,179 @@
+# Dynamic AI Agent from Visual Graphs
+
+This example demonstrates a runtime engine that can execute complex, graph-based AI workflows defined as simple JSON files. It showcases how to build a powerful AI agent that can reason, branch, and call other workflows recursively using the `workflow` framework.
+
+The system is designed to be highly modular, allowing you to define different use-cases (e.g., customer support, content creation, HR) by simply adding new workflow graphs, without changing the core application code.
+
+## Features
+
+- **File-Based Workflow Definitions**: Define complex workflows as simple JSON files. This decouples the logic from the code, allowing for easy creation, modification, and management of flows.
+- **Enhanced DAG Support**: The engine automatically detects both parallel start points and **parallel branching from any node in the graph (fan-out)**. This allows for complex, non-linear workflows where a single condition can trigger multiple independent paths to run concurrently.
+- **LLM-Powered Logic**: Utilizes generic, reusable nodes that call a Large Language Model (LLM) for sophisticated tasks:
+  - `llm-process`: For content generation, summarization, and data extraction.
+  - `llm-condition`: For natural language-based conditional branching (`true`/`false`).
+  - `llm-router`: For dynamic, multi-way branching based on an LLM's decision.
+- **Composable & Nested Workflows**: A `sub-workflow` node allows you to embed and reuse entire workflows within others, promoting modularity and DRY principles.
+- **Robust Data Handling**: The framework seamlessly passes data between nodes and even across sub-workflow boundaries. It includes a pattern for safely aggregating outputs from different conditional branches.
+- **Dynamic & Scalable**: A `WorkflowRegistry` dynamically loads all workflow definitions from a specified use-case directory on startup, making it easy to add or switch between different applications.
+
+## 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. **Choose a Use-Case**:
+    Open `src/main.ts` and configure the `ACTIVE_USE_CASE` constant at the top of the file to select which example to run.
+
+    ```typescript
+    // src/main.ts
+    // --- CONFIGURATION ---
+    // Change this value to run different use-cases.
+    const ACTIVE_USE_CASE: UseCase = '1.blog-post'
+    // const ACTIVE_USE_CASE: UseCase = '2.job-application'
+    // const ACTIVE_USE_CASE: UseCase = '3.customer-review'
+    // const ACTIVE_USE_CASE: UseCase = '4.content-moderation'
+    ```
+
+4. **Run the application**:
+
+    ```bash
+    npm start
+    ```
+
+## How It Works
+
+This example uses a `Registry -> Builder -> Executor` pattern to run workflows defined in the `data/` directory.
+
+1. **Workflow Definitions**: Workflows are defined as JSON files within a use-case-specific subdirectory (e.g., `data/customer-review/`). Each file is named with its ID (e.g., `300.json`) and contains a list of nodes and edges. Each subdirectory also contains a `README.md` with detailed information.
+
+2. **`WorkflowRegistry`**: On startup, the registry is initialized for a specific use-case directory. It reads all `.json` files, parses them into `WorkflowGraph` objects, and stores them in memory.
+
+3. **`FlowBuilder`**: When a flow is requested, the builder translates the declarative graph data (nodes and edges) into a connected graph of executable `Node` instances. It intelligently handles parallelism in two ways:
+    1. It wraps multiple start nodes in a `ParallelNode` for an initial fan-out.
+    2. More powerfully, if it detects that a single node's action (e.g., `'true'`) connects to multiple downstream nodes, it **dynamically inserts another `ParallelNode` to execute that branch concurrently**.
+
+4. **Generic Executor Nodes**: A small set of powerful, reusable nodes in `src/nodes.ts` provide the runtime logic. These nodes are configured entirely by the `data` field in the JSON definition, making them highly flexible.
+
+## Example Use-Cases
+
+The `data` directory contains several examples, each demonstrating different capabilities of the framework.
+
+### Use-Case 1: Blog Post Generation (Sequential Flow)
+
+A classic linear workflow for content creation, where the output of one step becomes the input for the next.
+
+```mermaid
+graph TD
+    subgraph "Blog Post Generation (ID: 100)"
+        A[generate_outline] --> B[draft_post]
+        B --> C[suggest_titles]
+        C --> D[final_output]
+    end
+```
+
+**Demonstrates**:
+
+- **Sequential Processing**: A simple, powerful chain of nodes.
+- **Content Generation Pipeline**: A common pattern for AI-powered content creation.
+- **For more details, see [`data/1.blog-post/README.md`](./data/1.blog-post/README.md).**
+
+### Use-Case 2: Job Applicant Screener (DAG with Conditional Branching)
+
+A workflow that analyzes a resume and cover letter in parallel, then makes a decision to call one of two sub-workflows.
+
+```mermaid
+graph TD
+    subgraph "Job Application Screener (ID: 200)"
+        A(Resume) --> B[extract_skills]
+        C(Cover Letter) --> D[analyze_tone]
+        B --> E{check_qualifications}
+        D --> E
+        E -- true --> F["Sub-Workflow: Send Interview (201)"]
+        E -- false --> G["Sub-Workflow: Send Rejection (202)"]
+        F --> H[final_output]
+        G --> H
+    end
+```
+
+**Demonstrates**:
+
+- **Parallel Inputs**: Processing multiple independent data sources concurrently.
+- **Conditional Branching**: Using an `llm-condition` node to direct the flow.
+- **Sub-Workflows**: Composing flows by calling other, reusable workflows.
+- **For more details, see [`data/2.job-application/README.md`](./data/2.job-application/README.md).**
+
+### Use-Case 3: Customer Review Analysis (DAG with Fan-Out)
+
+An advanced workflow that runs initial processing in parallel, makes a conditional decision, and then demonstrates a **mid-flow fan-out**, where one node triggers multiple parallel downstream actions.
+
+```mermaid
+graph TD
+    subgraph "Customer Review Analysis (ID: 300)"
+        A(Initial Review) --> B[summarize]
+        A --> C[categorize]
+        B --> D{check_sentiment}
+        C --> D
+        D -- true --> E["Sub-Workflow: Positive Reply (301)"]
+        D -- false --> F["Sub-Workflow: Create Ticket & Reply (302)"]
+
+        subgraph "Negative Path (Parallel Fan-Out)"
+            F --> G[send_to_ticketing_system]
+            F --> H[send_email_to_customer]
+        end
+
+        E --> Z[final_step]
+        G --> Z
+        H --> Z
+    end
+```
+
+**Demonstrates**:
+
+- **Mid-Flow Fan-Out**: A single node (`negative_branch`) triggers multiple concurrent downstream tasks.
+- **Complex Sub-Workflows**: The sub-workflows themselves can have parallel steps.
+- **Data Aggregation**: A final node gathers results from multiple, mutually exclusive branches.
+- **For more details, see [`data/3.customer-review/README.md`](./data/3.customer-review/README.md).**
+
+### Use-Case 4: Content Moderation (Router Pattern)
+
+A sophisticated workflow that performs multiple parallel checks on content and then uses a central **router** node to decide on one of several possible actions.
+
+```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
+```
+
+**Demonstrates**:
+
+- **LLM-Powered Routing**: Using the `llm-router` node to implement a dynamic `switch` statement based on multiple inputs.
+- **Multi-Way Branching**: Directing the flow to one of many distinct paths.
+- **Scalable Moderation Logic**: New moderation rules or actions can be added by modifying the graph and prompts, not the core code.
+- **For more details, see [`data/4.content-moderation/README.md`](./data/4.content-moderation/README.md).**

package/sandbox/4.dag/data/1.blog-post/100.json

@@ -0,0 +1,60 @@
+{
+	"nodes": [
+		{
+			"id": "generate_outline",
+			"type": "llm-process",
+			"data": {
+				"promptTemplate": "Generate a detailed, multi-point blog post outline for the topic: \"{{topic}}\".",
+				"inputs": {
+					"topic": "topic"
+				}
+			}
+		},
+		{
+			"id": "draft_post",
+			"type": "llm-process",
+			"data": {
+				"promptTemplate": "Write a full-length, engaging blog post based on the following outline:\n\n{{outline}}",
+				"inputs": {
+					"outline": "generate_outline"
+				}
+			}
+		},
+		{
+			"id": "suggest_titles",
+			"type": "llm-process",
+			"data": {
+				"promptTemplate": "Suggest 5 catchy, SEO-friendly titles for the following blog post. Respond with a simple numbered list.\n\nPost:\n{{draft}}",
+				"inputs": {
+					"draft": "draft_post"
+				}
+			}
+		},
+		{
+			"id": "final_output",
+			"type": "output",
+			"data": {
+				"outputKey": "final_output",
+				"promptTemplate": "--- TITLES ---\n{{titles}}\n\n--- DRAFT ---\n{{draft}}",
+				"inputs": {
+					"titles": "suggest_titles",
+					"draft": "draft_post"
+				}
+			}
+		}
+	],
+	"edges": [
+		{
+			"source": "generate_outline",
+			"target": "draft_post"
+		},
+		{
+			"source": "draft_post",
+			"target": "suggest_titles"
+		},
+		{
+			"source": "suggest_titles",
+			"target": "final_output"
+		}
+	]
+}

package/sandbox/4.dag/data/1.blog-post/README.md

@@ -0,0 +1,25 @@
+# Use Case 1: Blog Post Generation
+
+This workflow demonstrates a simple, linear pipeline for content creation. It takes an initial topic and sequentially processes it through a series of steps to produce a finished blog post with title suggestions.
+
+This is a classic example of how to chain nodes together to form a multi-step, sequential process where the output of one node becomes the input for the next.
+
+## Workflow ID: 100
+
+### Description
+
+1. **`generate_outline`**: Takes the initial `topic` and uses an LLM to generate a blog post outline.
+2. **`draft_post`**: Uses the generated outline to write a full-length blog post.
+3. **`suggest_titles`**: Analyzes the drafted post to suggest several catchy, SEO-friendly titles.
+4. **`final_output`**: Combines the suggested titles and the final draft into a single output string for review.
+
+### Visual Graph
+
+```mermaid
+graph TD
+    subgraph "Blog Post Generation (ID: 100)"
+        A[generate_outline] --> B[draft_post]
+        B --> C[suggest_titles]
+        C --> D[final_output]
+    end
+```

package/sandbox/4.dag/data/2.job-application/200.json

@@ -0,0 +1,103 @@
+{
+	"nodes": [
+		{
+			"id": "extract_skills",
+			"type": "llm-process",
+			"data": {
+				"promptTemplate": "Extract a list of all technical skills from this resume. Format as a simple comma-separated string:\n\n{{resume}}",
+				"inputs": {
+					"resume": "resume"
+				}
+			}
+		},
+		{
+			"id": "analyze_tone",
+			"type": "llm-process",
+			"data": {
+				"promptTemplate": "Analyze the tone of this cover letter. Respond with a single word: \"professional\", \"casual\", or \"unprofessional\".\n\n{{coverLetter}}",
+				"inputs": {
+					"coverLetter": "coverLetter"
+				}
+			}
+		},
+		{
+			"id": "check_qualifications",
+			"type": "llm-condition",
+			"data": {
+				"promptTemplate": "Does this list of skills `{{skills}}` contain all of the following required skills: `TypeScript, Node.js, SQL`? Also, is the cover letter tone `{{tone}}` professional? Respond only 'true' if both conditions are met, otherwise 'false'.",
+				"inputs": {
+					"skills": "extract_skills",
+					"tone": "analyze_tone"
+				}
+			}
+		},
+		{
+			"id": "send_interview_email",
+			"type": "sub-workflow",
+			"data": {
+				"workflowId": 201,
+				"outputs": {
+					"send_interview_email": "final_output"
+				},
+				"inputs": {
+					"applicantName": "applicantName"
+				}
+			}
+		},
+		{
+			"id": "send_rejection_email",
+			"type": "sub-workflow",
+			"data": {
+				"workflowId": 202,
+				"outputs": {
+					"send_rejection_email": "final_output"
+				},
+				"inputs": {
+					"applicantName": "applicantName"
+				}
+			}
+		},
+		{
+			"id": "final_output",
+			"type": "output",
+			"data": {
+				"promptTemplate": "Final email sent to {{applicantName}}:\n\n{{email_body}}",
+				"inputs": {
+					"applicantName": "applicantName",
+					"email_body": [
+						"send_interview_email",
+						"send_rejection_email"
+					]
+				}
+			}
+		}
+	],
+	"edges": [
+		{
+			"source": "extract_skills",
+			"target": "check_qualifications"
+		},
+		{
+			"source": "analyze_tone",
+			"target": "check_qualifications"
+		},
+		{
+			"source": "check_qualifications",
+			"target": "send_interview_email",
+			"action": "true"
+		},
+		{
+			"source": "check_qualifications",
+			"target": "send_rejection_email",
+			"action": "false"
+		},
+		{
+			"source": "send_interview_email",
+			"target": "final_output"
+		},
+		{
+			"source": "send_rejection_email",
+			"target": "final_output"
+		}
+	]
+}

package/sandbox/4.dag/data/2.job-application/201.json

@@ -0,0 +1,31 @@
+{
+	"nodes": [
+		{
+			"id": "gen_interview_email",
+			"type": "llm-process",
+			"data": {
+				"promptTemplate": "Write a polite and professional email inviting {{applicantName}} to an interview. Mention you were impressed with their resume.",
+				"inputs": {
+					"applicantName": "applicantName"
+				}
+			}
+		},
+		{
+			"id": "output_email",
+			"type": "output",
+			"data": {
+				"outputKey": "final_output",
+				"promptTemplate": "{{result}}",
+				"inputs": {
+					"result": "gen_interview_email"
+				}
+			}
+		}
+	],
+	"edges": [
+		{
+			"source": "gen_interview_email",
+			"target": "output_email"
+		}
+	]
+}

package/sandbox/4.dag/data/2.job-application/202.json

@@ -0,0 +1,31 @@
+{
+	"nodes": [
+		{
+			"id": "gen_rejection_email",
+			"type": "llm-process",
+			"data": {
+				"promptTemplate": "Write a polite and professional email to {{applicantName}} informing them that you will not be moving forward with their application at this time. Thank them for their interest.",
+				"inputs": {
+					"applicantName": "applicantName"
+				}
+			}
+		},
+		{
+			"id": "output_email",
+			"type": "output",
+			"data": {
+				"outputKey": "final_output",
+				"promptTemplate": "{{result}}",
+				"inputs": {
+					"result": "gen_rejection_email"
+				}
+			}
+		}
+	],
+	"edges": [
+		{
+			"source": "gen_rejection_email",
+			"target": "output_email"
+		}
+	]
+}