create-qflow

create-qflow is a command-line tool that helps you quickly scaffold new qflow projects. It allows you to choose from different workflow styles to get started with your preferred coding approach.

Installation

To use create-qflow, you need to have Bun installed. Then, you can use bunx to run the scaffolder:

bunx create-qflow@latest my-new-project

Usage

To create a new qflow project, run the following command:

bunx create-qflow@latest <project-name>

Replace <project-name> with the desired name for your new project. The tool will then prompt you to select a workflow style.

Understanding qflow and AGENTS.md

This template is designed to work with the @fractal-solutions/qflow library, a powerful tool for building asynchronous, node-based workflows. You can find more information about the qflow library here:

• npm package: https://www.npmjs.com/package/@fractal-solutions/qflow
• GitHub repository: https://github.com/fractal-solutions/qflow

Each qflow project generated by create-qflow includes an AGENTS.md file. This document serves as an authoritative guide for AI agents (and human developers!) working with the qflow library, outlining core principles, architecture, and best practices.

Selecting a Workflow Style

During the project creation process, you will be asked to choose one of the following workflow styles:

1. Concise (Functional): This approach uses a functional style where AsyncNode instances are created and their execAsync and postAsync methods are directly overridden. This is often the most straightforward for simple workflows.

   // Example: Functional Node Definition
   const myNode = new AsyncNode();
   myNode.execAsync = async (prepRes, shared) => {
     console.log("Executing myNode");
     shared.data = "Hello from functional node!";
   };
   myNode.postAsync = async (shared, prepRes, execRes) => {
     return "next";
   };

2. Flexible (Object Spread): This style uses the JavaScript object spread syntax (...new AsyncNode()) to create and extend AsyncNode instances. It can be more concise for defining nodes inline.

   // Example: Object Spread Node Definition
   const myNode = {
     ...new AsyncNode(),
     async execAsync(prepRes, shared) {
       console.log("Executing myNode");
       shared.data = "Hello from object spread node!";
     },
     async postAsync(shared, prepRes, execRes) {
       return "next";
     }
   };

3. Structured (Class-based): This is the most structured approach, where you define custom classes that extend AsyncNode or other specialized qflow nodes. This is recommended for complex nodes that require more encapsulated logic or reusability.

   // Example: Class-based Node Definition
   class MyCustomNode extends AsyncNode {
     async execAsync(prepRes, shared) {
       console.log("Executing MyCustomNode");
       shared.data = "Hello from class-based node!";
     }
     async postAsync(shared, prepRes, execRes) {
       return "next";
     }
   }
   const myNode = new MyCustomNode();

4. Agent (Generic LLM): This approach scaffolds a project with a generic AI agent capable of using various LLMs by configuring a base URL, API key, and model. It includes a custom GenericLLMNode for flexible LLM integration and a basic agent setup with tools like web search and system notifications.

Getting Started with Your New Project

After create-qflow finishes, navigate into your new project directory:

cd <project-name>

Then, install the dependencies:

bun install

Finally, run your qflow application:

bun run src/index.js