bitflicker64 commented on code in PR #408: URL: https://github.com/apache/hugegraph-ai/pull/408#discussion_r4505347370
########## README.md: ########## @@ -3,137 +3,228 @@ [](https://www.apache.org/licenses/LICENSE-2.0.html) [](https://deepwiki.com/apache/hugegraph-ai) -HugeGraph AI is the Python toolkit for building AI and data applications on [Apache HugeGraph](https://github.com/apache/hugegraph). It includes GraphRAG and knowledge-graph workflows, reusable extraction APIs, an MCP server, Python clients and graph machine-learning modules. +`hugegraph-ai` integrates [HugeGraph](https://github.com/apache/hugegraph) with artificial intelligence capabilities, providing comprehensive support for developers to build AI-powered graph applications. -**Start here:** [Choose a module](#choose-a-module) ยท [Quick start](#quick-start) ยท [Documentation](#documentation) ยท [Development](#development) +## โจ Key Features -## Choose a module +- **[LLM/GraphRAG](./hugegraph-llm/README.md#key-features)**: Build intelligent question-answering systems with graph-enhanced retrieval +- **[Knowledge Graph Construction](./hugegraph-llm/README.md#knowledge-graph-construction)**: Automated graph building from text using LLMs +- **[HugeGraph-LLM SDK](./hugegraph-llm-sdk/README.md)**: Design schemas and extract reviewed property graphs in your own Python project, without a UI or database service +- **[Graph ML](./hugegraph-ml/README.md)**: Integration with 20+ graph learning algorithms (GCN, GAT, GraphSAGE, etc.) +- **[HG-Python Client](./hugegraph-python-client/README.md)**: Easy-to-use Python interface for HugeGraph operations +- **[Vermeer Python Client](./vermeer-python-client/README.md)**: SDK/Interface for Graph Computing with [Vermeer](https://github.com/apache/hugegraph-computer/tree/master/vermeer#readme) +- **[MCP Server](./hugegraph-mcp/README.md)**: Connect MCP clients to typed graph tools with read-only defaults and controlled writes -| Goal | Module | -|---|---| -| Build a GraphRAG or knowledge-graph application | [`hugegraph-llm`](hugegraph-llm/) | -| Embed schema design and reviewed graph extraction in another Python project | [`hugegraph-llm-sdk`](hugegraph-llm-sdk/) | -| Connect an MCP client to HugeGraph tools | [`hugegraph-mcp`](hugegraph-mcp/) | -| Access HugeGraph from Python | [`hugegraph-python-client`](hugegraph-python-client/) | -| Run graph-learning models and examples | [`hugegraph-ml`](hugegraph-ml/) | -| Call Vermeer from Python | [`vermeer-python-client`](vermeer-python-client/) | +## ๐งฉ Architecture -`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. +The LLM application builds GraphRAG and extraction workflows on the reusable SDK and the HugeGraph Python client. The SDK can also be used by another Python application without the UI or database service. The MCP server offers a separate entry point for MCP clients. ```text -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 +โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ +โ HugeGraph AI โ +โ โ +โ โโโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโ โ +โ โ LLM Application โ โ MCP Server โ โ +โ โโโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโ โ +โ โ โ โ โ +โ โ โโโโโโโโโโโโโโโโโโโโโโโโโ โ โ +โ โผ โผ โผ โ +โ โโโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโ โ +โ โ LLM SDK โ โ Python Client โ โ +โ โโโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโ โ +โ โ โ โ +โโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโ + โผ โผ + โโโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโ + โ Model Providers โ โ HugeGraph Server โ + โโโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโ ``` -## Quick start +The diagram shows the main module relationships. The LLM application can also call model providers directly; SDK provider adapters are optional. -The main workspace uses Python 3.12 or later and [`uv`](https://docs.astral.sh/uv/). Read exact Python and dependency constraints from the root and module `pyproject.toml` files. +## ๐ Quick Start -### Run the LLM application from source +> [!NOTE] +> For a complete deployment guide and detailed examples, please refer to [hugegraph-llm/README.md](./hugegraph-llm/README.md) -Start a HugeGraph Server, then install the LLM dependency set: +### Prerequisites + +- Python 3.12โ3.14 for the LLM application, SDK, Python client and MCP +- [uv](https://docs.astral.sh/uv/) 0.13.6+ (required for workspace management) +- HugeGraph Server 1.3+ for the LLM application (1.5+ recommended), 1.5+ for the Python client, and 1.7.0+ for `hugegraph-mcp` +- Docker (optional, for containerized deployment) + +### Option 1: Docker Deployment (Recommended) ```bash 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](hugegraph-llm/) for model, embedding, vector-index and HugeGraph configuration. +Before starting Compose, follow the [LLM Docker Compose guide](./hugegraph-llm/README.md#option-1-docker-compose-recommended) to prepare both `docker/.env` and the mounted `hugegraph-llm/.env`, configure `GRAPH_URL` and model credentials, and restrict network access. The supplied Compose file publishes both the Server and unauthenticated RAG API on all host interfaces by default. The guide explains loopback-only bindings and authentication for remote access. + +```bash +cd docker +docker compose -f docker-compose-network.yml up -d +docker compose -f docker-compose-network.yml ps +``` + +With the local loopback bindings described in the guide, HugeGraph Server is available at `http://127.0.0.1:8080` and the RAG service at `http://127.0.0.1:8001`. -### Run the Docker environment +### Option 2: Source Installation ```bash +# 1. Start HugeGraph Server +docker run -itd --name=server -p 127.0.0.1:8080:8080 hugegraph/hugegraph + +# 2. Clone and set up the project git clone https://github.com/apache/hugegraph-ai.git cd hugegraph-ai -``` -Before starting Compose, follow the [LLM Docker Compose guide](hugegraph-llm/README.md#option-1-docker-compose-recommended) 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. +# 3. Install dependencies with workspace management +# uv sync automatically creates venv (.venv) and installs base dependencies +uv sync --extra llm # Install LLM-specific dependencies +# To select all root-project extras instead: uv sync --all-extras -```bash -cd docker -docker compose -f docker-compose-network.yml up -d +# 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:8001 ``` -### Use a library instead of the application +For MCP source development, follow the separate [MCP installation guide](./hugegraph-mcp/README.md); `uv sync --all-extras` does not install MCP. + +The source launcher binds to `127.0.0.1` by default and warns when a non-loopback `--host` is selected. The Server example also binds its port to loopback; configure authentication and network restrictions before remote access. -- Install and integrate [`hugegraph-llm-sdk`](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`](hugegraph-mcp/) when an MCP host needs typed graph tools, read-only defaults and controlled write confirmation. +### Examples -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. +- **GraphRAG**: Follow the [LLM quick start](./hugegraph-llm/quick_start.md) for indexing and querying workflows. +- **Graph machine learning**: Follow the [ML examples](./hugegraph-ml/README.md#examples) for node embedding and classification. The ML module uses a standalone environment outside the uv workspace and requires Python 3.12+ because it uses the local Python client. -## Modules +## ๐ฆ Modules -### `hugegraph-llm-sdk` +### [hugegraph-llm-sdk](./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](docs/sdk/architecture.md). +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](./hugegraph-llm-sdk/README.md) for source installation and offline examples, +and [architecture](./docs/sdk/architecture.md) for module responsibilities and extension boundaries. -### `hugegraph-llm` +### [hugegraph-llm](./hugegraph-llm) -Application services and examples for GraphRAG, knowledge-graph construction, natural-language graph access, prompt workflows, model configuration and the RAG API/UI. +Large language model integration for graph applications: -### `hugegraph-mcp` +- **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 with typed schema, graph, Gremlin and extraction tools. It defaults to constrained behavior and requires explicit confirmation for protected writes. +### [hugegraph-mcp](./hugegraph-mcp) -### `hugegraph-python-client` +Model Context Protocol server for safe, controlled HugeGraph access: -Python interface for schema, graph, traverser, variable, task and Gremlin operations. The distribution name is `hugegraph-python`; the import package is `pyhugegraph`. +- **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 `core` toolset with an opt-in `legacy` compatibility mode; the previous `1.7.1` release uses `v2_core` / `v1` -### `hugegraph-ml` and `vermeer-python-client` +### [hugegraph-ml](./hugegraph-ml) -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. +Graph machine learning with 20+ implemented algorithms: -## Documentation +- **Node Classification**: GCN, GAT, GraphSAGE, APPNP, etc. +- **Graph Classification**: DiffPool, P-GNN, etc. +- **Graph Embedding**: DeepWalk, Node2Vec, GRACE, etc. Review Comment: Minor: `hugegraph-ml` has no DeepWalk or Node2Vec model, and GCN, GAT and GraphSAGE appear only as layers inside other models, so this section and the `Graph ML` feature line advertise models users cannot run. List only models from `hugegraph-ml/src/hugegraph_ml/models`, such as DGI, GRACE, GRAND, APPNP and JKNet. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
