Apache HugeGraph AI

HugeGraph AI is the Python toolkit for building AI and data applications on Apache HugeGraph. It includes GraphRAG and knowledge-graph workflows, reusable extraction APIs, an MCP server, Python clients and graph machine-learning modules.

Start here: Choose a module · Quick start · Documentation · Development

Choose a module

Goal	Module
Build a GraphRAG or knowledge-graph application	hugegraph-llm
Embed schema design and reviewed graph extraction in another Python project	hugegraph-llm-sdk
Connect an MCP client to HugeGraph tools	hugegraph-mcp
Access HugeGraph from Python	hugegraph-python-client
Run graph-learning models and examples	hugegraph-ml
Call Vermeer from Python	vermeer-python-client

hugegraph-llm-sdk owns reusable schema and extraction contracts. hugegraph-llm is the application layer and depends on the SDK and Python client. Changes to either shared package require validation of their application callers.

Applications and MCP clients
           │
           ├─ hugegraph-llm-sdk ──► model providers
           ├─ hugegraph-llm ──────► GraphRAG, extraction and API/UI
           └─ hugegraph-mcp ──────► controlled graph tools
                         │
                         ▼
             hugegraph-python-client
                         │
                         ▼
                  HugeGraph Server

Quick start

The main workspace uses Python 3.12 or later and uv. Read exact Python and dependency constraints from the root and module pyproject.toml files.

Run the LLM application from source

Start a HugeGraph Server, then install the LLM dependency set:

git clone https://github.com/apache/hugegraph-ai.git
cd hugegraph-ai
uv sync --extra llm
source .venv/bin/activate
cd hugegraph-llm
python -m hugegraph_llm.demo.rag_demo.app

Open http://127.0.0.1:8001. The source launcher binds to loopback by default. Follow the LLM module guide for model, embedding, vector-index and HugeGraph configuration.

Run the Docker environment

git clone https://github.com/apache/hugegraph-ai.git
cd hugegraph-ai

Before starting Compose, follow the LLM Docker Compose guide to configure the mounted application .env and limit network access. The default Compose file publishes both the Server and unauthenticated RAG API on all host interfaces.

cd docker
docker compose -f docker-compose-network.yml up -d

Use a library instead of the application

• Install and integrate hugegraph-llm-sdk when another project needs schema design, validation or reviewed extraction without the demo application.
• Install hugegraph-python and import pyhugegraph when an application only needs the HugeGraph Python client.
• Run hugegraph-mcp when an MCP host needs typed graph tools, read-only defaults and controlled write confirmation.

Each module README owns its package name, optional extras, API examples and compatibility boundary. Keeping those details beside the package avoids stale copies in this root README.

Modules

hugegraph-llm-sdk

Reusable synchronous and asynchronous APIs for schema design, validation and property-graph extraction. Provider adapters are optional so the base package can remain independent of application and account-specific dependencies. See the SDK architecture.

hugegraph-llm

Application services and examples for GraphRAG, knowledge-graph construction, natural-language graph access, prompt workflows, model configuration and the RAG API/UI.

hugegraph-mcp

Model Context Protocol server with typed schema, graph, Gremlin and extraction tools. It defaults to constrained behavior and requires explicit confirmation for protected writes.

hugegraph-python-client

Python interface for schema, graph, traverser, variable, task and Gremlin operations. The distribution name is hugegraph-python; the import package is pyhugegraph.

hugegraph-ml and vermeer-python-client

Graph-learning algorithms and the Vermeer client are lower-frequency standalone modules. Follow their own environment and compatibility instructions instead of assuming they share every workspace dependency.

Documentation

• Repository documentation index: quality, testing, SDK architecture, release and documentation ownership.
• LLM module: GraphRAG, extraction, configuration, API and deployment details.
• SDK module: standalone installation and library integration.
• MCP module: server setup, client configuration, toolsets and safety behavior.
• Official HugeGraph AI guide: user-facing overview and deployment documentation.
• AGENTS.md: repository boundaries, testing expectations and agent navigation.

Every durable document should be reachable from the repository index or a module-local README. Avoid duplicating a module procedure in the root README, quality docs and agent instructions.

Development

Install workspace dependencies and run the checks for the modules you changed:

uv sync --all-extras
uv run --extra dev pre-commit install
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/pyhugegraph
uv run --extra dev ty check hugegraph-llm-sdk/src/hugegraph_llm_sdk

Run tests from the affected module. Shared SDK or Python-client changes also require the relevant hugegraph-llm tests. See CI policy and AGENTS.md for test selection; do not default to an expensive full-repository sweep when a precise affected-module set is available.

Related projects

• Apache HugeGraph: Server, PD, distributed Store and Helm chart.
• Apache HugeGraph Toolchain: Java client, Loader, Hubble, Tools and Spark connector.
• Apache HugeGraph Computer: graph computation and Vermeer.
• Apache HugeGraph Documentation: website and long-form user documentation.

Community and license

• Contribution guide
• Issue tracker
• Developer mailing list

HugeGraph AI is licensed under the Apache License 2.0.