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-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
hugegraph-llm-sdk when another project needs schema design, validation or reviewed extraction without the demo application.hugegraph-python and import pyhugegraph when an application only needs the HugeGraph Python client.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.
hugegraph-llm-sdkReusable 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-llmApplication services and examples for GraphRAG, knowledge-graph construction, natural-language graph access, prompt workflows, model configuration and the RAG API/UI.
hugegraph-mcpModel 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-clientPython 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-clientGraph-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.
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.
HugeGraph AI is licensed under the Apache License 2.0.