FlowGram.AI Documentation

repository·main·Indexed 27 days ago

https://github.com/bytedance/flowgram.ai

A composable and extensible workflow development framework for building AI workflow platforms. It provides core building blocks such as flow canvases, node configuration forms, and variable management engines. The framework supports both fixed-layout and free-layout editors, featuring a modular plugin architecture, a registry pattern for custom node types, and full TypeScript support.

Tokens
208.2K
Snippets
518
Records
1.3K
Agent score
93%

What's inside FlowGram.AI

  1. Overview of FlowGram.AI Fixed Layout Demo Tech Stack

    main

    The fixed-layout demo serves as a best-practices implementation for fixed-layout workflow development. It utilizes the following core technologies:

    • Frontend Framework: React 18 + TypeScript
    • Build Tool: Rsbuild (based on Rspack)
    • Styling: Less, Styled Components, and CSS Variables
    • UI Library: Semi Design (@douyinfe/semi-ui)
    • State Management: In-house Editor framework by Flowgram
    • Dependency Injection: Inversify
  2. Overview of FlowGram.AI Features

    main

    FlowGram is a composable, visual, and extensible workflow development framework designed to help developers build AI workflow platforms. Key features include:

    • Free Layout Canvas: A canvas where nodes can be placed anywhere and connected via edges.
    • Fixed Layout Canvas: A canvas where nodes are snapped to specific positions, supporting composite nodes like branches and loops.
    • Form Engine: Manages CRUD operations for node data, providing rendering, validation, side effects, linkage, and error handling to simplify node configuration development.
    • Variable Engine: Manages data flow within workflows with support for scope constraints, variable structure checking, and type inference.
  3. Introduction to FlowGram Runtime

    main

    FlowGram Runtime is a reference implementation of a workflow runtime engine designed for business developers to learn from and modify. It parses and executes graph-based workflows using various node types.

    ⚠️ Critical Limitations:

    • Early Development Stage: APIs are unstable and may change without backward compatibility.
    • Runtime Support: Currently supports only Node.js.
    • Layout Support: Currently works only in free layout.
    • Distribution: It is positioned as a demo/reference implementation, not an SDK. It will not be published as a package; developers should fork the repository to use it.
  4. Overview of FlowGram Features

    main

    FlowGram is a composable, visual, and extensible workflow development framework and toolkit designed to help developers build AI workflow platforms. Key features include:

    • Free Layout Canvas: A canvas where nodes can be placed arbitrarily and connected with freeform lines.
    • Fixed Layout Canvas: A canvas where nodes are snapped to specific positions, supporting composite nodes like branches and loops.
    • Form Engine: Manages CRUD operations for node data and provides rendering, validation, side effects, linking, and error capture to simplify node configuration development.
    • Variable Engine: Manages data flow within workflows by supporting scope constraints, variable structure inspection, and type inference.
  5. Overview of FlowGram Workflow Development Framework

    main

    FlowGram is a specialized workflow development framework and toolkit designed to help developers build AI workflow platforms. Unlike general-purpose graphics libraries, FlowGram provides built-in tools specifically for workflow scenarios, reducing the complexity of managing node data, dynamic forms, and variable scopes.

    Core features include:

    • Workflow Canvas: Supports both free and fixed layouts for visual orchestration of nodes and edges.
    • Forms: A form engine that manages CRUD operations for node data, including rendering, validation, side effects, linkage, and error-capturing.
    • Variables: A variable engine that handles scope constraints, variable structure inspection, and type inference to manage data flow.
    • Materials: A collection of reusable components, side effects, and validators to accelerate development.
  6. Understand Variable Engine Core Concepts

    main

    The FlowGram variable engine uses several core concepts to manage data during design and runtime:

    • Variable: Containers defined during design time (focusing on definitions) and evaluated during runtime (focusing on values).
    • Scope: A container that bundles variable information and defines access boundaries (who can access which variables). Common scopes include Node Scopes, Global Scopes, and Component Scopes.
    • AST (Abstract Syntax Tree): The structure used by scopes to store variable information. Each node in the tree describes a declaration, type, or expression.
    • Declaration: The combination of an Identifier (Key) and a Definition (e.g., Type + Initial Value). The engine supports VariableDeclaration (globally unique) and Property (unique within an object).
    • Type: Constraints on variable values (e.g., StringType, IntegerType, ObjectType, ArrayType, MapType, CustomType).
    • Expression: Logic that takes 0 or more variables as input and returns a new variable. In design mode, the engine tracks dependencies and infers return types.
  7. FlowGram Core Features Overview

    main

    FlowGram is a composable, visual, and extensible workflow development framework designed for building AI workflow platforms. Key features include:

    • Free Layout Canvas: A design canvas where nodes can be placed anywhere and connected freely via lines.
    • Fixed Layout Canvas: A structured canvas where nodes are snapped to specific positions, supporting composite nodes like branches and loops.
    • Form Engine: Manages node data CRUD operations, providing rendering, validation, side effects, binding, and error handling for node configurations.
    • Variable Engine: Manages data flow within workflows with support for scope constraints, variable structure inspection, and type inference.
  8. Understand the Workflow Engine implementation

    main

    The workflow engine is the core component responsible for parsing, scheduling, and executing workflows. It is primarily implemented in js-core/src/domain/engine/engine.ts.

    Key responsibilities include:

    • Workflow Parsing: Converting definitions into internal models.
    • Node Scheduling: Determining execution order based on edges.
    • Node Execution: Invoking node executors.
    • State & Variable Management: Tracking execution status and handling data transfer between nodes.
    • Error Handling: Managing exceptions during the workflow lifecycle.
    // Core method for workflow execution
    public async run(params: RunParams): Promise<RunResult> {
      const { schema, inputs, options } = params;
    
      // Create workflow context
      const context = this.createContext(schema, inputs, options);
    
      try {
        // Initialize workflow
        await this.initialize(context);
    
        // Execute workflow
        await this.execute(context);
    
        // Get workflow result
        const result = await this.getResult(context);
    
        return {
          status: 'success',
          outputs: result
        };
      } catch (error) {
        // Error handling
        return {
          status: 'fail',
          error: error.message
        };
      }
    }
  9. Compare FlowGram with ReactFlow features

    main

    FlowGram is designed as a complete out-of-the-box solution for flow editing, whereas ReactFlow focuses on a low-level rendering engine (Nodes, Edges, Handles) that requires significant upper-layer development for complex scenarios like fixed layouts.

    Many features that are paid in ReactFlow are supported natively in FlowGram, including:

    • Grouping
    • Redo/Undo
    • Copy/Paste
    • HelpLines
    • Custom nodes and shapes
    • Custom edges
    • AutoLayout
    • Expand/Collapse
    • WorkflowBuilder (Fixed Layout Example)

    Note: ForceLayout is currently not supported by FlowGram, and Collaborative features are planned for the future.

  10. Core Architecture and Design Principles of FlowGram.AI Free Layout

    main

    The FlowGram.AI Free Layout demo is built on a highly modular and extensible architecture designed for workflow development. Key architectural features include:

    • Plugin-based Architecture: Every feature is implemented as an independent plugin for easy maintenance and extension.
    • Node Registration System: New node types can be added via a registration system without modifying the core codebase.
    • Component-driven Design: UI components are highly reusable with clear responsibilities.
    • Type Safety: Full TypeScript support across the entire pipeline, including JSON Schema integration for node data structure validation and strongly typed plugin interfaces.
    • Extensibility: Supports custom node types, custom form configurations, and a multi-runtime environment (both browser and server).
    • Performance: Implements on-demand loading for components/plugins and debouncing for high-frequency operations like auto-saving.
  11. Understand the FlowGram.AI Design Philosophy

    main

    FlowGram.AI is built on several core principles designed for workflow development:

    • Highly Modular: Uses a plugin architecture where features are independent, a node registry system for adding node types without core changes, and componentized UI.
    • Type Safety: Provides full TypeScript support, JSON Schema integration for node data validation, and strongly typed plugin interfaces.
    • User Experience: Features real-time preview, rich interactions (dragging, zooming, snapping, shortcuts), and visual feedback (minimap, status indicators).
    • Extensibility: Supports an open plugin system, flexible node/form configurations, and multiple runtimes (browser and server).
    • Performance: Utilizes on-demand loading for components/plugins and debouncing for high-frequency operations like auto-save.
  12. Use the @flowgram.ai/free-layout-editor framework

    main

    The Free Layout demo is built upon the @flowgram.ai/free-layout-editor framework, which provides the foundational capabilities for free-form canvas editing. It includes:

    • A canvas system for free-form layouts.
    • Full undo/redo functionality.
    • Lifecycle management for nodes and connections (lines).
    • A variable engine and expression system.