This is an automated email from the ASF dual-hosted git repository.
jin pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-hugegraph-ai.git
The following commit(s) were added to refs/heads/main by this push:
new 6fbf164 chore: unify all modules with uv (#287)
6fbf164 is described below
commit 6fbf164f6bdac411b92cf2550ce76532fc08f15f
Author: imbajin <j...@apache.org>
AuthorDate: Mon Jul 21 17:33:56 2025 +0800
chore: unify all modules with uv (#287)
## Walkthrough
This update mainly focuses on project dependency management, construction
configuration, documentation and development process standardization.The core
changes include the introduction of a unified root-level pyproject.toml and uv
tools for dependency management, the removal of version constraints in each
submodule dependency, the standardization of the system to hatchling, and the
reconstruction and simplification of each README document and CI workflow.
---------
Co-authored-by: Hongjun Li
<103014488+returntoinnoce...@users.noreply.github.com>
Co-authored-by: jinglinwei <weijing...@sjtu.edu.cn>
---
.github/workflows/black.yml | 1 +
.github/workflows/hugegraph-python-client.yml | 17 ++--
.github/workflows/pylint.yml | 13 +--
.gitignore | 7 ++
README.md | 86 ++++++++++++----
docker/.dockerignore | 72 +++++++++++++
docker/Dockerfile.llm | 18 ++--
docker/Dockerfile.nk | 16 +--
hugegraph-llm/README.md | 17 ++--
hugegraph-llm/pyproject.toml | 68 ++++++-------
hugegraph-llm/requirements.txt | 20 ----
hugegraph-ml/README.md | 26 +++--
hugegraph-ml/pyproject.toml | 37 ++++---
hugegraph-python-client/README.md | 11 +-
hugegraph-python-client/pyproject.toml | 38 ++++---
pyproject.toml | 139 ++++++++++++++++++++++++++
vermeer-python-client/README.md | 49 +++++----
vermeer-python-client/pyproject.toml | 50 +++++----
18 files changed, 472 insertions(+), 213 deletions(-)
diff --git a/.github/workflows/black.yml b/.github/workflows/black.yml
index 6c123c7..6e512c4 100644
--- a/.github/workflows/black.yml
+++ b/.github/workflows/black.yml
@@ -1,3 +1,4 @@
+# TODO: replace by ruff & mypy soon
name: "Black Code Formatter"
on:
diff --git a/.github/workflows/hugegraph-python-client.yml
b/.github/workflows/hugegraph-python-client.yml
index 927a6b3..886c09e 100644
--- a/.github/workflows/hugegraph-python-client.yml
+++ b/.github/workflows/hugegraph-python-client.yml
@@ -44,22 +44,17 @@ jobs:
restore-keys: |
${{ runner.os }}-uv-${{ matrix.python-version }}-
- # TODO: use pyproject.toml later
- - name: Install dependencies
+ - name: Install dependencies with uv sync
run: |
- uv venv && source .venv/bin/activate
- uv pip install pytest
- uv pip install ./hugegraph-python-client
+ uv sync --extra python-client --extra dev
- name: Test example
run: |
- ls -al && source .venv/bin/activate
- export PYTHONPATH=$(pwd)/hugegraph-python-client/src
- echo ${PYTHONPATH}
- python
hugegraph-python-client/src/pyhugegraph/example/hugegraph_example.py
+ ls -al
+ export PYTHONPATH=$(pwd)/hugegraph-python-client/src && echo
${PYTHONPATH}
+ uv run python
hugegraph-python-client/src/pyhugegraph/example/hugegraph_example.py
- name: Test with pytest
run: |
- ls -al ../ && source ../.venv/bin/activate
- pytest
+ uv run pytest
working-directory: hugegraph-python-client
diff --git a/.github/workflows/pylint.yml b/.github/workflows/pylint.yml
index 7cf4fcf..351628a 100644
--- a/.github/workflows/pylint.yml
+++ b/.github/workflows/pylint.yml
@@ -1,3 +1,4 @@
+# TODO: replace by ruff & mypy soon
name: "Pylint"
on:
@@ -41,18 +42,12 @@ jobs:
- name: Install dependencies
run: |
- uv venv && source .venv/bin/activate
- uv pip install pylint pytest
- uv pip install ./hugegraph-python-client
- uv pip install ./hugegraph-llm
- uv pip install ./hugegraph-ml
+ uv sync --extra all --extra dev
- name: Check DGL version
run: |
- source .venv/bin/activate
- python -c "import dgl; print(dgl.__version__)"
+ uv run python -c "import dgl; print(dgl.__version__)"
- name: Analysing the code with pylint
run: |
- source .venv/bin/activate
- bash ./style/code_format_and_analysis.sh -p
+ uv run bash ./style/code_format_and_analysis.sh -p
diff --git a/.gitignore b/.gitignore
index 8d9bf4b..138ef2d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -115,6 +115,11 @@ ipython_config.py
# https://pdm.fming.dev/#use-with-ide
.pdm.toml
+# uv
+# uv.lock contains resolved dependencies and is generally recommended to
include in version control
+# for reproducible builds, but can be excluded if you prefer to resolve
dependencies fresh
+uv.lock
+
# PEP 582; used by e.g. github.com/David-OConnor/pyflow and
github.com/pdm-project/pdm
__pypackages__/
@@ -147,6 +152,8 @@ venv.bak/
# Rope project settings
.ropeproject
+.pre-commit-config.yaml
+
# mkdocs documentation
/site
diff --git a/README.md b/README.md
index 4d1ccbe..9773bf9 100644
--- a/README.md
+++ b/README.md
@@ -7,11 +7,11 @@
## ✨ Key Features
-- **GraphRAG**: Build intelligent question-answering systems with
graph-enhanced retrieval
-- **Knowledge Graph Construction**: Automated graph building from text using
LLMs
-- **Graph ML**: Integration with 20+ graph learning algorithms (GCN, GAT,
GraphSAGE, etc.)
-- **Python Client**: Easy-to-use Python interface for HugeGraph operations
-- **AI Agents**: Intelligent graph analysis and reasoning capabilities
+- **[LLM/GraphRAG](./hugegraph-llm/README.md#graphrag)**: 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
+- **[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/incubator-hugegraph-computer/tree/master/vermeer#readme)
## 🚀 Quick Start
@@ -19,8 +19,8 @@
> For a complete deployment guide and detailed examples, please refer to
> [hugegraph-llm/README.md](./hugegraph-llm/README.md)
### Prerequisites
-- Python 3.9+ (3.10+ recommended for hugegraph-llm)
-- [uv](https://docs.astral.sh/uv/) (recommended package manager)
+- Python 3.10+ (required for hugegraph-llm)
+- [uv](https://docs.astral.sh/uv/) 0.7+ (required for workspace management)
- HugeGraph Server 1.3+ (1.5+ recommended)
- Docker (optional, for containerized deployment)
@@ -51,19 +51,27 @@ docker run -itd --name=server -p 8080:8080
hugegraph/hugegraph
# 2. Clone and set up the project
git clone https://github.com/apache/incubator-hugegraph-ai.git
-cd incubator-hugegraph-ai/hugegraph-llm
+cd incubator-hugegraph-ai
+
+# 3. Install dependencies with workspace management
+# uv sync automatically creates venv (.venv) and installs base dependencies
+uv sync --extra llm # Install LLM-specific dependencies
+# Or install all optional dependencies: uv sync --all-extras
-# 3. Install dependencies
-uv venv && source .venv/bin/activate
-uv pip install -e .
+# 4. Activate virtual environment (recommended for easier commands)
+source .venv/bin/activate
-# 4. Start the demo
+# 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
```
### Basic Usage Examples
+> [!NOTE]
+> Examples assume you've activated the virtual environment with `source
.venv/bin/activate`
+
#### GraphRAG - Question Answering
```python
from hugegraph_llm.operators.graph_rag_task import RAGPipeline
@@ -76,6 +84,7 @@ result = (graph_rag
.extract_keywords(text="Tell me about Al Pacino.")
.keywords_to_vid()
.query_graphdb(max_deep=2, max_graph_items=30)
+ .merge_dedup_rerank()
.synthesize_answer()
.run())
```
@@ -98,10 +107,14 @@ builder = KgBuilder(LLMs().get_chat_llm())
```
#### Graph Machine Learning
-```python
-from pyhugegraph.client import PyHugeClient
-# Connect to HugeGraph and run ML algorithms
-# See hugegraph-ml documentation for detailed examples
+```bash
+# Install ML dependencies (ml module is not in workspace)
+uv sync --extra ml
+source .venv/bin/activate
+
+# Run ML algorithms
+cd hugegraph-ml
+python examples/your_ml_example.py
```
## 📦 Modules
@@ -120,6 +133,9 @@ Graph machine learning with 20+ implemented algorithms:
- **Graph Embedding**: DeepWalk, Node2Vec, GRACE, etc.
- **Link Prediction**: SEAL, GATNE, etc.
+> [!NOTE]
+> hugegraph-ml is not part of the workspace but linked via path dependency
+
### [hugegraph-python-client](./hugegraph-python-client)
Python client for HugeGraph operations:
- **Schema Management**: Define vertex/edge labels and properties
@@ -133,19 +149,47 @@ Python client for HugeGraph operations:
- [LLM Quick Start Guide](./hugegraph-llm/quick_start.md)
- [DeepWiki AI
Documentation](https://deepwiki.com/apache/incubator-hugegraph-ai)
-## 🔗 Related Projects
+## 🔗 Related HugeGraph Projects
-- [hugegraph](https://github.com/apache/hugegraph) - Core graph database
-- [hugegraph-toolchain](https://github.com/apache/hugegraph-toolchain) -
Development tools (Loader, Dashboard, etc.)
-- [hugegraph-computer](https://github.com/apache/hugegraph-computer) - Graph
computing system
+And here are links of other repositories:
+1. [hugegraph](https://github.com/apache/hugegraph) (graph's core component -
Graph server + PD + Store)
+2. [hugegraph-toolchain](https://github.com/apache/hugegraph-toolchain) (graph
tools
**[loader](https://github.com/apache/incubator-hugegraph-toolchain/tree/master/hugegraph-loader)/[dashboard](https://github.com/apache/incubator-hugegraph-toolchain/tree/master/hugegraph-hubble)/[tool](https://github.com/apache/incubator-hugegraph-toolchain/tree/master/hugegraph-tools)/[client](https://github.com/apache/incubator-hugegraph-toolchain/tree/master/hugegraph-client)**)
+3. [hugegraph-computer](https://github.com/apache/hugegraph-computer)
(integrated **graph computing** system)
+4. [hugegraph-website](https://github.com/apache/hugegraph-doc) (**doc &
website** code)
## 🤝 Contributing
We welcome contributions! Please see our [contribution
guidelines](https://hugegraph.apache.org/docs/contribution-guidelines/) for
details.
**Development Setup:**
+```bash
+# 1. Clone and navigate to project
+git clone https://github.com/apache/incubator-hugegraph-ai.git
+cd incubator-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 group
+```
+
+**Key Points:**
- Use [GitHub Desktop](https://desktop.github.com/) for easier PR management
-- Run `./style/code_format_and_analysis.sh` before submitting PRs
+- Use/Refer AI Coding basic rules (🚧 ing, on the way)
- Check existing issues before reporting bugs
[](https://github.com/apache/incubator-hugegraph-ai/graphs/contributors)
diff --git a/docker/.dockerignore b/docker/.dockerignore
new file mode 100644
index 0000000..4040ed5
--- /dev/null
+++ b/docker/.dockerignore
@@ -0,0 +1,72 @@
+# Git and version control
+.git/
+.gitignore
+.gitattributes
+
+# Python virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Python cache files
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# IDE and editor files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Logs
+logs/
+*.log
+
+# Test files
+tests/
+test/
+*_test.py
+test_*.py
+
+# Development files
+scripts/
+.github/
+style/
+
+# Lock files (will be regenerated)
+uv.lock
+hugegraph-llm/uv.lock
+hugegraph-python-client/uv.lock
+
+# Temporary files
+*.tmp
+*.temp
diff --git a/docker/Dockerfile.llm b/docker/Dockerfile.llm
index 2cc0449..8ebfa61 100644
--- a/docker/Dockerfile.llm
+++ b/docker/Dockerfile.llm
@@ -6,15 +6,14 @@ WORKDIR /home/work/
# Use uv instead of poetry for a more efficient, elegant, and unified py env
management```
RUN pip install --no-cache-dir uv
-# 1.1 Copy source code
-COPY hugegraph-python-client/ ./hugegraph-python-client/
-COPY hugegraph-llm/ ./hugegraph-llm/
+# 1.1 Copy source code (merged for efficiency)
+COPY . .
# 1.2 Install dependency
-RUN cd /home/work/hugegraph-llm && \
+RUN cd /home/work/ && \
uv venv && \
- uv pip install -e . && \
- uv pip install ../hugegraph-python-client
+ . .venv/bin/activate && \
+ uv sync --extra llm
# Stage 2: Runtime stage
FROM python:3.10.16-slim-bookworm
@@ -30,13 +29,14 @@ RUN useradd -m -s /bin/bash work && \
WORKDIR /home/work/
# Copy virtual environment and source code
-COPY --from=builder --chown=work:work /home/work/hugegraph-llm/.venv
/home/work/hugegraph-llm/.venv
+COPY --from=builder --chown=work:work /home/work/.venv /home/work/.venv
COPY --from=builder --chown=work:work /home/work/hugegraph-llm/src
/home/work/hugegraph-llm/src
COPY --from=builder --chown=work:work /home/work/hugegraph-llm/pyproject.toml
/home/work/hugegraph-llm/pyproject.toml
+COPY --from=builder --chown=work:work /home/work/hugegraph-python-client/src
/home/work/hugegraph-python-client/src
USER work
-ENV PATH="/home/work/hugegraph-llm/.venv/bin:$PATH"
-ENV PYTHONPATH="/home/work/hugegraph-llm/src"
+ENV PATH="/home/work/.venv/bin:$PATH"
+ENV
PYTHONPATH="/home/work/hugegraph-llm/src:/home/work/hugegraph-python-client/src"
WORKDIR /home/work/hugegraph-llm
VOLUME ["/home/work/hugegraph-llm/src/hugegraph_llm/resources"]
diff --git a/docker/Dockerfile.nk b/docker/Dockerfile.nk
index a754109..4de4081 100644
--- a/docker/Dockerfile.nk
+++ b/docker/Dockerfile.nk
@@ -3,21 +3,23 @@ FROM python:3.10.16-bookworm AS builder
WORKDIR /build/
-# 1.1 Copy source code
-COPY hugegraph-python-client/ ./hugegraph-python-client/
-COPY hugegraph-llm/ ./hugegraph-llm/
+# Use uv instead of poetry for a more efficient, elegant, and unified py env
management
+RUN pip install --no-cache-dir uv
+
+# 1.1 Copy source code (merged for efficiency)
+COPY . .
# 1.2 Install dependency
RUN apt update && \
apt install -y --no-install-recommends build-essential patchelf && \
- python -m pip install nuitka && \
- pip install ./hugegraph-python-client && \
- pip install -r ./hugegraph-llm/requirements.txt && \
+ uv venv && \
+ . .venv/bin/activate && \
+ uv sync --extra nk-llm && \
cd hugegraph-llm/src && \
export PYTHONPATH=/build/hugegraph-llm/src && \
python -m nuitka --follow-imports --standalone
--include-package-data=safehttpx,groovy,gradio,litellm,jieba
--include-module=hugegraph_llm.demo.rag_demo.app,litellm.litellm_core_utils.tokenizers
--include-data-dir=./hugegraph_llm/resources=hugegraph_llm/resources
./hugegraph_llm/demo/rag_demo/app.py && \
mv app.* ..
-
+
# Stage 2: Runtime stage
FROM python:3.10.16-slim-bookworm
LABEL maintainer="HugeGraph Docker Maintainers <d...@hugegraph.apache.org>"
diff --git a/hugegraph-llm/README.md b/hugegraph-llm/README.md
index 8907c31..24ffdc5 100644
--- a/hugegraph-llm/README.md
+++ b/hugegraph-llm/README.md
@@ -78,16 +78,16 @@ For development and customization:
# 1. Start HugeGraph Server
docker run -itd --name=server -p 8080:8080 hugegraph/hugegraph
-# 2. Install UV package manager
+# 2. Install UV package manager (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh
# 3. Clone and setup project
git clone https://github.com/apache/incubator-hugegraph-ai.git
cd incubator-hugegraph-ai/hugegraph-llm
-# 4. Create virtual environment and install dependencies
-uv venv && source .venv/bin/activate
-uv pip install -e .
+# 4. Install dependencies and activate environment
+uv sync # Automatically creates .venv and installs dependencies
+source .venv/bin/activate # Activate once - all commands below assume this
environment
# 5. Launch RAG demo
python -m hugegraph_llm.demo.rag_demo.app
@@ -99,16 +99,21 @@ python -m hugegraph_llm.demo.rag_demo.app --host 127.0.0.1
--port 18001
#### Additional Setup (Optional)
+> [!NOTE]
+> The following commands assume you're in the activated virtual environment
from step 4 above
+
```bash
# Download NLTK stopwords for better text processing
-python ./hugegraph_llm/operators/common_op/nltk_helper.py
+python ./src/hugegraph_llm/operators/common_op/nltk_helper.py
# Update configuration files
python -m hugegraph_llm.config.generate --update
```
> [!TIP]
-> Check our [Quick Start
Guide](https://github.com/apache/incubator-hugegraph-ai/blob/main/hugegraph-llm/quick_start.md)
for detailed usage examples and query logic explanations.
+> - `uv sync` automatically creates virtual environment (.venv) and installs
all dependencies
+> - Activate once with `source .venv/bin/activate` - all subsequent commands
assume this environment
+> - Check our [Quick Start
Guide](https://github.com/apache/incubator-hugegraph-ai/blob/main/hugegraph-llm/quick_start.md)
for detailed usage examples
## 💡 Usage Examples
diff --git a/hugegraph-llm/pyproject.toml b/hugegraph-llm/pyproject.toml
index 4ab5d09..dba36ca 100644
--- a/hugegraph-llm/pyproject.toml
+++ b/hugegraph-llm/pyproject.toml
@@ -25,54 +25,51 @@ authors = [
readme = "README.md"
license = "Apache-2.0"
requires-python = ">=3.10,<3.12"
-maintainers = [
- { name = "Apache HugeGraph Contributors", email =
"d...@hugegraph.apache.org" },
-]
dependencies = [
- "openai~=1.61.0",
- "ollama~=0.4.8",
- "qianfan~=0.3.18",
- "retry~=0.9.2",
- "tiktoken~=0.7.0",
- "nltk~=3.9.1",
- "gradio~=5.20.0",
- "jieba~=0.42.1",
- "numpy~=1.24.4",
- "python-docx~=1.1.2",
- "langchain-text-splitters~=0.2.2",
- "faiss-cpu~=1.8.0",
- "python-dotenv~=1.0.1",
- "pyarrow~=17.0.0",
- "pandas<2.2.2",
- "openpyxl~=3.1.5",
- "pydantic~=2.10.6",
- "pydantic-settings~=2.6.1",
- "decorator~=5.1.1",
- "requests~=2.32.0",
- "setuptools~=70.0.0",
- "urllib3~=2.2.2",
- "rich~=13.9.4",
- "apscheduler~=3.10.4",
- "litellm~=1.61.13",
+ # Common dependencies
+ "decorator",
+ "requests",
+ "setuptools",
+ "urllib3",
+ "rich",
+
+ # Data processing dependencies
+ "numpy",
+ "pandas",
+ "pydantic",
+
+ # LLM specific dependencies
+ "openai",
+ "ollama",
+ "qianfan",
+ "retry",
+ "tiktoken",
+ "nltk",
+ "gradio",
+ "jieba",
+ "python-docx",
+ "langchain-text-splitters",
+ "faiss-cpu",
+ "python-dotenv",
+ "pyarrow",
+ "openpyxl",
+ "pydantic-settings",
+ "apscheduler",
+ "litellm",
"hugegraph-python-client",
]
[project.urls]
homepage = "https://hugegraph.apache.org/";
repository = "https://github.com/apache/incubator-hugegraph-ai";
documentation = "https://hugegraph.apache.org/docs/quickstart/hugegraph-ai/";
-"Bug Tracker" = "https://github.com/apache/incubator-hugegraph-ai/issues";
+bug_tracker = "https://github.com/apache/incubator-hugegraph-ai/issues";
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
-#If you want to modify the network configuration file of the project, then you
can modify this part
-[[tool.uv.index]]
-url = "https://pypi.tuna.tsinghua.edu.cn/simple";
-default = true
-
[tool.hatch.build.targets.wheel]
packages = ["src/hugegraph_llm"]
@@ -82,11 +79,10 @@ include = [
"README.md",
"LICENSE",
"NOTICE",
- "MANIFEST.in"
]
[tool.hatch.metadata]
allow-direct-references = true
[tool.uv.sources]
-hugegraph-python-client = { path = "../hugegraph-python-client/", editable =
true }
+hugegraph-python-client = { workspace = true }
diff --git a/hugegraph-llm/requirements.txt b/hugegraph-llm/requirements.txt
deleted file mode 100644
index 5074a15..0000000
--- a/hugegraph-llm/requirements.txt
+++ /dev/null
@@ -1,20 +0,0 @@
-# TODO: remove this file after uv run stable, don't update it
-openai~=1.61.0
-ollama~=0.4.8
-qianfan~=0.3.18
-retry~=0.9.2
-tiktoken>=0.7.0
-nltk~=3.8.1
-gradio~=5.29.1
-jieba>=0.42.1
-numpy~=1.24.4
-python-docx~=1.1.2
-langchain-text-splitters~=0.2.2
-faiss-cpu~=1.8.0
-python-dotenv>=1.0.1
-pyarrow~=17.0.0 # TODO: a temporary dependency for pandas, figure out why
ImportError
-pandas~=2.2.2
-openpyxl~=3.1.5
-pydantic-settings~=2.6.1
-apscheduler~=3.10.4
-litellm~=1.61.13
diff --git a/hugegraph-ml/README.md b/hugegraph-ml/README.md
index d1c46e4..9e6eaf3 100644
--- a/hugegraph-ml/README.md
+++ b/hugegraph-ml/README.md
@@ -32,10 +32,11 @@ The implemented algorithm models can be found in the
[models](./src/hugegraph_ml
## Environment Requirements
-- python 3.9+
-- hugegraph-server 1.0+
+- python 3.9+ (standalone module, not part of workspace)
+- hugegraph-server 1.0+ (recommended: 1.5+)
+- [uv](https://docs.astral.sh/uv/) 0.7+ (for dependency management)
-## Preparation
+## Installation
1. Start the HugeGraph database, you can do it via
Docker/[Binary
packages](https://hugegraph.apache.org/docs/download/download/).
@@ -43,26 +44,31 @@ The implemented algorithm models can be found in the
[models](./src/hugegraph_ml
to [docker-link](https://hub.docker.com/r/hugegraph/hugegraph) &
[deploy-doc](https://hugegraph.apache.org/docs/quickstart/hugegraph-server/#31-use-docker-container-convenient-for-testdev)
for guidance
-2. Clone this project
+2. Clone and setup the project:
```bash
git clone https://github.com/apache/incubator-hugegraph-ai.git
+ cd incubator-hugegraph-ai/hugegraph-ml
```
-3. Install [hugegraph-python-client](../hugegraph-python-client) and
[hugegraph-ml](../hugegraph-ml)
+3. Install dependencies using uv:
```bash
- uv venv && source .venv/bin/activate # create and activate virtual
environment
- cd ./hugegraph-ml/ # navigate to the hugegraph-ml directory
- uv pip install . # install dependencies using uv
+ # uv sync automatically creates .venv and installs all dependencies
+ uv sync
+ # Activate virtual environment for easier command usage
+ source .venv/bin/activate
```
-4. Enter the project directory
+4. Navigate to source directory for examples:
```bash
- cd ./hugegraph-ml/src
+ cd ./src
```
+> [!NOTE]
+> All examples below assume you're in the activated virtual environment
+
## Examples
### Perform node embedding on the `Cora` dataset using the `DGI` model
diff --git a/hugegraph-ml/pyproject.toml b/hugegraph-ml/pyproject.toml
index a92cfae..6d46ba7 100644
--- a/hugegraph-ml/pyproject.toml
+++ b/hugegraph-ml/pyproject.toml
@@ -29,33 +29,30 @@ authors = [
]
readme = "README.md"
license = "Apache-2.0"
-requires-python = ">=3.9"
+requires-python = ">=3.10"
dependencies = [
- "dgl~=2.1.0",
- "ogb~=1.3.6",
- "pandas~=2.2.3",
- "catboost~=1.2.3",
- "category_encoders~=2.6.3",
- "numpy~=1.24.4",
- "torch==2.2.0",
- "tqdm~=4.66.5",
- "packaging~=24.1",
- "torchdata~=0.7.0",
- "PyYAML~=6.0.2",
- "pydantic~=2.9.2",
- "hugegraph-python-client"
+ # ML specific dependencies
+ "dgl",
+ "ogb",
+ "catboost",
+ "category-encoders",
+ "torch",
+ "tqdm",
+ "packaging",
+ "torchdata",
+ "PyYAML",
+ "hugegraph-python-client",
+ # Common data dependencies managed by root
+ "numpy",
+ "pandas",
+ "pydantic",
]
[project.urls]
homepage = "https://hugegraph.apache.org/";
repository = "https://github.com/apache/incubator-hugegraph-ai";
-# If you want to modify the network configuration file of the project, then
you can modify this part
-[[tool.uv.index]]
-url = "https://pypi.tuna.tsinghua.edu.cn/simple";
-default = true
-
[tool.hatch.build.targets.wheel]
packages = ["src/hugegraph_ml"]
@@ -71,4 +68,4 @@ include = [
allow-direct-references = true
[tool.uv.sources]
-hugegraph-python-client = { path = "../hugegraph-python-client/", editable =
true }
+hugegraph-python-client = { path = "../hugegraph-python-client", editable =
true }
diff --git a/hugegraph-python-client/README.md
b/hugegraph-python-client/README.md
index 36a26f2..67150d6 100644
--- a/hugegraph-python-client/README.md
+++ b/hugegraph-python-client/README.md
@@ -24,13 +24,14 @@ To install from the source, clone the repository and
install the required depend
git clone https://github.com/apache/incubator-hugegraph-ai.git
cd incubator-hugegraph-ai/hugegraph-python-client
-# Normal install
-uv pip install .
-
-# (Optional) install the devel version
-uv pip install -e .
+# Use uv sync to install dependencies (workspace member)
+uv sync # Automatically creates .venv and installs dependencies
+source .venv/bin/activate # Activate once - all commands below assume this
environment
```
+> [!NOTE]
+> All usage examples below assume you're in the activated virtual environment
+
## Usage
### Defining Graph Structures
diff --git a/hugegraph-python-client/pyproject.toml
b/hugegraph-python-client/pyproject.toml
index 27bceae..81565d9 100644
--- a/hugegraph-python-client/pyproject.toml
+++ b/hugegraph-python-client/pyproject.toml
@@ -27,25 +27,33 @@ license = "Apache-2.0"
requires-python = ">=3.9"
dependencies = [
- "decorator~=5.1.1",
- "requests~=2.32.0",
- "setuptools~=70.0.0",
- "urllib3~=2.2.2",
- "rich~=13.9.4",
+ # Common dependencies
+ "decorator",
+ "requests",
+ "setuptools",
+ "urllib3",
+ "rich",
]
[project.urls]
-"Homepage" = "https://github.com/apache/incubator-hugegraph-ai";
-"Repository" = "https://github.com/apache/incubator-hugegraph-ai";
-"Bug Tracker" = "https://github.com/apache/incubator-hugegraph-ai/issues";
+homepage = "https://github.com/apache/incubator-hugegraph-ai";
+repository = "https://github.com/apache/incubator-hugegraph-ai";
+bug_tracker = "https://github.com/apache/incubator-hugegraph-ai/issues";
[build-system]
-requires = ["setuptools>=61.0"]
-build-backend = "setuptools.build_meta"
+requires = ["hatchling"]
+build-backend = "hatchling.build"
-[tool.setuptools.packages.find]
-where = ["src"]
-exclude = ["tests"]
+[tool.hatch.build.targets.wheel]
+packages = ["src/pyhugegraph"]
-[tool.setuptools]
-package-dir = {"" = "src"}
+[tool.hatch.build.targets.sdist]
+include = [
+ "src/pyhugegraph",
+ "README.md",
+ "LICENSE",
+ "NOTICE",
+]
+
+[tool.hatch.metadata]
+allow-direct-references = true
diff --git a/pyproject.toml b/pyproject.toml
new file mode 100644
index 0000000..c56108b
--- /dev/null
+++ b/pyproject.toml
@@ -0,0 +1,139 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+[project]
+name = "hugegraph-ai"
+version = "1.5.0"
+description = "A repository for AI-related projects for Apache HugeGraph."
+authors = [
+ { name = "Apache HugeGraph Contributors", email =
"d...@hugegraph.apache.org" },
+]
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10" # Adjusted to the highest requirement among
submodules (hugegraph-llm)
+maintainers = [
+ { name = "Apache HugeGraph Contributors", email =
"d...@hugegraph.apache.org" },
+]
+
+dependencies = [
+ # Common dependencies can be listed here if any,
+ # but it's generally better to keep them within extras for clarity
+]
+
+[project.optional-dependencies]
+llm = ["hugegraph-llm"]
+ml = ["hugegraph-ml"]
+python-client = ["hugegraph-python-client"]
+vermeer = ["vermeer-python-client"]
+dev = [
+ "pytest~=8.0.0",
+ "pytest-cov~=5.0.0",
+ "pylint~=3.0.0",
+]
+
+nk-llm = ["hugegraph-llm", "hugegraph-python-client", "nuitka"]
+all = ["hugegraph-python-client", "hugegraph-llm", "hugegraph-ml",
"vermeer-python-client"]
+
+[project.urls]
+homepage = "https://hugegraph.apache.org/";
+repository = "https://github.com/apache/incubator-hugegraph-ai";
+documentation = "https://hugegraph.apache.org/docs/quickstart/hugegraph-ai/";
+bug_tracker = "https://github.com/apache/incubator-hugegraph-ai/issues";
+changelog = "https://github.com/apache/incubator-hugegraph-ai/releases";
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+# Comment explaining that this is an example and can be overridden
+# [[tool.uv.index]]
+# url = "https://pypi.tuna.tsinghua.edu.cn/simple"; # Example mirror for users
in China
+# default = true
+#
+# Users can override this in their personal configuration with: uv config
--global index.url https://pypi.org/simple
+
+[tool.hatch.metadata] # Keep this if hatch is still used by submodules,
otherwise remove
+allow-direct-references = true
+
+[tool.hatch.build.targets.wheel]
+packages = [
+ "hugegraph-llm",
+ "hugegraph-python-client"
+]
+
+[tool.hatch.build.targets.sdist]
+include = ["*/src", "README.md", "LICENSE", "NOTICE"]
+
+[tool.uv.sources]
+hugegraph-llm = { workspace = true }
+hugegraph-python-client = { workspace = true }
+hugegraph-ml = { path = "hugegraph-ml", editable = true }
+vermeer-python-client = { path = "vermeer-python-client", editable = true }
+
+[tool.uv.workspace]
+members = [
+ "hugegraph-llm",
+ "hugegraph-python-client"
+]
+
+[tool.uv]
+constraint-dependencies = [
+ # Common dependencies
+ "decorator~=5.1.1",
+ "requests~=2.32.0", # TODO: use httpx instead of urllib3 directly
+ "setuptools~=70.0.0", # TODO: remove it when we use hatchling well
+ "urllib3~=2.2.2",
+ "rich~=13.9.4",
+
+ # Data processing dependencies
+ "numpy~=1.24.4",
+ "pandas~=2.2.3", # TODO: replace by polars(rust) in the future
+ "pydantic~=2.10.6",
+
+ # LLM dependencies
+ "openai~=1.61.0",
+ "ollama~=0.4.8",
+ "qianfan~=0.3.18", # TODO: remove it
+ "retry~=0.9.2",
+ "tiktoken~=0.7.0",
+ "nltk~=3.9.1",
+ "gradio~=5.20.0",
+ "jieba~=0.42.1",
+ "python-docx~=1.1.2",
+ "langchain-text-splitters~=0.2.2",
+ "faiss-cpu~=1.8.0",
+ "python-dotenv~=1.0.1",
+ "pyarrow~=17.0.0",
+ "openpyxl~=3.1.5",
+ "pydantic-settings~=2.6.1",
+ "apscheduler~=3.10.4",
+ "litellm~=1.61.13",
+
+ # ML dependencies
+ "dgl~=2.1.0",
+ "ogb~=1.3.6",
+ "catboost~=1.2.3",
+ "category-encoders~=2.6.3",
+ "torch==2.2.0",
+ "tqdm~=4.66.5",
+ "packaging~=24.1",
+ "torchdata~=0.7.0",
+ "PyYAML~=6.0.2",
+
+ # Other dependencies
+ "python-dateutil~=2.9.0",
+]
diff --git a/vermeer-python-client/README.md b/vermeer-python-client/README.md
index 818feff..2b7b2ec 100644
--- a/vermeer-python-client/README.md
+++ b/vermeer-python-client/README.md
@@ -22,13 +22,14 @@ To install from the source, clone the repository and
install the required depend
git clone https://github.com/apache/incubator-hugegraph-ai.git
cd incubator-hugegraph-ai/vermeer-python-client
-# Normal install
-uv pip install .
-
-# (Optional) install the devel version
-uv pip install -e .
+# Use uv sync to install dependencies (standalone module, not in workspace)
+uv sync # Automatically creates .venv and installs dependencies
+source .venv/bin/activate # Activate once - all commands below assume this
environment
```
+> [!NOTE]
+> All usage examples below assume you're in the activated virtual environment
+
## Usage
This section provides examples of how to use the `vermeer-python-client`.
@@ -38,33 +39,37 @@ This section provides examples of how to use the
`vermeer-python-client`.
### Initialize the Client
```python
-from pyvermeer.client import VermeerClient
+from pyvermeer.client.client import PyVermeerClient
# Initialize the client
-client = VermeerClient(host="127.0.0.1", port="8080")
+client = PyVermeerClient(ip="127.0.0.1", port=8688, token="",
log_level="DEBUG")
print("Client initialized successfully.")
```
-### Example: Running a Graph Algorithm
+### Example: Creating a Task
```python
-# Placeholder for running a graph algorithm example
-try:
- result = client.run_algorithm(name="pagerank", params={"alpha": 0.85,
"max_iter": 10})
- print(f"PageRank results: {result}")
-except Exception as e:
- print(f"Error running algorithm: {e}")
-```
-
-### Example: Managing Jobs
+from pyvermeer.structure.task_data import TaskCreateRequest
-```python
-# Placeholder for managing jobs example
+# Example for creating a task
try:
- job_status = client.get_job_status(job_id="some_job_id")
- print(f"Job status: {job_status}")
+ create_response = client.tasks.create_task(
+ create_task=TaskCreateRequest(
+ task_type='load',
+ graph_name='DEFAULT-example',
+ params={
+ "load.hg_pd_peers": "[\"127.0.0.1:8686\"]",
+ "load.hugegraph_name": "DEFAULT/example/g",
+ "load.hugegraph_password": "xxx",
+ "load.hugegraph_username": "xxx",
+ "load.parallel": "10",
+ "load.type": "hugegraph"
+ },
+ )
+ )
+ print(f"Create task response: {create_response.to_dict()}")
except Exception as e:
- print(f"Error getting job status: {e}")
+ print(f"Error creating task: {e}")
```
Other info is under 🚧 (Welcome to add more docs for it)
diff --git a/vermeer-python-client/pyproject.toml
b/vermeer-python-client/pyproject.toml
index 2fd2391..9860108 100644
--- a/vermeer-python-client/pyproject.toml
+++ b/vermeer-python-client/pyproject.toml
@@ -17,37 +17,43 @@
[project]
name = "vermeer-python-client"
-version = "1.5.0"
-description = "A Python SDK for Apache Vermeer."
+version = "1.5.0" # Independently managed version for the
vermeer-python-client package
+description = "A Python client library for interacting with Vermeer, a tool
for managing and analyzing large-scale graph data."
authors = [
- { name = "Apache HugeGraph Contributors", email =
"d...@hugegraph.apache.org" },
+ { name = "Apache HugeGraph Contributors", email =
"d...@hugegraph.apache.org" }
]
readme = "README.md"
license = "Apache-2.0"
requires-python = ">=3.9"
+
dependencies = [
- "decorator~=5.1.1",
- "requests~=2.32.0",
- "urllib3~=2.2.2",
+ # Common dependencies
+ "decorator",
+ "requests",
+ "setuptools",
+ "urllib3",
+ "rich",
+
+ # Vermeer specific dependencies
+ "python-dateutil",
]
[project.urls]
-"Homepage" = "https://github.com/apache/incubator-hugegraph-ai";
-"Repository" = "https://github.com/apache/incubator-hugegraph-ai";
-"Bug Tracker" = "https://github.com/apache/incubator-hugegraph-ai/issues";
-
-[project.optional-dependencies]
-dev = [
- "pytest>=7.0.0",
- "black>=23.0.0",
- "isort>=5.0.0",
- "flake8>=6.0.0",
-]
+homepage = "https://hugegraph.apache.org/";
+repository = "https://github.com/apache/incubator-hugegraph-ai";
[build-system]
-requires = ["setuptools>=61.0"]
-build-backend = "setuptools.build_meta"
+requires = ["hatchling"] # Using hatchling like other submodules for
consistency
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pyvermeer"] # Based on the setup.py's find_packages and
package_dir
+
+[tool.hatch.build.targets.sdist]
+include = [
+ "src/pyvermeer",
+ "README.md",
+]
-[tool.setuptools.packages.find]
-where = ["src"]
-exclude = ["tests"]
+[tool.hatch.metadata]
+allow-direct-references = true
