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 cd6fd33 fix(config): enhance config path handling and add project
root validation (#262)
cd6fd33 is described below
commit cd6fd333a60a91811386b74ce11c8127dde902b5
Author: Linyu <94553312+weijing...@users.noreply.github.com>
AuthorDate: Wed Jun 4 22:11:48 2025 +0800
fix(config): enhance config path handling and add project root validation
(#262)
# Add Path Checking Logic for Configuration Files
## Description
This PR introduces path validation logic to ensure the application is
running from the correct project root directory. It adds a new utility
function to determine the project root and implements checks to prevent
configuration loading from incorrect working directories.
## Changes
- Added new utility function `get_project_root()` in
`hugegraph_llm/utils/anchor.py` to reliably determine the project root
directory
- Updated configuration file path in `base_prompt_config.py` to use the
correct path structure
- Implemented working directory validation in
`BasePromptConfig.ensure_yaml_file_exists()`
- Added graceful error handling with informative messages when running
from incorrect directory
## Technical Details
- The path checking logic verifies if the current working directory
matches the project root
- If running from incorrect directory, the application will exit with a
clear error message
- Configuration file path has been updated to use the correct structure
under `src/hugegraph_llm/resources/demo`
## Testing
- [x] Verify application runs correctly from project root
- [x] Confirm appropriate error message when running from incorrect
directory
- [x] Test configuration file loading with the new path structure
## Impact
This change improves the reliability of the application by ensuring
configuration files are loaded from the correct location and provides
better error handling for incorrect usage.
---------
Co-authored-by: imbajin <j...@apache.org>
---
docker/Dockerfile.llm | 30 ++++++++--------
docker/Dockerfile.nk | 2 +-
hugegraph-llm/README.md | 41 +++++++++++++++++++---
.../config/models/base_prompt_config.py | 15 ++++++++
hugegraph-llm/src/hugegraph_llm/utils/anchor.py | 39 ++++++++++++++++++++
5 files changed, 106 insertions(+), 21 deletions(-)
diff --git a/docker/Dockerfile.llm b/docker/Dockerfile.llm
index 1d527c6..8508090 100644
--- a/docker/Dockerfile.llm
+++ b/docker/Dockerfile.llm
@@ -1,23 +1,20 @@
-# TODO: we could use 'uv' to replace the poetry + python image (Also use the
slime image)
# Stage 1: Build stage (Isolating the build env)
FROM python:3.10.16-bookworm AS builder
-WORKDIR /build/
+WORKDIR /home/work/
-# 1.1 Install poetry
-RUN pip install --no-cache-dir poetry
+# Use uv instead of poetry for a more efficient, elegant, and unified py env
management```
+RUN pip install --no-cache-dir uv
-# 1.2 Copy source code
+# 1.1 Copy source code
COPY hugegraph-python-client/ ./hugegraph-python-client/
COPY hugegraph-llm/ ./hugegraph-llm/
-# 1.3 Install dependencies
-RUN cd /build/hugegraph-llm && \
- poetry config virtualenvs.in-project true && \
- poetry lock && \
- poetry install --no-interaction --no-ansi --verbose && \
- .venv/bin/pip install ../hugegraph-python-client && \
- poetry build
+# 1.2 Install dependency
+RUN cd /home/work/hugegraph-llm && \
+ uv venv && \
+ uv pip install -e . && \
+ uv pip install ../hugegraph-python-client
# Stage 2: Runtime stage
FROM python:3.10.16-slim-bookworm
@@ -32,14 +29,15 @@ RUN useradd -m -s /bin/bash work && \
WORKDIR /home/work/
-# Copy only the built packages and virtual environment from the builder stage
-COPY --from=builder --chown=work:work /build/hugegraph-llm/.venv
/home/work/hugegraph-llm/.venv
-COPY --from=builder --chown=work:work /build/hugegraph-llm/src
/home/work/hugegraph-llm/src
+# 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/hugegraph-llm/src
/home/work/hugegraph-llm/src
USER work
ENV PATH="/home/work/hugegraph-llm/.venv/bin:$PATH"
+ENV PYTHONPATH="/home/work/hugegraph-llm/src"
-WORKDIR /home/work/hugegraph-llm/src
+WORKDIR /home/work/hugegraph-llm
VOLUME ["/home/work/hugegraph-llm/src/hugegraph_llm/resources"]
EXPOSE 8001
diff --git a/docker/Dockerfile.nk b/docker/Dockerfile.nk
index ecefbe8..ba6c084 100644
--- a/docker/Dockerfile.nk
+++ b/docker/Dockerfile.nk
@@ -15,7 +15,7 @@ RUN apt update && \
pip install -r ./hugegraph-llm/requirements.txt && \
cd hugegraph-llm/src && \
export PYTHONPATH=/build/hugegraph-llm/src && \
- python -m nuitka --follow-imports --standalone
--include-package-data=safehttpx,groovy,gradio,litellm
--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 && \
+ 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
diff --git a/hugegraph-llm/README.md b/hugegraph-llm/README.md
index 4c2a201..ae5e281 100644
--- a/hugegraph-llm/README.md
+++ b/hugegraph-llm/README.md
@@ -23,6 +23,38 @@ graph systems and large language models.
## 3. Preparation
+### 3.1 Docker
+
+**Docker Deployment**
+ Alternatively, you can deploy HugeGraph-AI using Docker:
+ - Ensure you have Docker installed
+ - We provide two container images:
+ - **Image 1**:
[hugegraph/rag](https://hub.docker.com/r/hugegraph/rag/tags)
+ For building and running the RAG functionality, suitable for quick
deployment and development
+ - **Image 2**:
[hugegraph/rag-bin](https://hub.docker.com/r/hugegraph/rag-bin/tags)
+ Binary version compiled with Nuitka for more stable and efficient
performance in production
+ - Pull the Docker images:
+ ```bash
+ docker pull hugegraph/rag:latest # Pull Image 1
+ docker pull hugegraph/rag-bin:latest # Pull Image 2
+ ```
+ - Start the Docker container:
+ ```bash
+ docker run -it --name rag -p 8001:8001 hugegraph/rag bash
+ docker run -it --name rag-bin -p 8001:8001 hugegraph/rag-bin bash
+ ```
+ - Start the Graph RAG demo:
+ ```bash
+ # For Image 1
+ python ./src/hugegraph_llm/demo/rag_demo/app.py # or run python -m
hugegraph_llm.demo.rag_demo.app
+
+ # For Image 2
+ ./app.dist/app.bin
+ ```
+ - Access the interface at http://localhost:8001
+
+### 3.2 Build from Source
+
1. Start the HugeGraph database, you can run it via
[Docker](https://hub.docker.com/r/hugegraph/hugegraph)/[Binary
Package](https://hugegraph.apache.org/docs/download/download/).
There is a simple method by docker:
```bash
@@ -47,7 +79,8 @@ graph systems and large language models.
uv pip install -e .
```
If dependency download fails or too slow due to network issues, it is
recommended to modify `hugegraph-llm/pyproject.toml`.
-6. Start the gradio interactive demo of **Graph RAG**, you can run with the
following command and open http://127.0.0.1:8001 after starting
+
+5. Start the gradio interactive demo of **Graph RAG**, you can run with the
following command and open http://127.0.0.1:8001 after starting
```bash
python -m hugegraph_llm.demo.rag_demo.app # same as "uv run xxx"
```
@@ -56,18 +89,18 @@ graph systems and large language models.
python -m hugegraph_llm.demo.rag_demo.app --host 127.0.0.1 --port 18001
```
-7. After running the web demo, the config file `.env` will be automatically
generated at the path `hugegraph-llm/.env`. Additionally, a prompt-related
configuration file `config_prompt.yaml` will also be generated at the path
`hugegraph-llm/src/hugegraph_llm/resources/demo/config_prompt.yaml`.
+6. After running the web demo, the config file `.env` will be automatically
generated at the path `hugegraph-llm/.env`. Additionally, a prompt-related
configuration file `config_prompt.yaml` will also be generated at the path
`hugegraph-llm/src/hugegraph_llm/resources/demo/config_prompt.yaml`.
You can modify the content on the web page, and it will be automatically
saved to the configuration file after the corresponding feature is triggered.
You can also modify the file directly without restarting the web application;
refresh the page to load your latest changes.
(Optional)To regenerate the config file, you can use `config.generate`
with `-u` or `--update`.
```bash
python -m hugegraph_llm.config.generate --update
```
Note: `Litellm` support multi-LLM provider, refer
[litellm.ai](https://docs.litellm.ai/docs/providers) to config it
-8. (__Optional__) You could use
+7. (__Optional__) You could use
[hugegraph-hubble](https://hugegraph.apache.org/docs/quickstart/hugegraph-hubble/#21-use-docker-convenient-for-testdev)
to visit the graph data, could run it via
[Docker/Docker-Compose](https://hub.docker.com/r/hugegraph/hubble)
for guidance. (Hubble is a graph-analysis dashboard that includes data
loading/schema management/graph traverser/display).
-9. (__Optional__) offline download NLTK stopwords
+8. (__Optional__) offline download NLTK stopwords
```bash
python ./hugegraph_llm/operators/common_op/nltk_helper.py
```
diff --git
a/hugegraph-llm/src/hugegraph_llm/config/models/base_prompt_config.py
b/hugegraph-llm/src/hugegraph_llm/config/models/base_prompt_config.py
index 5341fd8..563845d 100644
--- a/hugegraph-llm/src/hugegraph_llm/config/models/base_prompt_config.py
+++ b/hugegraph-llm/src/hugegraph_llm/config/models/base_prompt_config.py
@@ -15,11 +15,14 @@
# specific language governing permissions and limitations
# under the License.
+import sys
import os
+from pathlib import Path
import yaml
from hugegraph_llm.utils.log import log
+from hugegraph_llm.utils.anchor import get_project_root
dir_name = os.path.dirname
F_NAME = "config_prompt.yaml"
@@ -38,6 +41,18 @@ class BasePromptConfig:
doc_input_text: str = ''
def ensure_yaml_file_exists(self):
+ current_dir = Path.cwd().resolve()
+ project_root = get_project_root()
+ if current_dir == project_root:
+ log.info("Current working directory is the project root,
proceeding to run the app.")
+ else:
+ error_msg = (
+ f"Current working directory is not the project root. "
+ f"Please run this script from the project root directory:
{project_root}\n"
+ f"Current directory: {current_dir}"
+ )
+ log.error(error_msg)
+ sys.exit(1)
if os.path.exists(yaml_file_path):
log.info("Loading prompt file '%s' successfully.", F_NAME)
with open(yaml_file_path, "r", encoding="utf-8") as file:
diff --git a/hugegraph-llm/src/hugegraph_llm/utils/anchor.py
b/hugegraph-llm/src/hugegraph_llm/utils/anchor.py
new file mode 100644
index 0000000..d5f687a
--- /dev/null
+++ b/hugegraph-llm/src/hugegraph_llm/utils/anchor.py
@@ -0,0 +1,39 @@
+# 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.
+
+from pathlib import Path
+
+def get_project_root() -> Path:
+ """
+ Returns the Path object of the project root directory.
+
+ The function searches for common project root indicators like
pyproject.toml
+ or .git directory by traversing up the directory tree from the current
file location.
+
+ Returns:
+ Path: The absolute path to the project root directory
+
+ Raises:
+ RuntimeError: If no project root indicators could be found
+ """
+ current_path = Path(__file__).resolve()
+ for parent in current_path.parents:
+ if (parent / "pyproject.toml").exists() or (parent / ".git").exists():
+ return parent
+ # Raise an error if no project root is found
+ raise RuntimeError(
+ "Project root could not be determined. "
+ "Ensure that 'pyproject.toml' or '.git' exists in the project
directory."
+ )
