What is Text2Gremlin in HugeGraph AI and How Does It Work?

Text2Gremlin is a pipeline-based system in HugeGraph AI that converts natural language questions into executable Gremlin graph queries using a large language model (LLM), schema context, and example-based retrieval.

Text2Gremlin serves as the core natural language interface for Apache HugeGraph, enabling users to query graph databases without writing complex Gremlin syntax. The implementation follows a modular, node-based architecture defined in the apache/incubator-hugegraph-ai repository, allowing developers to customize LLM providers, prompts, and execution strategies.

How Text2Gremlin Works: The Pipeline Architecture

The Text2Gremlin system operates as an orchestrated flow that chains specialized nodes together to transform user input into a structured graph query.

Flow Orchestration with Text2GremlinFlow

The Text2GremlinFlow class in hugegraph_llm/flows/text2gremlin.py constructs a GPipeline that manages the entire transformation process. This flow handles input validation, node registration, and post-processing of results.

The flow prepares five primary input parameters:

• query: The natural language question
• example_num: Number of similar examples to retrieve
• schema: The graph schema definition
• gremlin_prompt: Optional custom prompt template
• requested_outputs: Specific result fields to return

The Four Core Nodes

The pipeline wires together four specialized nodes in hugegraph_llm/flows/text2gremlin.py:

1. SchemaNode – Loads and serializes the graph schema into a deterministic string representation using _stable_schema_string.

2. GremlinExampleIndexQueryNode – Retrieves the most relevant example queries from the vector index based on semantic similarity to the user's question.

3. Text2GremlinNode – The central processing unit that invokes the LLM to synthesize the Gremlin query based on schema context and examples.

4. GremlinExecuteNode – Optionally executes the generated Gremlin query against the HugeGraph database and returns the raw results.

After execution, the post_deal method normalizes the output into five fixed keys: match_result, template_gremlin, raw_gremlin, template_execution_result, and raw_execution_result.

Deep Dive: From Natural Language to Gremlin Query

Node Initialization and LLM Configuration

The Text2GremlinNode in hugegraph_llm/nodes/llm_node/text2gremlin.py initializes the synthesis process by:

• Selecting the LLM via get_text2gql_llm(), which supports multiple providers (OpenAI, local models, etc.)
• Serializing the graph schema deterministically to ensure consistent prompt context
• Loading the prompt template from prompt_cfg.gremlin_generate_prompt or using a user-provided custom prompt
• Instantiating the GremlinGenerateSynthesize operator with the configured LLM, schema, optional vertex list, and prompt template

Prompt Engineering in GremlinGenerateSynthesize

The GremlinGenerateSynthesize operator in hugegraph_llm/operators/llm_op/gremlin_generate.py constructs two distinct prompts to improve query accuracy:

Raw Prompt – A minimal example (e.g., "who is peter") that generates a baseline Gremlin query without additional context.

Initialized Prompt – An enriched prompt containing:

• The retrieved example matches from the vector index
• The full graph schema definition
• Optional vertex list for entity disambiguation
• The user's natural language query

The operator calls the LLM synchronously (as currently implemented) to generate both the raw and template-enhanced Gremlin queries.

Result Extraction and Normalization

After LLM generation, the operator extracts the Gremlin code block using the gremlin markdown syntax (```gremlin). It stores the results in the pipeline context as:

• result: The template-enhanced Gremlin query
• raw_result: The plain Gremlin query without context enrichment
• call_count: Incremented for observability and rate limiting

The post_deal method in the flow ensures the final output always contains the five standardized keys, making the API predictable for frontend applications.

Implementing Text2Gremlin: Code Examples

Using the Scheduler API

The SchedulerSingleton provides the primary programmatic interface for executing Text2Gremlin flows:

from hugegraph_llm.scheduler import SchedulerSingleton, FlowName

# Convert natural language to Gremlin

response = SchedulerSingleton.get_instance().schedule_flow(
    FlowName.TEXT2GREMLIN,
    inp="Find all friends of Alice born after 1990",
    example_num=3,
    schema_input="graph schema JSON or string",
    gremlin_prompt_input=None,  # use default prompt

    requested_outputs=["template_gremlin", "raw_gremlin"]
)

print(response["template_gremlin"])
print(response["raw_gremlin"])

REST API Integration

For service-oriented architectures, the RAG API exposes Text2Gremlin as a REST endpoint:

from hugegraph_llm.api.rag_api import text2gremlin

result = text2gremlin(
    query="Show vertices with label Person and age > 30",
    example_num=2,
    schema="...",  # graph schema definition

    gremlin_prompt=None,  # optional custom prompt

    requested_outputs=["template_gremlin"]
)

print(result["template_gremlin"])

Building a Gradio UI

The demo application includes a Gradio interface in hugegraph_llm/demo/rag_demo/text2gremlin_block.py. The core callback function wires user inputs to the scheduler:

def gremlin_generate_for_ui(
    inp: str,
    example_num: int,
    schema_input: str,
    gremlin_prompt_input: str,
) -> tuple:
    return SchedulerSingleton.get_instance().schedule_flow(
        FlowName.TEXT2GREMLIN,
        inp,
        example_num,
        schema_input,
        gremlin_prompt_input,
        None,
    )

Key Files and Components

Understanding the source structure helps with customization and debugging:

Component	File Path	Purpose
Flow Definition	hugegraph_llm/flows/text2gremlin.py	Orchestrates the pipeline, defines node dependencies, and normalizes output
Node Implementation	hugegraph_llm/nodes/llm_node/text2gremlin.py	Initializes LLM configuration and schema serialization
LLM Operator	hugegraph_llm/operators/llm_op/gremlin_generate.py	Builds dual prompts (raw and initialized), calls LLM, extracts Gremlin code
Prompt Configuration	hugegraph_llm/config/prompt_config.py	Stores default Gremlin generation prompt templates
Scheduler	hugegraph_llm/scheduler.py	Singleton entry point for executing flows programmatically
API Layer	hugegraph_llm/api/rag_api.py	REST interface exposing text2gremlin endpoint
UI Demo	hugegraph_llm/demo/rag_demo/text2gremlin_block.py	Gradio-based web interface for interactive query generation

Summary

Text2Gremlin in HugeGraph AI provides a robust, modular architecture for converting natural language into executable Gremlin graph queries:

• Pipeline Architecture: Uses Text2GremlinFlow to orchestrate four specialized nodes—schema loading, example retrieval, LLM synthesis, and query execution—defined in hugegraph_llm/flows/text2gremlin.py.
• Dual Prompt Strategy: The GremlinGenerateSynthesize operator generates both a raw baseline query and a context-enriched template query using schema definitions and retrieved examples.
• Standardized Output: The system guarantees five consistent response keys (template_gremlin, raw_gremlin, match_result, template_execution_result, raw_execution_result) for reliable frontend integration.
• Flexible Integration: Supports programmatic access via SchedulerSingleton, REST API endpoints, and interactive Gradio UIs.

Frequently Asked Questions

How does Text2Gremlin handle schema changes in the graph database?

Text2Gremlin dynamically loads the current graph schema via SchemaNode before each query generation. The _stable_schema_string method in hugegraph_llm/nodes/llm_node/text2gremlin.py serializes the schema deterministically, ensuring the LLM always receives up-to-date vertex labels, edge labels, and property keys without requiring manual prompt updates.

Can I use a custom LLM provider with Text2Gremlin?

Yes. The Text2GremlinNode uses get_text2gql_llm() to initialize the language model, which supports multiple providers including OpenAI, Azure OpenAI, and local models. You can configure the desired provider through the HugeGraph AI configuration system, and the operator will automatically use the specified LLM endpoint for both raw and initialized prompt generation.

What is the difference between template_gremlin and raw_gremlin outputs?

The raw_gremlin field contains the query generated from a minimal prompt without schema context or examples, serving as a baseline. The template_gremlin field contains the query generated from the enriched prompt that includes the graph schema, retrieved example queries, and optional vertex lists. The template version typically produces more accurate queries for complex graph structures, while the raw version demonstrates the LLM's baseline Gremlin knowledge.

How does Text2Gremlin retrieve relevant example queries?

The GremlinExampleIndexQueryNode performs a vector similarity search against a pre-built index of example queries. When a user submits a natural language question, the node embeds the query text and retrieves the top example_num matches (defaulting to the configuration value) from the vector store. These retrieved examples are then injected into the initialized prompt in GremlinGenerateSynthesize, providing the LLM with contextual patterns of how similar questions map to Gremlin syntax.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}