flowcraft 1.0.0-beta.1

package/docs/index.md

@@ -0,0 +1,56 @@
+---
+layout: home
+
+hero:
+  name: Flowcraft
+  text: A Workflow Framework
+  tagline: Build complex, multi-step processes, from simple sequences to dynamic, graph-driven AI agents.
+  actions:
+    - theme: brand
+      text: Introduction
+      link: /guide/
+    - theme: alt
+      text: Recipes
+      link: /guide/recipes/
+    - theme: alt
+      text: Sandbox
+      link: https://github.com/gorango/flowcraft/tree/master/sandbox
+
+features:
+  - title: Zero Dependencies
+    icon: 🌱
+    details: Lightweight and dependency-free, ensuring a small footprint and easy integration.
+  - title: Composable & Reusable
+    icon: 🧩
+    details: Define workflows by chaining nodes or embedding other flows as nodes.
+  - title: Extensible Execution Engine
+    icon: 🔌
+    details: A pluggable Executor pattern enables in-memory or distributed flows.
+  # - title: Type-Safe
+  #   icon: 🛡️
+  #   details: Written in TypeScript to provide strong typing for your workflow definitions and context.
+  # - title: Async by Default
+  #   icon: ⚡
+  #   details: Built on an asynchronous foundation to handle I/O-bound and CPU-bound tasks.
+  - title: Middleware
+    icon: 🥪
+    details: Intercept execution of nodes to handle cross-cutting concerns like logging, timing, or auth.
+  # - title: Conditional Branching
+  #   icon: 🔀
+  #   details: Direct the flow's execution path based on the results of any node.
+  # - title: Retry Logic & Fallbacks
+  #   icon: 🔄
+  #   details: Retry failed operations with configurable delays and fallback logic.
+  - title: Cancellation
+    icon: 🛑
+    details: Gracefully abort in-progress workflows using standard AbortControllers.
+  # - title: Pluggable Logging
+  #   icon: 📝
+  #   details: Use the built-in ConsoleLogger or bring your own (e.g., Pino, Winston).
+  - title: Dynamic Graph Engine
+    icon: 🌐
+    details: Define complex, graph-based workflows as simple JSON files.
+  # - title: Fluent & Functional API
+  #   icon: ✨
+  #   details: A chainable API on the Node class and a collection of functional helpers.
+---

package/eslint.config.js

@@ -0,0 +1,16 @@
+import antfu from '@antfu/eslint-config'
+
+export default antfu({
+	stylistic: {
+		indent: 'tab',
+		quotes: 'single',
+		semi: false,
+	},
+}, {
+	rules: {
+		'no-console': 'off',
+		'unused-imports/no-unused-vars': 'off',
+		'unused-imports/no-unused-imports': 'off',
+		'ts/no-this-alias': 'off',
+	},
+})

package/package.json

@@ -0,0 +1,40 @@
+{
+	"name": "flowcraft",
+	"type": "module",
+	"version": "1.0.0-beta.1",
+	"packageManager": "pnpm@10.13.1",
+	"description": "A flexible workflow framework",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		}
+	},
+	"engines": {
+		"node": ">=24",
+		"pnpm": ">=10"
+	},
+	"scripts": {
+		"dev": "tsup --watch --config config/tsup.config.ts",
+		"build": "tsup --config config/tsup.config.ts",
+		"test": "vitest run --config config/vitest.config.ts",
+		"test:watch": "vitest --config config/vitest.config.ts",
+		"coverage": "vitest run --coverage --config config/vitest.config.ts",
+		"lint": "eslint --fix . --ext .ts --config eslint.config.js",
+		"docs:dev": "vitepress dev docs",
+		"docs:build": "vitepress build docs",
+		"docs:preview": "vitepress preview docs"
+	},
+	"devDependencies": {
+		"@antfu/eslint-config": "^4.16.2",
+		"@types/node": "^24.0.13",
+		"@vitest/coverage-v8": "3.2.4",
+		"eslint": "^9.31.0",
+		"mermaid": "^11.9.0",
+		"tsup": "^8.5.0",
+		"typescript": "^5.8.3",
+		"vitepress": "^1.6.3",
+		"vitepress-plugin-mermaid": "^2.0.17",
+		"vitest": "^3.2.4"
+	}
+}

package/pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+packages:
+  - 'sandbox/*'

package/sandbox/1.basic/README.md

@@ -0,0 +1,45 @@
+# Article Writing Workflow
+
+A `workflow` example that demonstrates an article writing workflow using a sequence of `Node`s and `Flow`.
+
+## Features
+
+- **Generate Outline**: Creates a simple outline with up to 3 main sections using YAML structured output.
+- **Write Content**: Uses a `BatchNode`-like pattern within a single Node to write concise content for each section.
+- **Apply Style**: Applies a conversational, engaging style to the final article.
+
+## How to Run
+
+1. **Install dependencies**:
+
+    ```bash
+    npm install
+    ```
+
+2. **Set your OpenAI API key**:
+    Create a `.env` file in this directory or set an environment variable:
+
+    ```
+    OPENAI_API_KEY="your-api-key-here"
+    ```
+
+3. **Run the application**:
+
+    ```bash
+    npm start
+    ```
+
+    To specify a topic, pass it as an argument:
+
+    ```bash
+    npm start -- "The Future of Renewable Energy"
+    ```
+
+## How It Works
+
+The workflow consists of three sequential nodes:
+
+```mermaid
+graph LR
+    Outline[Generate Outline] --> Write[Write Content]
+    Write --> Style[Apply Style]

package/sandbox/1.basic/package.json

@@ -0,0 +1,16 @@
+{
+	"name": "basic-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/1.basic/src/flow.ts

@@ -0,0 +1,17 @@
+import { Flow } from 'flowcraft'
+import {
+	ApplyStyleNode,
+	GenerateOutlineNode,
+	WriteContentNode,
+} from './nodes'
+
+export function createArticleFlow(): Flow {
+	const outlineNode = new GenerateOutlineNode()
+	const writeContentFlow = new WriteContentNode()
+	const styleNode = new ApplyStyleNode()
+
+	outlineNode.next(writeContentFlow)
+	writeContentFlow.next(styleNode)
+
+	return new Flow(outlineNode)
+}

package/sandbox/1.basic/src/main.ts

@@ -0,0 +1,22 @@
+import type { Context } from 'flowcraft'
+import process from 'node:process'
+import dotenv from 'dotenv'
+import { ConsoleLogger, TypedContext } from 'flowcraft'
+import { createArticleFlow } from './flow'
+import { FINAL_ARTICLE, TOPIC } from './nodes'
+
+dotenv.config()
+
+async function runFlow(topic: string) {
+	const context: Context = new TypedContext([[TOPIC, topic]])
+	const logger = new ConsoleLogger()
+	console.log(`\n=== Starting Article Workflow on Topic: ${topic} ===\n`)
+	const flow = createArticleFlow()
+	await flow.run(context, { logger })
+	console.log('\n=== Workflow Completed ===\n')
+	console.log(`Topic: ${context.get(TOPIC)}`)
+	console.log(`Final Article Length: ${context.get(FINAL_ARTICLE)?.length || 0} characters`)
+}
+
+const topic = process.argv[2] || 'AI Safety'
+runFlow(topic)

package/sandbox/1.basic/src/nodes.ts

@@ -0,0 +1,112 @@
+import type { AbstractNode, NodeArgs } from 'flowcraft'
+import { BatchFlow, contextKey, Node } from 'flowcraft'
+import yaml from 'yaml'
+import { callLLM } from './utils'
+
+export const TOPIC = contextKey<string>('topic')
+export const SECTIONS = contextKey<string[]>('sections')
+export const DRAFT = contextKey<string>('draft')
+export const FINAL_ARTICLE = contextKey<string>('final_article')
+export const SECTION_CONTENTS = contextKey<Record<string, string>>('section_contents')
+
+/**
+ * Generates an article outline from a topic in the context.
+ */
+export class GenerateOutlineNode extends Node<string, { sections: string[] }> {
+	async prep({ ctx }: NodeArgs): Promise<string> {
+		return ctx.get(TOPIC)!
+	}
+
+	async exec({ prepRes: topic }: NodeArgs<string>): Promise<{ sections: string[] }> {
+		const prompt = `
+Create a simple outline for an article about "${topic}".
+Include at most 3 main sections (no subsections).
+Output the sections in YAML format as a list under the key "sections".`
+		const response = callLLM(prompt)
+		const structuredResult = yaml.parse(response)
+		return structuredResult
+	}
+
+	async post({ ctx, execRes }: NodeArgs<string, { sections: string[] }>) {
+		console.log('\n===== PARSED OUTLINE =====')
+		execRes.sections.forEach((s, i) => console.log(`${i + 1}. ${s}`))
+		console.log('==========================\n')
+		ctx.set(SECTIONS, execRes.sections)
+	}
+}
+
+/**
+ * A BatchFlow that orchestrates writing content for each section of the outline.
+ */
+export class WriteContentNode extends BatchFlow {
+	protected nodeToRun: AbstractNode = new WriteSingleSectionNode()
+
+	async prep({ ctx }: NodeArgs) {
+		const sections = ctx.get(SECTIONS) || []
+		return sections.map(section => ({ section }))
+	}
+
+	async post({ ctx }: NodeArgs) {
+		const sectionContents = ctx.get(SECTION_CONTENTS) || {}
+		const draft = (ctx.get(SECTIONS) || []).map(section =>
+			`## ${section}\n\n${sectionContents[section]}\n`,
+		).join('\n')
+		ctx.set(DRAFT, draft)
+
+		console.log('\n===== SECTION CONTENTS =====\n')
+		for (const section in sectionContents)
+			console.log(`--- ${section} ---\n${sectionContents[section]}\n`)
+
+		console.log('============================\n')
+	}
+}
+
+/**
+ * Writes content for a single section, intended to be run by the WriteContentNode batch flow.
+ */
+export class WriteSingleSectionNode extends Node<string, string> {
+	async prep({ params }: NodeArgs): Promise<string> {
+		return params.section
+	}
+
+	async exec({ prepRes: section }: NodeArgs<string>): Promise<string> {
+		const prompt = `
+Write a short paragraph (MAXIMUM 100 WORDS) about this section: "${section}".
+Explain the idea in simple, easy-to-understand terms, avoiding jargon.
+Include one brief example or analogy.`
+		const content = callLLM(prompt)
+		console.log(`✓ Completed section: ${section}`)
+		return content
+	}
+
+	async post({ ctx, prepRes: section, execRes: content }: NodeArgs<string, string>) {
+		const contents = ctx.get(SECTION_CONTENTS) || {}
+		contents[section] = content
+		ctx.set(SECTION_CONTENTS, contents)
+	}
+}
+
+/**
+ * Applies a final style pass to the complete draft article.
+ */
+export class ApplyStyleNode extends Node<string, string> {
+	async prep({ ctx }: NodeArgs): Promise<string> {
+		return ctx.get(DRAFT) || ''
+	}
+
+	async exec({ prepRes: draft }: NodeArgs<string>): Promise<string> {
+		const prompt = `
+Rewrite the following draft in a conversational, engaging style.
+Make it warm in tone, include rhetorical questions, and add a strong opening and conclusion.
+
+${draft}`
+		return callLLM(prompt)
+	}
+
+	async post({ ctx, execRes: finalArticle }: NodeArgs<string, string>) {
+		ctx.set(FINAL_ARTICLE, finalArticle)
+		console.log('\n===== FINAL ARTICLE =====\n')
+		console.log(finalArticle)
+		console.log('\n=========================\n')
+	}
+}

package/sandbox/1.basic/src/utils.ts

@@ -0,0 +1,35 @@
+export function callLLM(prompt: string): string {
+	console.log(`[MOCK LLM] Processing prompt: ${prompt.substring(0, 50)}...`)
+
+	if (prompt.includes('outline') && prompt.includes('sections')) {
+		return `sections:
+  - Introduction to the Topic
+  - Key Concepts and Applications
+  - Future Implications`
+	}
+
+	if (prompt.includes('paragraph') && prompt.includes('100 WORDS')) {
+		const section = prompt.match(/"([^"]+)"/)?.[1] || 'the topic'
+		return `This section covers ${section} in detail. It's an important concept that helps us understand the broader implications. For example, consider how this applies in real-world scenarios. The key takeaway is that understanding this concept enables better decision-making and practical applications in various contexts.`
+	}
+
+	if (prompt.includes('conversational') && prompt.includes('engaging')) {
+		return `Have you ever wondered about this fascinating topic? Let me take you on a journey through these important concepts.
+
+## Introduction to the Topic
+
+This section covers Introduction to the Topic in detail. It's an important concept that helps us understand the broader implications. For example, consider how this applies in real-world scenarios. The key takeaway is that understanding this concept enables better decision-making and practical applications in various contexts.
+
+## Key Concepts and Applications
+
+This section covers Key Concepts and Applications in detail. It's an important concept that helps us understand the broader implications. For example, consider how this applies in real-world scenarios. The key takeaway is that understanding this concept enables better decision-making and practical applications in various contexts.
+
+## Future Implications
+
+This section covers Future Implications in detail. It's an important concept that helps us understand the broader implications. For example, consider how this applies in real-world scenarios. The key takeaway is that understanding this concept enables better decision-making and practical applications in various contexts.
+
+In conclusion, these concepts work together to create a comprehensive understanding that will serve you well in future endeavors.`
+	}
+
+	return `Mock response for: ${prompt.substring(0, 100)}`
+}

package/sandbox/1.basic/tsconfig.json

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

package/sandbox/2.research/README.md

@@ -0,0 +1,46 @@
+# Research Agent
+
+This project demonstrates a simple yet powerful research agent that can search the web and answer questions. It uses conditional branching in `workflow` to decide its next action.
+
+## Features
+
+- Performs web searches to gather information.
+- Makes decisions about when to search vs. when to answer.
+- Generates comprehensive answers based on research findings.
+
+## How to Run
+
+1. **Install dependencies**:
+
+    ```bash
+    npm install
+    ```
+
+2. **Set your OpenAI API key**:
+    Create a `.env` file in this directory or set an environment variable:
+
+    ```
+    OPENAI_API_KEY="your-api-key-here"
+    ```
+
+    You will also need a free API key from [SerpApi](https://serpapi.com/) for web search.
+
+    ```
+    SERPAPI_API_KEY="your-serpapi-key-here"
+    ```
+
+3. **Run the application**:
+
+    ```bash
+    npm start -- "Who won the Nobel Prize in Physics 2024?"
+    ```
+
+## How It Works
+
+The agent uses a graph structure with a decision loop:
+
+```mermaid
+graph TD
+    A[DecideAction] -->|"search"| B[SearchWeb]
+    A -->|"answer"| C[AnswerQuestion]
+    B -->|"decide"| A

package/sandbox/2.research/package.json

@@ -0,0 +1,16 @@
+{
+	"name": "research-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/2.research/src/flow.ts

@@ -0,0 +1,14 @@
+import { Flow } from 'flowcraft'
+import { AnswerQuestionNode, DecideActionNode, SearchWebNode } from './nodes.js'
+
+export function createAgentFlow(): Flow {
+	const decideNode = new DecideActionNode()
+	const searchNode = new SearchWebNode()
+	const answerNode = new AnswerQuestionNode()
+
+	decideNode.next(searchNode, 'search')
+	decideNode.next(answerNode, 'answer')
+	searchNode.next(decideNode, 'decide')
+
+	return new Flow(decideNode)
+}

package/sandbox/2.research/src/main.ts

@@ -0,0 +1,31 @@
+import type { Context } from 'flowcraft'
+import process from 'node:process'
+import dotenv from 'dotenv'
+import { ConsoleLogger, TypedContext } from 'flowcraft'
+import { createAgentFlow } from './flow.js'
+
+dotenv.config()
+const MAX_SEARCHES = 2
+
+async function runAgent(question: string) {
+	if (!question) {
+		question = 'Who won the Nobel Prize in Physics 2024?'
+	}
+
+	const context: Context = new TypedContext([
+		['question', question],
+		['search_count', 0],
+		['max_searches', MAX_SEARCHES],
+	])
+
+	console.log(`🤔 Processing question: ${question}`)
+	console.log(`(Agent will stop after ${MAX_SEARCHES} searches)`)
+	const agentFlow = createAgentFlow()
+	await agentFlow.run(context, { logger: new ConsoleLogger() })
+	console.log('\n🎯 Final Answer:')
+
+	console.log(context.get<string>('answer') || 'No answer found.')
+}
+
+const question = process.argv.slice(2).join(' ')
+runAgent(question)

package/sandbox/2.research/src/nodes.ts

@@ -0,0 +1,108 @@
+import type { NodeArgs } from 'flowcraft'
+import { DEFAULT_ACTION, Node } from 'flowcraft'
+import yaml from 'yaml'
+import { callLLM, searchWeb } from './utils.js'
+
+interface Decision {
+	action: 'search' | 'answer'
+	reason: string
+	search_query?: string
+}
+
+interface DecidePrepRes {
+	question: string
+	context: string
+	searchCount: number
+	maxSearches: number
+}
+
+export class DecideActionNode extends Node<DecidePrepRes, Decision, string> {
+	async prep({ ctx }: NodeArgs) {
+		const question = ctx.get<string>('question')!
+		const context = ctx.get<string>('context') || 'No previous search results.'
+		const searchCount = ctx.get<number>('searchCount') || 0
+		const maxSearches = ctx.get<number>('maxSearches') ?? 2
+		return { question, context, searchCount, maxSearches }
+	}
+
+	async exec({ prepRes }: NodeArgs<DecidePrepRes>) {
+		const { question, context, searchCount, maxSearches } = prepRes
+		const prompt = `
+You are a research assistant. Based on the question, context, and the number of searches performed, decide whether to search for more information or answer the question.
+
+Question: "${question}"
+
+Context:
+${context}
+
+Number of searches performed so far: ${searchCount}
+
+RULES:
+1. If the context contains a clear answer to the question, choose 'answer'.
+2. If the context is insufficient, choose 'search'.
+3. **ESCAPE HATCH**: If the number of searches is ${maxSearches} or greater, you MUST choose 'answer' to avoid getting stuck in a loop.
+
+Return your decision in YAML format inside a markdown code block.
+Your response must include "action" ('search' or 'answer') and a "reason".
+If the action is 'search', you MUST include a "search_query".`
+
+		const response = await callLLM(prompt)
+		const yamlMatch = response.match(/```(?:yaml)?\n([\s\S]*?)\n```/)
+		return yaml.parse(yamlMatch ? yamlMatch[1] : response) as Decision
+	}
+
+	async post({ ctx, execRes: decision }: NodeArgs<any, Decision>): Promise<string> {
+		console.log(`\n🤔 Agent decides to ${decision?.action}. Reason: ${decision?.reason}`)
+		if (decision?.action === 'search') {
+			ctx.set('search_query', decision?.search_query)
+			console.log(`🔍 Search Query: ${decision?.search_query}`)
+		}
+		return decision?.action ?? DEFAULT_ACTION
+	}
+}
+
+export class SearchWebNode extends Node<string, string, string> {
+	async prep({ ctx }: NodeArgs) {
+		return ctx.get<string>('search_query')!
+	}
+
+	async exec({ prepRes: query }: NodeArgs<string>) {
+		return searchWeb(query)
+	}
+
+	async post({ ctx, prepRes: query, execRes: searchResults }: NodeArgs<string, string>) {
+		const currentContext = ctx.get('context') || ''
+		const newContext = `${currentContext}\n\nSearch for "${query}":\n${searchResults}`
+		ctx.set('context', newContext)
+
+		const count = ctx.get<number>('searchCount') || 0
+		ctx.set('searchCount', count + 1)
+
+		console.log(`📚 Found information (Search #${count + 1}), analyzing results...`)
+		return 'decide'
+	}
+}
+
+export class AnswerQuestionNode extends Node<{ question: string, context: string }, string> {
+	async prep({ ctx }: NodeArgs) {
+		const question = ctx.get<string>('question')!
+		const context = ctx.get<string>('context') || 'No context provided.'
+		return { question, context }
+	}
+
+	async exec({ prepRes }: NodeArgs<{ question: string, context: string }>) {
+		const { question, context } = prepRes
+		const prompt = `Based on the following context, provide a comprehensive answer to the question.
+Context:
+${context}
+
+Question: "${question}"`
+		console.log('✍️  Crafting final answer...')
+		return callLLM(prompt)
+	}
+
+	async post({ ctx, execRes: answer }: NodeArgs<any, string>) {
+		ctx.set('answer', answer)
+		console.log('✅ Answer generated successfully.')
+	}
+}

package/sandbox/2.research/src/utils.ts

@@ -0,0 +1,45 @@
+import process from 'node:process'
+import OpenAI from 'openai'
+
+const openaiClient = new OpenAI({
+	apiKey: process.env.OPENAI_API_KEY,
+})
+
+/**
+ * Synchronously 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 openaiClient.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}`
+	}
+}
+
+/**
+ * Placeholder for a synchronous web search function.
+ * In a real application, using an async flow and an async search function is highly recommended.
+ * @param query The search query.
+ * @returns A formatted string of placeholder search results.
+ */
+export function searchWeb(query: string): string {
+	console.log(`[SYNC PLACEHOLDER] Searching for: "${query}"`)
+	// In a real implementation, you would use a library that makes an async HTTP request.
+	return `
+Title: Placeholder Result for ${query}
+URL: http://example.com/search?q=${encodeURIComponent(query)}
+Snippet: This is a placeholder result. For actual web search capabilities, it is highly recommended to use an asynchronous flow (AsyncFlow) with an async-capable search utility.
+
+Title: Second Placeholder
+URL: http://example.com/placeholder
+Snippet: Using synchronous I/O in Node.js can block the event loop, impacting performance. Async operations are the standard.
+`.trim()
+}

package/sandbox/2.research/src/visualize.ts

@@ -0,0 +1,29 @@
+import { DEFAULT_ACTION, Flow, generateMermaidGraph, Node } from 'flowcraft'
+
+// Re-create the Research Agent flow from the README
+class DecideActionNode extends Node {
+	async post() {
+		// Simulate a decision
+		const decision = Math.random() > 0.5 ? 'search' : 'answer'
+		console.log(`Decision: ${decision}`)
+		return decision
+	}
+}
+
+class SearchWebNode extends Node { }
+class AnswerQuestionNode extends Node { }
+
+const decideNode = new DecideActionNode()
+const searchNode = new SearchWebNode()
+const answerNode = new AnswerQuestionNode()
+
+// Wire the graph
+decideNode.next(searchNode, 'search')
+decideNode.next(answerNode, 'answer')
+searchNode.next(decideNode, DEFAULT_ACTION) // Loop back
+
+const researchAgentFlow = new Flow(decideNode)
+
+// Generate and print the Mermaid syntax
+const mermaidGraph = generateMermaidGraph(researchAgentFlow)
+console.log(mermaidGraph)

package/sandbox/2.research/tsconfig.json

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