use-build-prompt-options.ts

Overview

The use-build-prompt-options.ts file provides a custom React hook, useBuildPromptExtraPromptOptions, designed to generate a set of enriched prompt options for use in an agent-based flow or UI. These prompt options are dynamically constructed by fetching predefined prompt templates, wrapping them with specific tags, and conditionally filtering them based on the presence of sub-agents or tools connected to a given node. This utility enhances the flexibility and contextual relevance of prompts used within a prompt-driven agent framework, specifically within a React application.

Detailed Breakdown

Constants

PromptIdentity: string

• Description: A constant string identifier ('RAGFlow-Prompt') used to label the group of prompt options created by this hook. This identity is used as a label in the options UI to group related prompts under a recognizable heading.

• Usage: Helps in UI display and logical grouping of prompt options.

Functions

wrapPromptWithTag(text: string, tag: string): string

• Purpose: Wraps a given prompt text inside an uppercase XML-like tag.

• Parameters:

  • text (string): The prompt text that needs to be wrapped.

  • tag (string): The tag name to wrap the prompt with.

• Returns: A string where text is enclosed within an uppercase version of the provided tag.

• Example:

  wrapPromptWithTag("Use proper citations.", "citation_guidelines");
  // Returns:
  // <CITATION_GUIDELINES>
  // Use proper citations.
  // </CITATION_GUIDELINES>
  

• Details: This function normalizes the tag to uppercase and formats the prompt text inside opening and closing tags, which likely helps downstream parsing or rendering logic that recognizes these tagged prompt blocks.

Hook

useBuildPromptExtraPromptOptions(edges: Edge[], nodeId?: string): { extraOptions: Array }

• Purpose: A React hook that builds an array of extra prompt options based on the prompts fetched from an external source and the graph structure represented by edges and a specific node ID.

• Parameters:

  • edges (Edge[]): An array representing connections (edges) between nodes in a graph. Each Edge is assumed to represent a link between agents/tools.

  • nodeId? (string | undefined): Optional identifier for a specific node in the graph. Used to check for the presence of sub-agents or tools connected to this node.

• Returns:

  • An object containing:

    • extraOptions: An array of option groups. Each group has:

      • label: A string label for the group (here it is the value of PromptIdentity).

      • title: A localized string fetched from i18n translation under the key 'flow.frameworkPrompts'.

      • options: An array of individual prompt options, each having:

        • label: The prompt name/key.

        • value: The prompt text wrapped inside an uppercase tag (via wrapPromptWithTag).

• Implementation Details:

  • Uses the custom hook useFetchPrompt to asynchronously fetch all available prompts.

  • Uses useTranslation from react-i18next for localization of UI strings.

  • Uses a utility function hasSubAgentOrTool to determine if the current node is connected to any sub-agents or tools.

  • Prompts are filtered based on hasSubAgentOrTool result:

    • If no sub-agent or tool is present, only the prompt labeled 'citation_guidelines' is included.

    • Otherwise, all prompts are included.

  • Uses useMemo to memoize the computed options for performance optimization, recalculating only if has or prompts changes.

• Usage Example:

  import { useBuildPromptExtraPromptOptions } from './use-build-prompt-options';
  import { Edge } from '@xyflow/react';
  
  function ExampleComponent({ edges, nodeId }: { edges: Edge[], nodeId: string }) {
    const { extraOptions } = useBuildPromptExtraPromptOptions(edges, nodeId);
  
    return (
      <div>
        {extraOptions.map(group => (
          <fieldset key={group.label}>
            <legend>{group.title}</legend>
            <ul>
              {group.options.map(option => (
                <li key={option.label}>
                  <strong>{option.label}</strong>: {option.value}
                </li>
              ))}
            </ul>
          </fieldset>
        ))}
      </div>
    );
  }
  

Important Implementation Details

• Prompt Wrapping: Wrapping prompts in uppercase tags makes it easier for downstream consumers (e.g., parsers or rendering engines) to identify and handle prompt blocks distinctly.

• Conditional Filtering: The presence or absence of sub-agents/tools (determined by hasSubAgentOrTool) directly influences which prompt options are available, enabling context-sensitive prompt customization.

• Performance Optimization: Use of useMemo ensures that the prompt options are only recalculated when necessary, avoiding unnecessary re-renders or computations.

Interaction With Other Parts of the System

• useFetchPrompt Hook: This hook fetches the base prompt templates from a remote or local source, making useBuildPromptExtraPromptOptions dependent on the prompt data provided by useFetchPrompt.

• hasSubAgentOrTool Utility: This utility examines the graph edges and node to determine if additional sub-agents or tools exist, affecting prompt filtering.

• react-i18next: Provides translation/localization for UI labels, ensuring internationalization support.

• Graph Structure (Edge[]): The hook relies on the structure of the agent/tool graph, using edges and nodes to dynamically adjust prompt options, making it tightly coupled with the graph model of the system.

• UI Components: The resulting extraOptions object is intended for consumption by UI components that render prompt selection dropdowns or lists within an agent flow interface.

Visual Diagram

flowchart TD
    A[useBuildPromptExtraPromptOptions] --> B[useFetchPrompt]
    A --> C[useTranslation (i18n)]
    A --> D[hasSubAgentOrTool]
    A --> E[wrapPromptWithTag]

    subgraph "Output"
        F[extraOptions: Array]
    end

    B -->|prompts data| A
    C -->|t() function| A
    D -->|has boolean| A
    E -->|wrap text with tag| A
    A --> F

Summary

The use-build-prompt-options.ts file encapsulates a specialized React hook that builds a categorized list of prompt options by fetching prompt templates, wrapping them with tags, and filtering based on graph connectivity. It serves as a key piece in a prompt-driven agent system, enabling dynamic and context-aware prompt customization that integrates tightly with the agent graph and localization infrastructure. This hook is intended for UI components that require flexible and enriched prompt options in complex agent workflows.