hugegraph-ai integrates HugeGraph with artificial intelligence capabilities, providing comprehensive support for developers to build AI-powered graph applications.
Contributor workflows: CI selection and full validation, release preparation.
- LLM/GraphRAG: Build intelligent question-answering systems with graph-enhanced retrieval
- Knowledge Graph Construction: Automated graph building from text using LLMs
- HugeGraph-LLM SDK: Design schemas and extract reviewed property graphs in your own Python project, without a UI or database service
- Graph ML: Integration with 20+ graph learning algorithms (GCN, GAT, GraphSAGE, etc.)
- HG-Python Client: Easy-to-use Python interface for HugeGraph operations
- Vermeer Python Client: SDK/Interface for Graph Computing with Vermeer
Note
For a complete deployment guide and detailed examples, please refer to hugegraph-llm/README.md
- Python 3.12–3.14 for the LLM application, SDK, Python client and MCP
- uv 0.13.6+ (required for workspace management)
- HugeGraph Server 1.3+ for the LLM/client modules (1.5+ recommended);
hugegraph-mcprequires 1.7.0+ - Docker (optional, for containerized deployment)
# Clone the repository
git clone https://github.com/apache/hugegraph-ai.git
cd hugegraph-ai
# Set up environment and start services
cp docker/env.template docker/.env
# Edit docker/.env to set your PROJECT_PATH
cd docker
# same as `docker-compose` (Legacy)
docker compose -f docker-compose-network.yml up -d
# Access services:
# - HugeGraph Server: http://localhost:8080
# - RAG Service: http://localhost:8001The RAG service is published on the host port by default, and the HTTP API is unauthenticated by default. Before
using this deployment outside a trusted local environment, either enable the built-in Bearer authentication with
ENABLE_LOGIN=true and a strong, non-default USER_TOKEN, or configure reverse proxy authentication. Also restrict
access with a firewall or trusted network.
# 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/hugegraph-ai.git
cd hugegraph-ai
# 3. Install dependencies with workspace management
# uv sync automatically creates venv (.venv) and installs base dependencies
# NOTE: If download is slow, uncomment mirror lines in pyproject.toml or use: uv config --global index.url https://pypi.tuna.tsinghua.edu.cn/simple
# Or create local uv.toml with mirror settings to avoid git diff (see uv.toml example in root)
uv sync --extra llm # Install LLM-specific dependencies
# For HugeGraph MCP source development, install its standalone package directly.
# Or install all optional dependencies: uv sync --all-extras
# 4. Activate virtual environment (recommended for easier commands)
source .venv/bin/activate
# 5. Start the demo (no uv run prefix needed when venv activated)
cd hugegraph-llm
python -m hugegraph_llm.demo.rag_demo.app
# Visit http://127.0.0.1:8001The source launcher binds to 127.0.0.1 by default and warns when a non-loopback --host is selected.
Note
Examples assume you've activated the virtual environment with source .venv/bin/activate
ML remains outside this workspace and is not part of the dependency modernization. Its standalone environment requires Python 3.12+ because it uses the local Python client. Follow the ML module for installation and examples.
HugeGraph-LLM SDK is an independently installable Python interface for reusable LLM capabilities. Its current
scope is schema design, validation, and reviewed property-graph extraction. Inject your own model or install an
optional provider adapter; synchronous and asynchronous APIs share the same graph rules. The SDK and application
are sibling packages: hugegraph-llm depends on hugegraph-llm-sdk, while external projects can install the SDK
alone. See its integration guide for source installation and offline examples,
and architecture for module responsibilities and extension boundaries.
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
Model Context Protocol server for safe, controlled HugeGraph access:
- Stable Tool Contract: Typed graph, schema, Gremlin, and extraction tools for MCP clients
- Safe Writes: Read-only defaults plus dry-run, persistent single-use confirmation, and target revalidation
- Compatibility: Default
coretoolset with an opt-inlegacycompatibility mode; the previous1.7.1release usesv2_core/v1
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.
Note
hugegraph-ml is not part of the uv workspace.
Python client for HugeGraph operations, distributed as hugegraph-python (uv pip install hugegraph-python) and imported as pyhugegraph:
- 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
- Project Homepage
- LLM Quick Start Guide
- Reviewed Property-Graph Extraction — optional API review, bounded repair, concurrent chunks, and per-chunk results
- DeepWiki AI Documentation
And here are links of other repositories:
- hugegraph (graph's core component - Graph server + PD + Store)
- hugegraph-toolchain (graph tools loader/dashboard/tool/client)
- hugegraph-computer (integrated graph computing system)
- hugegraph-website (doc & website code)
We welcome contributions! Please see our contribution guidelines for details.
[!IMPORTANT] > For project contributors using AI coding tools, please follow these guidelines:
- Start Here: First read
rules/README.mdfor the complete AI-assisted development workflow- Module Context: When
AGENTS.mdexists 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.mdfor 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:
# 1. Clone and navigate to project
git clone https://github.com/apache/hugegraph-ai.git
cd hugegraph-ai
# 2. Install all development dependencies
# uv sync creates venv automatically and installs base dependencies
uv sync --all-extras # Install all optional dependency groups
source .venv/bin/activate # Activate for easier command usage
# 3. Run tests for workspace members
cd hugegraph-llm && pytest
cd ../hugegraph-python-client && pytest
# 4. Run tests for path dependencies
cd ../hugegraph-ml && pytest # If tests exist
# 5. Format and lint code
./style/code_format_and_analysis.sh
# 6. Add new dependencies to workspace
uv add numpy # Add to base dependencies
uv add --group dev pytest-mock # Add to dev groupFrom the repository root:
uv run --extra dev ruff format --check .
uv run --extra dev ruff check .
uv run --extra dev ty check hugegraph-llm/src/hugegraph_llm hugegraph-python-client/src/pyhugegraphRuff and ty use >= requirements in root pyproject.toml.
The pre-commit hooks run Ruff through uv and inherit that range.
Enable hooks with uv run --extra dev pre-commit install. CI runs Ruff and affected-module ty
checks in existing runners; application type checks remain advisory while the
existing diagnostic baseline is resolved. See CI policy.
Key Points:
- Use GitHub Desktop for easier PR management
- Check existing issues before reporting bugs
hugegraph-ai is licensed under Apache 2.0 License.
- GitHub Issues: Report bugs or request features (fastest response)
- Email: dev@hugegraph.apache.org (subscription required)
- Slack: Join the ASF HugeGraph channel
- WeChat: Follow "Apache HugeGraph" official account
