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

> Understand Text2Gremlin in HugeGraph AI. Learn how this LLM-powered system transforms natural language questions into Gremlin queries for efficient graph data exploration.

- Repository: [The Apache Software Foundation/incubator-hugegraph-ai](https://github.com/apache/incubator-hugegraph-ai)
- Tags: deep-dive
- Published: 2026-02-24

---

**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`](https://github.com/apache/incubator-hugegraph-ai/blob/main/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`](https://github.com/apache/incubator-hugegraph-ai/blob/main/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`](https://github.com/apache/incubator-hugegraph-ai/blob/main/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`](https://github.com/apache/incubator-hugegraph-ai/blob/main/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:

```python
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:

```python
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:

```python
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`](https://github.com/apache/incubator-hugegraph-ai/blob/main/hugegraph_llm/flows/text2gremlin.py) | Orchestrates the pipeline, defines node dependencies, and normalizes output |
| **Node Implementation** | [`hugegraph_llm/nodes/llm_node/text2gremlin.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/hugegraph_llm/nodes/llm_node/text2gremlin.py) | Initializes LLM configuration and schema serialization |
| **LLM Operator** | [`hugegraph_llm/operators/llm_op/gremlin_generate.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/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`](https://github.com/apache/incubator-hugegraph-ai/blob/main/hugegraph_llm/config/prompt_config.py) | Stores default Gremlin generation prompt templates |
| **Scheduler** | [`hugegraph_llm/scheduler.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/hugegraph_llm/scheduler.py) | Singleton entry point for executing flows programmatically |
| **API Layer** | [`hugegraph_llm/api/rag_api.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/hugegraph_llm/api/rag_api.py) | REST interface exposing `text2gremlin` endpoint |
| **UI Demo** | [`hugegraph_llm/demo/rag_demo/text2gremlin_block.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/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`](https://github.com/apache/incubator-hugegraph-ai/blob/main/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`](https://github.com/apache/incubator-hugegraph-ai/blob/main/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.