Text2Gremlin Data Generation and Model Fine-Tuning System (Vertical Scenarios and General Scenarios)

[LRriver]

LLM-based Gremlin QA Synthesis and Generalization in Vertical Scenarios.

🏗️ Project Structure

Vertical_Text2Gremlin/
├── README.md
├── __pycache__/
├── data/
├── db_data/
├── graph2gremlin.py
├── gremlin_checker.py
├── gremlin_qa_dataset.csv
├── instruct_convert.py
├── llm_handler.py
└── qa_generalize.py

• ./graph2gremlin.py: Initially generates Gremlin data based on templates and graph data, ensuring correctness through templates, and translates and preliminarily generalizes the Gremlin data and questions.
• ./gremlin_checker.py: Performs syntax checking using Antlr4.
• ./llm_handler.py: An LLM interaction model that inputs QA data for each batch of seed numbers (during seed data generation, queries undergo a small batch generalization), allowing the LLM to understand how to write text2gremlin, first generalizing Gremlin, then translating and generalizing the query.
• ./qa_generalize.py: Calls gremlin_checker and llm_handler for seed data generalization.
• ./instruct_convert.py: Handles instruction format conversion and the division of training and test sets.
• ./db_data: Contains schema and graph data.
• ./data/seed_data: Seed data (to be uploaded).
• ./data/vertical_training_sets: Vertical scenario generalization data (to be uploaded).

Gremlin Corpus Generation System Based on Recursive Backtracking in General Scenarios.

📋 Project Overview
This PR adds a complete Text-to-Gremlin corpus generation system based on a recursive backtracking recipe-guided generation approach, capable of automatically generating large-scale and diverse training data from Gremlin query templates.

🏗️ Project Structure

├── generate_corpus.py                   # 主程序
├── gremlin_templates.csv                # 模板文件
├── config.json                          # 配置
├── base/
│   ├── generator.py                     # 解析泛化控制器
│   ├── Config.py                        # 配置管理模块
│   ├── Schema.py                        # Schema和数据管理
│   ├── GremlinParse.py                  # 数据结构定义
│   ├── GremlinExpr.py                   # 复杂表达式定义(谓词、匿名遍历等)
│   ├── GremlinTransVisitor.py           # AST解析
│   ├── TraversalGenerator.py            # 遍历生成器
│   ├── combination_control_config.json  # 组合控制配置
│   ├── GremlinBase.py                   # 翻译引擎
│   ├── gremlin/                         # ANTLR生成的解析器
│   └── template/                        # 翻译字典
│       ├── schema_dict.txt              # Schema术语翻译
│       └── syn_dict.txt                 # 同义词字典
├── db_data/                             # 数据和 Schema
└── output/                              # 输出目录

🎯 Core Features

1. Recipe-Guided Generation

   • Parse Gremlin queries into Recipes using ANTLR
   • Perform intelligent parameter generalization based on Schema
   • Generate large numbers of valid variants through recursive backtracking

2. Large-Scale Data Processing

   • Support batch loading of query templates from CSV files
   • Process 3514 real cypher2gremlin dataset entries
   • Global deduplication to ensure corpus quality

3. Complete Error Handling

   • Support complex query types (g.call(), .with(), etc.)
   • Individual failures don't affect overall processing
   • Detailed statistics and error reporting

4. Intelligent Constraint Mechanism

   • Schema connectivity validation
   • Syntax validity checking
   • Combinatorial explosion control (320k → 7k valid combinations)

📊 System Capabilities

• Query type support: V/E traversals, graph algorithm calls, complex filtering, etc.
• Generation scale: Single complex template can generate 6000+ valid variants
• Processing efficiency: Batch processing of 3514 templates with robust error handling
• Output quality: JSON format with query-description pairs and detailed metadata

🧪 Technical Features

• Recursive backtracking algorithm: Systematically explore parameter combination space
• Recipe abstraction: Structure queries into generalizable Recipes
• Constraint optimization: 97%+ invalid combinations intelligently filtered
• Modular design: Core components can be used and tested independently

📈 Application Value

• Text-to-Gremlin training: Provide large-scale training data for NLP models
• Query diversity: Generate rich query variants from limited templates
• Data quality: Ensure syntactic correctness and semantic reasonableness of generated queries
• Extensibility: Support extension of new schemas and query types

🔧 Usage

# Basic usage
from generator import generate_corpus_from_templates

templates = ["g.V().hasLabel('person')", "g.V().out('knows')"]
result = generate_corpus_from_templates(templates)
print(f"Generated {result['total_unique_queries']} unique queries")

📋 Documentation

• README.md: Quick start guide

Summary by CodeRabbit

版本说明

• 新功能

  • 添加 Gremlin 查询语料库生成系统，支持从模板生成多样化查询并去重
  • 新增查询语法校验工具
  • 提供命令行工具与可通过包调用的 Python 接口
  • 支持基于配置的生成策略（组合控制、随机增强、填充值策略）

• 文档

  • 添加完整中文使用说明、快速上手和模板/配置示例，包含常见问题与示例脚本

[coderabbitai]

Note

Other AI code review bot(s) detected

CodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review.

Walkthrough

该提交在 text2gremlin/AST_Text2Gremlin 下新增完整的 Gremlin 语料库生成子系统：配置、模式与数据文件、ANTLR 词法/语法产物、解析器与访问器、表达式/遍历数据结构、生成与控制引擎、命令行入口及中文文档与词典（无现有 API 修改）。

Changes

内聚组 / 文件(s)	变更摘要
文档与根配置 text2gremlin/AST_Text2Gremlin/README.md, text2gremlin/AST_Text2Gremlin/config.json, text2gremlin/AST_Text2Gremlin/requirements.txt	新增中文 README、主配置与依赖清单
包初始化与许可 text2gremlin/AST_Text2Gremlin/base/__init__.py, text2gremlin/AST_Text2Gremlin/base/gremlin/__init__.py, .licenserc.yaml	新增包导出、许可头与 license-eye 忽略规则
配置与控制 text2gremlin/AST_Text2Gremlin/base/Config.py, text2gremlin/AST_Text2Gremlin/base/CombinationController.py, text2gremlin/AST_Text2Gremlin/combination_control_config.json	新增 Config 类与 CombinationController；添加组合控制配置 JSON
模式与数据 text2gremlin/AST_Text2Gremlin/base/Schema.py, text2gremlin/AST_Text2Gremlin/db_data/schema/movie_schema.json, .../base/template/schema_dict.txt, .../base/template/syn_dict.txt	新增 Schema 管理、电影领域 schema 和中英词典/同义词文件
表达式与解析数据结构 text2gremlin/AST_Text2Gremlin/base/GremlinExpr.py, text2gremlin/AST_Text2Gremlin/base/GremlinParse.py	新增 Predicate/TextPredicate/AnonymousTraversal/Connector/Terminal、Step 与 Traversal 类型
Gremlin 基础与模板翻译 text2gremlin/AST_Text2Gremlin/base/GremlinBase.py	新增 GremlinBase：规则名加载、模板翻译与 schema 词典支持
ANTLR 访问器与解析器 text2gremlin/AST_Text2Gremlin/base/gremlin/Gremlin.tokens, .../GremlinLexer.tokens, .../GremlinVisitor.py, text2gremlin/AST_Text2Gremlin/base/GremlinTransVisitor.py	新增 ANTLR 词法/语法产物与完整 GremlinTransVisitor，提供 parse_gremlin_query 接口
遍历生成器与主生成逻辑 text2gremlin/AST_Text2Gremlin/base/TraversalGenerator.py, text2gremlin/AST_Text2Gremlin/base/generator.py	新增 TraversalGenerator（递归生成、随机增强等）与 generator.py（语法校验、按模板生成语料并去重）
CLI 脚本 text2gremlin/AST_Text2Gremlin/generate_corpus.py	新增命令行入口，加载配置并调用生成流程

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant CLI as generate_corpus.py
    participant Config
    participant Schema
    participant Gen as generator.py
    participant Parser as GremlinTransVisitor
    participant TG as TraversalGenerator
    participant GB as GremlinBase

    User->>CLI: 运行 CLI（模板/配置/输出）
    CLI->>Config: 加载 config.json
    CLI->>Schema: 初始化 schema 与数据目录
    CLI->>Gen: 调用 generate_gremlin_corpus(...)
    Gen->>GB: 初始化 GremlinBase（加载模板/词典）
    loop 每个模板
        Gen->>Parser: parse_gremlin_query(template)
        Parser-->>Gen: Traversal 对象
        Gen->>TG: 创建 TraversalGenerator(schema, recipe, gremlin_base)
        TG->>Schema: 请求有效步骤与样本数据
        Schema-->>TG: 步骤选项与示例值
        TG->>TG: 递归生成查询变体（应用 CombinationController 策略）
        TG-->>Gen: 查询-描述 列表
        Gen->>Gen: 逐条 check_gremlin_syntax 和去重
    end
    Gen-->>CLI: 写入输出 JSON（可选）
    CLI-->>User: 返回统计与文件位置

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 分钟

需要特别关注：

• GremlinTransVisitor.py（大量 visit 方法与解析规则映射）
• TraversalGenerator.py（递归生成、随机增强、去重逻辑与终止条件）
• CombinationController.py（配置验证与策略选择实现）
• Schema.py（CSV 解析、懒加载与数据返回的一致性）
• generator.py（错误处理、语法检测与全局去重）
• GremlinBase.py（模板格式化、schema 词典加载与占位符替换）

Suggested labels

llm

Poem

🐰 新枝叶下种子翻，
模板化链路悄然安，
中文词典与规则藏，
生成语料逐步漫，
一欢一跳，查询起航 ✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 7.61% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title Check	✅ Passed	该标题直接涉及changeset的主要内容，明确指出了"Text2Gremlin Data Generation"系统及其"Model Fine-Tuning"功能，并明确区分了"Vertical Scenarios and General Scenarios"两个子系统。从raw_summary可以看出，PR的主要变化包括两套系统的完整实现（Vertical_Text2Gremlin和AST_Text2Gremlin），其中AST_Text2Gremlin是关于Gremlin查询生成的基础设施，而Vertical_Text2Gremlin涉及LLM辅助的QA生成和模型微调。标题准确地反映了这个双系统架构和核心功能意图。虽然标题相对宽泛，涵盖了多个方面，但这反映了PR本身的复杂性和两个互补系统的特性。
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

@codecov-ai-reviewer review

[coderabbitai]

Actionable comments posted: 28

♻️ Duplicate comments (1)

text2gremlin/AST_Text2Gremlin/base/test/test_csv_queries.py (1)

30-41: 代码重复：与 test_recipe_extraction_failures.py 中的 SyntaxErrorListener 相同

此类与 test_recipe_extraction_failures.py (lines 24-35) 中的定义完全相同。如前面评论所述，建议提取到共享测试工具模块 test_utils.py 中。

参见对 test_recipe_extraction_failures.py lines 24-35 的评论。

🧹 Nitpick comments (29)

text2gremlin/AST_Text2Gremlin/config.json (1)

5-5: 澄清空值的用途或移除无用配置。

"common" 字段的值为空字符串。如果此字段未使用，建议移除以避免混淆；如果它有特定用途（如作为默认值或占位符），请在文档中说明其语义。

text2gremlin/AST_Text2Gremlin/base/test/test_generator.py (2)

24-28: 建议添加输出文件清理机制

测试运行后会产生 test_generator_output.json 文件，但没有清理逻辑。建议在测试完成后清理临时文件，或者使用临时目录。

+import os
+import tempfile
+
 def test_generator():
     """测试生成器的完整流程"""
     print("🧪 开始测试generator.py...")
     
+    # 使用临时文件
+    temp_file = tempfile.NamedTemporaryFile(mode='w', suffix='.json', delete=False)
+    output_file = temp_file.name
+    temp_file.close()
+    
     # 测试模板（模拟从CSV加载的数据）
     test_templates = [
         ...
     ]
     
     print(f"使用 {len(test_templates)} 个测试模板...")
     
     try:
         result = generate_corpus_from_templates(
             test_templates, 
-            output_file='test_generator_output.json'
+            output_file=output_file
         )
         
         print(f"\n✅ 生成成功!")
         ...
         
         return True
         
     except Exception as e:
         print(f"❌ 生成失败: {str(e)}")
         return False
+    finally:
+        # 清理临时文件
+        if os.path.exists(output_file):
+            os.remove(output_file)

---

39-41: 异常处理过于宽泛

捕获所有异常（except Exception）会掩盖潜在的编程错误。建议捕获更具体的异常类型，或至少记录完整的堆栈信息以便调试。

+    import traceback
+    
     try:
         result = generate_corpus_from_templates(
             test_templates, 
             output_file='test_generator_output.json'
         )
         ...
         
     except Exception as e:
-        print(f"❌ 生成失败: {str(e)}")
+        print(f"❌ 生成失败: {str(e)}")
+        traceback.print_exc()  # 打印完整堆栈跟踪
         return False

text2gremlin/AST_Text2Gremlin/base/test/analyze_line73_explosion.py (2)

147-147: 硬编码的分析数量限制

将分析限制为前 100 个查询是一个魔术数字，应该作为可配置参数。

-    for query_gen, desc in corpus[:100]:  # 只分析前100个
+    # 在函数参数中添加
+    def analyze_actual_generation(query: str, schema: Schema, config: Config, 
+                                  gremlin_base: GremlinBase, sample_size: int = 100):
+        ...
+        for query_gen, desc in corpus[:sample_size]:  # 只分析前N个

---

131-139: 缺少生成过程的错误处理

TraversalGenerator.generate() 可能会失败或返回空结果，但没有错误处理。

     visitor = GremlinTransVisitor()
     recipe = visitor.parse_and_visit(query)
     
+    if not recipe:
+        print("❌ Recipe解析失败")
+        return
+    
     generator = TraversalGenerator(schema, recipe, gremlin_base)
-    corpus = generator.generate()
+    try:
+        corpus = generator.generate()
+    except Exception as e:
+        print(f"❌ 生成失败: {e}")
+        return
     
+    if not corpus:
+        print("⚠️  未生成任何查询")
+        return
+    
     print(f"实际生成数量: {len(corpus):,}")

text2gremlin/AST_Text2Gremlin/base/Config.py (2)

38-47: 考虑简化输出路径逻辑

get_output_path 中的条件逻辑可以更清晰。当前实现在判断目录后拼接路径，可以提取为辅助方法提高可读性。

可选重构建议：

 def get_output_path(self):
     if self.gen_query:
         dir_or_file = self.config_data.get("output_query_dir_or_file")
-        if os.path.isdir(dir_or_file):
-            output_path = os.path.join(dir_or_file, self.db_id + ".txt")
-            return output_path
-        else:
-            return dir_or_file
+        return self._resolve_output_path(dir_or_file, self.db_id)
     else:
         return self.config_data.get("output_prompt_path")
+
+def _resolve_output_path(self, dir_or_file: str, db_id: str) -> str:
+    """解析输出路径：如果是目录则拼接 db_id，否则直接返回"""
+    if os.path.isdir(dir_or_file):
+        return os.path.join(dir_or_file, f"{db_id}.txt")
+    return dir_or_file

---

22-24: 建议指定文件编码

打开文件时未指定编码，在某些环境下可能导致编码问题。

建议显式指定 UTF-8 编码（已在上面的异常处理建议中包含）：

-    with open(self.file_path, "r") as file:
+    with open(self.file_path, "r", encoding="utf-8") as file:

text2gremlin/AST_Text2Gremlin/base/test/test_recipe_extraction_failures.py (2)

148-148: 硬编码的 CSV 文件路径降低了测试灵活性

CSV 文件路径被硬编码在 main() 函数中，不便于在不同环境或数据集上运行测试。

建议通过命令行参数或环境变量使路径可配置：

 def main():
     """主函数"""
     print("=== Recipe Extraction 失败分析脚本 ===")
     print(f"开始时间: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
     
-    # 配置文件路径
-    csv_file_path = "gremlin_query_errors_20250928_030206.csv"
+    # 从命令行参数或环境变量获取 CSV 文件路径
+    import argparse
+    parser = argparse.ArgumentParser(description='分析 Recipe extraction 失败的查询')
+    parser.add_argument('--csv', default='gremlin_query_errors_20250928_030206.csv',
+                       help='CSV 文件路径（默认：gremlin_query_errors_20250928_030206.csv）')
+    args = parser.parse_args()
+    csv_file_path = args.csv

---

110-140: analyze_query_structure 函数的分析逻辑过于简化

当前的查询结构分析仅使用字符串搜索来检测步骤类型（如 'g.call' in query），这可能产生误报（例如，字符串字面量或注释中包含这些模式）。

可选改进：虽然对于快速诊断工具来说当前实现已足够，但如果需要更准确的分析，可以考虑使用正则表达式或实际的 AST 解析来检测步骤类型。例如：

import re

def analyze_query_structure(query: str):
    """分析查询的结构，帮助理解为什么提取失败"""
    print(f"\n=== 查询结构分析 ===")
    print(f"查询长度: {len(query)}")
    
    # 使用正则表达式更精确地匹配 Gremlin 步骤
    steps = []
    if re.search(r'\bg\.call\s*\(', query):
        steps.append('call')
    if re.search(r'\bg\.V\s*\(', query):
        steps.append('V')
    if re.search(r'\bg\.E\s*\(', query):
        steps.append('E')
    if re.search(r'\bg\.inject\s*\(', query):
        steps.append('inject')
    
    print(f"检测到的起始步骤: {steps}")
    # ... 其余逻辑

text2gremlin/AST_Text2Gremlin/base/test/test_csv_queries.py (2)

178-186: 多个硬编码路径降低了测试可移植性

测试脚本中硬编码了多个路径（CSV 文件、config.json、schema 文件等），这使得测试难以在不同环境或项目结构下运行。

建议通过命令行参数或配置文件使路径可配置：

 def main():
     """主函数"""
     print("=== Gremlin查询测试脚本 ===")
     print(f"开始时间: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
     
-    # 配置文件路径
-    csv_file_path = "cypher2gremlin_dataset_thread.csv"
+    # 解析命令行参数
+    import argparse
+    parser = argparse.ArgumentParser(description='测试 CSV 中的 Gremlin 查询')
+    parser.add_argument('--csv', default='cypher2gremlin_dataset_thread.csv',
+                       help='CSV 文件路径')
+    parser.add_argument('--config', help='配置文件路径（默认：自动检测）')
+    parser.add_argument('--schema', help='Schema 文件路径（默认：自动检测）')
+    args = parser.parse_args()
     
+    csv_file_path = args.csv
+    
     # 获取项目根目录路径
     current_dir = os.path.dirname(os.path.abspath(__file__))
     base_root = os.path.dirname(current_dir)  
     project_root = os.path.dirname(base_root)
-    config_path = os.path.join(project_root, 'config.json')
-    schema_path = os.path.join(project_root, 'db_data', 'schema', 'movie_schema.json')
-    data_path = os.path.join(project_root, 'db_data')
+    config_path = args.config or os.path.join(project_root, 'config.json')
+    schema_path = args.schema or os.path.join(project_root, 'db_data', 'schema', 'movie_schema.json')
+    data_path = os.path.join(project_root, 'db_data')

---

43-77: 考虑复用 check_gremlin_syntax 函数

check_gremlin_syntax 函数的实现很清晰且可复用。考虑将其也提取到共享的 test_utils.py 模块中，因为语法检查在多个测试场景中都很有用。

可以将此函数与 SyntaxErrorListener 一起移到 test_utils.py 中：

# text2gremlin/AST_Text2Gremlin/base/test/test_utils.py

def check_gremlin_syntax(query_string: str) -> tuple[bool, str]:
    """
    检查给定的Gremlin查询语句的语法。
    
    Args:
        query_string: The Gremlin query to check.
        
    Returns:
        A tuple containing:
        - bool: True if syntax is correct, False otherwise.
        - str: An error message if syntax is incorrect, or "Syntax OK" if correct.
    """
    # ... 当前实现

然后在测试文件中导入使用。

text2gremlin/AST_Text2Gremlin/base/GremlinExpr.py (3)

11-13: 改进前向声明以避免循环导入

当前第13行的字符串字面量 'Step' 不是有效的前向声明。建议使用 typing.TYPE_CHECKING 和条件导入来正确处理循环依赖。

应用此差异：

 from typing import Any, List
 
-# 由于 AnonymousTraversal 包含 Step 对象,而 Step 将在 GremlinParse 中定义,
-# 而 GremlinParse 又导入了本文件,因此使用前向声明避免循环导入问题。
-'Step'
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .GremlinParse import Step

然后将第61行的类型注解更新为正常引用：

-    self.steps: List['Step'] = []
+    self.steps: List[Step] = []

---

15-49: 考虑合并 Predicate 和 TextPredicate 类以减少重复

Predicate 和 TextPredicate 类的实现几乎完全相同，仅在 __repr__ 中的前缀不同（P. vs TextP.）。建议使用单一类并通过参数控制前缀，或使用继承来减少代码重复。

可选方案1：使用单一类和前缀参数

class Predicate:
    def __init__(self, operator: str, value: Any, prefix: str = "P"):
        self.operator = operator
        self.value = value
        self.prefix = prefix
    
    def __repr__(self) -> str:
        return f"{self.prefix}.{self.operator}({repr(self.value)})"

# 使用时
text_pred = Predicate("startingWith", "mark", prefix="TextP")

可选方案2：使用继承

class Predicate:
    prefix = "P"
    
    def __init__(self, operator: str, value: Any):
        self.operator = operator
        self.value = value
    
    def __repr__(self) -> str:
        return f"{self.prefix}.{self.operator}({repr(self.value)})"

class TextPredicate(Predicate):
    prefix = "TextP"

---

67-69: 增强 AnonymousTraversal 的 repr 健壮性

当 self.steps 为空时，__repr__ 会返回 "__." 这可能不是期望的行为。建议添加空列表检查。

 def __repr__(self) -> str:
+    if not self.steps:
+        return "__"
     step_reprs = ".".join(map(repr, self.steps))
     return f"__.{step_reprs}"

text2gremlin/AST_Text2Gremlin/base/Schema.py (2)

61-86: 改进 CSV 解析的错误处理和日志记录

当前 _parse_custom_csv 方法捕获 FileNotFoundError 和 IndexError，但可能还有其他异常（如编码错误、CSV格式错误）会导致静默失败。建议：

1. 捕获更广泛的异常类型
2. 使用 logging 模块而非 print
3. 考虑在严重错误时抛出异常而非返回空 DataFrame

+import logging
+
 def _parse_custom_csv(self, file_path: str, header_line_index: int) -> pd.DataFrame:
     """解析自定义多行表头的 CSV 文件。"""
     try:
         with open(file_path, 'r', encoding='utf-8') as f:
             lines = f.readlines()
         
+        if header_line_index > len(lines):
+            logging.warning(f"header_line_index {header_line_index} 超出文件行数: {file_path}")
+            return pd.DataFrame()
+        
         # 从第二行解析列名
         header_line = lines[header_line_index - 1]
         column_defs = header_line.strip().split(',')
         column_names = [d.split(':')[0] for d in column_defs]
 
         # 从指定header行之后开始读取数据
         data_lines = lines[header_line_index:]
         
         if not data_lines:
             return pd.DataFrame(columns=column_names)
 
         # 使用pandas从内存中的字符串列表读取数据
         from io import StringIO
         csv_data = StringIO("".join(data_lines))
         df = pd.read_csv(csv_data, header=None, names=column_names)
         return df
 
-    except (FileNotFoundError, IndexError) as e:
-        print(f"警告: 读取或解析文件失败: {file_path}, 错误: {e}")
+    except (FileNotFoundError, IndexError, UnicodeDecodeError, pd.errors.ParserError) as e:
+        logging.warning(f"读取或解析文件失败: {file_path}, 错误: {e}")
         return pd.DataFrame()

---

152-184: 控制随机种子以提高可测试性

get_instances 方法使用 random.randint 和 df.sample，但没有提供控制随机种子的机制。这使得测试和调试变得困难。建议添加可选的 random_state 参数。

-def get_instances(self, label: str, count: int = None) -> List[Dict]:
+def get_instances(self, label: str, count: int = None, random_state: int = None) -> List[Dict]:
     """获取多个实例
     
     Args:
         label: 标签名
         count: 要获取的实例数量，如果为None则随机选择2-5个
+        random_state: 随机种子，用于可重现的结果
         
     Returns:
         实例列表
     """
     import random
     
     is_edge = label in self.edges
     data_cache = self.edge_data if is_edge else self.vertex_data
     load_func = self._load_edge_data if is_edge else self._load_vertex_data
     
     if label not in data_cache: 
         load_func(label)
     
     df = data_cache.get(label)
     if df is None or df.empty:
         return []
     
     # 如果没有指定数量，随机选择2-5个
     if count is None:
+        if random_state is not None:
+            random.seed(random_state)
         count = random.randint(2, 5)
     
     # 如果实际数据量小于要求的数量，就全部取出
     actual_count = min(count, len(df))
     
     # 随机采样
-    sampled_df = df.sample(actual_count)
+    sampled_df = df.sample(actual_count, random_state=random_state)
     return sampled_df.to_dict('records')

text2gremlin/AST_Text2Gremlin/base/GremlinBase.py (3)

131-156: 增强 get_token_desc 的参数验证和错误处理

当前方法的异常处理（第153行）捕获 IndexError 和 KeyError，但没有记录导致错误的具体参数信息，这使得调试变得困难。此外，应验证 token_key 的类型。

+import logging
+
 def get_token_desc(self, token_key: str, *args) -> str:
     """
     根据 token 和参数获取一个随机的、格式化后的中文描述。
     """
+    if not isinstance(token_key, str):
+        logging.warning(f"token_key 应为字符串类型，实际为: {type(token_key)}")
+        return ""
+    
     key = token_key.upper()
     if key in self.token_dict:
         index = self.token_dict[key]
         # 随机选择一个模板
         selected_template = random.choice(self.template[index])
         try:
             # 翻译参数中的schema术语
             translated_args = []
             for arg in args:
                 if isinstance(arg, str):
                     # 尝试翻译schema术语
                     translated_arg = self.get_schema_desc(arg)
                     translated_args.append(translated_arg)
                 else:
                     translated_args.append(arg)
             
             # 使用翻译后的参数格式化模板
             return selected_template.format(*translated_args)
-        except (IndexError, KeyError):
+        except (IndexError, KeyError) as e:
+            logging.debug(f"模板格式化失败 - token: {token_key}, 模板: {selected_template}, 参数: {args}, 错误: {e}")
             # 如果参数数量不匹配，返回原始模板
             return selected_template
     return "" # 如果 token 不存在，返回空字符串

---

85-129: 考虑将翻译模板外部化以提高可维护性

当前翻译模板硬编码在 _initialize_translation_templates 方法中。随着支持的 Gremlin 步骤增加，这个方法会变得冗长。建议将模板移至外部 JSON 或 YAML 文件中。

创建 template/translation_templates.json:

{
  "v": ["查询图中的所有顶点", "获取所有节点"],
  "e": ["查询图中的所有边", "获取所有关系"],
  "out": ["从当前位置出发，沿着 '{}' 方向的出边前进", "找到 '{}' 类型的邻居"]
}

然后修改方法：

def _initialize_translation_templates(self):
    """初始化 Gremlin 步骤的翻译模板。"""
    template_file = os.path.join(
        os.path.dirname(__file__), 
        'template', 
        'translation_templates.json'
    )
    
    if os.path.exists(template_file):
        with open(template_file, 'r', encoding='utf-8') as f:
            templates_data = json.load(f)
    else:
        # 回退到硬编码模板
        templates_data = { ... }
    
    for index, (key, value) in enumerate(templates_data.items()):
        self.token_dict[key.upper()] = index
        self.template.append(value)

---

55-56: 细化异常处理以避免隐藏配置错误

第55行捕获所有异常并仅打印信息日志。如果配置方法存在但抛出了严重错误（如权限问题、配置损坏），这种处理方式可能会隐藏问题。

     try:
         if hasattr(self.config, 'get_schema_dict_path'):
             schema_dict_paths = self.config.get_schema_dict_path()
             if isinstance(schema_dict_paths, list):
                 file_paths.extend(schema_dict_paths)
             elif isinstance(schema_dict_paths, str):
                 file_paths.append(schema_dict_paths)
         
         if hasattr(self.config, 'get_syn_dict_path'):
             syn_dict_path = self.config.get_syn_dict_path()
             if syn_dict_path:
                 file_paths.append(syn_dict_path)
                 
-    except Exception as e:
-        print(f"[INFO] Config paths not available: {e}")
+    except AttributeError as e:
+        print(f"[INFO] Config methods not available: {e}")
+    except Exception as e:
+        print(f"[WARNING] Unexpected error loading config paths: {e}")
+        raise

text2gremlin/AST_Text2Gremlin/base/GremlinTransVisitor.py (3)

25-53: 改进错误处理粒度

parse_and_visit 方法捕获了所有异常并返回 None，这使得调用方难以区分不同类型的错误（例如语法错误 vs 系统错误）。

考虑细化错误处理：

 def parse_and_visit(self, query_string: str):
     try:
         self.traversal = Traversal()
         
         input_stream = InputStream(query_string)
         lexer = GremlinLexer(input_stream)
         stream = CommonTokenStream(lexer)
         parser = GremlinParser(stream)
-        # 【修正】使用queryList作为入口规则，它包含一个或多个query
         tree = parser.queryList()
         
-        # Visit the parse tree - 访问第一个query
         result = self.visit(tree.query(0))
         
         return result if result else self.traversal
         
+    except RecognitionException as e:
+        print(f"Syntax error parsing query '{query_string}': {e}")
+        return None
+    except AttributeError as e:
+        print(f"Query structure error '{query_string}': {e}")
+        return None
     except Exception as e:
         print(f"Error parsing query '{query_string}': {e}")
         return None

---

111-155: 考虑提取重复的参数处理逻辑

多个 has 方法变体（lines 111-155）使用了相似的参数提取模式。

考虑提取公共辅助方法：

def _extract_has_params(self, ctx):
    """提取 has 方法的通用参数"""
    params = []
    if hasattr(ctx, 'stringNullableLiteral') and ctx.stringNullableLiteral():
        params.append(self.visit(ctx.stringNullableLiteral()))
    if hasattr(ctx, 'stringNullableArgument') and ctx.stringNullableArgument():
        params.append(self.visit(ctx.stringNullableArgument()))
    if hasattr(ctx, 'genericArgument') and ctx.genericArgument():
        params.append(self.visit(ctx.genericArgument()))
    if hasattr(ctx, 'traversalPredicate') and ctx.traversalPredicate():
        params.append(self.visit(ctx.traversalPredicate()))
    if hasattr(ctx, 'nestedTraversal') and ctx.nestedTraversal():
        params.append(self.visit(ctx.nestedTraversal()))
    if hasattr(ctx, 'traversalT') and ctx.traversalT():
        params.append(self.visit(ctx.traversalT()))
    return params

---

971-1390: 建议将测试代码移至专用测试文件

__main__ 块中包含了 400+ 行的综合测试代码（lines 971-1390）。虽然测试覆盖很全面，但这些代码应该移至专门的测试文件中（如 test_gremlin_trans_visitor.py），以保持主模块的简洁性。

创建新文件 text2gremlin/AST_Text2Gremlin/base/test/test_gremlin_trans_visitor_comprehensive.py 并将测试代码移至其中：

# test/test_gremlin_trans_visitor_comprehensive.py
import unittest
from GremlinTransVisitor import GremlinTransVisitor, parse_gremlin_query
from GremlinParse import Traversal
from GremlinExpr import Predicate, TextPredicate, AnonymousTraversal

class TestGremlinTransVisitorComprehensive(unittest.TestCase):
    def setUp(self):
        self.visitor = GremlinTransVisitor()
    
    def test_spawn_methods(self):
        # 将现有的测试类别转换为单元测试
        ...

if __name__ == '__main__':
    unittest.main()

在主模块中保留简单的演示示例即可。

text2gremlin/AST_Text2Gremlin/base/generator.py (3)

165-168: 考虑将警告阈值配置化

硬编码的警告阈值（5000 条生成查询，0 条新查询）可能需要根据不同场景调整。

将阈值移至配置文件或函数参数：

 def generate_corpus_from_template(
     template_string: str,
     config: Config,
     schema: Schema,
     gremlin_base: GremlinBase,
-    global_corpus_dict: dict
+    global_corpus_dict: dict,
+    large_generation_threshold: int = 5000
 ) -> tuple[int, dict]:
     ...
-    if stats['generated_count'] > 5000:
+    if stats['generated_count'] > large_generation_threshold:
         stats['warning'] = f'由于本条模版的Recip复杂,生成了大量查询({stats["generated_count"]}条)'

---

494-498: 增强 Gremlin 查询格式验证

当前仅检查查询是否以 g. 开头（line 495），这可能不足以捕获所有格式错误。

考虑使用 check_gremlin_syntax 进行预验证：

                     # 基本语法检查
                     if not gremlin_query.startswith('g.'):
                         stats['failed_loads'] += 1
                         stats['failed_queries'].append(f"第{row_num}行: 格式错误")
                         continue
+                    
+                    # 可选：进行完整语法检查（可能影响加载性能）
+                    # is_valid, error_msg = check_gremlin_syntax(gremlin_query)
+                    # if not is_valid:
+                    #     stats['failed_loads'] += 1
+                    #     stats['failed_queries'].append(f"第{row_num}行: {error_msg}")
+                    #     continue
                     
                     templates.append(gremlin_query)

---

518-518: 将 CSV 文件路径配置化

CSV 文件路径硬编码为 "cypher2gremlin_dataset.csv"（line 518）。

建议通过命令行参数或配置文件指定：

+import argparse

 if __name__ == '__main__':
+    parser = argparse.ArgumentParser(description='Generate Gremlin corpus from templates')
+    parser.add_argument('--csv', default='cypher2gremlin_dataset.csv', 
+                       help='Path to CSV file containing templates')
+    parser.add_argument('--output', default='generated_corpus.json',
+                       help='Output file path')
+    args = parser.parse_args()
+    
-    csv_file_path = "cypher2gremlin_dataset.csv"
+    csv_file_path = args.csv
     
     print(f"🔄 从 {csv_file_path} 加载Gremlin查询模板...")
     templates, load_stats = load_templates_from_csv(csv_file_path)
     ...
-        result = generate_corpus_from_templates(templates)
+        result = generate_corpus_from_templates(templates, output_file=args.output)

text2gremlin/AST_Text2Gremlin/base/TraversalGenerator.py (2)

43-77: 考虑将随机值生成参数配置化

随机值生成使用了硬编码的参数：

• 字符串长度：5-8 个字符（lines 51, 71）
• 整数范围：1-10000（lines 53, 73）
• 值数量：2-5 个（line 59）

考虑通过配置文件或类参数使这些值可配置：

class TraversalGenerator:
    def __init__(self, schema: Schema, recipe: Traversal, gremlin_base: GremlinBase,
                 string_length_range: Tuple[int, int] = (5, 8),
                 int_value_range: Tuple[int, int] = (1, 10000),
                 instance_count_range: Tuple[int, int] = (2, 5)):
        self.schema = schema
        self.recipe = recipe
        self.gremlin_base = gremlin_base
        self.generated_pairs: Set[Tuple[str, str]] = set()
        self.string_length_range = string_length_range
        self.int_value_range = int_value_range
        self.instance_count_range = instance_count_range

---

319-373: 增强概率和参数应配置化

增强方法中硬编码了多个概率值和参数范围：

• limit 概率: 40%（line 324）
• range 概率: 20%（line 335）
• sample 概率: 30%（line 347）
• dedup 概率: 30%（line 357）
• order 概率: 20%（line 363）
• 各种数值范围（lines 327-341）

考虑创建配置类来管理这些参数：

@dataclass
class EnhancementConfig:
    """增强配置参数"""
    limit_probability: float = 0.4
    range_probability: float = 0.2
    sample_probability: float = 0.3
    dedup_probability: float = 0.3
    order_probability: float = 0.2
    
    limit_common_values: List[int] = field(default_factory=lambda: [1, 3, 5, 10, 20, 50, 100])
    limit_max_random: int = 200
    
    # ... 其他参数

class TraversalGenerator:
    def __init__(self, schema: Schema, recipe: Traversal, gremlin_base: GremlinBase,
                 enhancement_config: EnhancementConfig = None):
        ...
        self.enhancement_config = enhancement_config or EnhancementConfig()

text2gremlin/AST_Text2Gremlin/base/gremlin/GremlinVisitor.py (2)

1-1: 自动生成文件中暴露了绝对路径。

第 1 行的注释包含开发者的本地绝对路径 /root/lzj/ospp/Gremlin_Antlr4/Gremlin.g4。虽然这是 ANTLR 生成代码的标准输出，但建议在文档中说明生成步骤，以便其他贡献者可以重新生成此文件而不会混淆路径。

---

10-10: 考虑为访问器模式添加文档说明。

GremlinVisitor 是 ANTLR 生成的基础访问器类，作为 GremlinTransVisitor（在 PR 的其他文件中）的父类。对于不熟悉 ANTLR 访问器模式的维护者，建议在模块或 README 中添加简短说明：

• 访问器模式的作用（遍历语法树）
• 如何扩展此类（重写特定的 visitXxx 方法）
• 与 GremlinTransVisitor 的关系
• 示例：如何使用访问器解析 Gremlin 查询

需要我生成一个文档模板或使用示例吗？

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 9e76c2a and b14ffb3.

⛔ Files ignored due to path filters (19)

• text2gremlin/AST_Text2Gremlin/base/cypher2gremlin_dataset.csv is excluded by !**/*.csv
• text2gremlin/AST_Text2Gremlin/base/gremlin/antlr-4.13.1-complete.jar is excluded by !**/*.jar
• text2gremlin/AST_Text2Gremlin/base/test/cypher2gremlin_dataset_thread.csv is excluded by !**/*.csv
• text2gremlin/AST_Text2Gremlin/base/test/gremlin_query_errors_20250928_014705_pre.csv is excluded by !**/*.csv
• text2gremlin/AST_Text2Gremlin/base/test/gremlin_query_errors_20250928_030206.csv is excluded by !**/*.csv
• text2gremlin/AST_Text2Gremlin/base/test/recipe_extraction_detailed_failures_20250928_031211.csv is excluded by !**/*.csv
• text2gremlin/AST_Text2Gremlin/db_data/movie/raw_data/edge_acted_in.csv is excluded by !**/*.csv
• text2gremlin/AST_Text2Gremlin/db_data/movie/raw_data/edge_directed.csv is excluded by !**/*.csv
• text2gremlin/AST_Text2Gremlin/db_data/movie/raw_data/edge_has_genre.csv is excluded by !**/*.csv
• text2gremlin/AST_Text2Gremlin/db_data/movie/raw_data/edge_has_keyword.csv is excluded by !**/*.csv
• text2gremlin/AST_Text2Gremlin/db_data/movie/raw_data/edge_is_friend.csv is excluded by !**/*.csv
• text2gremlin/AST_Text2Gremlin/db_data/movie/raw_data/edge_produce.csv is excluded by !**/*.csv
• text2gremlin/AST_Text2Gremlin/db_data/movie/raw_data/edge_rate.csv is excluded by !**/*.csv
• text2gremlin/AST_Text2Gremlin/db_data/movie/raw_data/edge_write.csv is excluded by !**/*.csv
• text2gremlin/AST_Text2Gremlin/db_data/movie/raw_data/vertex_genre.csv is excluded by !**/*.csv
• text2gremlin/AST_Text2Gremlin/db_data/movie/raw_data/vertex_keyword.csv is excluded by !**/*.csv
• text2gremlin/AST_Text2Gremlin/db_data/movie/raw_data/vertex_movie.csv is excluded by !**/*.csv
• text2gremlin/AST_Text2Gremlin/db_data/movie/raw_data/vertex_person.csv is excluded by !**/*.csv
• text2gremlin/AST_Text2Gremlin/db_data/movie/raw_data/vertex_user.csv is excluded by !**/*.csv

📒 Files selected for processing (21)

• text2gremlin/AST_Text2Gremlin/README.md (1 hunks)
• text2gremlin/AST_Text2Gremlin/base/Config.py (1 hunks)
• text2gremlin/AST_Text2Gremlin/base/GremlinBase.py (1 hunks)
• text2gremlin/AST_Text2Gremlin/base/GremlinExpr.py (1 hunks)
• text2gremlin/AST_Text2Gremlin/base/GremlinParse.py (1 hunks)
• text2gremlin/AST_Text2Gremlin/base/GremlinTransVisitor.py (1 hunks)
• text2gremlin/AST_Text2Gremlin/base/Schema.py (1 hunks)
• text2gremlin/AST_Text2Gremlin/base/TraversalGenerator.py (1 hunks)
• text2gremlin/AST_Text2Gremlin/base/generator.py (1 hunks)
• text2gremlin/AST_Text2Gremlin/base/gremlin/Gremlin.tokens (1 hunks)
• text2gremlin/AST_Text2Gremlin/base/gremlin/GremlinLexer.tokens (1 hunks)
• text2gremlin/AST_Text2Gremlin/base/gremlin/GremlinVisitor.py (1 hunks)
• text2gremlin/AST_Text2Gremlin/base/template/schema_dict.txt (1 hunks)
• text2gremlin/AST_Text2Gremlin/base/template/syn_dict.txt (1 hunks)
• text2gremlin/AST_Text2Gremlin/base/test/analyze_line73_explosion.py (1 hunks)
• text2gremlin/AST_Text2Gremlin/base/test/combination_explosion_report.md (1 hunks)
• text2gremlin/AST_Text2Gremlin/base/test/test_csv_queries.py (1 hunks)
• text2gremlin/AST_Text2Gremlin/base/test/test_generator.py (1 hunks)
• text2gremlin/AST_Text2Gremlin/base/test/test_recipe_extraction_failures.py (1 hunks)
• text2gremlin/AST_Text2Gremlin/config.json (1 hunks)
• text2gremlin/AST_Text2Gremlin/db_data/schema/movie_schema.json (1 hunks)

🧰 Additional context used

🧠 Learnings (1)

📓 Common learnings

Learnt from: CR
PR: hugegraph/hugegraph-ai#0
File: hugegraph-llm/AGENTS.md:0-0
Timestamp: 2025-09-16T06:40:44.968Z
Learning: Applies to hugegraph-llm/src/hugegraph_llm/operators/gremlin_generate_task.py : Maintain the Text2Gremlin pipeline in src/hugegraph_llm/operators/gremlin_generate_task.py

🧬 Code graph analysis (8)

text2gremlin/AST_Text2Gremlin/base/GremlinParse.py (1)

text2gremlin/AST_Text2Gremlin/base/GremlinExpr.py (4)

• Predicate (15-30)
• AnonymousTraversal (51-69)
• TextPredicate (33-48)
• Connector (72-88)

text2gremlin/AST_Text2Gremlin/base/test/test_recipe_extraction_failures.py (4)

text2gremlin/AST_Text2Gremlin/base/GremlinTransVisitor.py (1)

• GremlinTransVisitor (21-955)

text2gremlin/AST_Text2Gremlin/base/GremlinParse.py (1)

• Traversal (42-70)

text2gremlin/AST_Text2Gremlin/base/test/test_csv_queries.py (2)

• SyntaxErrorListener (30-41)
• main (172-254)

text2gremlin/AST_Text2Gremlin/base/test/analyze_line73_explosion.py (1)

• main (185-227)

text2gremlin/AST_Text2Gremlin/base/test/test_generator.py (1)

text2gremlin/AST_Text2Gremlin/base/generator.py (1)

• generate_corpus_from_templates (179-324)

text2gremlin/AST_Text2Gremlin/base/generator.py (5)

text2gremlin/AST_Text2Gremlin/base/Schema.py (1)

• Schema (17-184)

text2gremlin/AST_Text2Gremlin/base/GremlinBase.py (1)

• GremlinBase (12-187)

text2gremlin/AST_Text2Gremlin/base/GremlinParse.py (1)

• Traversal (42-70)

text2gremlin/AST_Text2Gremlin/base/TraversalGenerator.py (1)

• TraversalGenerator (19-417)

text2gremlin/AST_Text2Gremlin/base/GremlinTransVisitor.py (2)

• GremlinTransVisitor (21-955)
• parse_and_visit (25-53)

text2gremlin/AST_Text2Gremlin/base/GremlinTransVisitor.py (4)

text2gremlin/AST_Text2Gremlin/base/gremlin/GremlinParser.py (2)

• GremlinParser (1481-32734)
• queryList (2356-2400)

text2gremlin/AST_Text2Gremlin/base/gremlin/GremlinVisitor.py (1)

• GremlinVisitor (10-2084)

text2gremlin/AST_Text2Gremlin/base/GremlinParse.py (2)

• Traversal (42-70)
• Step (13-40)

text2gremlin/AST_Text2Gremlin/base/GremlinExpr.py (5)

• Predicate (15-30)
• TextPredicate (33-48)
• AnonymousTraversal (51-69)
• Connector (72-88)
• Terminal (91-104)

text2gremlin/AST_Text2Gremlin/base/test/analyze_line73_explosion.py (4)

text2gremlin/AST_Text2Gremlin/base/GremlinTransVisitor.py (2)

• GremlinTransVisitor (21-955)
• parse_and_visit (25-53)

text2gremlin/AST_Text2Gremlin/base/TraversalGenerator.py (1)

• TraversalGenerator (19-417)

text2gremlin/AST_Text2Gremlin/base/Schema.py (3)

• Schema (17-184)
• get_vertex_labels (99-100)
• get_edge_labels (102-103)

text2gremlin/AST_Text2Gremlin/base/GremlinBase.py (1)

• GremlinBase (12-187)

text2gremlin/AST_Text2Gremlin/base/test/test_csv_queries.py (4)

text2gremlin/AST_Text2Gremlin/base/Schema.py (1)

• Schema (17-184)

text2gremlin/AST_Text2Gremlin/base/TraversalGenerator.py (1)

• TraversalGenerator (19-417)

text2gremlin/AST_Text2Gremlin/base/GremlinTransVisitor.py (2)

• GremlinTransVisitor (21-955)
• parse_and_visit (25-53)

text2gremlin/AST_Text2Gremlin/base/test/test_recipe_extraction_failures.py (2)

• SyntaxErrorListener (24-35)
• syntaxError (32-35)

text2gremlin/AST_Text2Gremlin/base/TraversalGenerator.py (4)

text2gremlin/AST_Text2Gremlin/base/Schema.py (9)

• Schema (17-184)
• get_instance (147-150)
• get_instances (152-184)
• get_vertex_creation_info (131-135)
• get_properties_with_type (105-107)
• get_valid_steps (109-122)
• get_step_result_label (124-129)
• get_vertex_labels (99-100)
• get_updatable_properties (141-145)

text2gremlin/AST_Text2Gremlin/base/GremlinParse.py (2)

• Traversal (42-70)
• Step (13-40)

text2gremlin/AST_Text2Gremlin/base/GremlinExpr.py (1)

• Predicate (15-30)

text2gremlin/AST_Text2Gremlin/base/GremlinBase.py (2)

• GremlinBase (12-187)
• get_schema_desc (179-187)

🪛 markdownlint-cli2 (0.18.1)

text2gremlin/AST_Text2Gremlin/base/test/combination_explosion_report.md

49-49: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

68-68: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

text2gremlin/AST_Text2Gremlin/README.md

49-49: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

68-68: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: build (3.11)
• GitHub Check: build (3.10)

🔇 Additional comments (18)

text2gremlin/AST_Text2Gremlin/base/GremlinParse.py (1)

13-70: 数据结构设计合理。

Step 和 Traversal 类的设计简洁清晰，文档完善。类型注解准确，__repr__ 方法实现良好，便于调试。这两个类为后续的 Gremlin 查询解析和生成奠定了良好的基础。

text2gremlin/AST_Text2Gremlin/db_data/schema/movie_schema.json (2)

1-316: Schema 定义结构良好。

整体 schema 定义清晰完整，涵盖了电影领域的主要实体和关系。类型定义准确，主键、可选字段和索引标记使用恰当。CSV 文件映射详细，包含了必要的 SRC_ID 和 DST_ID 信息。这为数据加载和查询生成提供了坚实的基础。

---

236-241: 未在 Schema.py 中发现对 “SKIP” 列的处理逻辑，请手动确认 CSV 加载器是否支持该跳过列的语法，或在文档中说明此自定义约定。

text2gremlin/AST_Text2Gremlin/base/test/combination_explosion_report.md (1)

1-129: 文档内容质量很高

这份分析报告非常详细和专业，清晰地解释了组合爆炸的原因、约束机制以及优化建议。文档结构良好，数学计算准确，对理解系统行为很有帮助。

text2gremlin/AST_Text2Gremlin/base/gremlin/GremlinLexer.tokens (1)

1-533: 自动生成的词法分析器令牌文件

这是一个由 ANTLR 自动生成的令牌定义文件，包含 270 个令牌定义，涵盖 Gremlin 查询语言的所有关键字、操作符和字面量。文件格式符合 ANTLR 标准，无需手动修改。

注意事项：

• 此文件应由 ANTLR 工具重新生成，而不是手动编辑
• 确保与对应的 .g4 语法文件保持同步
• 建议在 .gitattributes 中标记为自动生成文件

text2gremlin/AST_Text2Gremlin/base/test/test_recipe_extraction_failures.py (1)

63-108: 测试函数的错误处理逻辑清晰完善

test_recipe_extraction 函数很好地处理了多种失败场景（语法错误、空 recipe、无步骤等），并提供了详细的错误信息。异常捕获和堆栈跟踪也有助于调试。

text2gremlin/AST_Text2Gremlin/base/test/test_csv_queries.py (2)

79-127: 测试编排逻辑设计良好

test_single_query 函数很好地编排了完整的测试流程：语法检查 → Recipe 提取 → 泛化生成 → 生成查询的语法验证。错误处理全面，返回值清晰，有助于调试。

---

244-252: 错误统计逻辑为调试提供了有价值的洞察

按错误类型分组统计的逻辑有助于快速识别最常见的失败模式，对于改进生成系统非常有用。

text2gremlin/AST_Text2Gremlin/base/GremlinBase.py (1)

12-28: 代码逻辑正确，初始化流程清晰

__init__ 方法正确地按顺序初始化了配置、规则名、翻译模板和字典。加载顺序合理，确保了依赖关系的正确处理。

text2gremlin/AST_Text2Gremlin/base/Schema.py (1)

68-70: 验证列定义解析的健壮性并修正检查脚本

第70行 d.split(':')[0] 假定每个定义都包含冒号，建议改为只分割第一个冒号并做防御性检查：

column_names = [d.split(':', 1)[0] if ':' in d else d for d in column_defs]

同时，原示例脚本因 -x sh -c 不支持 if ! 语法而失败，建议改为使用 bash 并以兼容写法验证 CSV：

#!/usr/bin/env bash
fd -e csv -x bash -c '
  echo "检查文件: {}"
  head -n 2 {} | tail -n 1 | tr "," "\n" | while IFS= read -r col; do
    if echo "$col" | grep -q ":"; then
      :
    else
      echo "  警告: 列定义缺少冒号: $col"
    fi
  done
'

请使用上述脚本验证所有 CSV 文件，确保列定义格式一致。

text2gremlin/AST_Text2Gremlin/base/GremlinTransVisitor.py (3)

88-165: LGTM - Spawn 和导航方法实现正确

Spawn 方法（V, E, addV, addE, inject, io, call）和导航方法（out, in, both, outE, inE, bothE, outV, inV, bothV）的实现逻辑正确，正确处理了各种参数变体。

---

280-302: LGTM - 嵌套遍历的状态管理实现正确

visitNestedTraversal 方法正确地保存和恢复了遍历状态，避免了状态污染。这种临时遍历的方式是处理匿名遍历的标准做法。

---

8-19: 确认相对导入路径正确

所有 gremlin.* 和本地模块的文件均存在于 text2gremlin/AST_Text2Gremlin/base 目录下，可正常解析，无需调整。

text2gremlin/AST_Text2Gremlin/base/generator.py (1)

26-73: LGTM - 语法检查实现正确

SyntaxErrorListener 和 check_gremlin_syntax 的实现正确捕获了 ANTLR 解析错误，为后续的语法验证提供了可靠的基础。

text2gremlin/AST_Text2Gremlin/base/TraversalGenerator.py (2)

19-41: LGTM - 生成器初始化和入口方法设计合理

使用 Set[Tuple[str, str]] 进行去重是正确的选择，generate 方法作为公共 API 入口点设计清晰。

---

154-188: LGTM - 导航步骤的泛化逻辑实现优秀

导航步骤（out/in/both）的处理逻辑正确实现了配方泛化：

1. 优先使用配方中指定的边标签（lines 159-168）
2. 同时生成其他可能的边变体（lines 170-178）
3. 正确更新结果标签和类型

这种设计很好地平衡了忠实度和多样性。

text2gremlin/AST_Text2Gremlin/base/gremlin/Gremlin.tokens (1)

1-532: ANTLR生成的tokens文件 - 避免手动修改

此文件定义了Gremlin词法分析器使用的完整token集合（267个关键字token + 标点符号token + 字面量token）。这类文件通常由ANTLR从语法文件(.g4)自动生成，包含token的数值映射和字符串表示。

注意事项：

• 如果此文件是自动生成的，应避免手动修改，所有更改应通过修改源语法文件并重新生成来完成
• 确保与GremlinLexer.tokens和语法定义保持同步
• Token数值的连续性和唯一性对解析器正确运行至关重要

text2gremlin/AST_Text2Gremlin/base/gremlin/GremlinVisitor.py (1)

2088-2088: 命名空间清理处理得当。

使用 del GremlinParser 清理模块命名空间是良好实践，确保此模块只公开 GremlinVisitor 类，符合 ANTLR 生成代码的标准模式。

[coderabbitai]

🛠️ Refactor suggestion | 🟠 Major

清理或文档化注释掉的模板列表

60 行注释掉的模板列表（lines 394-452）占用了大量空间。

选项 1：如果这些模板仍然有用，将它们移至独立的示例文件：

# examples/sample_templates.py
SAMPLE_TEMPLATES = [
    # 查询操作
    "g.V().has('name', 'John')",
    ...
]

选项 2：如果不再需要，直接删除这些注释。

🤖 Prompt for AI Agents

In text2gremlin/AST_Text2Gremlin/base/generator.py around lines 393 to 452 there
is a large block of 60 commented-out template strings that clutter the file;
either extract them into a separate example file (e.g.,
examples/sample_templates.py as a SAMPLE_TEMPLATES list and import or reference
it) or remove them entirely if unused; implement the extraction by creating the
new module containing the templates and replacing the commented block with a
short comment and an import/use note, or simply delete the commented templates
if they are obsolete.

[coderabbitai]

🛠️ Refactor suggestion | 🟠 Major

🧩 Analysis chain

确认自动生成代码的版本控制策略。

此文件由 ANTLR 自动生成，包含约 270 个访问器方法的样板代码。通常，自动生成的代码有两种处理方式：

1. 不提交到版本控制：在 .gitignore 中排除，由构建脚本从语法文件重新生成
2. 提交到版本控制：便于审查和调试，但需要文档说明重新生成步骤

请确认项目的策略。如果选择提交生成的代码，建议在 README 或构建文档中添加：

• 语法文件位置（Gremlin.g4）
• ANTLR 版本（4.13.1）
• 重新生成命令

---

🏁 Script executed:

#!/bin/bash
# 检查是否存在 .gitignore 规则或文档说明生成代码的处理方式

# 搜索 .gitignore 中是否排除了生成的文件
if [ -f .gitignore ]; then
  echo "=== .gitignore 中与 ANTLR 生成文件相关的规则 ==="
  rg -n "GremlinVisitor|GremlinParser|\.g4" .gitignore || echo "未找到相关规则"
fi

echo ""
echo "=== 搜索文档中关于 ANTLR 代码生成的说明 ==="
rg -n -i "antlr|生成|generate.*gremlin" README.md text2gremlin/AST_Text2Gremlin/README.md 2>/dev/null || echo "未找到相关文档"

echo ""
echo "=== 检查是否存在构建脚本 ==="
fd -t f "build|generate|setup" -e sh -e py -e yml -e yaml | head -10

Length of output: 3237

---

补充 ANTLR 生成文件的文档说明。 在 text2gremlin/AST_Text2Gremlin/README.md 中明确 Gremlin.g4 语法文件路径、使用的 ANTLR 版本（如 4.13.1）及重新生成 GremlinVisitor.py 的命令示例；或根据项目策略将生成文件移出版本控制并在构建脚本中添加自动生成步骤。

🤖 Prompt for AI Agents

In text2gremlin/AST_Text2Gremlin/base/gremlin/GremlinVisitor.py (lines 8-2085)
the reviewer asks for documentation about this ANTLR-generated file; update
text2gremlin/AST_Text2Gremlin/README.md to state the path to the Gremlin.g4
grammar, the ANTLR version used (e.g. 4.13.1), and include an exact command
example to regenerate GremlinVisitor.py (including Java/ANTLR jar invocation or
the maven/gradle task as appropriate); alternatively, if project policy prefers
generated files excluded from VCS, move GremlinVisitor.py out of version control
and add an automated regeneration step to the build scripts (show the build step
and where it runs) so developers can recreate the file reproducibly.

[coderabbitai]

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

统一路径格式以提高一致性。

"movie" 的路径使用了 ../db_data/schema/movie_schema.json（向上一级目录），而其他路径使用 ./db_data/schema/（当前目录）。这种不一致可能表明目录结构存在问题或配置错误。请验证正确的相对路径，并确保所有 schema 路径使用统一的基准目录。

运行以下脚本验证所有 schema 文件是否存在：

---

🏁 Script executed:

#!/bin/bash
# 验证 config.json 中的 schema 路径
cd text2gremlin/AST_Text2Gremlin
for schema in "yago" "movie" "the_three_body" "finbench" "SNB" "three_kingdoms"; do
  path=$(jq -r ".db_schema_path.${schema}" config.json)
  if [ "$path" != "" ] && [ "$path" != "null" ]; then
    if [ -f "$path" ]; then
      echo "✓ $schema: $path"
    else
      echo "✗ $schema: $path (文件不存在)"
    fi
  fi
done

Length of output: 327

---

🏁 Script executed:

#!/bin/bash
# 定位项目中所有 db_data 目录和 schema 文件
find . -type d | sed -e 's|^\./||' | grep db_data || echo "No db_data directories found"
find . -type f | sed -e 's|^\./||' | grep '/db_data/' || echo "No db_data files found"

Length of output: 1159

---

统一并修正 schema 路径及文件

• 将所有 db_schema_path 统一改为相对于 config.json 的 "./db_data/schema/<name>_schema.json"，去除 ../ 前缀
• 为每个引用的 schema 添加或重命名对应的 JSON 文件（目前只有 movie_schema.json 存在，其他均缺失）

🤖 Prompt for AI Agents

In text2gremlin/AST_Text2Gremlin/config.json around line 7, the schema path for
"movie" and other schema entries use a ../ prefix and some referenced schema
files are missing; update all db_schema_path entries to use paths relative to
config.json like "./db_data/schema/<name>_schema.json" (remove "../"), and
ensure every referenced schema has a corresponding JSON file in
text2gremlin/AST_Text2Gremlin/db_data/schema named <name>_schema.json (create or
rename files as needed so all references resolve).

[coderabbitai]

⚠️ Potential issue | 🟠 Major

避免使用绝对路径以提高可移植性。

"wandering_earth" 使用了绝对路径 /root/work_repo/db_data/schema/wandering_earth.json，这会导致配置在不同环境或用户间无法移植。建议改用相对路径，与其他 schema 路径保持一致。

应用此修改（假设文件结构一致）：

-        "wandering_earth": "/root/work_repo/db_data/schema/wandering_earth.json"
+        "wandering_earth": "./db_data/schema/wandering_earth.json"

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	"wandering_earth": "/root/work_repo/db_data/schema/wandering_earth.json"
	"wandering_earth": "./db_data/schema/wandering_earth.json"

🤖 Prompt for AI Agents

In text2gremlin/AST_Text2Gremlin/config.json around line 12, the
"wandering_earth" entry uses an absolute path
(/root/work_repo/db_data/schema/wandering_earth.json) which breaks portability;
change it to a relative path consistent with other schema entries (e.g.,
../db_data/schema/wandering_earth.json or ./schema/wandering_earth.json
depending on repo layout), update any related docs or scripts if they assume the
old absolute path, and run a quick config-load test to ensure the relative path
resolves correctly in CI and local environments.

[coderabbitai]

Actionable comments posted: 20

🧹 Nitpick comments (30)

text2gremlin/Vertical_Text2Gremlin/data/book/book_process.py (3)

81-82: 检查父节点存在性是良好实践

在添加子节点前检查 current_chapter 存在性可防止在文件以 ## 开头时出错。相同的检查应该应用到 level 3。

可以为 level 3 添加相同的检查以保持一致性：

             if current_section_lvl2:
                 current_section_lvl2["children"].append(current_section_lvl3)
+            elif current_chapter:
+                current_chapter["children"].append(current_section_lvl3)

---

117-205: 移除已注释的大段代码

这个 88 行的注释代码块增加了维护负担。如果需要保留作为参考，应将其移至文档或版本历史中。

-# def parse_markdown_with_hierarchical_levels(
-#     file_path: str, 
-#     output_path: str = "gremlin_book_hierarchical.json"
-# ) -> None:
-#     try:
-#         with open(file_path, 'r', encoding='utf-8') as f:
-#             lines = f.readlines()
-... [删除全部注释代码]
-#     except Exception as e:
-#         print(f"写入JSON文件时发生错误: {e}")
-

---

206-209: 主函数硬编码了文件路径

主函数使用硬编码路径，降低了可重用性。建议使用命令行参数或配置文件。

考虑使用 argparse 提高灵活性：

if __name__ == "__main__":
    import argparse
    parser = argparse.ArgumentParser(description='解析Markdown为层级JSON')
    parser.add_argument('--input', default='./data/book/Gremlin-Graph-Guide.md', help='输入Markdown文件路径')
    parser.add_argument('--output', default='./data/book/gremlin_book.json', help='输出JSON文件路径')
    args = parser.parse_args()
    parse_markdown_with_hierarchical_levels(args.input, args.output)

text2gremlin/Vertical_Text2Gremlin/data/book/chunk_analysis.py (1)

26-50: 可以优化区间统计逻辑以减少重复

当前使用多个 if-elif 分支进行区间统计，代码较为冗长。可以使用数据驱动的方式简化。

考虑使用循环和边界列表：

        range_boundaries = [
            (1, 100, "1-100"),
            (100, 300, "100-300"),
            (300, 500, "300-500"),
            (500, 800, "500-800"),
            (800, 1000, "800-1000"),
            (1000, 1500, "1000-1500"),
            (1500, 2000, "1500-2000"),
            (2000, float('inf'), "2000+")
        ]
        
        for item in data:
            if 'metadata' in item and 'word_count' in item['metadata']:
                wc = item['metadata']['word_count']
                max_word_count = max(max_word_count, wc)
                total_word_count += wc
                
                for low, high, label in range_boundaries:
                    if low <= wc < high:
                        ranges[label] += 1
                        break

text2gremlin/Vertical_Text2Gremlin/data/book/book_qa_gen.py (3)

16-18: 输入输出文件路径使用相对路径

相对路径 gremlin_book_chunks.jsonl 依赖于脚本执行时的工作目录，可能导致文件未找到错误。建议使用相对于脚本文件的路径或命令行参数。

-INPUT_FILE = "gremlin_book_chunks.jsonl"
+INPUT_FILE = os.path.join(os.path.dirname(__file__), "gremlin_book_chunks.jsonl")
 # INPUT_FILE = "test.jsonl"
-OUTPUT_FILE = "gremlin_qa_dataset_final_epoch_3.jsonl"
+OUTPUT_FILE = os.path.join(os.path.dirname(__file__), "gremlin_qa_dataset_final_epoch_3.jsonl")

或者，使用 argparse 允许用户指定路径。

---

92-124: 移除大段已注释代码

这 33 行注释代码与当前实现几乎相同，仅缺少错误处理。应该删除以减少维护负担。

-# @retry(stop=stop_after_attempt(RETRY_ATTEMPTS), wait=wait_exponential(multiplier=1, min=RETRY_WAIT_SECONDS, max=10))
-# async def process_chunk(chunk: dict, index: int) -> list:
-#     """
-#     处理chunk。
-#     """
-... [删除全部注释代码]
-#     return formatted_pairs
-

---

90-90: AsyncOpenAI 客户端未显式关闭

虽然 Python 的垃圾回收通常会处理资源释放，但最佳实践是显式关闭 HTTP 客户端或使用上下文管理器以确保连接正确清理。

考虑使用异步上下文管理器：

-client = AsyncOpenAI(api_key=API_KEY, base_url=BASE_URL)
-
 @retry(stop=stop_after_attempt(RETRY_ATTEMPTS), wait=wait_exponential(multiplier=1, min=RETRY_WAIT_SECONDS, max=10))
 async def process_chunk(chunk: dict, index: int) -> list:
+    # 在函数内使用全局 client 或通过参数传递

并在 main() 中：

async def main():
    async with AsyncOpenAI(api_key=API_KEY, base_url=BASE_URL) as client:
        # ... 使用 client

但需要将 client 作为参数传递给 process_chunk。当前实现可接受，但显式管理更佳。

text2gremlin/Vertical_Text2Gremlin/data/book/integrity_check.py (3)

5-12: 函数签名和文档字符串清晰。

函数定义明确，类型注解完整。文档字符串简洁说明了功能（基于字数的完整性校验），建议补充参数说明和可能的异常情况。

可选的改进建议：

 def verify_word_count_across_pipeline(
     original_md_path: str,
     structured_json_path: str,
     chunks_jsonl_path: str
 ):
-    """chunk数据统计
-    对整个数据处理流水线，统一按"字数 (Word Count)"进行完整性校验。
-    """
+    """
+    对整个数据处理流水线，统一按"字数 (Word Count)"进行完整性校验。
+    
+    Args:
+        original_md_path: 原始 Markdown 文件路径
+        structured_json_path: 结构化 JSON 文件路径
+        chunks_jsonl_path: 切分后的 JSONL 文件路径
+    
+    Prints:
+        校验结果和分析结论到标准输出
+    """

---

31-46: 递归字数统计逻辑正确，建议增强鲁棒性。

_sum_content_words 正确递归遍历 children 并累加 content 字段的字数。建议对 JSON 结构进行基本验证，以防格式不符预期导致静默失败。

可选的改进：

     try:
         with open(structured_json_path, 'r', encoding='utf-8') as f:
             book_structure = json.load(f)
+        if not isinstance(book_structure, list):
+            raise ValueError(f"期望顶层为列表，实际为 {type(book_structure).__name__}")
         for chapter in book_structure:
             structured_word_count += _sum_content_words(chapter)

---

61-80: 分析逻辑清晰，建议增加错误返回机制。

校验结论分析逻辑合理，覆盖了预期和异常情况。但当检测到不合理情况时（Line 69, 76），仅打印消息而未返回错误状态或抛出异常，调用方无法感知校验失败。

建议返回布尔值或抛出异常：

-def verify_word_count_across_pipeline(
+def verify_word_count_across_pipeline(
     original_md_path: str,
     structured_json_path: str,
     chunks_jsonl_path: str
-):
+) -> bool:
     """
-    对整个数据处理流水线，统一按"字数 (Word Count)"进行完整性校验。
+    对整个数据处理流水线，统一按"字数 (Word Count)"进行完整性校验。
+    
+    Returns:
+        True if all checks pass, False otherwise
     """
+    passed = True
     ...
     if original_word_count > structured_word_count:
         ...
     else:
         print(f"不合理,结构化JSON的字数未少于原始MD文件。")
+        passed = False
     
     if total_chunks_word_count > structured_word_count:
         ...
     else:
         print(f"可能存在问题，最终Chunks的总字数未多于结构化JSON，可能重叠策略未生效或内容有丢失。")
+        passed = False
         
     print("\n" + "="*60)
     print("校验完成。")
     print("="*60)
+    return passed

text2gremlin/Vertical_Text2Gremlin/data/book/divide_chunks.py (5)

5-8: 常量定义清晰，建议集中配置管理。

核心参数定义明确。如果项目中有多个模块需要共享这些参数，建议将其移至统一的配置文件或类中。

---

89-107: 递归遍历逻辑正确，层级关系构建清晰。

通过 level 字段动态构建层级字典，递归处理子节点，逻辑清晰。建议增加基本的结构验证以提高鲁棒性。

可选改进：

 def _traverse_and_chunk_node(
     node: Dict[str, Any], 
     parent_hierarchy: Dict[str, Any], 
     final_chunks: List[Dict[str, Any]]
 ):
+    if not isinstance(node, dict):
+        return
+    
     current_hierarchy = parent_hierarchy.copy()

---

109-131: 主函数结构合理，错误处理得当。

加载、遍历、写入流程清晰，异常捕获确保了错误提示。JSONL 格式适合大规模数据处理。

可选改进：在 Line 118 之后增加结构验证：

     try:
         with open(input_json_path, 'r', encoding='utf-8') as f:
             book_structure = json.load(f)
+        if not isinstance(book_structure, list):
+            print(f"错误：期望顶层为列表，实际为 {type(book_structure).__name__}")
+            return
     except Exception as e:

---

132-139: 建议移除注释掉的代码或提供格式选项。

注释掉的代码展示了另一种输出格式（美化的 JSON）。如果需要保留，建议通过参数控制输出格式，而不是保留大段注释代码。

可以添加格式参数：

def create_fine_grained_chunks(
    input_json_path: str, 
    output_jsonl_path: str,
    format: str = "jsonl"  # "jsonl" or "json"
):
    ...
    if format == "jsonl":
        # 现有 JSONL 写入逻辑
    elif format == "json":
        # 美化 JSON 写入逻辑

或者直接移除注释代码以保持清晰。

---

141-145: 建议使用共享配置管理文件路径。

divide_chunks.py 和 integrity_check.py 都硬编码了相同的文件名（gremlin_book.json、gremlin_book_chunks.jsonl），这增加了维护成本和不一致的风险。

建议创建共享配置模块（如 config.py）：

# config.py
ORIGINAL_MD_FILE = "Gremlin-Graph-Guide.md"
STRUCTURED_JSON_FILE = "gremlin_book.json"
CHUNKS_JSONL_FILE = "gremlin_book_chunks.jsonl"

然后在两个文件中导入使用：

from config import STRUCTURED_JSON_FILE, CHUNKS_JSONL_FILE

这样修改路径时只需更新一处。

text2gremlin/Vertical_Text2Gremlin/gremlin_checker.py (1)

7-12: 路径操作可能存在脆弱性。

当前使用相对路径操作 (..) 来定位 gremlin 模块。这种方式依赖于文件的物理位置，可能在不同的执行环境或部署场景下失败。

建议考虑以下改进方案：

方案1（推荐）：使用包相对导入

如果 gremlin 模块位于同一个包层级，使用相对导入：

-current_dir = os.path.dirname(os.path.abspath(__file__))
-parent_dir = os.path.join(current_dir, '..')
-sys.path.insert(0, parent_dir)
-
-from gremlin.GremlinLexer import GremlinLexer
-from gremlin.GremlinParser import GremlinParser
+from ..gremlin.GremlinLexer import GremlinLexer
+from ..gremlin.GremlinParser import GremlinParser

方案2：使用 PYTHONPATH 环境变量

在项目文档中说明需要将项目根目录添加到 PYTHONPATH，移除路径操作代码。

text2gremlin/Vertical_Text2Gremlin/instruct_convert.py (4)

3-3: 移除未使用的导入。

os 模块已导入但未在代码中使用。

-import os

---

6-13: 硬编码路径降低了代码灵活性。

所有文件路径都是硬编码的常量，使得代码在不同环境下的复用性较差。

建议接受命令行参数或从配置文件读取路径：

import argparse

def parse_args():
    parser = argparse.ArgumentParser()
    parser.add_argument('--input', default='test_gremlin_qa_dataset.csv')
    parser.add_argument('--output', default='instruct_data.json')
    parser.add_argument('--train-ratio', type=float, default=0.7)
    return parser.parse_args()

或者使用配置文件：

import json

def load_config(config_path='config.json'):
    with open(config_path, 'r') as f:
        return json.load(f)

---

25-52: 手动构建 JSON 数组存在风险。

当前手动写入 JSON 数组的开闭括号和逗号，如果处理过程中发生异常，可能导致 JSON 文件格式不完整。

建议先将所有数据收集到内存中，最后一次性写入：

def convert_csv_to_json():
    print("数据转换 CSV -> JSON")
    print(f"输入: '{INPUT_CSV_PATH}'")
    print(f"输出: '{OUTPUT_JSON_PATH}'")
    
    instruction_text = "你是一位精通图数据库查询语言Gremlin的专家。你的任务是根据用户输入的自然语言问题，将其准确地转换为对应的Gremlin查询语句。"
    
    try:
        all_data = []
        csv_reader = pd.read_csv(INPUT_CSV_PATH, chunksize=CHUNK_SIZE, iterator=True)
        
        for i, chunk_df in enumerate(csv_reader):
            for index, row in chunk_df.iterrows():
                if pd.notna(row['question']) and pd.notna(row['gremlin_query']):
                    all_data.append({
                        "instruction": instruction_text,
                        "input": row['question'],
                        "output": row['gremlin_query']
                    })
            print(f"  已处理 {i+1} 个数据块，累计处理 {len(all_data)} 行...")
        
        with open(OUTPUT_JSON_PATH, 'w', encoding='utf-8') as f:
            json.dump(all_data, f, ensure_ascii=False, indent=2)
        
        print(f"\n 数据转换完成！总共转换了 {len(all_data)} 条数据,保存文件至 {OUTPUT_JSON_PATH}")
        return True
        
    except FileNotFoundError:
        print(f"错误: 输入文件未找到 '{INPUT_CSV_PATH}'。请检查文件名和路径。")
        return False
    except Exception as e:
        print(f"发生未知错误: {e}")
        return False

---

84-90: 缺少输出目录检查。

在写入文件前未检查输出目录是否存在，可能导致 FileNotFoundError。

添加目录创建逻辑：

+    import os
+    
+    # 确保输出目录存在
+    os.makedirs(os.path.dirname(TRAIN_OUTPUT_PATH), exist_ok=True)
+    os.makedirs(os.path.dirname(TEST_OUTPUT_PATH), exist_ok=True)
+    
     print(f"  保存训练集到 '{TRAIN_OUTPUT_PATH}'...")
     with open(TRAIN_OUTPUT_PATH, 'w', encoding='utf-8') as f:
         json.dump(train_data, f, ensure_ascii=False, indent=2)

text2gremlin/Vertical_Text2Gremlin/data/book/augment_dataset.py (2)

12-12: API 密钥命名不规范。

环境变量名 ds_api_key 使用了小写，不符合环境变量的命名惯例。

建议使用大写命名：

-API_KEY = os.getenv("ds_api_key") 
+API_KEY = os.getenv("DS_API_KEY")

并在 .env 文件中相应更新：

DS_API_KEY=your_api_key_here

---

52-56: 缺少输入验证。

函数未验证 qa_pair 字典是否包含必需的键（input、output），可能导致运行时错误。

添加输入验证：

def create_user_prompt(qa_pair: dict) -> str:
    """生成用户指令"""
    if "input" not in qa_pair or "output" not in qa_pair:
        raise ValueError(f"QA pair missing required keys: {qa_pair}")
    
    original_input = qa_pair["input"]
    original_output = qa_pair["output"]
    return f"请为下面的原始问答对生成3到4个泛化版本。\n\n[原始问题]\n{original_input}\n\n[原始答案]\n{original_output}"

text2gremlin/Vertical_Text2Gremlin/llm_handler.py (2)

56-69: 改进错误处理和可观测性

当前错误处理存在以下不足：

1. 使用泛型 Exception 捕获，可能掩盖不应被静默处理的错误（如配置错误）
2. 错误信息仅 print 到 stdout，生产环境难以追踪
3. 失败时返回空列表，调用方无法区分"LLM 返回空结果"和"调用失败"

建议改进：

+import logging
+
+logger = logging.getLogger(__name__)
+
 def generate_gremlin_variations(seed_query: str, seed_questions: List[str]) -> List[str]:
     """
     基于种子数据，调用LLM生成多个Gremlin查询变体。
     """
     ...
     try:
         response = client.chat.completions.create(...)
         content = response.choices[0].message.content
         return json.loads(content).get("gremlin_variations", [])
+    except json.JSONDecodeError as e:
+        logger.error(f"LLM 返回的 JSON 格式无效: {e}, content: {content[:200]}")
+        return []
+    except (APIConnectionError, RateLimitError, APIStatusError) as e:
+        logger.error(f"LLM API 调用失败: {type(e).__name__}: {e}")
+        return []
     except Exception as e:
-        print(f"Error calling LLM for Gremlin generation: {e}")
+        logger.exception(f"LLM 调用出现未预期错误: {e}")
         return []

Based on learnings

---

100-114: 改进错误处理和可观测性

与 generate_gremlin_variations 函数相同的错误处理问题。

应用与前述相同的错误处理改进。

text2gremlin/Vertical_Text2Gremlin/qa_generalize.py (3)

78-78: 使用更智能的速率限制策略替代硬编码的 sleep

time.sleep(1) 是粗糙的速率限制方式，无法应对不同的 API 配额或动态调整。

建议：

1. 基于 API 响应头动态调整等待时间
2. 使用指数退避处理速率限制错误
3. 将速率限制配置提取为常量

+RATE_LIMIT_DELAY = 1.0  # 秒

 for valid_query in valid_queries:
     generated_texts = generate_texts_for_gremlin(valid_query)
     if generated_texts:
         print(f"      -> 为查询 '{valid_query[:80]}...' 生成了 {len(generated_texts)} 个问题。")
         for text in generated_texts:
             new_data_for_group.append({'question': text, 'gremlin_query': valid_query})
-    time.sleep(1)
+    time.sleep(RATE_LIMIT_DELAY)

更进一步，可以在 llm_handler.py 的 API 调用层面实现速率限制和重试逻辑。

---

82-128: 增强处理流程的健壮性和可恢复性

当前实现在以下方面存在改进空间：

1. 缺少输入验证：在开始处理前未检查文件是否存在
2. 无去重机制：可能生成重复的 QA 对
3. 不支持断点续传：长时间运行中断后需从头开始
4. 内存管理：write_buffer 无上限可能导致内存问题

建议改进：

def main():
    # 验证输入文件
    if not os.path.exists(INPUT_CSV_PATH):
        print(f"错误: 输入文件不存在 '{INPUT_CSV_PATH}'")
        return
    
    # 如果输出文件存在，加载已有数据用于去重
    existing_queries = set()
    if os.path.exists(OUTPUT_CSV_PATH):
        try:
            existing_df = pd.read_csv(OUTPUT_CSV_PATH)
            existing_queries = set(existing_df['gremlin_query'].unique())
            print(f"检测到已有输出文件，加载了 {len(existing_queries)} 个已处理的查询")
        except Exception as e:
            print(f"警告：无法加载已有输出文件: {e}")
    
    is_first_write = not os.path.exists(OUTPUT_CSV_PATH)
    write_buffer = []
    seen_qa_pairs = set()  # (question, gremlin_query) 去重
    carry_over_df = pd.DataFrame()
    
    try:
        csv_reader = pd.read_csv(INPUT_CSV_PATH, chunksize=CHUNK_SIZE, iterator=True)
        
        for i, chunk_df in enumerate(csv_reader):
            # ... 处理逻辑 ...
            
            # 去重检查
            for data in new_data:
                qa_key = (data['question'], data['gremlin_query'])
                if qa_key not in seen_qa_pairs:
                    seen_qa_pairs.add(qa_key)
                    write_buffer.append(data)
            
            # 限制缓冲区大小
            if len(write_buffer) >= WRITE_THRESHOLD:
                is_first_write = save_and_clear_buffer(write_buffer, is_first_write)
                
    except KeyboardInterrupt:
        print("\n检测到中断，保存已处理的数据...")
        save_and_clear_buffer(write_buffer, is_first_write)
        print("已保存进度，可稍后继续处理")
    # ... 其他异常处理 ...

---

122-125: 改进异常处理的粒度和信息量

当前异常处理过于宽泛，且错误信息不足以调试问题。

     except FileNotFoundError:
         print(f"错误: 输入文件未找到 '{INPUT_CSV_PATH}'")
+        return 1  # 返回非零退出码
     except Exception as e:
-        print(f"发生未知错误: {e}")
+        import traceback
+        print(f"发生未知错误: {e}")
+        traceback.print_exc()
+        # 尝试保存已处理的数据
+        if write_buffer:
+            print("尝试保存已处理的部分数据...")
+            save_and_clear_buffer(write_buffer, is_first_write)
+        return 1
 
     print("\nQA泛化完成!")
+    return 0

text2gremlin/Vertical_Text2Gremlin/graph2gremlin.py (3)

189-217: 改进查询生成的去重逻辑和终止条件

当前实现存在以下问题：

1. generated_queries 集合用于去重，但生成的 QA pairs 可能仍然重复（相同 query 配不同 question）
2. Line 209 的提前终止条件阈值（num_queries_needed * 2）是任意的
3. 无法持久化已生成的查询，重启后需重新生成

建议改进：

def main(num_to_generate=500, questions_per_query=3):
    if not setup_component_library():
        print("已终止。")
        return

    # 尝试加载已有输出，实现增量生成
    output_path = Path("test_gremlin_qa_dataset.csv")
    existing_qa_pairs = []
    generated_queries = set()
    
    if output_path.exists():
        try:
            existing_df = pd.read_csv(output_path)
            existing_qa_pairs = existing_df.to_dict('records')
            generated_queries = set(existing_df['gremlin_query'].unique())
            print(f"检测到已有 {len(existing_qa_pairs)} 条 QA 对，{len(generated_queries)} 个唯一查询")
        except Exception as e:
            print(f"警告：无法加载已有输出: {e}")
    
    all_qa_pairs = existing_qa_pairs.copy()
    num_queries_needed = (num_to_generate - len(all_qa_pairs)) // questions_per_query + 1
    
    print(f"\n目标生成 {num_to_generate} 条 QA 对（当前已有 {len(all_qa_pairs)}），需要约 {num_queries_needed} 个新查询")
    
    max_attempts = num_queries_needed * 3  # 设置最大尝试次数
    attempts = 0
    
    while len(all_qa_pairs) < num_to_generate and attempts < max_attempts:
        attempts += 1
        gremlin_query, description = generate_gremlin_query()
        
        if not gremlin_query or gremlin_query in generated_queries:
            continue
            
        generated_queries.add(gremlin_query)
        print(f"\n生成新 Gremlin 查询 ({len(generated_queries)}/{num_queries_needed}): {gremlin_query}")
        
        qa_pairs = translate_and_paraphrase(gremlin_query, description, questions_per_query)
        if qa_pairs:
            all_qa_pairs.extend(qa_pairs)
            print(f" -> 成功泛化 {len(qa_pairs)} 个问题。当前总数: {len(all_qa_pairs)}")
            
            # 定期保存进度
            if len(all_qa_pairs) % 100 == 0:
                output_df = pd.DataFrame(all_qa_pairs)
                output_df.to_csv(output_path, index=False, encoding='utf-8-sig')
                print(f"   [进度已保存]")
    
    if attempts >= max_attempts:
        print(f"\n警告：达到最大尝试次数 ({max_attempts})，可能素材库已难以产生新查询")
    
    print(f"\n--- 生成完成！共获得 {len(all_qa_pairs)} 条 QA 对 ---")
    output_df = pd.DataFrame(all_qa_pairs)
    output_df.to_csv(output_path, index=False, encoding='utf-8-sig')
    print(f"数据集已保存到 {output_path}")

---

175-187: 改进 LLM 调用的错误处理和超时配置

与其他文件相同，此处缺少超时配置和细粒度的错误处理。

应用与 llm_handler.py 相同的改进：

     try:
         print("调用API生成问题...")
-        response = client.chat.completions.create(
+        response = client.with_options(timeout=30.0).chat.completions.create(
             model="deepseek-chat",
             messages=[{"role": "user", "content": prompt}],
             temperature=1.3
         )
         questions = response.choices[0].message.content.strip().split('\n')
         qa_pairs = [{"question": q.lstrip("*-123456789. "), "gremlin_query": query} for q in questions if q]
         return qa_pairs
+    except (APIConnectionError, RateLimitError, APIStatusError) as e:
+        print(f"API 调用失败 ({type(e).__name__}): {e}")
+        return []
     except Exception as e:
-        print(f"调用API时出错: {e}")
+        print(f"未预期的错误: {e}")
+        import traceback
+        traceback.print_exc()
         return []

Based on learnings

---

106-107: 增强 Gremlin 字符串转义以提高健壮性

验证结果：当前 CSV 数据仅含单引号，未发现反斜杠、换行、制表符或双引号等需额外转义的字符，因此现有 str(entity_name).replace("'", "\\'") 可正确处理当前数据中的单引号。
建议为未来潜在的特殊字符（如 \、\n、\r、\t 等）补充通用转义函数，示例：

def escape_gremlin_string(s: str) -> str:
    return (
        str(s)
        .replace('\\', '\\\\')
        .replace("'", "\\'")
        .replace('\n', '\\n')
        .replace('\r', '\\r')
        .replace('\t', '\\t')
    )

# 使用
entity_name = escape_gremlin_string(entity_name)

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between b14ffb3 and 4120356.

⛔ Files ignored due to path filters (15)

• text2gremlin/Vertical_Text2Gremlin/data/seed_data/seed_gremlin_qa_dataset.csv is excluded by !**/*.csv
• text2gremlin/Vertical_Text2Gremlin/db_data/movie/raw_data/edge_acted_in.csv is excluded by !**/*.csv
• text2gremlin/Vertical_Text2Gremlin/db_data/movie/raw_data/edge_directed.csv is excluded by !**/*.csv
• text2gremlin/Vertical_Text2Gremlin/db_data/movie/raw_data/edge_has_genre.csv is excluded by !**/*.csv
• text2gremlin/Vertical_Text2Gremlin/db_data/movie/raw_data/edge_has_keyword.csv is excluded by !**/*.csv
• text2gremlin/Vertical_Text2Gremlin/db_data/movie/raw_data/edge_is_friend.csv is excluded by !**/*.csv
• text2gremlin/Vertical_Text2Gremlin/db_data/movie/raw_data/edge_produce.csv is excluded by !**/*.csv
• text2gremlin/Vertical_Text2Gremlin/db_data/movie/raw_data/edge_rate.csv is excluded by !**/*.csv
• text2gremlin/Vertical_Text2Gremlin/db_data/movie/raw_data/edge_write.csv is excluded by !**/*.csv
• text2gremlin/Vertical_Text2Gremlin/db_data/movie/raw_data/vertex_genre.csv is excluded by !**/*.csv
• text2gremlin/Vertical_Text2Gremlin/db_data/movie/raw_data/vertex_keyword.csv is excluded by !**/*.csv
• text2gremlin/Vertical_Text2Gremlin/db_data/movie/raw_data/vertex_movie.csv is excluded by !**/*.csv
• text2gremlin/Vertical_Text2Gremlin/db_data/movie/raw_data/vertex_person.csv is excluded by !**/*.csv
• text2gremlin/Vertical_Text2Gremlin/db_data/movie/raw_data/vertex_user.csv is excluded by !**/*.csv
• text2gremlin/Vertical_Text2Gremlin/gremlin_qa_dataset.csv is excluded by !**/*.csv

📒 Files selected for processing (16)

• text2gremlin/Vertical_Text2Gremlin/README.md (1 hunks)
• text2gremlin/Vertical_Text2Gremlin/data/book/READMD.md (1 hunks)
• text2gremlin/Vertical_Text2Gremlin/data/book/augment_dataset.py (1 hunks)
• text2gremlin/Vertical_Text2Gremlin/data/book/book_process.py (1 hunks)
• text2gremlin/Vertical_Text2Gremlin/data/book/book_qa_gen.py (1 hunks)
• text2gremlin/Vertical_Text2Gremlin/data/book/chunk_analysis.py (1 hunks)
• text2gremlin/Vertical_Text2Gremlin/data/book/divide_chunks.py (1 hunks)
• text2gremlin/Vertical_Text2Gremlin/data/book/integrity_check.py (1 hunks)
• text2gremlin/Vertical_Text2Gremlin/data/book/test.jsonl (1 hunks)
• text2gremlin/Vertical_Text2Gremlin/data/book/word_count_analysis.txt (1 hunks)
• text2gremlin/Vertical_Text2Gremlin/db_data/schema/movie_schema.json (1 hunks)
• text2gremlin/Vertical_Text2Gremlin/graph2gremlin.py (1 hunks)
• text2gremlin/Vertical_Text2Gremlin/gremlin_checker.py (1 hunks)
• text2gremlin/Vertical_Text2Gremlin/instruct_convert.py (1 hunks)
• text2gremlin/Vertical_Text2Gremlin/llm_handler.py (1 hunks)
• text2gremlin/Vertical_Text2Gremlin/qa_generalize.py (1 hunks)

✅ Files skipped from review due to trivial changes (3)

• text2gremlin/Vertical_Text2Gremlin/db_data/schema/movie_schema.json
• text2gremlin/Vertical_Text2Gremlin/data/book/test.jsonl
• text2gremlin/Vertical_Text2Gremlin/data/book/word_count_analysis.txt

🧰 Additional context used

🧠 Learnings (2)

📓 Common learnings

Learnt from: CR
PR: hugegraph/hugegraph-ai#0
File: hugegraph-llm/AGENTS.md:0-0
Timestamp: 2025-09-16T06:40:44.968Z
Learning: Applies to hugegraph-llm/src/hugegraph_llm/operators/gremlin_generate_task.py : Maintain the Text2Gremlin pipeline in src/hugegraph_llm/operators/gremlin_generate_task.py

📚 Learning: 2025-09-16T06:40:44.968Z

Learnt from: CR
PR: hugegraph/hugegraph-ai#0
File: hugegraph-llm/AGENTS.md:0-0
Timestamp: 2025-09-16T06:40:44.968Z
Learning: Applies to hugegraph-llm/src/hugegraph_llm/operators/gremlin_generate_task.py : Maintain the Text2Gremlin pipeline in src/hugegraph_llm/operators/gremlin_generate_task.py

Applied to files:

• text2gremlin/Vertical_Text2Gremlin/graph2gremlin.py

🧬 Code graph analysis (4)

text2gremlin/Vertical_Text2Gremlin/qa_generalize.py (1)

text2gremlin/Vertical_Text2Gremlin/llm_handler.py (2)

• generate_gremlin_variations (21-69)
• generate_texts_for_gremlin (71-114)

text2gremlin/Vertical_Text2Gremlin/data/book/augment_dataset.py (1)

text2gremlin/Vertical_Text2Gremlin/data/book/book_qa_gen.py (2)

• create_user_prompt (67-87)
• main (171-224)

text2gremlin/Vertical_Text2Gremlin/data/book/book_qa_gen.py (1)

text2gremlin/Vertical_Text2Gremlin/data/book/augment_dataset.py (2)

• create_user_prompt (52-56)
• main (142-194)

text2gremlin/Vertical_Text2Gremlin/data/book/divide_chunks.py (1)

hugegraph-llm/src/hugegraph_llm/document/chunk_split.py (1)

• split (50-56)

🪛 markdownlint-cli2 (0.18.1)

text2gremlin/Vertical_Text2Gremlin/data/book/READMD.md

17-17: Spaces inside code span elements

(MD038, no-space-in-code)

---

18-18: Spaces inside code span elements

(MD038, no-space-in-code)

---

19-19: Spaces inside code span elements

(MD038, no-space-in-code)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: build (3.10)
• GitHub Check: build (3.11)

🔇 Additional comments (14)

text2gremlin/Vertical_Text2Gremlin/data/book/chunk_analysis.py (1)

104-112: 主执行块的逻辑清晰

代码正确处理了返回值并执行后续操作。重复计算平均值（第 111 行）与 analyze_word_count 中的计算存在轻微冗余，但可接受。

text2gremlin/Vertical_Text2Gremlin/data/book/book_qa_gen.py (4)

73-82: 标题去重逻辑可能不够完善

第 81 行的条件 unique_path_parts[-1] not in part 只检查前一个部分是否为当前部分的子串。如果标题是 "1. Introduction" 和 "1.1. Introduction to Graphs"，第二个不会被过滤。逻辑可能需要澄清意图。

请验证此去重逻辑是否符合预期。如果意图是去除完全相同的连续标题，应使用：

for part in path_parts:
    if not unique_path_parts or unique_path_parts[-1] != part:
        unique_path_parts.append(part)

如果意图是去除父标题包含在子标题中的情况（如 "Introduction" 与 "Introduction to Graphs"），当前逻辑正确但建议添加注释说明。

---

125-168: process_chunk 函数的错误处理和重试机制良好

使用 tenacity 进行重试，处理 JSON 解码错误和空响应的逻辑正确。代码质量高。

---

179-215: 主函数的批处理和错误处理逻辑健壮

批量读取、并发处理、缓冲写入的流程设计合理。文件未找到异常的处理正确。

---

196-201: 异常处理使用 return_exceptions=True 是正确的

使用 return_exceptions=True 确保一个任务失败不会影响其他任务。检查 isinstance(result, list) 来区分成功和失败的结果是良好实践。

text2gremlin/Vertical_Text2Gremlin/data/book/integrity_check.py (2)

17-28: 原始文件字数统计逻辑正确。

使用正则 \w+ 统计单词，覆盖字母、数字和下划线，符合预期。异常处理确保文件读取失败时有提示信息。

---

48-59: JSONL 字数统计逻辑正确。

逐行解析 JSON 并累加 chunk_content 字段的字数，处理得当。异常捕获确保格式错误时有提示。

text2gremlin/Vertical_Text2Gremlin/data/book/divide_chunks.py (1)

10-38: 语义单元提取逻辑基本正确，但正则捕获组使用需要验证。

Line 18 的非捕获组修复正确。但 Line 26 的 master_pattern 在整个交替模式外层使用了捕获组 ()，这可能导致 split() 返回额外的空字符串或重复元素。

建议验证 split() 的输出是否符合预期。可以通过单元测试确认：

# 测试用例
test_text = """
普通段落

```python
code here

• list item
• another item

普通段落2
"""
units = _get_semantic_units(test_text)
print(f"语义单元数量: {len(units)}")
for i, unit in enumerate(units):
print(f"Unit {i}: {unit[:50]}...")

如果发现额外的空元素或重复，考虑将 Line 26 的捕获组改为非捕获组，或在 Line 28 之后增加过滤逻辑。

</blockquote></details>
<details>
<summary>text2gremlin/Vertical_Text2Gremlin/README.md (1)</summary><blockquote>

`1-17`: **文档结构清晰，内容完整。**

README 很好地描述了 Vertical_Text2Gremlin 项目的各个组件及其用途，包括数据生成流程、语法检查、LLM 交互、数据泛化和格式转换等关键模块。文档为开发者提供了良好的项目概览。

</blockquote></details>
<details>
<summary>text2gremlin/Vertical_Text2Gremlin/gremlin_checker.py (2)</summary><blockquote>

`14-26`: **LGTM！**

`SyntaxErrorListener` 类正确实现了 ANTLR4 错误监听器接口，能够捕获并存储语法错误信息。实现简洁且功能完整。

---

`28-57`: **LGTM！语法检查逻辑正确。**

函数正确地构建了词法分析器和语法分析器，替换了默认的错误监听器，并返回了适当的结果。类型提示清晰，返回值格式合理。

</blockquote></details>
<details>
<summary>text2gremlin/Vertical_Text2Gremlin/data/book/augment_dataset.py (2)</summary><blockquote>

`94-141`: **LGTM！异常处理逻辑合理。**

函数正确实现了带重试的异步 API 调用，包含了 JSON 解析错误和通用异常的处理。即使失败也会保留原始 QA 对，确保数据不丢失。

---

`177-181`: **文件追加模式可能导致数据重复。**

使用 `'a'` 模式打开文件，如果脚本多次运行，会不断追加数据到同一文件，导致数据重复。



建议在脚本开始时检查输出文件是否存在，并提示用户：

```python
async def main():
    # 检查输出文件
    if os.path.exists(OUTPUT_FILE):
        response = input(f"警告: 输出文件 '{OUTPUT_FILE}' 已存在。是否覆盖? (y/n): ")
        if response.lower() == 'y':
            os.remove(OUTPUT_FILE)
        else:
            print("操作已取消。")
            return
    
    qa_buffer = []
    # ... 其余代码

或者使用时间戳生成唯一文件名：

from datetime import datetime

timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
OUTPUT_FILE = f"gremlin_qa_dataset_augmented_{timestamp}.jsonl"

text2gremlin/Vertical_Text2Gremlin/data/book/READMD.md (1)

1-91: 文档内容详尽且结构清晰。

文档详细描述了从 Markdown 到训练数据的三阶段处理流程（解析、切分、格式化），包含了具体的实现细节、参数说明和 JSON 输出格式示例。这为实施该方案提供了清晰的指导。

注意：静态分析工具标记了 Lines 17-19 的代码块格式问题（MD038），这是 markdown 格式的小问题（代码块内有多余空格），可以选择性修复：

-      * 遇到` #  `（一级标题），则创建一个新的顶级"章"节点。
-      * 遇到` ##  `（二级标题），则在当前的"章"节点下创建一个"节"节点。
-      * 遇到` ###  `（三级标题），则在当前的"节"节点下创建一个"小节"节点。
+      * 遇到 `#`（一级标题），则创建一个新的顶级"章"节点。
+      * 遇到 `##`（二级标题），则在当前的"章"节点下创建一个"节"节点。
+      * 遇到 `###`（三级标题），则在当前的"节"节点下创建一个"小节"节点。

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

潜在的误识别风险需要人工复查

注释指出行内包含 # 字符的内容（如代码注释、代码块中的 markdown）可能被误识别为标题。建议添加基本的代码块检测（如 ``` 包裹区域），或至少在文档中明确说明此限制。

应用此修改以改进逻辑（增加简单的代码块状态跟踪）：

+    in_code_block = False
     #可能出现误差，比如存在"#"注释，最好人工筛查一遍
     for line in lines:
+        if line.strip().startswith('```'):
+            in_code_block = not in_code_block
+            add_content_to_current_node(line)
+            continue
+        
+        if in_code_block:
+            add_content_to_current_node(line)
+            continue
+            
         if line.startswith('# '):

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	#可能出现误差，比如存在"#"注释，最好人工筛查一遍
	# 添加简单的代码块状态跟踪，避免将代码块内的“#”误识别为标题
	in_code_block = False
	# 可能出现误差，比如存在"#"注释，最好人工筛查一遍
	for line in lines:
	if line.strip().startswith('

🤖 Prompt for AI Agents

In text2gremlin/Vertical_Text2Gremlin/data/book/book_process.py around line 47,
the parser can misinterpret '#' inside fenced code blocks as headings; add a
simple code-block state toggle and guard: introduce an in_code_block boolean
that flips when encountering fence delimiters (```), append the line to the
current node and continue immediately, and if in_code_block is true skip heading
detection (append lines to the current node and continue) so that lines inside
fenced code blocks are not treated as headings.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

标题解析逻辑正确，但缺少对空标题的边界检查

当标题为空（例如 # \n）时，title 将为空字符串，但仍会创建节点。建议添加空标题检查。

         if line.startswith('# '):
             level1_counter += 1
             level2_counter = 0
             level3_counter = 0
             
             level_str = f"{level1_counter}"
             title = line.strip('# \n')
+            
+            if not title:
+                add_content_to_current_node(line)
+                continue
             
             current_section_lvl2 = {}

Committable suggestion skipped: line range outside the PR's diff.

🤖 Prompt for AI Agents

In text2gremlin/Vertical_Text2Gremlin/data/book/book_process.py around lines
49-66, the code creates a chapter node even when the stripped title is empty
(e.g., "# \n"); compute title first (use title = line.strip('# \n').strip()),
check if title is falsy and if so skip processing that header (continue) so no
empty node is added, and only increment level counters and create the
chapter/node after passing this non-empty title check.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

环境变量配置存在潜在问题

使用相对路径 '..', '..' 构建 .env 路径可能在不同执行上下文中失败（例如从不同目录运行脚本）。建议使用 find_dotenv() 或绝对路径。

应用此修改以提高可靠性：

 from dotenv import load_dotenv

-env_path = os.path.join(os.path.dirname(__file__), '..', '..', '.env')
-load_dotenv(dotenv_path=env_path)
+from dotenv import find_dotenv
+load_dotenv(dotenv_path=find_dotenv(), override=False)

或者，如果 .env 位置固定，使用项目根目录的绝对路径。

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	env_path = os.path.join(os.path.dirname(__file__), '..', '..', '.env')
	load_dotenv(dotenv_path=env_path)
	API_KEY = os.getenv("ds_api_key")
	BASE_URL = "https://api.deepseek.com/v1"
	MODEL_NAME = "deepseek-chat"
	from dotenv import load_dotenv
	from dotenv import find_dotenv
	load_dotenv(dotenv_path=find_dotenv(), override=False)
	API_KEY = os.getenv("ds_api_key")
	BASE_URL = "https://api.deepseek.com/v1"
	MODEL_NAME = "deepseek-chat"

🤖 Prompt for AI Agents

In text2gremlin/Vertical_Text2Gremlin/data/book/book_qa_gen.py around lines 9 to
14, the .env path is built with a relative '..','..' which can break when the
script is run from other working directories; replace this with a reliable
locator: either call load_dotenv(find_dotenv()) after importing find_dotenv from
dotenv, or compute an absolute path from the file location (e.g., resolve
Path(__file__) and use parents to reach the project root then /'.env') and pass
that absolute path to load_dotenv; ensure any necessary imports (find_dotenv or
pathlib.Path) are added.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

API 密钥和基础 URL 配置缺少验证

如果 ds_api_key 环境变量未设置，API_KEY 将为 None，导致后续 API 调用失败。建议在启动时验证必需的配置。

 API_KEY = os.getenv("ds_api_key") 
 BASE_URL = "https://api.deepseek.com/v1"
 MODEL_NAME = "deepseek-chat"
+
+if not API_KEY:
+    raise ValueError("错误: 环境变量 'ds_api_key' 未设置。请在 .env 文件中配置。")

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	API_KEY = os.getenv("ds_api_key")
	BASE_URL = "https://api.deepseek.com/v1"
	MODEL_NAME = "deepseek-chat"
	API_KEY = os.getenv("ds_api_key")
	BASE_URL = "https://api.deepseek.com/v1"
	MODEL_NAME = "deepseek-chat"
	if not API_KEY:
	raise ValueError("错误: 环境变量 'ds_api_key' 未设置。请在 .env 文件中配置。")

🤖 Prompt for AI Agents

In text2gremlin/Vertical_Text2Gremlin/data/book/book_qa_gen.py around lines 12
to 14, the environment-derived configuration (API_KEY and BASE_URL) is used
without validation; add a startup check that ensures os.getenv("ds_api_key")
returns a non-empty value (otherwise raise a clear RuntimeError or exit with a
logged error message), and optionally validate BASE_URL/MODEL_NAME are set or
have acceptable defaults; perform this validation immediately after these
assignments so the process fails fast with a helpful message when required
config is missing.

[coderabbitai]

🛠️ Refactor suggestion | 🟠 Major

缺少随机种子设置，影响结果可复现性。

random.shuffle() 未设置种子，导致每次运行产生不同的训练/测试集划分，影响实验的可重复性。

在划分数据集前设置随机种子：

+    # 设置随机种子以确保可复现性
+    random.seed(42)
     random.shuffle(data)

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	random.shuffle(data)
	# 设置随机种子以确保可复现性
	random.seed(42)
	random.shuffle(data)

🤖 Prompt for AI Agents

In text2gremlin/Vertical_Text2Gremlin/instruct_convert.py around line 75,
random.shuffle(data) is called without setting a seed which breaks
reproducibility; set a deterministic seed before shuffling (e.g. call
random.seed(SEED) where SEED is a constant or passed-in parameter) so runs
produce the same train/test split, and document or expose the seed so callers
can control or vary it for experiments.

[coderabbitai]

⚠️ Potential issue | 🔴 Critical

消除重复的客户端初始化并修复环境变量不一致

存在以下问题：

1. Lines 12-15 和 16-19 完全重复初始化了 OpenAI 客户端
2. Line 11 加载了 DEEPSEEK_API_KEY 但从未使用
3. 客户端实际使用 ds_api_key 环境变量，造成混淆

应用此 diff 修复：

 load_dotenv()
-api_key = os.environ.get("DEEPSEEK_API_KEY")
-client = OpenAI(
-    api_key=os.getenv("ds_api_key"),
-    base_url="https://api.deepseek.com/v1",
-)
 client = OpenAI(
     api_key=os.getenv("ds_api_key"),
     base_url="https://api.deepseek.com/v1",
 )

建议进一步规范环境变量命名，统一使用 DEEPSEEK_API_KEY：

 load_dotenv()
 client = OpenAI(
-    api_key=os.getenv("ds_api_key"),
+    api_key=os.getenv("DEEPSEEK_API_KEY"),
     base_url="https://api.deepseek.com/v1",
 )

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	load_dotenv()
	api_key = os.environ.get("DEEPSEEK_API_KEY")
	client = OpenAI(
	api_key=os.getenv("ds_api_key"),
	base_url="https://api.deepseek.com/v1",
	)
	client = OpenAI(
	api_key=os.getenv("ds_api_key"),
	base_url="https://api.deepseek.com/v1",
	)
	load_dotenv()
	client = OpenAI(
	api_key=os.getenv("DEEPSEEK_API_KEY"),
	base_url="https://api.deepseek.com/v1",
	)

🤖 Prompt for AI Agents

In text2gremlin/Vertical_Text2Gremlin/llm_handler.py around lines 10 to 19, the
OpenAI client is initialized twice and the environment variable usage is
inconsistent (DEEPSEEK_API_KEY is loaded but ds_api_key is used); remove the
duplicated client initialization, keep a single client creation, use
os.environ.get("DEEPSEEK_API_KEY") (or os.getenv("DEEPSEEK_API_KEY")) for the
api_key parameter so the loaded variable is actually used, and ensure
load_dotenv() remains before reading the env var; also delete the unused
variable assignment to avoid confusion.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

为 LLM 调用添加超时和重试配置

当前 LLM 调用缺少超时配置，可能导致请求无限期挂起。OpenAI 客户端默认超时为 10 分钟，对于生产环境过长。

建议在客户端初始化时配置合理的超时和重试策略：

 client = OpenAI(
     api_key=os.getenv("DEEPSEEK_API_KEY"),
     base_url="https://api.deepseek.com/v1",
+    timeout=30.0,  # 30 秒超时
+    max_retries=3,  # 最多重试 3 次
 )

或者针对单个请求覆盖超时设置：

response = client.with_options(timeout=30.0).chat.completions.create(
    model="deepseek-chat",
    messages=[...],
    ...
)

Based on learnings

🤖 Prompt for AI Agents

In text2gremlin/Vertical_Text2Gremlin/llm_handler.py around lines 56 to 64, the
LLM call has no timeout or retry behavior configured which can cause requests to
hang; update the code to use the client's per-request timeout option (e.g. call
client.with_options(timeout=30.0) before chat.completions.create) or, better,
configure a sensible default timeout and retry policy on the client when
initializing it (set a default timeout like 30s and add a retry strategy with
limited attempts and backoff) so every request fails fast and is retried
deterministically.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

为 LLM 调用添加超时和重试配置

与 generate_gremlin_variations 函数相同，此处也缺少超时配置。

应用与前述相同的超时和重试配置。

🤖 Prompt for AI Agents

In text2gremlin/Vertical_Text2Gremlin/llm_handler.py around lines 101 to 109,
the LLM call to client.chat.completions.create lacks the timeout and retry
configuration; add the same timeout and retry settings used in
generate_gremlin_variations (apply the same request timeout value and
retry/backoff policy parameters) so the call includes explicit timeout and retry
behavior to avoid hanging or transient failures.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

避免硬编码的文件路径，使用配置管理

硬编码的输入输出路径降低了代码的可移植性和可测试性。

建议使用环境变量或配置文件管理路径：

+import os
+from pathlib import Path
+
-INPUT_CSV_PATH = 'test_gremlin_qa_dataset.csv'  # 种子qa数据
-OUTPUT_CSV_PATH = 'augmented_text2gremlin.csv' # 输出路径
+INPUT_CSV_PATH = os.getenv('INPUT_CSV_PATH', 'test_gremlin_qa_dataset.csv')
+OUTPUT_CSV_PATH = os.getenv('OUTPUT_CSV_PATH', 'augmented_text2gremlin.csv')
 CHUNK_SIZE = 100        # 每次从CSV中读取的行数
 WRITE_THRESHOLD = 200   # 缓冲区中累积多少条新数据，持久化写入一次
 GROUP_SIZE = 5          # 泛化时参考的同组问题数量

或者使用配置类：

from dataclasses import dataclass

@dataclass
class Config:
    input_csv_path: str = 'test_gremlin_qa_dataset.csv'
    output_csv_path: str = 'augmented_text2gremlin.csv'
    chunk_size: int = 100
    write_threshold: int = 200
    group_size: int = 5

config = Config()

🤖 Prompt for AI Agents

In text2gremlin/Vertical_Text2Gremlin/qa_generalize.py around lines 8 to 12, the
input/output paths and other constants are hard-coded; replace these with
configurable values via environment variables or a config object/class and
default to the current literals. Specifically: create a Config dataclass or read
from os.environ (with sensible defaults) to supply input_csv_path,
output_csv_path, chunk_size, write_threshold, and group_size; update any
imports/usage to reference the config instance instead of the hard-coded
constants so the script can be configured in different environments and is
easier to test.

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (8)

text2gremlin/Vertical_Text2Gremlin/graph2gremlin.py (4)

185-187: 改进错误处理和诊断信息

当前的异常处理过于宽泛且缺乏足够的诊断信息：

• 使用泛化的 except Exception 捕获所有错误
• 仅通过 print 输出错误，不适合生产环境
• 调用方无法区分失败类型（网络错误、API 限流、解析错误等）

建议改进错误处理：

-    except Exception as e:
-        print(f"调用API时出错: {e}")
+    except json.JSONDecodeError as e:
+        print(f"解析API响应失败: {e}")
+        print(f"原始响应: {response.choices[0].message.content if 'response' in locals() else 'N/A'}")
+    except Exception as e:
+        print(f"调用API时出错 (类型: {type(e).__name__}): {e}")
+        import traceback
+        traceback.print_exc()
         return []

---

106-107: 考虑使用参数化查询以增强安全性

当前使用简单的字符串转义（replace("'", "\\'")）来防止注入，这在大多数情况下是有效的，但不是最安全的方法。

如果 Gremlin 客户端支持参数化查询，建议使用参数化方式构建查询：

# 示例（取决于具体的 Gremlin 客户端实现）:
query_template = "g.V().has(?, ?, ?).values(?)"
params = [node_type, id_prop, entity_name, prop]
# 然后通过客户端执行参数化查询

如果当前的字符串转义方式已满足需求，可以保持现状。

---

214-216: 使输出路径可配置

输出文件路径 test_gremlin_qa_dataset.csv 是硬编码的相对路径，可能会导致：

• 在不同目录运行时输出位置不一致
• 无法自定义输出目录和文件名
• 注意：第 216 行的日志消息提到 gremlin_qa_dataset.csv，与实际文件名不一致

建议将输出路径作为参数或环境变量：

-def main(num_to_generate=500, questions_per_query=3):
+def main(num_to_generate=500, questions_per_query=3, output_path=None):
     if not setup_component_library():
         print("已终止。")
         return
 
+    if output_path is None:
+        output_path = os.getenv('OUTPUT_PATH', 'test_gremlin_qa_dataset.csv')
+
     # ... existing code ...
     
     print(f"\n--- 生成完成！共获得 {len(all_qa_pairs)} 条 QA 对 ---")
     output_df = pd.DataFrame(all_qa_pairs)
-    output_df.to_csv("test_gremlin_qa_dataset.csv", index=False, encoding='utf-8-sig')
-    print("数据集已保存到 gremlin_qa_dataset.csv")
+    output_df.to_csv(output_path, index=False, encoding='utf-8-sig')
+    print(f"数据集已保存到 {output_path}")

---

177-181: 考虑将 temperature 设置参数化

使用了 temperature=1.3，这是一个较高的值，会增加输出的随机性和多样性。虽然这对于生成多样化的问题可能是有意的，但建议：

• 将其作为可配置参数，以便于调优
• 在文档中说明选择该值的原因

-def translate_and_paraphrase(query, description, num_variants=5):
+def translate_and_paraphrase(query, description, num_variants=5, temperature=1.3):
     """Gremlin翻译"""
     if not query: return []
     prompt = f"""
     # ... 
     """
     try:
         print("调用API生成问题...")
         response = client.chat.completions.create(
             model="deepseek-chat",
             messages=[{"role": "user", "content": prompt}],
-            temperature=1.3
+            temperature=temperature
         )

text2gremlin/Vertical_Text2Gremlin/llm_handler.py (4)

10-16: 添加环境变量验证

当前代码未验证环境变量是否成功加载，如果 .env 文件缺失或变量未设置，客户端初始化可能会失败但错误不明确。

建议添加显式验证：

 load_dotenv()
 
 API_KEY = os.getenv("API_KEY")
 MODEL_NAME = os.getenv("MODEL_NAME")
 BASE_URL = os.getenv("BASE_URL")
+
+# 验证必需的环境变量
+if not API_KEY:
+    raise ValueError("环境变量 API_KEY 未设置")
+if not MODEL_NAME:
+    raise ValueError("环境变量 MODEL_NAME 未设置")
+if not BASE_URL:
+    raise ValueError("环境变量 BASE_URL 未设置")
+
 client = OpenAI(
     api_key=API_KEY,
     base_url=BASE_URL,
 )

---

22-49: 考虑将提示词模板外部化

当前提示词直接硬编码在函数中，这使得：

• 难以进行提示词工程和迭代优化
• 无法进行 A/B 测试不同的提示词版本
• 代码可读性受到长字符串的影响

建议将提示词模板提取到配置文件或单独的模块中：

# prompts.py
GREMLIN_VARIATION_SYSTEM_PROMPT = """
你是一位精通图数据库和 Gremlin 查询语言的专家。
...
"""

GREMLIN_VARIATION_USER_PROMPT_TEMPLATE = """
请基于以下种子数据,为我生成{num_variations}个Gremlin查询变体...
"""

# llm_handler.py
from .prompts import GREMLIN_VARIATION_SYSTEM_PROMPT, GREMLIN_VARIATION_USER_PROMPT_TEMPLATE

def generate_gremlin_variations(seed_query: str, seed_questions: List[str]) -> List[str]:
    system_prompt = GREMLIN_VARIATION_SYSTEM_PROMPT
    user_prompt = GREMLIN_VARIATION_USER_PROMPT_TEMPLATE.format(
        num_variations="3-5",
        seed_questions=json.dumps(seed_questions, ensure_ascii=False),
        seed_query=seed_query
    )
    # ...

---

60-60: 记录 temperature 参数选择的依据

两个函数使用了略有不同的 temperature 值：

• generate_gremlin_variations: 1.3 (line 60)
• generate_texts_for_gremlin: 1.4 (line 104)

虽然这种差异可能是基于实验结果的有意选择，但建议在文档或注释中说明原因，或者考虑将这些值提取为模块级常量以便于调整。

# 模块级常量
GREMLIN_VARIATION_TEMPERATURE = 1.3  # 用于生成查询变体
TEXT_GENERATION_TEMPERATURE = 1.4    # 用于生成自然语言问题

def generate_gremlin_variations(...):
    # ...
    response = client.chat.completions.create(
        # ...
        temperature=GREMLIN_VARIATION_TEMPERATURE
    )

---

62-66: 考虑添加响应格式验证

当前代码使用 response_format={'type': 'json_object'} 要求 LLM 返回 JSON，但仅通过 .get() 方法访问期望的字段，没有验证：

• JSON 结构是否符合预期
• 返回的列表是否为空
• 列表元素的类型是否正确

可以添加简单的验证逻辑：

     try:
         response = client.chat.completions.create(
             # ...
         )
         content = response.choices[0].message.content
-        return json.loads(content).get("gremlin_variations", [])
+        data = json.loads(content)
+        variations = data.get("gremlin_variations", [])
+        if not isinstance(variations, list):
+            print(f"警告: gremlin_variations 不是列表类型: {type(variations)}")
+            return []
+        if not variations:
+            print("警告: LLM 返回了空的变体列表")
+        return variations
     except Exception as e:
         print(f"Error calling LLM for Gremlin generation: {e}")
         return []

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 4120356 and 67b523a.

📒 Files selected for processing (2)

• text2gremlin/Vertical_Text2Gremlin/graph2gremlin.py (1 hunks)
• text2gremlin/Vertical_Text2Gremlin/llm_handler.py (1 hunks)

🧰 Additional context used

🧠 Learnings (2)

📓 Common learnings

Learnt from: CR
PR: hugegraph/hugegraph-ai#0
File: hugegraph-llm/AGENTS.md:0-0
Timestamp: 2025-09-16T06:40:44.968Z
Learning: Applies to hugegraph-llm/src/hugegraph_llm/operators/gremlin_generate_task.py : Maintain the Text2Gremlin pipeline in src/hugegraph_llm/operators/gremlin_generate_task.py

📚 Learning: 2025-09-16T06:40:44.968Z

Learnt from: CR
PR: hugegraph/hugegraph-ai#0
File: hugegraph-llm/AGENTS.md:0-0
Timestamp: 2025-09-16T06:40:44.968Z
Learning: Applies to hugegraph-llm/src/hugegraph_llm/operators/gremlin_generate_task.py : Maintain the Text2Gremlin pipeline in src/hugegraph_llm/operators/gremlin_generate_task.py

Applied to files:

• text2gremlin/Vertical_Text2Gremlin/graph2gremlin.py

🪛 GitHub Actions: License header & 3rd-party check

text2gremlin/Vertical_Text2Gremlin/llm_handler.py

[error] 1-1: Missing or invalid license header.

text2gremlin/Vertical_Text2Gremlin/graph2gremlin.py

[error] 1-1: Missing or invalid license header.

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: build (3.10)

[coderabbitai]

⚠️ Potential issue | 🔴 Critical

添加 Apache-2.0 许可证头以修复管道失败

管道检查报告缺少许可证头。根据项目约定，所有源文件都应包含 Apache-2.0 许可证声明。

在文件开头添加以下许可证头：

+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
 import pandas as pd

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	import pandas as pd
	# Licensed to the Apache Software Foundation (ASF) under one
	# or more contributor license agreements. See the NOTICE file
	# distributed with this work for additional information
	# regarding copyright ownership. The ASF licenses this file
	# to you under the Apache License, Version 2.0 (the
	# "License"); you may not use this file except in compliance
	# with the License. You may obtain a copy of the License at
	#
	# http://www.apache.org/licenses/LICENSE-2.0
	#
	# Unless required by applicable law or agreed to in writing,
	# software distributed under the License is distributed on an
	# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	# KIND, either express or implied. See the License for the
	# specific language governing permissions and limitations
	# under the License.
	import pandas as pd

🧰 Tools

🪛 GitHub Actions: License header & 3rd-party check

[error] 1-1: Missing or invalid license header.

🤖 Prompt for AI Agents

In text2gremlin/Vertical_Text2Gremlin/graph2gremlin.py around lines 1 to 1, the
file is missing the required Apache-2.0 license header which causes the pipeline
check to fail; add the standard project Apache-2.0 license header (the exact
header used across the repo) as the very first lines of the file before any
imports, matching the project template (include copyright year and owner as used
in other files).

[coderabbitai]

⚠️ Potential issue | 🔴 Critical

添加 Apache-2.0 许可证头以修复管道失败

管道检查报告缺少许可证头。根据项目约定，所有源文件都应包含 Apache-2.0 许可证声明。

在文件开头添加以下许可证头：

+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
 # LLM交互模块，泛化qa数据

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	# LLM交互模块，泛化qa数据
	# Licensed to the Apache Software Foundation (ASF) under one
	# or more contributor license agreements. See the NOTICE file
	# distributed with this work for additional information
	# regarding copyright ownership. The ASF licenses this file
	# to you under the Apache License, Version 2.0 (the
	# "License"); you may not use this file except in compliance
	# with the License. You may obtain a copy of the License at
	#
	# http://www.apache.org/licenses/LICENSE-2.0
	#
	# Unless required by applicable law or agreed to in writing,
	# software distributed under the License is distributed on an
	# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	# KIND, either express or implied. See the License for the
	# specific language governing permissions and limitations
	# under the License.
	# LLM交互模块，泛化qa数据

🧰 Tools

🪛 GitHub Actions: License header & 3rd-party check

[error] 1-1: Missing or invalid license header.

🤖 Prompt for AI Agents

In text2gremlin/Vertical_Text2Gremlin/llm_handler.py around line 1, the file is
missing the required Apache-2.0 license header which causes the pipeline check
to fail; add the standard Apache License 2.0 header comment block at the very
top of the file (before any code or imports), matching the project's canonical
header format (including copyright line, SPDX identifier if used, and the full
Apache-2.0 notice) so the file complies with repository licensing checks.

[Copilot]

Pull Request Overview

This PR introduces a comprehensive Text-to-Gremlin corpus generation system designed for LLM-based graph query synthesis. The system includes two main approaches: a vertical scenario generation pipeline using template-based methods and LLM augmentation, and a general scenario corpus generation system using recursive backtracking with recipe-guided generation.

• Template-based Gremlin query generation with syntax validation and LLM-powered question-answer pair creation
• Recursive backtracking recipe-guided generation system for large-scale diverse training data
• Complete data processing pipeline from raw markdown documentation to fine-tuned training datasets

Reviewed Changes

Copilot reviewed 60 out of 91 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
text2gremlin/Vertical_Text2Gremlin/qa_generalize.py	Main generalization pipeline for processing seed QA data with LLM and syntax validation
text2gremlin/Vertical_Text2Gremlin/llm_handler.py	LLM interaction module for generating Gremlin variations and corresponding text questions
text2gremlin/Vertical_Text2Gremlin/instruct_convert.py	Instruction format conversion and training/test set division utilities
text2gremlin/Vertical_Text2Gremlin/gremlin_checker.py	ANTLR4-based Gremlin syntax validation system
text2gremlin/Vertical_Text2Gremlin/graph2gremlin.py	Template-based initial Gremlin data generation with graph schema integration
text2gremlin/Vertical_Text2Gremlin/db_data/schema/movie_schema.json	Movie database schema definition with vertices and edges
text2gremlin/Vertical_Text2Gremlin/db_data/movie/raw_data/*.csv	Movie database raw data files for vertices and edges
text2gremlin/Vertical_Text2Gremlin/data/book/*.py	Documentation processing pipeline for chunk generation and QA creation

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

Hardcoded model name should use the MODEL_NAME constant defined at line 11 for consistency and maintainability.

Suggested change

	model="deepseek-chat",
	model=MODEL_NAME,

[Copilot]

Hardcoded absolute paths should be replaced with relative paths or configurable paths to improve portability and maintainability.

Suggested change

	persons_df = pd.read_csv('/root/lzj/ospp/schema_gremlin/db_data/movie/raw_data/vertex_person.csv', header=1)
	movies_df = pd.read_csv('/root/lzj/ospp/schema_gremlin/db_data/movie/raw_data/vertex_movie.csv', header=1)
	# 获取CSV文件路径，优先使用环境变量，否则使用相对路径
	base_dir = os.path.dirname(os.path.abspath(__file__))
	person_csv_path = os.getenv("PERSON_CSV_PATH", os.path.join(base_dir, "db_data/movie/raw_data/vertex_person.csv"))
	movie_csv_path = os.getenv("MOVIE_CSV_PATH", os.path.join(base_dir, "db_data/movie/raw_data/vertex_movie.csv"))
	persons_df = pd.read_csv(person_csv_path, header=1)
	movies_df = pd.read_csv(movie_csv_path, header=1)

[Copilot]

Hardcoded file paths should be made configurable through command line arguments or configuration files to improve flexibility.

[Copilot]

Commented code and hardcoded filenames should be removed or made configurable. The commented line should be deleted and file paths should be parameterized.

Suggested change

	INPUT_FILE = "gremlin_book_chunks.jsonl"
	# INPUT_FILE = "test.jsonl"
	OUTPUT_FILE = "gremlin_qa_dataset_final_epoch_3.jsonl"
	INPUT_FILE = os.getenv("INPUT_FILE", "gremlin_book_chunks.jsonl")
	OUTPUT_FILE = os.getenv("OUTPUT_FILE", "gremlin_qa_dataset_final_epoch_3.jsonl")

[Copilot]

Hardcoded filename should be made configurable through command line arguments or constants to improve flexibility.

[coderabbitai]

Actionable comments posted: 10

♻️ Duplicate comments (7)

text2gremlin/AST_Text2Gremlin/README.md (1)

34-47: 代码块缺少语言标识符

此代码块缺少语言标识符，影响 Markdown 渲染。这个问题在之前的评审中已被指出。

应用此差异：

-```
+```text
 ├── generate_corpus.py              # 主程序
 ├── gremlin_templates.csv           # 模板文件
 ...

</blockquote></details>
<details>
<summary>text2gremlin/AST_Text2Gremlin/base/Config.py (3)</summary><blockquote>

`8-15`: **消除重复的导入语句**

发现重复导入：`json` 被导入两次（第9行和第12行），`pandas` 被导入两次（第10行和第14行），`random` 被导入两次（第13行和第174行），`typing` 的导入也重复。这个问题在之前的评审中已被指出。


应用此差异：

```diff
 import os
 import json
+import random
 import pandas as pd
-from typing import List, Dict
-import json
-import random
-import pandas as pd
-from typing import List, Dict, Any, Tuple
+from typing import List, Dict, Any, Tuple

---

21-23: 缺少异常处理可能导致启动失败

load_config 方法直接打开并解析 JSON 文件，但没有处理 FileNotFoundError 或 json.JSONDecodeError 等异常。如果配置文件缺失或格式错误，会导致程序崩溃且错误信息不清晰。这个问题在之前的评审中已被指出。

建议添加异常处理并提供清晰的错误消息：

 def load_config(self):
-    with open(self.file_path, "r") as file:
-        return json.load(file)
+    try:
+        with open(self.file_path, "r", encoding="utf-8") as file:
+            return json.load(file)
+    except FileNotFoundError:
+        raise FileNotFoundError(f"配置文件不存在: {self.file_path}")
+    except json.JSONDecodeError as e:
+        raise ValueError(f"配置文件 JSON 格式错误: {self.file_path}, 错误: {e}")

---

60-62: 潜在的 KeyError 风险

get_schema_path 方法在访问 schema_dict[db_id] 时可能抛出 KeyError，如果 db_id 在字典中不存在。注释中提到 "todo error check"，但尚未实现。这个问题在之前的评审中已被指出。

建议添加错误检查：

 def get_schema_path(self, db_id):
     schema_dict = self.config_data.get("db_schema_path")
-    return schema_dict[db_id]  # todo error check
+    if not schema_dict:
+        raise ValueError("配置中缺少 'db_schema_path' 字段")
+    if db_id not in schema_dict:
+        raise KeyError(f"未找到 db_id '{db_id}' 对应的 schema 路径")
+    return schema_dict[db_id]

text2gremlin/AST_Text2Gremlin/base/Schema.py (2)

8-15: 消除重复的导入语句

发现重复导入：json 被导入两次（第9行和第12行），pandas 被导入两次（第10行和第14行），random 被导入两次（第13行和第174行），typing 的导入也重复。这个问题在之前的评审中已被指出。

应用此差异：

 import os
 import json
+import random
 import pandas as pd
-from typing import List, Dict
-import json
-import random
-import pandas as pd
-from typing import List, Dict, Any, Tuple
+from typing import List, Dict, Any, Tuple

---

136-141: 修复潜在的 KeyError 风险

get_step_result_label 方法在第138-139行直接访问 self.edges[step_param] 而没有检查键是否存在，可能导致 KeyError。这个问题在之前的评审中已被指出。

应用此差异：

 def get_step_result_label(self, start_label: str, step: Dict) -> Tuple[str, str]:
     step_name, step_param = step.get('step'), step.get('param')
-    if step_name == 'out': return self.edges[step_param]['destination'], 'vertex'
-    if step_name == 'in': return self.edges[step_param]['source'], 'vertex'
+    if step_name == 'out':
+        if step_param in self.edges:
+            return self.edges[step_param]['destination'], 'vertex'
+        return None, None
+    if step_name == 'in':
+        if step_param in self.edges:
+            return self.edges[step_param]['source'], 'vertex'
+        return None, None
     if step_name in ['properties', 'has', 'values']: return start_label, 'vertex'
     return None, None

text2gremlin/AST_Text2Gremlin/base/generator.py (1)

303-304: 将 datetime 的导入移至文件顶部（PEP 8）

+from datetime import datetime
@@
-    from datetime import datetime

Also applies to: 7-11

🧹 Nitpick comments (14)

text2gremlin/AST_Text2Gremlin/requirements.txt (1)

46-46: 添加文件末尾换行符。

根据 PEP 8 惯例，Python 文件应以换行符结尾。建议在 Line 46 之后添加一个空行。

text2gremlin/AST_Text2Gremlin/output/README.md (1)

8-10: 建议为代码块添加语言标识符

根据静态分析提示，此代码块缺少语言标识符，会影响 Markdown 渲染效果。

应用此差异：

-```
+```text
 generated_corpus_YYYYMMDD_HHMMSS.json

</blockquote></details>
<details>
<summary>text2gremlin/AST_Text2Gremlin/README.md (2)</summary><blockquote>

`183-191`: **代码块缺少语言标识符**

此代码块缺少语言标识符，建议添加以改善渲染效果。

应用此差异：

```diff
-```
+```text
 模板: g.V().hasLabel('person').out('acted_in')
 
 泛化:
 ...

---

`205-209`: **代码块缺少语言标识符**

此代码块缺少语言标识符，建议添加以改善渲染效果。

应用此差异：

```diff
-```
+```text
 g.V().hasLabel('person').out('acted_in').has('title', 'Inception')
 ↓
 从图中开始查找所有顶点，过滤出'人'类型的顶点，沿'参演'边out方向遍历，其'标题'为'Inception'

</blockquote></details>
<details>
<summary>text2gremlin/AST_Text2Gremlin/output/SYNTAX_ANALYSIS_SUMMARY.md (1)</summary><blockquote>

`45-56`: **建议为代码块添加语言标识符**

此代码块显示步骤分类占比的可视化条形图，缺少语言标识符。

应用此差异：

```diff
-```
+```text
 过滤步骤 ████████████████████████████████ 29.63%
 图遍历   ████████████████████████ 23.47%
 起始步骤 ████████████████████ 20.17%
 ...

</blockquote></details>
<details>
<summary>text2gremlin/AST_Text2Gremlin/base/Schema.py (1)</summary><blockquote>

`174-174`: **冗余的 import 语句**

第174行在函数内部导入 `random`，但该模块已在文件顶部第13行导入过。

应用此差异：

```diff
     """
-    import random
-    
     is_edge = label in self.edges

text2gremlin/AST_Text2Gremlin/base/CombinationController.py (4)

57-79: 可重复性与测试性：注入 RNG 而非直接使用 random 模块

为便于复现实验、编写单测与 A/B，对随机性统一注入随机数生成器。

示例改造（展示关键点，类似处同改）：

-from typing import List, Dict, Any
+from typing import List, Dict, Any, Optional
 import random
 ...
-    def __init__(self, config: Dict):
+    def __init__(self, config: Dict, rng: Optional[random.Random] = None):
         ...
-        self.config = config
+        self.config = config
+        self.rng = rng or random.Random()
 ...
-        return random.random() < probability
+        return self.rng.random() < probability
 ...
-            target = random.randint(min_count, max_count)
+            target = self.rng.randint(min_count, max_count)
 ...
-            selected.extend(random.sample(other_options, sample_count))
+            selected.extend(self.rng.sample(other_options, sample_count))
 ...
-            combo = random.sample(other_options, param_count)
+            combo = self.rng.sample(other_options, param_count)
 ...
-            return random.randint(min_times, max_times)
+            return self.rng.randint(min_times, max_times)

Also applies to: 95-99, 138-147, 209-218, 239-242

---

121-149: select_sibling_options 返回别名列表且与“必须包含配方项”表述可能不一致

• full_coverage 分支直接返回传入的 all_options（引用同一列表），上层如修改将产生副作用。
• 若 recipe_option 不在 all_options，docstring 表述“必须包含”与实际不一致。

建议：

• 返回副本，避免别名副作用：

-            return all_options
+            return list(all_options)

• 若要确保“必须包含”，在 full_coverage 分支也应合并 recipe_option（若存在且未包含），或更新注释明确例外情况。

---

150-219: 多参数组合去重未考虑“组合无序等价”，可能产生成本高的重复

当前用 list 比较去重，['a','b'] 与 ['b','a'] 被视为不同；若语义上无序等价（如 hasLabel），会引入重复。

在组合阶段用规范化 key 去重，并保留原顺序输出：

-        combinations = []
+        combinations = []
+        seen = set()
 ...
-        combinations.append(recipe_params.copy())
+        combinations.append(recipe_params.copy())
+        seen.add(tuple(sorted(recipe_params)))
 ...
-            combo = random.sample(other_options, param_count)
+            combo = random.sample(other_options, param_count)
             # 避免重复组合
-            if combo not in combinations:
-                combinations.append(combo)
+            key = tuple(sorted(combo))
+            if key not in seen:
+                seen.add(key)
+                combinations.append(combo)

如某些步骤顺序确实重要，请按步骤类型选择是否使用排序作为 key。

---

262-283: 调试输出使用 print，建议切换到 logging 并可由配置开关控制

库代码直接 print 会干扰上层应用输出与测试快照。

• 使用标准 logging（模块级 logger）。
• 通过配置或构造参数开启/关闭调试输出（如 verbose/debug）。

text2gremlin/AST_Text2Gremlin/base/generator.py (4)

56-62: 语法检查未捕捉词法错误：也应为 Lexer 安装 ErrorListener

目前仅为 Parser 安装监听器，Lexer 报错不会被统计。

最小改动如下：

-        # 移除默认的控制台错误监听器
-        parser.removeErrorListeners()
-        
-        # 添加自定义的监听器
-        error_listener = SyntaxErrorListener()
-        parser.addErrorListener(error_listener)
+        # 移除默认监听器
+        lexer.removeErrorListeners()
+        parser.removeErrorListeners()
+        # 添加自定义监听器
+        error_listener = SyntaxErrorListener()
+        lexer.addErrorListener(error_listener)
+        parser.addErrorListener(error_listener)

---

136-151: 性能优化：先做全局去重，再做语法检查

重复查询此前已通过过语法检查，无需再次解析，先判重可显著降低解析成本。

-            try:
-                # 首先进行语法检查
-                is_valid, error_msg = check_gremlin_syntax(query)
-                
-                if not is_valid:
-                    syntax_error_count += 1
-                    continue
-                    
-                if query not in global_corpus_dict:
+            try:
+                # 先判重，避免对重复项做语法检查
+                if query in global_corpus_dict:
+                    duplicate_count += 1
+                    continue
+                # 再进行语法检查
+                is_valid, error_msg = check_gremlin_syntax(query)
+                if not is_valid:
+                    syntax_error_count += 1
+                    continue
-                    global_corpus_dict[query] = description
+                global_corpus_dict[query] = description
                 new_pairs_count += 1
-                else:
-                    # 重复的查询，跳过
-                    duplicate_count += 1

---

305-326: 确保输出文件目录存在，避免 FileNotFoundError

写文件前未创建父目录，可能在自定义路径下失败。

-    if output_file:
+    if output_file:
+        # 确保输出目录存在
+        out_dir = os.path.dirname(os.path.abspath(output_file))
+        if out_dir:
+            os.makedirs(out_dir, exist_ok=True)
         # 确保只保存成功生成的查询-描述对
         corpus_data = {

---

249-286: 控制台输出建议改用 logging，并通过 verbose 开关控制

生成过程包含大量 print 与 emoji，作为库函数应避免污染 stdout。

• 增加 verbose/quiet 参数或从 Config 读取。
• 用模块级 logger 替换 print（info/warning/exception 分级）。

Also applies to: 387-422

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 67b523a and bccc147.

⛔ Files ignored due to path filters (1)

• text2gremlin/AST_Text2Gremlin/gremlin_templates.csv is excluded by !**/*.csv

📒 Files selected for processing (16)

• text2gremlin/AST_Text2Gremlin/README.md (1 hunks)
• text2gremlin/AST_Text2Gremlin/base/CombinationController.py (1 hunks)
• text2gremlin/AST_Text2Gremlin/base/Config.py (1 hunks)
• text2gremlin/AST_Text2Gremlin/base/GremlinBase.py (1 hunks)
• text2gremlin/AST_Text2Gremlin/base/GremlinExpr.py (1 hunks)
• text2gremlin/AST_Text2Gremlin/base/GremlinParse.py (1 hunks)
• text2gremlin/AST_Text2Gremlin/base/Schema.py (1 hunks)
• text2gremlin/AST_Text2Gremlin/base/__init__.py (1 hunks)
• text2gremlin/AST_Text2Gremlin/base/combination_control_config.json (1 hunks)
• text2gremlin/AST_Text2Gremlin/base/generator.py (1 hunks)
• text2gremlin/AST_Text2Gremlin/config.json (1 hunks)
• text2gremlin/AST_Text2Gremlin/output/README.md (1 hunks)
• text2gremlin/AST_Text2Gremlin/output/SYNTAX_ANALYSIS_SUMMARY.md (1 hunks)
• text2gremlin/AST_Text2Gremlin/output/SYNTAX_DISTRIBUTION_REPORT.md (1 hunks)
• text2gremlin/AST_Text2Gremlin/output/syntax_distribution_stats.json (1 hunks)
• text2gremlin/AST_Text2Gremlin/requirements.txt (1 hunks)

✅ Files skipped from review due to trivial changes (1)

• text2gremlin/AST_Text2Gremlin/output/syntax_distribution_stats.json

🚧 Files skipped from review as they are similar to previous changes (4)

• text2gremlin/AST_Text2Gremlin/config.json
• text2gremlin/AST_Text2Gremlin/base/GremlinParse.py
• text2gremlin/AST_Text2Gremlin/base/GremlinExpr.py
• text2gremlin/AST_Text2Gremlin/base/GremlinBase.py

🧰 Additional context used

🧬 Code graph analysis (3)

text2gremlin/AST_Text2Gremlin/base/__init__.py (1)

text2gremlin/AST_Text2Gremlin/base/generator.py (1)

• generate_gremlin_corpus (178-352)

text2gremlin/AST_Text2Gremlin/base/generator.py (10)

text2gremlin/AST_Text2Gremlin/base/Config.py (1)

• Config (12-65)

text2gremlin/AST_Text2Gremlin/base/Schema.py (1)

• Schema (17-196)

text2gremlin/AST_Text2Gremlin/base/GremlinBase.py (1)

• GremlinBase (11-322)

text2gremlin/AST_Text2Gremlin/base/GremlinParse.py (1)

• Traversal (40-68)

text2gremlin/AST_Text2Gremlin/base/TraversalGenerator.py (2)

• TraversalGenerator (21-3210)
• generate (286-335)

text2gremlin/AST_Text2Gremlin/base/GremlinTransVisitor.py (2)

• GremlinTransVisitor (20-2352)
• parse_and_visit (24-51)

text2gremlin/AST_Text2Gremlin/base/gremlin/GremlinLexer.py (1)

• GremlinLexer (1137-1596)

text2gremlin/AST_Text2Gremlin/base/gremlin/GremlinParser.py (2)

• GremlinParser (1481-32734)
• queryList (2356-2400)

hugegraph-python-client/src/pyhugegraph/client.py (1)

• schema (61-62)

hugegraph-python-client/src/pyhugegraph/structure/response_data.py (1)

• result (34-35)

text2gremlin/AST_Text2Gremlin/base/Config.py (1)

text2gremlin/AST_Text2Gremlin/base/GremlinBase.py (2)

• get_schema_dict_path (327-328)
• get_syn_dict_path (329-330)

🪛 GitHub Actions: License header & 3rd-party check

text2gremlin/AST_Text2Gremlin/base/__init__.py

[error] 1-1: License header is missing or invalid.

text2gremlin/AST_Text2Gremlin/base/CombinationController.py

[error] 1-1: License header is missing or invalid.

text2gremlin/AST_Text2Gremlin/requirements.txt

[error] 1-1: Dependency review detected vulnerable packages. GHSA-4xh5-x5gv-qwph (pip 25.1.1 tar extraction vulnerability).

text2gremlin/AST_Text2Gremlin/base/generator.py

[error] 1-1: License header is missing or invalid.

text2gremlin/AST_Text2Gremlin/base/Schema.py

[error] 1-1: License header is missing or invalid.

text2gremlin/AST_Text2Gremlin/base/Config.py

[error] 1-1: License header is missing or invalid.

🪛 LanguageTool

text2gremlin/AST_Text2Gremlin/output/SYNTAX_ANALYSIS_SUMMARY.md

[uncategorized] ~93-~93: 动词的修饰一般为‘形容词（副词）+地+动词’。您的意思是否是：常见"地"过滤
Context: ... (大于) 占 8.44%，用于数值比较 - 说明：排除模式是最常见的过滤需求 --- ## 💡 实践建议 ### 对于查询优化 1. *...

(wb4)

text2gremlin/AST_Text2Gremlin/output/SYNTAX_DISTRIBUTION_REPORT.md

[grammar] ~262-~262: Ensure spelling is correct
Context: ...s**: 这两个过滤步骤使用最频繁 2. **优化出边遍历**: out步骤占比最高 3. **优化groupCount`**: 聚合操作需要特别关注性能 ### 对于文...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

text2gremlin/AST_Text2Gremlin/README.md

[uncategorized] ~27-~27: 动词的修饰一般为‘形容词（副词）+地+动词’。您的意思是否是：流畅"地"查询
Context: ...**: 自动控制组合爆炸，避免生成过多查询 - 中文描述: 自动生成流畅的查询描述 - 语法分析: 统计生成查询的语法分布 --- ## 项目...

(wb4)

---

[uncategorized] ~199-~199: 动词的修饰一般为‘形容词（副词）+地+动词’。您的意思是否是：相同"地"查询
Context: ...属性积极泛化，数据值保守填充 ### 3. 自动去重 - 查询级去重（完全相同的查询） - 语义级去重（等价查询） - 保证生成的查询都是唯一的 ### 4....

(wb4)

🪛 markdownlint-cli2 (0.18.1)

text2gremlin/AST_Text2Gremlin/output/SYNTAX_ANALYSIS_SUMMARY.md

45-45: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

text2gremlin/AST_Text2Gremlin/output/SYNTAX_DISTRIBUTION_REPORT.md

48-48: Tables should be surrounded by blank lines

(MD058, blanks-around-tables)

---

54-54: Tables should be surrounded by blank lines

(MD058, blanks-around-tables)

---

71-71: Tables should be surrounded by blank lines

(MD058, blanks-around-tables)

---

86-86: Tables should be surrounded by blank lines

(MD058, blanks-around-tables)

---

100-100: Tables should be surrounded by blank lines

(MD058, blanks-around-tables)

---

113-113: Tables should be surrounded by blank lines

(MD058, blanks-around-tables)

---

129-129: Tables should be surrounded by blank lines

(MD058, blanks-around-tables)

---

139-139: Tables should be surrounded by blank lines

(MD058, blanks-around-tables)

---

149-149: Tables should be surrounded by blank lines

(MD058, blanks-around-tables)

---

157-157: Tables should be surrounded by blank lines

(MD058, blanks-around-tables)

---

168-168: Tables should be surrounded by blank lines

(MD058, blanks-around-tables)

---

177-177: Tables should be surrounded by blank lines

(MD058, blanks-around-tables)

---

186-186: Tables should be surrounded by blank lines

(MD058, blanks-around-tables)

---

197-197: Tables should be surrounded by blank lines

(MD058, blanks-around-tables)

text2gremlin/AST_Text2Gremlin/README.md

34-34: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

183-183: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

205-205: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

text2gremlin/AST_Text2Gremlin/output/README.md

8-8: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: build (3.10)
• GitHub Check: build (3.11)

🔇 Additional comments (6)

text2gremlin/AST_Text2Gremlin/output/SYNTAX_DISTRIBUTION_REPORT.md (1)

1-277: LGTM! 统计报告内容详尽

该文档提供了全面的 Gremlin 语法词汇分布统计，包括总体统计、Top 20 最常用步骤、步骤分类统计、谓词分布、关键发现和使用建议。结构清晰，数据完整，对于理解生成的查询语料库特征非常有帮助。

注：静态分析工具提示的表格周围空行问题是格式偏好，不影响文档的可读性和功能性。

text2gremlin/AST_Text2Gremlin/output/SYNTAX_ANALYSIS_SUMMARY.md (1)

1-178: LGTM! 分析总结全面且有价值

该文档提供了基于 1,493 个查询的深度语法分析，包括核心发现、关键数据、深度分析、实践建议和分析方法说明。内容详实，对于优化查询引擎、设计测试用例和编写文档都提供了数据支持。

text2gremlin/AST_Text2Gremlin/base/__init__.py (1)

14-19: LGTM! 包初始化设置正确

模块正确导出了主要的 API 接口 generate_gremlin_corpus，版本号已定义，__all__ 列表也已配置。结构清晰简洁。

text2gremlin/AST_Text2Gremlin/base/combination_control_config.json (1)

1-279: LGTM! 配置文件结构完善

该 JSON 配置文件定义了全面的组合控制策略，包括：

• 链长度分类阈值
• 随机增强控制
• 数据值填充策略
• 属性泛化策略（针对不同链长度）
• 总查询数量限制
• 多参数泛化控制
• 嵌套遍历泛化控制

每个配置项都包含详细的描述、示例和使用说明，便于理解和维护。配置参数设计合理，考虑了不同场景下的需求，能够有效控制查询生成的组合爆炸问题。

text2gremlin/AST_Text2Gremlin/base/Schema.py (1)

61-98: LGTM! CSV 解析实现稳健

_parse_custom_csv 方法处理多行表头的 CSV 文件，包含了以下良好实践：

• 处理重复列名（添加后缀）
• 异常处理（捕获 FileNotFoundError 和 IndexError）
• 返回空 DataFrame 作为失败时的安全回退

这种实现方式确保了数据加载的健壮性。

text2gremlin/AST_Text2Gremlin/base/generator.py (1)

38-49: 项目已支持 Python 3.10+，新型类型注解语法完全适配，无需修改

项目 pyproject.toml 已明确指定 requires-python = ">=3.10"，此版本完全支持 PEP 585 新型类型注解语法（list[str]、tuple[bool, str] 等）。无需改为 typing.List/typing.Tuple 或添加 __future__ 导入。

Likely an incorrect or invalid review comment.

[coderabbitai]

⚠️ Potential issue | 🔴 Critical

num_queries 参数未生效，可能导致组合爆炸与资源消耗不可控

generate_gremlin_corpus 的 num_queries 没有约束每模板的产出，属功能性缺陷。

两种可行修复（择一）：

• A. 将 limit 贯穿到 generate_corpus_from_template 并在该函数内截断：

- def generate_corpus_from_template(
+ from typing import Optional
+ def generate_corpus_from_template(
     template_string: str,
     config: Config,
     schema: Schema,
     gremlin_base: GremlinBase,
-    global_corpus_dict: dict
-) -> tuple[int, dict]:
+    global_corpus_dict: dict,
+    limit: Optional[int] = None
+) -> tuple[int, dict]:
@@
-        corpus = generator.generate()
+        corpus = generator.generate()
+        if limit is not None:
+            corpus = corpus[:max(0, int(limit))]
-        stats['generated_count'] = len(corpus)
+        stats['generated_count'] = len(corpus)

并在调用处传入 num_queries：

-            new_pairs_count, template_stats = generate_corpus_from_template(
+            new_pairs_count, template_stats = generate_corpus_from_template(
                 template_string=template,
                 config=config,
                 schema=schema,
                 gremlin_base=gremlin_base,
-                global_corpus_dict=global_corpus_dict
+                global_corpus_dict=global_corpus_dict,
+                limit=num_queries
             )

• B. 若 TraversalGenerator.generate 已支持上限参数，则直接传递（示例）：

-        corpus = generator.generate()
+        corpus = generator.generate(max_count=num_queries)

请按实际签名选择其一。

Also applies to: 252-259, 121-130

🤖 Prompt for AI Agents

In text2gremlin/AST_Text2Gremlin/base/generator.py around lines 178-184 (also
affects 252-259 and 121-130), num_queries currently isn't enforcing a
per-template or generator-level cap, causing uncontrolled output; fix by
threading the num_queries limit into the generation call: either A) extend
generate_corpus_from_template to accept a limit and truncate the produced
queries inside that function, then pass the per-template quota when invoking it,
or B) if TraversalGenerator.generate already accepts a max/limit parameter, pass
num_queries (or a computed per-template cap) directly to
TraversalGenerator.generate; ensure you choose the option matching the actual
function signatures, apply the same change at the other affected call-sites, and
enforce that the total produced queries do not exceed num_queries (e.g., divide
num_queries among templates or stop when the overall count is reached).

[LRriver]

已经有数据爆炸控制策略，我会移除这个参数

[coderabbitai]

@LRriver 好的，明白了！既然已经通过 CombinationController 和相关配置（如 combination_control_config.json 中的 max_total_combinations、max_per_step_choices 等）实现了组合爆炸的控制策略，移除这个未使用的 num_queries 参数确实能让代码更清晰。👍

---

🧠 Learnings used

Learnt from: CR
PR: hugegraph/hugegraph-ai#0
File: hugegraph-llm/AGENTS.md:0-0
Timestamp: 2025-09-16T06:40:44.968Z
Learning: Applies to hugegraph-llm/src/hugegraph_llm/operators/gremlin_generate_task.py : Maintain the Text2Gremlin pipeline in src/hugegraph_llm/operators/gremlin_generate_task.py

[coderabbitai]

⚠️ Potential issue | 🟠 Major

构建工具不应在 requirements.txt 中固定版本。

Lines 29、38 和 46 分别固定了 pip、setuptools 和 wheel 的版本。这些是构建和部署工具，不是运行时依赖，不应出现在 requirements.txt 中。它们应该在 setup.py 的 setup_requires 中或单独的 constraints.txt 中管理。

建议修复：移除这三行：

-pip==25.1.1
-setuptools==80.9.0
-wheel==0.45.1

如果确实需要控制这些工具的版本，考虑在项目的 CI/CD 配置或 pyproject.toml 中指定。

Also applies to: 38-38, 46-46

🤖 Prompt for AI Agents

In text2gremlin/AST_Text2Gremlin/requirements.txt around lines 29, 38 and 46,
remove the pinned build-tool entries (pip, setuptools, wheel) from
requirements.txt; these are build-time tools and should not be listed as runtime
requirements. Delete those three lines and, if you must pin versions, move their
pins into setup_requires in setup.py, a constraints.txt, pyproject.toml, or into
CI/CD configuration instead so runtime requirements remain clean.

---

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

修复 pip 安全漏洞 (GHSA-4xh5-x5gv-qwph)。

Line 29 中的 pip==25.1.1 存在已知安全漏洞（tar 提取漏洞）。此问题已被 GitHub 依赖检查工具检测到，必须在发布前修复。建议升级到最新的安全版本或移除此行（pip 不应该被固定在 requirements.txt 中）。

建议的修复方案：移除 pip 依赖或升级到已修复的版本。请搜索最新的 pip 安全修复版本：

---

🌐 Web query:

pip 25.1.1 安全漏洞 GHSA-4xh5-x5gv-qwph 修复版本

💡 Result:

修复版本：已在 pip 25.2 中修复（受影响版本 < 25.2，包含 25.1.1）。[1][2]

参考：
[1] GitHub Advisory GHSA-4xh5-x5gv-qwph.
[2] OSV / GHSA-4xh5-x5gv-qwph.

---

---

升级 pip 至 25.2 以修复安全漏洞 GHSA-4xh5-x5gv-qwph，并优化依赖管理。

第 29 行的 pip==25.1.1 存在已知安全漏洞（tar 提取漏洞），已在 pip 25.2 中修复。建议：

• 将 pip==25.1.1 升级至 pip==25.2 或更新版本
• 移除 pip、setuptools（第 38 行）、wheel（第 46 行）这些构建工具从 requirements.txt，改用 pyproject.toml 或单独的 requirements-dev.txt，因为它们不是应用运行时依赖
• 添加文件末尾的空行（符合 PEP 8 规范）

🤖 Prompt for AI Agents

In text2gremlin/AST_Text2Gremlin/requirements.txt around line 29, update the
pinned pip version from pip==25.1.1 to pip==25.2 (or later) to address
GHSA-4xh5-x5gv-qwph; remove build tools pip, setuptools (line ~38) and wheel
(line ~46) from this requirements.txt and relocate them into pyproject.toml or a
separate requirements-dev.txt/constraints file since they are not runtime
dependencies; finally ensure the file ends with a single trailing newline to
satisfy PEP 8.

[coderabbitai]

Actionable comments posted: 4

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between bccc147 and 44592b4.

📒 Files selected for processing (1)

• text2gremlin/AST_Text2Gremlin/README.md (1 hunks)

🧰 Additional context used

🧠 Learnings (1)

📓 Common learnings

Learnt from: CR
PR: hugegraph/hugegraph-ai#0
File: hugegraph-llm/AGENTS.md:0-0
Timestamp: 2025-09-16T06:40:44.968Z
Learning: Applies to hugegraph-llm/src/hugegraph_llm/operators/gremlin_generate_task.py : Maintain the Text2Gremlin pipeline in src/hugegraph_llm/operators/gremlin_generate_task.py

🪛 LanguageTool

text2gremlin/AST_Text2Gremlin/README.md

[uncategorized] ~27-~27: 动词的修饰一般为‘形容词（副词）+地+动词’。您的意思是否是：流畅"地"查询
Context: ...**: 自动控制组合爆炸，避免生成过多查询 - 中文描述: 自动生成流畅的查询描述 - 语法分析: 统计生成查询的语法分布 --- ## 项目...

(wb4)

---

[uncategorized] ~174-~174: 动词的修饰一般为‘形容词（副词）+地+动词’。您的意思是否是：相同"地"查询
Context: ...属性积极泛化，数据值保守填充 ### 3. 自动去重 - 查询级去重（完全相同的查询） - 语义级去重（等价查询） - 保证生成的查询都是唯一的 ### 4....

(wb4)

🪛 markdownlint-cli2 (0.18.1)

text2gremlin/AST_Text2Gremlin/README.md

34-34: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

158-158: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

180-180: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: build (3.11)
• GitHub Check: build (3.10)

🔇 Additional comments (1)

text2gremlin/AST_Text2Gremlin/README.md (1)

112-129: 添加JSON代码块的语言标识符

第114行代码块缺少语言标识符。应该在开始的反引号后添加 json 以支持正确的语法高亮。

 ## 输出格式
 
-```json
+```json
 {
   "metadata": {

请注意：此处已正确包含 json 标识符，请检查原始文件的第114行。

[coderabbitai]

Actionable comments posted: 2

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 44592b4 and a1d614c.

📒 Files selected for processing (14)

• text2gremlin/AST_Text2Gremlin/README.md (1 hunks)
• text2gremlin/AST_Text2Gremlin/base/CombinationController.py (1 hunks)
• text2gremlin/AST_Text2Gremlin/base/Config.py (1 hunks)
• text2gremlin/AST_Text2Gremlin/base/GremlinBase.py (1 hunks)
• text2gremlin/AST_Text2Gremlin/base/GremlinExpr.py (1 hunks)
• text2gremlin/AST_Text2Gremlin/base/GremlinParse.py (1 hunks)
• text2gremlin/AST_Text2Gremlin/base/Schema.py (1 hunks)
• text2gremlin/AST_Text2Gremlin/base/__init__.py (1 hunks)
• text2gremlin/AST_Text2Gremlin/base/generator.py (1 hunks)
• text2gremlin/AST_Text2Gremlin/base/gremlin/GremlinVisitor.py (1 hunks)
• text2gremlin/AST_Text2Gremlin/base/gremlin/__init__.py (1 hunks)
• text2gremlin/AST_Text2Gremlin/config.json (1 hunks)
• text2gremlin/AST_Text2Gremlin/generate_corpus.py (1 hunks)
• text2gremlin/AST_Text2Gremlin/requirements.txt (1 hunks)

✅ Files skipped from review due to trivial changes (1)

• text2gremlin/AST_Text2Gremlin/base/gremlin/init.py

🚧 Files skipped from review as they are similar to previous changes (6)

• text2gremlin/AST_Text2Gremlin/base/init.py
• text2gremlin/AST_Text2Gremlin/base/GremlinParse.py
• text2gremlin/AST_Text2Gremlin/config.json
• text2gremlin/AST_Text2Gremlin/requirements.txt
• text2gremlin/AST_Text2Gremlin/base/Config.py
• text2gremlin/AST_Text2Gremlin/base/gremlin/GremlinVisitor.py

🧰 Additional context used

🧠 Learnings (2)

📓 Common learnings

Learnt from: CR
PR: hugegraph/hugegraph-ai#0
File: hugegraph-llm/AGENTS.md:0-0
Timestamp: 2025-09-16T06:40:44.968Z
Learning: Applies to hugegraph-llm/src/hugegraph_llm/operators/gremlin_generate_task.py : Maintain the Text2Gremlin pipeline in src/hugegraph_llm/operators/gremlin_generate_task.py

📚 Learning: 2025-09-16T06:40:44.968Z

Learnt from: CR
PR: hugegraph/hugegraph-ai#0
File: hugegraph-llm/AGENTS.md:0-0
Timestamp: 2025-09-16T06:40:44.968Z
Learning: Applies to hugegraph-llm/src/hugegraph_llm/operators/gremlin_generate_task.py : Maintain the Text2Gremlin pipeline in src/hugegraph_llm/operators/gremlin_generate_task.py

Applied to files:

• text2gremlin/AST_Text2Gremlin/generate_corpus.py
• text2gremlin/AST_Text2Gremlin/base/GremlinBase.py
• text2gremlin/AST_Text2Gremlin/base/generator.py
• text2gremlin/AST_Text2Gremlin/README.md
• text2gremlin/AST_Text2Gremlin/base/GremlinExpr.py

🧬 Code graph analysis (3)

text2gremlin/AST_Text2Gremlin/generate_corpus.py (2)

text2gremlin/AST_Text2Gremlin/base/generator.py (1)

• generate_gremlin_corpus (198-375)

text2gremlin/AST_Text2Gremlin/base/Config.py (1)

• load_config (39-46)

text2gremlin/AST_Text2Gremlin/base/generator.py (6)

text2gremlin/AST_Text2Gremlin/base/Config.py (1)

• Config (30-92)

text2gremlin/AST_Text2Gremlin/base/Schema.py (1)

• Schema (31-215)

text2gremlin/AST_Text2Gremlin/base/GremlinBase.py (1)

• GremlinBase (29-340)

text2gremlin/AST_Text2Gremlin/base/GremlinParse.py (1)

• Traversal (58-86)

text2gremlin/AST_Text2Gremlin/base/TraversalGenerator.py (2)

• TraversalGenerator (33-3224)
• generate (281-330)

text2gremlin/AST_Text2Gremlin/base/GremlinTransVisitor.py (2)

• GremlinTransVisitor (38-2370)
• parse_and_visit (42-69)

text2gremlin/AST_Text2Gremlin/base/GremlinExpr.py (1)

text2gremlin/AST_Text2Gremlin/base/GremlinParse.py (1)

• add_step (68-75)

🪛 LanguageTool

text2gremlin/AST_Text2Gremlin/README.md

[uncategorized] ~27-~27: 动词的修饰一般为‘形容词（副词）+地+动词’。您的意思是否是：流畅"地"查询
Context: ...**: 自动控制组合爆炸，避免生成过多查询 - 中文描述: 自动生成流畅的查询描述 - 语法分析: 统计生成查询的语法分布 --- ## 项目...

(wb4)

---

[uncategorized] ~170-~170: 动词的修饰一般为‘形容词（副词）+地+动词’。您的意思是否是：相同"地"查询
Context: ...属性积极泛化，数据值保守填充 ### 3. 自动去重 - 查询级去重（完全相同的查询） - 语义级去重（等价查询） - 保证生成的查询都是唯一的 ### 4....

(wb4)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: build (3.10)
• GitHub Check: build (3.11)

🔇 Additional comments (12)

text2gremlin/AST_Text2Gremlin/README.md (1)

1-183: 文档质量良好

README 结构清晰，涵盖了快速开始、核心功能、项目结构、使用方式、配置说明和输出格式等关键信息。之前评审中指出的问题（重复的项目结构、错误的目录路径、pip 安装命令等）已在 bccc147 提交中修复。

静态分析工具提示的语言问题极为轻微（"流畅的查询描述" vs "流畅地查询描述"），属于可选的风格改进，不影响理解。

text2gremlin/AST_Text2Gremlin/base/Schema.py (2)

150-161: 边标签验证处理得当

代码现在对 step_param 是否存在于 self.edges 进行了显式检查，并在缺失时抛出带有清晰错误信息的 KeyError。这种快速失败的策略优于静默返回 (None, None)，有助于尽早发现配置或数据问题。

---

75-112: CSV 解析错误处理稳健

_parse_custom_csv 方法妥善处理了文件缺失和索引错误，返回空 DataFrame 并记录警告，避免了程序崩溃。重复列名处理（lines 87-96）通过添加后缀确保了列名唯一性。

text2gremlin/AST_Text2Gremlin/generate_corpus.py (1)

136-151: 输入验证逻辑完善

文件存在性检查全面，涵盖了模板、配置、schema 和数据目录，并为每种缺失情况提供了清晰的错误消息和退出机制。

text2gremlin/AST_Text2Gremlin/base/GremlinExpr.py (1)

1-120: 数据结构设计简洁明确

各类（Predicate、TextPredicate、AnonymousTraversal、Connector、Terminal）的定义清晰，使用前向声明避免了循环导入问题。__repr__ 方法为调试提供了有用的字符串表示。实现简洁且无明显问题。

text2gremlin/AST_Text2Gremlin/base/GremlinBase.py (1)

102-283: 翻译模板覆盖全面

_initialize_translation_templates 定义了丰富的中文翻译模板，覆盖了 Gremlin 的主要步骤、谓词和操作符。同时支持大小写变体（如 V/v、addV/addv），适配不同的使用习惯。

text2gremlin/AST_Text2Gremlin/base/generator.py (3)

155-175: 语法检查与去重顺序优化

代码先进行去重判断（line 158），再执行语法检查（line 163），避免了对重复查询的冗余语法验证。这种顺序安排提升了性能，且异常处理（lines 173-175）确保单个查询的错误不会中断整个生成流程。

---

222-228: 必需参数验证完善

在函数入口处对 config_path、schema_path 和 data_path 进行了严格验证，在文件不存在时立即抛出 FileNotFoundError，避免了在后续处理中出现难以追踪的错误。

---

271-317: 逐模板错误隔离机制

使用 try-except 包裹单个模板的处理逻辑（lines 272-317），确保某个模板处理失败不会影响其他模板。失败详情被记录到 processing_stats['failed_details']（lines 299-304），便于后续诊断。

text2gremlin/AST_Text2Gremlin/base/CombinationController.py (3)

32-75: 配置验证逻辑健全

构造函数现在包含了全面的配置验证：

• 使用 try-except 捕获缺失的必需配置项并抛出清晰的错误（lines 42-55）
• 验证关键类别的存在性（lines 62-69）
• 检查每个类别的必需字段（lines 70-74）

这种早期验证机制能够在初始化阶段就发现配置问题，避免运行时出现难以追踪的错误。

---

139-186: 通用同级选项选择器设计灵活

select_sibling_options 方法提供了统一的选项选择策略，适用于顶点标签、边标签、属性等多种场景。逻辑清晰：

1. 保证配方选项必须包含
2. 根据阈值决定是否全覆盖
3. 对于大选项集，随机选择额外选项

这种设计避免了组合爆炸，同时保持了生成结果的多样性。

---

188-261: 多参数组合生成策略合理

select_multi_param_schema_options 方法针对多参数场景的三种情况制定了不同策略：

• 可选参数不足：仅返回原配方（lines 234-235）
• 可选参数恰好相等：仅返回原配方（lines 240-241）
• 可选参数充足：随机生成组合（lines 246-260）

使用排序后的元组进行去重（line 254）保证了参数顺序无关的语义一致性，且设置了 max_attempts 避免无限循环（line 247）。

[coderabbitai]

🛠️ Refactor suggestion | 🟠 Major

简化 Schema 翻译路径解析逻辑

当前实现在两处构建了默认路径（lines 76-81 和 lines 88-93），增加了代码复杂度。建议合并为单一的路径解析流程：

def _load_schema_translations(self):
    """加载schema翻译字典"""
    file_paths = []
    
    # 1. 尝试从配置获取路径
    try:
        if hasattr(self.config, 'get_schema_dict_path'):
            schema_dict_paths = self.config.get_schema_dict_path()
            if isinstance(schema_dict_paths, list):
                file_paths.extend(schema_dict_paths)
            elif isinstance(schema_dict_paths, str):
                file_paths.append(schema_dict_paths)
        
        if hasattr(self.config, 'get_syn_dict_path'):
            syn_dict_path = self.config.get_syn_dict_path()
            if syn_dict_path:
                file_paths.append(syn_dict_path)
    except Exception as e:
        print(f"[INFO] Config paths not available: {e}")
    
    # 2. 验证路径并回退到默认
    existing_paths = [path for path in file_paths if os.path.exists(path)]
    
    if not existing_paths:
        current_dir = os.path.dirname(os.path.abspath(__file__))
        default_paths = [
            os.path.join(current_dir, 'template', 'schema_dict.txt'),
            os.path.join(current_dir, 'template', 'syn_dict.txt')
        ]
        existing_paths = [path for path in default_paths if os.path.exists(path)]
        if existing_paths:
            print(f"[INFO] Using default dictionary paths: {existing_paths}")
    
    # 3. 加载字典
    if existing_paths:
        self.load_dict_from_file(existing_paths)
    else:
        print(f"[WARNING] No dictionary files found")

[coderabbitai]

⚠️ Potential issue | 🟠 Major

配置加载失败时的空字典回退可能导致运行时错误

当配置文件加载失败时，load_config 返回空字典 {}。虽然打印了警告，但后续代码（lines 124-128）会尝试从这个空字典中获取配置值。如果配置文件确实缺失或损坏，程序仍会继续运行并可能在后续步骤失败，且错误信息可能不够明确。

建议在配置加载失败时提前退出，或确保关键配置项有合理的默认值：

def load_config(config_path='config.json'):
    """加载配置文件"""
    try:
        with open(config_path, 'r', encoding='utf-8') as f:
            return json.load(f)
    except Exception as e:
        print(f"❌ 错误: 无法加载配置文件 {config_path}: {e}")
        sys.exit(1)

🤖 Prompt for AI Agents

text2gremlin/AST_Text2Gremlin/generate_corpus.py lines 45-52: currently
load_config returns an empty dict on failure which leads to downstream runtime
errors; change it to terminate with a clear non-zero exit (e.g., call
sys.exit(1)) after logging the failure, or alternatively return a validated
config with required defaults and raise an error if required keys are missing;
ensure you add an import for sys if you use sys.exit and make the log message an
error-level message that includes the exception details.

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

.licenserc.yaml (1)

85-87: **/*.csv 模式可能过于宽泛。

新增的三个忽略模式中，前两个 (**/*.interp 和 **/*.tokens) 正确地针对 ANTLR 生成的工件。但 **/*.csv 模式将全局忽略所有 CSV 文件的许可证头检查。

根据 PR 目标，AST_Text2Gremlin 系统包含 cypher2gremlin_dataset.csv 等数据文件，这些可能确实无需许可证头。但此宽泛模式可能会无意中忽略源代码树中其他应该检查许可证的 CSV 文件。

如果只有特定路径下的 CSV 数据文件无需检查，建议使用更具体的模式（例如 **/AST_Text2Gremlin/**/*.csv 或 **/data/**/*.csv），而不是全局忽略所有 CSV 文件。

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between a1d614c and 471e141.

📒 Files selected for processing (1)

• .licenserc.yaml (1 hunks)

🧰 Additional context used

🧠 Learnings (1)

📓 Common learnings

Learnt from: CR
PR: hugegraph/hugegraph-ai#0
File: hugegraph-llm/AGENTS.md:0-0
Timestamp: 2025-09-16T06:40:44.968Z
Learning: Applies to hugegraph-llm/src/hugegraph_llm/operators/gremlin_generate_task.py : Maintain the Text2Gremlin pipeline in src/hugegraph_llm/operators/gremlin_generate_task.py

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: build (3.11)
• GitHub Check: build (3.10)