use-get-begin-query.tsx

Overview

This file contains a collection of React hooks and utility functions centered around managing, querying, and building options for the "Begin" node in a flow-based agent system. The "Begin" node represents the starting point of a dialogue flow or task sequence and stores input fields (inputs) and output fields (outputs) that can be referenced by other nodes.

The main functionalities include:

• Extracting and formatting input/output data from the "Begin" node.

• Building selectable options for variables and components used in queries or UI forms.

• Traversing graph structures to find upstream nodes and their outputs.

• Providing label lookup utilities for variable/component references.

• Ensuring safe usage of node input queries.

These utilities integrate deeply with the system's graph store (likely Zustand or similar) and context providers, enabling dynamic and consistent flow editing and execution.

Detailed Explanation of Exports

Hook: useSelectBeginNodeDataInputs()

• Purpose:
  Fetches and returns a structured list of input fields from the "Begin" node.

• Implementation Details:

  • Uses useGraphStore to get the node data for the node with id BeginId.

  • Extracts form.inputs from the node's data.

  • Uses buildBeginInputListFromObject utility to format inputs into a list.

• Returns:
  BeginQuery[] — an array representing the input fields of the Begin node.

• Usage Example:

  const beginInputs = useSelectBeginNodeDataInputs();
  console.log(beginInputs);
  

Hook: useIsTaskMode()

• Purpose:
  Determines if the current mode of the "Begin" node's form is set to AgentDialogueMode.Task.

• Implementation Details:

  • Retrieves the "Begin" node from the graph store.

  • Checks node.data.form.mode equality against AgentDialogueMode.Task.

  • Uses useMemo for performance optimization.

• Returns:
  boolean — true if mode is Task, otherwise false.

Hook: useGetBeginNodeDataQuery()

• Purpose:
  Provides a memoized callback function to retrieve the formatted input data query from the "Begin" node.

• Returns:
  A function () => BeginQuery[] that when called returns structured begin input data.

• Usage Example:

  const getBeginQuery = useGetBeginNodeDataQuery();
  const queryData = getBeginQuery();
  

Hook: useGetBeginNodeDataInputs()

• Purpose:
  Returns a memoized list of the "Begin" node's input fields.

• Returns:
  BeginQuery[] — list of input fields.

• Differences from useSelectBeginNodeDataInputs:
  This hook memoizes the inputs for performance, while useSelectBeginNodeDataInputs directly returns the list.

Hook: useGetBeginNodeDataQueryIsSafe()

• Purpose:
  Checks if the "Begin" node's input query is "safe," meaning it does not contain any required (optional === false) inputs of type file.

• Implementation Details:

  • Uses useSelectBeginNodeDataInputs to get inputs.

  • Checks if any input is required and of type 'file'.

  • Updates local state isBeginNodeDataQuerySafe accordingly.

• Returns:
  boolean — true if safe, else false.

• Use Case:
  Useful for validating queries before execution.

Function: filterAllUpstreamNodeIds(edges: Edge[], nodeIds: string[]): string[]

• Purpose:
  Recursively finds and returns all upstream node IDs connected to the given node IDs via edges.

• Parameters:

  • edges: Edge[] - List of graph edges (connections).

  • nodeIds: string[] - Target node IDs to find upstream nodes for.

• Returns:
  string[] - All upstream node IDs (direct and indirect).

• Algorithm:

  • For each node ID, find edges where the node is the target.

  • Collect the source node IDs from those edges.

  • Recursively collect upstream nodes of these source nodes.

  • Accumulate unique IDs in a result list.

• Usage Example:

  const upstreamNodes = filterAllUpstreamNodeIds(edges, [currentNodeId]);
  

Function: buildOutputOptions(outputs: Record<string, any>, nodeId?: string, parentLabel?: ReactNode, icon?: ReactNode)

• Purpose:
  Converts a node's outputs object into an array of option objects suitable for UI selects.

• Parameters:

  • outputs: Object mapping output keys to their metadata.

  • nodeId: ID of the node (used to build value string).

  • parentLabel: Optional label to group under.

  • icon: Optional icon React node for display.

• Returns:
  Array of objects each with:
  { label, value, parentLabel, icon, type }

• Example Output:

  [
    { label: 'output1', value: 'nodeId@output1', parentLabel: 'NodeName', icon: <Icon />, type: 'string' },
    ...
  ]
  

Hook: useBuildNodeOutputOptions(nodeId?: string)

• Purpose:
  Builds an array of grouped output options for all upstream nodes of the given nodeId, excluding the node itself.

• Parameters:

  • nodeId?: string - ID of the node to find upstream outputs.

• Returns:
  Array of grouped options, each group representing a node with its outputs.

• Implementation Highlights:

  • Uses filterAllUpstreamNodeIds to get upstream nodes.

  • Filters nodes that have outputs.

  • Excludes the current node.

  • Builds output options using buildOutputOptions.

  • Includes an icon per node using OperatorIcon.

Constants: ExcludedNodes and StringList

• ExcludedNodes: List of operators/nodes excluded from some filtering logic (e.g., Categorize, Relevant, Begin, Note).

• StringList: List of BeginQueryType values considered as string types (Line, Paragraph, Options).

Function: transferToVariableType(type: string)

• Purpose:
  Converts certain begin query types to a generic variable type.

• Logic:

  • If type is in StringList, returns VariableType.String.

  • Otherwise, returns the original type.

Hook: useBuildBeginVariableOptions()

• Purpose:
  Builds variable options based on the "Begin" node's inputs, formatted for UI selects.

• Returns:
  Options grouped under label flow.beginInput with icons and converted variable types.

Hook: useBuildVariableOptions(nodeId?: string, parentId?: string)

• Purpose:
  Combines variable options from the "Begin" node inputs, upstream node outputs of the current node, and upstream node outputs of the parent node.

• Parameters:

  • nodeId?: string - Current node ID.

  • parentId?: string - Parent node ID.

• Returns:
  Combined array of options suitable for select dropdowns.

Hook: useBuildQueryVariableOptions(n?: RAGFlowNodeType)

• Purpose:
  Builds variable options including global variables fetched from agent DSL globals, combined with local variable options.

• Parameters:

  • n?: RAGFlowNodeType - Optional node from context or passed in.

• Implementation Details:

  • Uses useFetchAgent hook to get DSL globals.

  • Builds local options using useBuildVariableOptions.

  • Adds global options with special handling for array types and files.

  • Returns combined options grouping globals under the same group as begin inputs.

Hook: useBuildComponentIdOptions(nodeId?: string, parentId?: string)

• Purpose:
  Builds options for components (nodes) that can be referenced, excluding certain operator types and filtering nodes by parent relationship.

• Parameters:

  • nodeId?: string - Current node to exclude from list.

  • parentId?: string - Parent node id to limit peer references.

• Returns:
  Options grouped under "Component Output" with labels and values.

• Filtering Logic:

  • Excludes nodes with operators in ExcludedNodes.

  • Limits nodes inside iteration to peers with the same parentId or external nodes.

Hook: useBuildComponentIdAndBeginOptions(nodeId?: string, parentId?: string)

• Purpose:
  Combines component ID options and begin variable options into a single array.

Hook: useGetComponentLabelByValue(nodeId: string)

• Purpose:
  Provides a function to get the label of a component option by its value.

• Returns:
  (val?: string) => ReactNode | undefined — function to get label.

• Implementation Details:

  • Flattens options from useBuildComponentIdAndBeginOptions.

  • Returns matching label or undefined.

Hook: useGetVariableLabelByValue(nodeId: string)

• Purpose:
  Provides a function to get the label of a variable option by its value.

• Returns:
  (val?: string) => ReactNode | undefined — function to get label.

• Implementation Details:

  • Uses useBuildQueryVariableOptions for options.

  • Flattens the options for easy lookup.

Important Implementation Details and Algorithms

• Graph Traversal:
  The function filterAllUpstreamNodeIds recursively determines all upstream nodes for a given node. This is crucial for dependency resolution and building variable outputs that depend on prior nodes.

• Option Building:
  Several hooks and functions build nested option structures for UI selects. These options include labels, values, icons, and types, facilitating user-friendly and context-aware selections.

• Memoization and Callbacks:
  The use of useMemo and useCallback ensures that expensive computations (like filtering nodes or building options) are only recalculated when dependencies change, improving performance in React apps.

• Context and Store Integration:
  The file integrates tightly with external hooks and contexts such as useGraphStore, useFetchAgent, and AgentFormContext to obtain up-to-date data about nodes, edges, and agent configurations.

Interaction with Other Parts of the System

• Graph Store (useGraphStore):
  Central to this file, the graph store provides access to nodes, edges, and node-specific data, allowing the hooks to query flow structure and node data.

• Agent Context and DSL (useFetchAgent, AgentFormContext):
  Fetches agent-level data such as global variables and provides context about the current node in focus.

• Constants and Interfaces:
  Uses constants like BeginId, AgentDialogueMode, and interfaces like BeginQuery to maintain consistent typing and behavior.

• UI Components:
  Utilizes OperatorIcon for rendering icons associated with node operators within option lists.

• Utility Functions:
  Uses buildBeginInputListFromObject for converting raw input objects into usable lists.

Visual Diagram of File Structure and Hook Relationships

flowchart TD
  subgraph GraphStore
    G1[getNode()]
    G2[nodes]
    G3[edges]
  end

  subgraph BeginNodeHooks
    B1[useSelectBeginNodeDataInputs]
    B2[useIsTaskMode]
    B3[useGetBeginNodeDataQuery]
    B4[useGetBeginNodeDataInputs]
    B5[useGetBeginNodeDataQueryIsSafe]
  end

  subgraph OutputOptions
    O1[buildOutputOptions]
    O2[useBuildNodeOutputOptions]
  end

  subgraph VariableOptions
    V1[useBuildBeginVariableOptions]
    V2[useBuildVariableOptions]
    V3[useBuildQueryVariableOptions]
  end

  subgraph ComponentOptions
    C1[useBuildComponentIdOptions]
    C2[useBuildComponentIdAndBeginOptions]
    C3[useGetComponentLabelByValue]
  end

  subgraph LabelLookup
    L1[useGetVariableLabelByValue]
  end

  G1 --> B1
  G1 --> B2
  G1 --> B3
  G1 --> B4
  B1 --> B5
  G2 --> O2
  G3 --> O2
  O1 --> O2
  B1 --> V1
  O2 --> V2
  V1 --> V2
  V2 --> V3
  G2 --> C1
  C1 --> C2
  V1 --> C2
  C2 --> C3
  V3 --> L1

  style B1 fill:#f9f,stroke:#333,stroke-width:1px
  style O2 fill:#bbf,stroke:#333,stroke-width:1px
  style V2 fill:#bfb,stroke:#333,stroke-width:1px
  style C2 fill:#fbf,stroke:#333,stroke-width:1px

Diagram Explanation:

• The GraphStore provides fundamental data (getNode, nodes, edges).

• The BeginNodeHooks extract or compute data related to the "Begin" node.

• OutputOptions build node output selections based on graph data.

• VariableOptions build options for variable selection combining begin inputs and node outputs.

• ComponentOptions handle component-level option building and label lookups.

• LabelLookup hooks provide utility functions to get labels by value.

Summary

This file provides essential hooks and utility functions to manage and manipulate the "Begin" node data within a flow-based agent system. It handles input/output extraction, safety validation, option building for UI selects, and label lookups, leveraging the graph structure and agent context to maintain accurate and efficient state management. The use of memoization and recursion ensures performance and correctness in complex graph scenarios.