feat: add ruff lint & pre-commit

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -15,7 +15,7 @@ body:
         Issue 标题请保持原有模板分类(例如:`[Bug]`), 长段描述之间可以增加`空行`或使用`序号`标记，保持排版清晰。
         3. Please submit an issue in the corresponding module, lack of valid information / long time (>14 days) unanswered issues may be closed (will be reopened when updated).
         请在对应的模块提交 issue, 缺乏有效信息 / 长时间 (> 14 天) 没有回复的 issue 可能会被 **关闭**(更新时会再开启)。
-  
+
   - type: dropdown
     attributes:
       label: Bug Type (问题类型)
@@ -26,7 +26,7 @@ body:
         - data inconsistency (数据不一致)
         - exception / error (异常报错)
         - others (please comment below)
-  
+
   - type: checkboxes
     attributes:
       label: Before submit
@@ -45,16 +45,16 @@ body:
         - Data Size: xx vertices, xx edges <!-- (like 1000W 点，9000W 边) -->>
     validations:
       required: true
-  
+
   - type: textarea
     attributes:
       label: Expected & Actual behavior (期望与实际表现)
       description: |
         we can refer [How to create a minimal reproducible Example](https://stackoverflow.com/help/minimal-reproducible-example), if possible, please provide screenshots or GIF.
         可以参考 [如何提供最简的可复现用例](https://stackoverflow.com/help/minimal-reproducible-example)，请提供清晰的截图，动图录屏更佳。
       placeholder: |
-        type the main problem here 
-        
+        type the main problem here
+
         ```java
         // Detailed exception / error info (尽可能详细的日志 + 完整异常栈)
 

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -23,7 +23,7 @@ body:
       description: >
         Please describe the function you want in as much detail as possible. (请简要描述新功能 /
         需求的使用场景或上下文, 最好能给个具体的例子说明)
-      placeholder: type the feature description here 
+      placeholder: type the feature description here
     validations:
       required: true
 
@@ -50,4 +50,3 @@ body:
   - type: markdown
     attributes:
       value: "Thanks for completing our form, and we will reply you as soon as possible."
-

.github/ISSUE_TEMPLATE/question_ask.yml

@@ -27,7 +27,7 @@ body:
         - configs (配置项 / 文档相关)
         - exception / error (异常报错)
         - others (please comment below)
-  
+
   - type: checkboxes
     attributes:
       label: Before submit
@@ -54,8 +54,8 @@ body:
         For issues related to graph usage/configuration, please refer to [REST-API documentation](https://hugegraph.apache.org/docs/clients/restful-api/), and [Server configuration documentation](https://hugegraph.apache.org/docs/config/config-option/) (if possible, please provide screenshots or GIF).
         图使用 / 配置相关问题，请优先参考 [REST-API 文档](https://hugegraph.apache.org/docs/clients/restful-api/), 以及 [Server 配置文档](https://hugegraph.apache.org/docs/config/config-option/) (请提供清晰的截图，动图录屏更佳)
       placeholder: |
-        type the main problem here 
-        
+        type the main problem here
+
         ```java
         // Exception / Error info (尽可能详细的日志 + 完整异常栈)
 

.github/workflows/pylint.yml → .github/workflows/ruff.yml

@@ -1,20 +1,18 @@
-# TODO: replace by ruff & mypy soon
-name: "Pylint"
+name: "Ruff Code Quality"
 
 on:
   push:
     branches:
-      - 'main'
-      - 'master'
-      - 'release-*'
+      - "main"
+      - "release-*"
   pull_request:
 
 jobs:
   build:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.10", "3.11"]
+        python-version: ["3.10", "3.11", "3.12"]
 
     steps:
       - uses: actions/checkout@v4
@@ -48,6 +46,10 @@ jobs:
         run: |
           uv run python -c "import dgl; print(dgl.__version__)"
 
-      - name: Analysing the code with pylint
+      - name: Check code formatting with Ruff
         run: |
-          uv run bash ./style/code_format_and_analysis.sh -p
+          uv run ruff format --check .
+
+      - name: Lint code with Ruff
+        run: |
+          uv run ruff check .

.gitignore

@@ -185,8 +185,6 @@ venv.bak/
 # Rope project settings
 .ropeproject
 
-.pre-commit-config.yaml
-
 # mkdocs documentation
 /site
 

.pre-commit-config.yaml

@@ -0,0 +1,39 @@
+# 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.
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+        args: ["--maxkb=1000"]
+      - id: check-merge-conflict
+      - id: check-case-conflict
+      - id: check-docstring-first
+      - id: debug-statements
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.13.1
+    hooks:
+      - id: ruff-format
+        types_or: [python, pyi]
+      - id: ruff
+        types_or: [python, pyi]
+        args: [--fix]

DISCLAIMER

@@ -1,7 +1,7 @@
 Apache HugeGraph (incubating) is an effort undergoing incubation at The Apache Software Foundation (ASF), sponsored by the Apache Incubator PMC.
 
-Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, 
+Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications,
 and decision making process have stabilized in a manner consistent with other successful ASF projects.
 
-While incubation status is not necessarily a reflection of the completeness or stability of the code, 
+While incubation status is not necessarily a reflection of the completeness or stability of the code,
 it does indicate that the project has yet to be fully endorsed by the ASF.

README.md

@@ -178,8 +178,19 @@ uv add numpy  # Add to base dependencies
 uv add --group dev pytest-mock  # Add to dev group
 ```
 
-**Key Points:**
+### Code Quality (ruff + pre-commit)
+
+- Ruff is used for linting and formatting:
+  - \`ruff format .\`
+  - \`ruff check .\`
+- Enable Git hooks via pre-commit:
+  - \`pre-commit install\`
+  - \`pre-commit run --all-files\`
+- Config: [.pre-commit-config.yaml](.pre-commit-config.yaml). CI enforces these checks.
+  **Key Points:**
+- Config: [.pre-commit-config.yaml](.pre-commit-config.yaml). CI enforces these checks.
 
+**Key Points:**
 - Use [GitHub Desktop](https://desktop.github.com/) for easier PR management
 - Check existing issues before reporting bugs
 

docker/docker-compose-network.yml

@@ -48,4 +48,4 @@ services:
       interval: 30s
       timeout: 10s
       retries: 3
-      start_period: 60s 
+      start_period: 60s

hugegraph-llm/AGENTS.md

@@ -4,9 +4,9 @@ This file provides guidance to AI coding tools and developers when working with
 
 ## Project Overview
 
-HugeGraph-LLM is a comprehensive toolkit that bridges graph databases and large language models, 
-part of the Apache HugeGraph AI ecosystem. It enables seamless integration between HugeGraph and LLMs for building 
-intelligent applications with three main capabilities: Knowledge Graph Construction, Graph-Enhanced RAG, 
+HugeGraph-LLM is a comprehensive toolkit that bridges graph databases and large language models,
+part of the Apache HugeGraph AI ecosystem. It enables seamless integration between HugeGraph and LLMs for building
+intelligent applications with three main capabilities: Knowledge Graph Construction, Graph-Enhanced RAG,
 and Text2Gremlin query generation.
 
 ## Tech Stack

hugegraph-llm/CI_FIX_SUMMARY.md

@@ -33,7 +33,7 @@
     export SKIP_EXTERNAL_SERVICES=true
     cd hugegraph-llm
     export PYTHONPATH="$(pwd)/src:$PYTHONPATH"
-    
+
     # 跳过有问题的测试
     python -m pytest src/tests/ -v --tb=short \
       --ignore=src/tests/integration/ \
@@ -46,7 +46,7 @@
 - uses: actions/checkout@v4
   with:
     fetch-depth: 0  # 获取完整历史
-    
+
 - name: Sync latest changes
   run: |
     git pull origin main  # 确保获取最新更改

hugegraph-llm/README.md

@@ -22,6 +22,16 @@ For detailed source code doc, visit our [DeepWiki](https://deepwiki.com/apache/i
 > - **HugeGraph Server**: 1.3+ (recommended: 1.5+)
 > - **UV Package Manager**: 0.7+
 
+### Code Quality (ruff + pre-commit)
+
+- Ruff is used for linting and formatting:
+  - `ruff format .`
+  - `ruff check .`
+- Enable Git hooks via pre-commit:
+  - `pre-commit install` (in the root dir)
+  - `pre-commit run --all-files`
+- Config: [../.pre-commit-config.yaml](../.pre-commit-config.yaml)
+
 ## 🚀 Quick Start
 
 Choose your preferred deployment method:
@@ -177,7 +187,7 @@ The system supports both English and Chinese prompts. To switch languages:
 
 If you previously used high-level classes like `RAGPipeline` or `KgBuilder`, the project now exposes stable flows through the `Scheduler` API. Use `SchedulerSingleton.get_instance().schedule_flow(...)` to invoke workflows programmatically. Below are concise, working examples that match the new architecture.
 
-1) RAG (graph-only) query example
+1. RAG (graph-only) query example
 
 ```python
 from hugegraph_llm.flows.scheduler import SchedulerSingleton
@@ -196,7 +206,7 @@ res = scheduler.schedule_flow(
 print(res.get("graph_only_answer"))
 ```
 
-2) RAG (vector-only) query example
+2. RAG (vector-only) query example
 
 ```python
 from hugegraph_llm.flows.scheduler import SchedulerSingleton
@@ -212,7 +222,7 @@ res = scheduler.schedule_flow(
 print(res.get("vector_only_answer"))
 ```
 
-3) Text -> Gremlin (text2gremlin) example
+3. Text -> Gremlin (text2gremlin) example
 
 ```python
 from hugegraph_llm.flows.scheduler import SchedulerSingleton
@@ -230,7 +240,7 @@ response = scheduler.schedule_flow(
 print(response.get("template_gremlin"))
 ```
 
-4) Build example index (used by text2gremlin examples)
+4. Build example index (used by text2gremlin examples)
 
 ```python
 from hugegraph_llm.flows.scheduler import SchedulerSingleton

hugegraph-llm/quick_start.md

@@ -26,7 +26,7 @@ graph TD;
     A --> F[Text Segmentation]
     F --> G[LLM extracts graph based on schema \nand segmented text]
     G --> H[Store graph in Graph Database, \nautomatically vectorize vertices \nand store in Vector Database]
-    
+
     I[Retrieve vertices from Graph Database] --> J[Vectorize vertices and store in Vector Database \nNote: Incremental update]
 ```
 
@@ -85,7 +85,7 @@ graph TD;
     F --> G[Match vertices precisely in Graph Database \nusing keywords; perform fuzzy matching in \nVector Database &#40graph vid&#41]
     G --> H[Generate Gremlin query using matched vertices and query with LLM]
     H --> I[Execute Gremlin query; if successful, finish; if failed, fallback to BFS]
-    
+
     B --> J[Sort results]
     I --> J
     J --> K[Generate answer]
@@ -162,7 +162,7 @@ The first part is straightforward, so the focus is on the second part.
 graph TD;
     A[Gremlin Pairs File] --> C[Vectorize query]
     C --> D[Store in Vector Database]
-    
+
     F[Natural Language Query] --> G[Search for the most similar query \nin the Vector Database \n&#40If no Gremlin pairs exist in the Vector Database, \ndefault files will be automatically vectorized&#41 \nand retrieve the corresponding Gremlin]
     G --> H[Add the matched pair to the prompt \nand use LLM to generate the Gremlin \ncorresponding to the Natural Language Query]
 ```

hugegraph-llm/src/hugegraph_llm/api/admin_api.py

@@ -17,7 +17,7 @@
 
 import os
 
-from fastapi import status, APIRouter
+from fastapi import APIRouter, status
 from fastapi.responses import StreamingResponse
 
 from hugegraph_llm.api.exceptions.rag_exceptions import generate_response

hugegraph-llm/src/hugegraph_llm/api/exceptions/rag_exceptions.py

@@ -16,14 +16,13 @@
 # under the License.
 
 from fastapi import HTTPException
+
 from hugegraph_llm.api.models.rag_response import RAGResponse
 
 
 class ExternalException(HTTPException):
     def __init__(self):
-        super().__init__(
-            status_code=400, detail="Connect failed with error code -1, please check the input."
-        )
+        super().__init__(status_code=400, detail="Connect failed with error code -1, please check the input.")
 
 
 class ConnectionFailedException(HTTPException):