Basic Concepts

Goal : To understand the basic concepts of Cascaide and how they map to DAGs

Cascaide treats your application’s dynamic logic and data flow as a single graph. You can think of every part of it, UI components, functions, API calls, database operations etc. as nodes in a graph. The logic definining which nodes should be executed when forms the edges and all the information about the application form the state.

Prerequisites

We assume knowledge of

• Typescript
• React

In addition, it is great if you understand Redux because we use it under the hood. However, it is not strictly required as you will not be directly dealing with it. At the moment, all examples are built on Next.js, however, Cascaide can be used in any React application built with frameworks like Remix or Vite, provided you have a mechanism to host the server-side Node execution logic (e.g., in Node.js or serverless functions).

Concepts

In this section, we will dive into the basic concepts. Later, we will go deeper in the advanced concepts section.

State

State is how information in the app is stored. It has 4 parts

• context : This is data you store, typically as a sequence (array) of updates (crucial for history and immutability), to be accessible to different nodes. Nodes may read the latest value and write new objects to context.
• activeNodes : This tracks which nodes are currently executing and the data associated with them
• history : This maintains a record of which nodes were active in the past
• errors : This keeps track of errors thrown by failed nodes

State is stored in a global redux store immutably.

Nodes

Nodes are units of work. They accept an input upon activation and/or read additional information from the context, execute their tasks, writes back to the context and initiate the next nodes.

Nodes are just functions. They come in two main flavours: UI Nodes (which run on the client and could pause the workflow for human interaction) and Logic Nodes (which run on the server via the Workflow Engine)

client workflow config snippet (more on this later)
 
 
analyticsAgentNode: { name: 'analyticsAgentNode', isUINode: false}
 

Node Lifecycle (Only for Logic Nodes)

Each node follows a fixed lifecycle:

• prep - in the prep step, a node accepts an input and/or selects(selector step) data from the context and prepares it for execution
• exec - in this step, the output from the prep step is used to execute core logic
• post - finally, results are written to the context and the next node(s) are spawned

In addition, they may be streaming nodes or not.

server workflow config snippet (more on this later)
 
analyticsAgentNode: {
      name: 'analyticsAgentNode',
      prep: { selector: analyticsAgentNodeSelector, fn: analyticsAgentNodePrep },
      exec: analyticsAgentNodeExec,
      post: analyticsAgentNodePost,
      isStreaming: true,
    },

Spawning : Realising Edges

Spawning is how edges are realised. When a node decides which node(s) are to be activated, they spawn them by returning the node name, the required data for the new node and the updates(if it is a logic node), or by using useWorkflow hook is it is an uiNode (more on this later).

return {
    updates: {
        history: updatedHistory,
        status: 'complete', 
    },
    spawnNodes: ['analyticsAgentNode'],
    spawnContext: [history: updatedHistory],
  };

Workflow

Workflow binds all three elements : state, nodes and edges together and realises the application. It has three parts

• Workflow Engine : The core orchestrator that does all the heavy lifting (You will usually never touch this).
• Client Workflow Config : A declarative object that provides node metadata and UI component registry
• Server Workflow Config : A declarative object that provides node implemenations to the engine

The Client Workflow Config tells the UI what components to render for a node, and the Server Workflow Config tells the Engine how to execute the node’s logic. They must agree on the nodeName. You build applications by creating these workflow configurations. Examples below.

Note : Unlike other AI orchestration frameworks that use DAGs, graph topology is not predefined explicitly in Cascaide. It emerges at runtime.

Client Workflow Config

 
export const homeWorkflowConfig: WorkflowConfig = {
  workflowGraph: {
    reactAgent: { name: 'reactAgent', isUINode: true },
    analyticsAgentNode: { name: 'analyticsAgentNode', isUINode: false},
    analyticsToolNode: { name: 'analyticsToolNode', isUINode: false },
  }, 
  uiComponentRegistry: {
    reactAgent: ReactAnalysisAgent,
  },
}
 

Sever Workflow Config

export const serverWorkflowConfig = {
    analyticsAgentNode: {
      name: 'analyticsAgentNode',
      prep: { selector: analyticsAgentNodeSelector, fn: analyticsAgentNodePrep },
      exec: analyticsAgentNodeExec,
      post: analyticsAgentNodePost,
      isStreaming: true,
    },
    analyticsToolNode: {
      name: 'analyticsToolNode',
      prep: { selector: analyticsToolNodeSelector, fn: analyticsToolNodePrep },
      exec: analyticsToolNodeExec,
      post: analyticsToolNodePost,
    },
}

Next, we will learn about the client side infrastructure we need to use Cascaide - WorkflowProvider and WorkflowRenderer.