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
| 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
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.
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.
git clone https://github.com/apache/hugegraph-ai.git
cd hugegraph-aiBefore 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- Install and integrate
hugegraph-llm-sdkwhen another project needs schema design, validation or reviewed extraction without the demo application. - Install
hugegraph-pythonand importpyhugegraphwhen an application only needs the HugeGraph Python client. - Run
hugegraph-mcpwhen 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.
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.
Application services and examples for GraphRAG, knowledge-graph construction, natural-language graph access, prompt workflows, model configuration and the RAG API/UI.
Model Context Protocol server with typed schema, graph, Gremlin and extraction tools. It defaults to constrained behavior and requires explicit confirmation for protected writes.
Python interface for schema, graph, traverser, variable, task and Gremlin operations. The distribution name is hugegraph-python; the import package is pyhugegraph.
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.
- 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.
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.
- 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.
HugeGraph AI is licensed under the Apache License 2.0.