This is an automated email from the ASF dual-hosted git repository.
jin pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-hugegraph-ai.git
The following commit(s) were added to refs/heads/main by this push:
new 9e76c2a0 docs(llm): use AGENTS.md as LLM standard doc (#299)
9e76c2a0 is described below
commit 9e76c2a0f6cfad226e99fddf887358b6f82ce5ec
Author: LingXiao Qi <[email protected]>
AuthorDate: Thu Sep 11 12:23:06 2025 +0800
docs(llm): use AGENTS.md as LLM standard doc (#299)
---
.gitignore | 2 +-
README.md | 24 ++++++++++++++++------
hugegraph-llm/{basic-introduction.md => AGENTS.md} | 0
hugegraph-llm/README.md | 15 +++++++++++---
rules/README.md | 8 ++++++--
5 files changed, 37 insertions(+), 12 deletions(-)
diff --git a/.gitignore b/.gitignore
index 42a06764..76412112 100644
--- a/.gitignore
+++ b/.gitignore
@@ -135,7 +135,7 @@ celerybeat.pid
# prompt config
config_prompt.yaml*
-# AI-IDE prompt files (generated from basic-introduction.md)
+# AI-IDE prompt files (generated from AGENTS.md)
# Claude Projects
CLAUDE.md
diff --git a/README.md b/README.md
index e9d87ac7..14f02ca1 100644
--- a/README.md
+++ b/README.md
@@ -19,6 +19,7 @@
> For a complete deployment guide and detailed examples, please refer to
> [hugegraph-llm/README.md](./hugegraph-llm/README.md)
### Prerequisites
+
- Python 3.10+ (required for hugegraph-llm)
- [uv](https://docs.astral.sh/uv/) 0.7+ (required for workspace management)
- HugeGraph Server 1.3+ (1.5+ recommended)
@@ -75,6 +76,7 @@ python -m hugegraph_llm.demo.rag_demo.app
> Examples assume you've activated the virtual environment with `source
> .venv/bin/activate`
#### GraphRAG - Question Answering
+
```python
from hugegraph_llm.operators.graph_rag_task import RAGPipeline
@@ -92,6 +94,7 @@ result = (graph_rag
```
#### Knowledge Graph Construction
+
```python
from hugegraph_llm.models.llms.init_llm import LLMs
from hugegraph_llm.operators.kg_construction_task import KgBuilder
@@ -109,6 +112,7 @@ builder = KgBuilder(LLMs().get_chat_llm())
```
#### Graph Machine Learning
+
```bash
# Install ML dependencies (ml module is not in workspace)
uv sync --extra ml
@@ -122,14 +126,18 @@ python examples/your_ml_example.py
## 📦 Modules
### [hugegraph-llm](./hugegraph-llm) [](https://deepwiki.com/apache/incubator-hugegraph-ai)
+
Large language model integration for graph applications:
+
- **GraphRAG**: Retrieval-augmented generation with graph data
-- **Knowledge Graph Construction**: Build KGs from text automatically
+- **Knowledge Graph Construction**: Build KGs from text automatically
- **Natural Language Interface**: Query graphs using natural language
- **AI Agents**: Intelligent graph analysis and reasoning
### [hugegraph-ml](./hugegraph-ml)
+
Graph machine learning with 20+ implemented algorithms:
+
- **Node Classification**: GCN, GAT, GraphSAGE, APPNP, etc.
- **Graph Classification**: DiffPool, P-GNN, etc.
- **Graph Embedding**: DeepWalk, Node2Vec, GRACE, etc.
@@ -139,7 +147,9 @@ Graph machine learning with 20+ implemented algorithms:
> hugegraph-ml is not part of the workspace but linked via path dependency
### [hugegraph-python-client](./hugegraph-python-client)
+
Python client for HugeGraph operations:
+
- **Schema Management**: Define vertex/edge labels and properties
- **CRUD Operations**: Create, read, update, delete graph data
- **Gremlin Queries**: Execute graph traversal queries
@@ -154,6 +164,7 @@ Python client for HugeGraph operations:
## 🔗 Related HugeGraph Projects
And here are links of other repositories:
+
1. [hugegraph](https://github.com/apache/hugegraph) (graph's core component -
Graph server + PD + Store)
2. [hugegraph-toolchain](https://github.com/apache/hugegraph-toolchain) (graph
tools
**[loader](https://github.com/apache/incubator-hugegraph-toolchain/tree/master/hugegraph-loader)/[dashboard](https://github.com/apache/incubator-hugegraph-toolchain/tree/master/hugegraph-hubble)/[tool](https://github.com/apache/incubator-hugegraph-toolchain/tree/master/hugegraph-tools)/[client](https://github.com/apache/incubator-hugegraph-toolchain/tree/master/hugegraph-client)**)
3. [hugegraph-computer](https://github.com/apache/hugegraph-computer)
(integrated **graph computing** system)
@@ -165,19 +176,19 @@ We welcome contributions! Please see our [contribution
guidelines](https://hugeg
### 🤖 AI Coding Guidelines for Developers
-> [!IMPORTANT]
-> **For project contributors using AI coding tools**, please follow these
guidelines:
->
+> [!IMPORTANT] > **For project contributors using AI coding tools**, please
follow these guidelines:
+>
> - **Start Here**: First read `rules/README.md` for the complete AI-assisted
> development workflow
-> - **Module Context**: When `basic-introduction.md` exists in any module,
rename it as context for your LLM (e.g., `CLAUDE.md`, `copilot-instructions.md`)
+> - **Module Context**: When `AGENTS.md` exists in any module, rename it as
context for your LLM (e.g., `CLAUDE.md`, `copilot-instructions.md`)
> - **Documentation Standards**: Follow the structured documentation approach
> in `rules/prompts/project-general.md`
> - **Deep Analysis**: For complex features, refer to
> `rules/prompts/project-deep.md` for comprehensive code analysis methodology
> - **Code Quality**: Maintain consistency with existing patterns and ensure
> proper type annotations
> - **Testing**: Follow TDD principles and ensure comprehensive test coverage
> for new features
->
+>
> These guidelines ensure consistent code quality and maintainable development
> workflow with AI assistance.
**Development Setup:**
+
```bash
# 1. Clone and navigate to project
git clone https://github.com/apache/incubator-hugegraph-ai.git
@@ -204,6 +215,7 @@ uv add --group dev pytest-mock # Add to dev group
```
**Key Points:**
+
- Use [GitHub Desktop](https://desktop.github.com/) for easier PR management
- Check existing issues before reporting bugs
diff --git a/hugegraph-llm/basic-introduction.md b/hugegraph-llm/AGENTS.md
similarity index 100%
rename from hugegraph-llm/basic-introduction.md
rename to hugegraph-llm/AGENTS.md
diff --git a/hugegraph-llm/README.md b/hugegraph-llm/README.md
index 63642557..526320d4 100644
--- a/hugegraph-llm/README.md
+++ b/hugegraph-llm/README.md
@@ -7,6 +7,7 @@
HugeGraph-LLM is a comprehensive toolkit that combines the power of graph
databases with large language models. It enables seamless integration between
HugeGraph and LLMs for building intelligent applications.
### Key Features
+
- 🏗️ **Knowledge Graph Construction** - Build KGs automatically using LLMs +
HugeGraph
- 🗣️ **Natural Language Querying** - Operate graph databases using natural
language (Gremlin/Cypher)
- 🔍 **Graph-Enhanced RAG** - Leverage knowledge graphs to improve answer
accuracy (GraphRAG & Graph Agent)
@@ -16,6 +17,7 @@ For detailed source code doc, visit our
[DeepWiki](https://deepwiki.com/apache/i
## 📋 Prerequisites
> [!IMPORTANT]
+>
> - **Python**: 3.10+ (not tested on 3.12)
> - **HugeGraph Server**: 1.3+ (recommended: 1.5+)
> - **UV Package Manager**: 0.7+
@@ -53,6 +55,7 @@ docker-compose -f docker-compose-network.yml ps
For more control over individual components:
#### Available Images
+
- **`hugegraph/rag`** - Development image with source code access
- **`hugegraph/rag-bin`** - Production-optimized binary (compiled with Nuitka)
@@ -118,6 +121,7 @@ python -m hugegraph_llm.config.generate --update
```
> [!TIP]
+>
> - `uv sync` automatically creates virtual environment (.venv) and installs
> all dependencies
> - Activate once with `source .venv/bin/activate` - all subsequent commands
> assume this environment
> - Check our [Quick Start
> Guide](https://github.com/apache/incubator-hugegraph-ai/blob/main/hugegraph-llm/quick_start.md)
> for detailed usage examples
@@ -131,10 +135,12 @@ python -m hugegraph_llm.config.generate --update
Use the Gradio interface for visual knowledge graph building:
**Input Options:**
+
- **Text**: Direct text input for RAG index creation
- **Files**: Upload TXT or DOCX files (multiple selection supported)
**Schema Configuration:**
+
- **Custom Schema**: JSON format following our
[template](https://github.com/apache/incubator-hugegraph-ai/blob/aff3bbe25fa91c3414947a196131be812c20ef11/hugegraph-llm/src/hugegraph_llm/config/config_data.py#L125)
- **HugeGraph Schema**: Use existing graph instance schema (e.g., "hugegraph")
@@ -163,6 +169,7 @@ builder = KgBuilder(LLMs().get_chat_llm())
```
**Pipeline Workflow:**
+
```mermaid
graph LR
A[Import Schema] --> B[Chunk Split]
@@ -200,6 +207,7 @@ graph_rag = RAGPipeline()
```
**RAG Pipeline Flow:**
+
```mermaid
graph TD
A[User Query] --> B[Extract Keywords]
@@ -222,6 +230,7 @@ After running the demo, configuration files are
automatically generated:
- **Environment**: `hugegraph-llm/.env`
- **Prompts**:
`hugegraph-llm/src/hugegraph_llm/resources/demo/config_prompt.yaml`
+
### Language Support
The system supports both English and Chinese prompts. To switch languages:
@@ -230,6 +239,7 @@ The system supports both English and Chinese prompts. To
switch languages:
2. **Restart the application**: The system will automatically regenerate
prompts in the selected language
**Supported Values:**
+
- `LANGUAGE=EN` - English prompts (default)
- `LANGUAGE=CN` - Chinese prompts (中文提示词)
@@ -240,11 +250,10 @@ The system supports both English and Chinese prompts. To
switch languages:
## 🤖 Developer Guidelines
-> [!IMPORTANT]
-> **For developers contributing to hugegraph-llm with AI coding assistance:**
+> [!IMPORTANT] > **For developers contributing to hugegraph-llm with AI coding
assistance:**
>
> - **Start Here**: First read `../rules/README.md` for the complete
> AI-assisted development workflow
-> - **Module Context**: Rename `basic-introduction.md` in this directory as
context for your LLM (e.g., `CLAUDE.md`, `copilot-instructions.md`)
+> - **Module Context**: Rename `AGENTS.md` in this directory as context for
your LLM (e.g., `CLAUDE.md`, `copilot-instructions.md`)
> - **Code Analysis**: Follow comprehensive analysis methodology in
> `../rules/prompts/project-deep.md`
> - **Documentation**: Maintain structured documentation standards from
> `../rules/prompts/project-general.md`
> - **Quality Standards**: Ensure type annotations, proper testing, and
> consistent patterns
diff --git a/rules/README.md b/rules/README.md
index 2e78d48a..8b2f6db0 100644
--- a/rules/README.md
+++ b/rules/README.md
@@ -16,6 +16,8 @@
- 为了保证上下文质量，最佳实践是 STEP4(execute)时新开一个 Chat
+- ⭐️ 欢迎维护和补充各模块下的 AGENTS.md, 迭代为面向 AI 的最佳语料和规范
+
### 开发者阅读指南
> 如果你是使用本 AI Coding 助手的开发者，请注意以下要点：
@@ -73,8 +75,10 @@
## 项目规范
-每个模块下的 `base_introduction.md`介绍各自模块的最核心的结构/概览，可直接重命名为 GEMINI/CLAUDE/copilot.md
给 `LLM Coding`
-作为默认参考考 (./{module_name}/base-introduction.md)
+每个模块下的 `AGENTS.md`负责介绍各自模块的最核心的结构/概览（面向 AI），统一给 `LLM Coding`
+作为指导文档 (./{module_name}/AGENTS.md)
+
+- 命名参考[AGENTS.md](https://agents.md/)，也可重命名为 GEMINI/CLAUDE.md 等
## 测试规范
