You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@hugegraph.apache.org by "bitflicker64 (via GitHub)" <gi...@apache.org> on 2026/09/05 18:53:18 UTC
[PR] doc(ai): sync vermeer-python-client with main [hugegraph-doc]
bitflicker64 opened a new pull request, #484:
URL: https://github.com/apache/hugegraph-doc/pull/484
Adds the missing `vermeer-python-client` quick start page (en and cn). The module is referenced by name in `content/*/docs/quickstart/hugegraph-ai/_index.md:16` and `content/*/docs/introduction/_index.md:89`, but had no page anywhere in `content/`.
The page sits in the `hugegraph-ai` section at `weight: 6`, after `rest-api.md`. Section navigation is Hugo weight-driven, so no `_index.md` or `SUMMARY.md` change is needed. Layout and frontmatter follow `content/*/docs/quickstart/client/hugegraph-client-python.md`.
The module is not a stub: it has a working client, two registered API groups, five endpoint wrappers, full response models and a runnable demo. It ships no test suite, so every example was verified against `src/pyvermeer/**` and the bundled demo.
| Page | Wrong | Changed to | Source |
|---|---|---|---|
| new page, intro | missing | The Python SDK for the Vermeer memory-first graph computing engine; the import package is `pyvermeer`; no Vermeer server version is pinned | `vermeer-python-client/README.md:3`, `vermeer-python-client/pyproject.toml:50` |
| new page, Requirements | missing | Python 3.9+ for the module alone, 3.10+ for the repo; Vermeer master over HTTP (the demo uses port 8688); deps `requests`, `urllib3`, `python-dateutil`, `decorator`, `rich`, `setuptools` | `vermeer-python-client/pyproject.toml:27,29-39`, `pyproject.toml:27`, `.../demo/task_demo.py:26` |
| new page, Installation | missing | Distribution name `vermeer-python-client`, version managed independently, not yet on PyPI; `uv sync --extra vermeer` from the repo root; editable path dependency, not a uv workspace member; standalone `uv sync` inside the module dir | `vermeer-python-client/pyproject.toml:19-20`, `vermeer-python-client/README.md:7-15,22-27`, `pyproject.toml:41,91,93-97` |
| new page, Connect to a Vermeer Master | missing | `PyVermeerClient(ip, port, token, timeout=None, log_level="INFO")` parameter table, plus the behaviour notes: token cannot be `None` and is sent as `Authorization`; omitting `timeout` stores `None`, because the client always forwards its own argument over the `(0.5, 15.0)` default in `VermeerConfig`; the base URL is always plain `http://{ip}:{port}/`; `params` is JSON-serialized into the body for every method including GET; 3 retries with backoff 0.1 on 500, 502 and 504; the console handler is fixed at INFO, so `DEBUG` is not printed | `.../client/client.py:30-48`, `.../utils/vermeer_config.py:29`, `.../utils/vermeer_requests.py:36-38,48-52,61-70,82,96`, `.../utils/log.py:37,47` |
| new page, End-to-End Example | missing | A runnable `load` task example based on the bundled demo, extended with task read-back and graph inspection; the password is read from the environment rather than hardcoded | `.../demo/task_demo.py:22-45` |
| new page, API Surface | missing | `client.graph`: `get_graphs()` to `GET /graphs`, `get_graph(name)` to `GET /graphs/{name}`. `client.tasks`: `get_tasks()` to `GET /tasks`, `get_task(id)` to `GET /task/{id}`, `create_task(req)` to `POST /tasks/create`. `client.send_request()` as the shared escape hatch. Master and worker API groups are unimplemented placeholders, even though `MasterResponse` and `WorkersResponse` exist | `.../api/graph.py:26-37`, `.../api/task.py:25-38`, `.../client/client.py:47,56-57`, `.../api/master.py:1-16`, `.../api/worker.py:1-16`, `.../structure/master_data.py:71-82`, `.../structure/worker_data.py:99-111` |
| new page, Requests and Responses | missing | `TaskCreateRequest(task_type, graph_name, params)` serializes `graph_name` as `graph`; all responses expose `errcode` / `message` / `to_dict()` with 0 ok, 1 error, -1 absent; `VermeerGraph` and `TaskInfo` field lists; timestamps parsed by `python-dateutil`, empty string becomes `None` | `.../structure/task_data.py:47-142,145-156`, `.../structure/base_data.py:18-50`, `.../structure/graph_data.py:95-209`, `.../utils/vermeer_datetime.py:23-28` |
| new page, Task Parameters | missing | The client does not validate `params`; the keys come from the engine; load then compute sequence; points at the Vermeer quick start for the parameter lists | `.../api/task.py:35-38`, `.../structure/task_data.py:154-156` |
| new page, Errors | missing | `ConnectError`, `TimeOutError`, `JsonDecodeError`, `UnknownError` with their trigger conditions; the HTTP status code is never checked, so callers must read `errcode` | `.../utils/exception.py:19-44`, `.../utils/vermeer_requests.py:91-107` |
| new page, Development Checks | missing | `./style/code_format_and_analysis.sh` from the repo root; source under `vermeer-python-client/src/pyvermeer/`; the module ships no test suite | `vermeer-python-client/README.md:80` |
## Follow-up left out on purpose
`content/*/docs/quickstart/hugegraph-ai/_index.md` has a "Next Steps" list that links every sibling page in the section. Adding `vermeer-python-client.md` there would make the section self-consistent, but that file is owned by the hugegraph-llm sync PR, and adding the link from either side creates a dead link until both PRs merge. Worth a small follow-up once both are in.
--
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: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org
Re: [PR] doc(ai): sync vermeer-python-client with main [hugegraph-doc]
Posted by "imbajin (via GitHub)" <gi...@apache.org>.
imbajin commented on code in PR #484:
URL: https://github.com/apache/hugegraph-doc/pull/484#discussion_r3942866300
##########
content/en/docs/quickstart/hugegraph-ai/vermeer-python-client.md:
##########
@@ -0,0 +1,202 @@
+---
+title: "Vermeer Python Client"
+linkTitle: "Vermeer Client"
+weight: 6
+---
+
+`vermeer-python-client` is the Python SDK for [Vermeer](../computing/hugegraph-vermeer.md), the memory-first graph computing engine written in Go. The SDK wraps the REST API of the Vermeer master so you can list graphs, submit load and compute tasks, and read task state from Python. The import package is `pyvermeer`.
+
+The module does not pin a Vermeer server version. It talks to the Vermeer master over HTTP using the endpoints listed in [API Surface](#api-surface).
+
+## Requirements
+
+- Python 3.9 or later for the module on its own. The HugeGraph-AI repository as a whole requires Python 3.10 or later.
+- A running Vermeer master reachable over HTTP. The demo shipped with the module uses port `8688`.
+- `uv` (recommended) or `pip`
+
+Runtime dependencies: `requests`, `urllib3`, `python-dateutil`, `decorator`, `rich`, and `setuptools`.
+
+## Installation
+
+The distribution name in the packaging metadata is `vermeer-python-client` and the version is managed independently of the repository version. The package is not published on PyPI yet, so install it from source.
+
+From the root of the HugeGraph-AI repository, the `vermeer` extra installs it into the shared virtual environment:
+
+```bash
+git clone https://github.com/apache/hugegraph-ai.git
+cd hugegraph-ai
+uv sync --extra vermeer
+source .venv/bin/activate
+```
+
+`vermeer-python-client` is wired in as an editable path dependency rather than a `uv` workspace member, so a plain `uv sync` at the repository root does not install it. You have to ask for the extra (or for `--all-extras`).
+
+To install the module standalone:
+
+```bash
+git clone https://github.com/apache/hugegraph-ai.git
+cd hugegraph-ai/vermeer-python-client
+uv sync
+source .venv/bin/activate
+```
+
+## Connect to a Vermeer Master
+
+```python
+from pyvermeer.client.client import PyVermeerClient
+
+client = PyVermeerClient(
+ ip="127.0.0.1",
+ port=8688,
+ token="",
+ timeout=(0.5, 15.0),
+ log_level="INFO",
+)
+```
+
+Constructor parameters:
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `ip` | `str` | required | Host name or IP address of the Vermeer master |
+| `port` | `int` | required | REST port of the Vermeer master |
+| `token` | `str` | required | Sent verbatim as the `Authorization` request header |
+| `timeout` | `(float, float)` or `None` | `None` | Connect and read timeouts in seconds |
+| `log_level` | `str` | `"INFO"` | Level applied to the shared `VermeerClient` logger |
+
+Behavior worth knowing before you connect:
+
+- `token` may be an empty string when the master does not check authorization, but it cannot be `None`. The session raises `ValueError("Vermeer Token must be provided.")` in that case.
+- `timeout` is a `(connect, read)` pair. `VermeerConfig` has its own default of `(0.5, 15.0)`, but the client always forwards its own argument, so omitting `timeout` stores `None` and the request waits without a deadline. Pass the pair explicitly if you want one.
+- The base URL is always built as `http://{ip}:{port}/`, so the client speaks plain HTTP.
+- Every request sets `Content-Type: application/json` and serializes `params` into the request body, including for `GET` requests.
+- The underlying session retries up to 3 times with a backoff factor of `0.1` on HTTP 500, 502, and 504.
+- `log_level` sets the level of the shared logger named `VermeerClient`. Its console handler is fixed at `INFO`, so `DEBUG` records are not printed to the console today.
+
+## End-to-End Example
+
+The module ships a runnable demo at `vermeer-python-client/src/pyvermeer/demo/task_demo.py`. The version below adds the polling step and reads the HugeGraph password from the environment:
+
+```python
+import os
+
+from pyvermeer.client.client import PyVermeerClient
+from pyvermeer.structure.task_data import TaskCreateRequest
+
+client = PyVermeerClient(ip="127.0.0.1", port=8688, token="", log_level="INFO")
+
+# List the tasks the master knows about
+tasks = client.tasks.get_tasks()
+print(tasks.to_dict())
+
+# Load a graph from HugeGraph into Vermeer
+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_username": "admin",
+ "load.hugegraph_password": os.environ["HUGEGRAPH_PASSWORD"],
+ "load.parallel": "10",
+ "load.type": "hugegraph",
+ },
+ )
+)
+print(create_response.errcode, create_response.message)
+
+# Read the task back and check its state
+task_id = create_response.task.id
+task = client.tasks.get_task(task_id)
+print(task.task.state)
+
+# Once the graph is loaded, inspect it
+print(client.graph.get_graph("DEFAULT-example").to_dict())
+```
+
+Never hardcode a real HugeGraph password into a script or a configuration file. Read it from an environment variable or a credential store, as above.
+
+After installing the module you can also run the shipped demo as is:
+
+```bash
+python vermeer-python-client/src/pyvermeer/demo/task_demo.py
Review Comment:
🧹 Minor: The standalone installation above leaves the shell in `hugegraph-ai/vermeer-python-client`, so this command resolves to a nonexistent nested `vermeer-python-client/vermeer-python-client/...` path. Please either tell standalone users to run it from the repository root or use `python src/pyvermeer/demo/task_demo.py` there, and mirror the correction in the Chinese page.
##########
content/en/docs/quickstart/hugegraph-ai/vermeer-python-client.md:
##########
@@ -0,0 +1,202 @@
+---
+title: "Vermeer Python Client"
+linkTitle: "Vermeer Client"
+weight: 6
+---
+
+`vermeer-python-client` is the Python SDK for [Vermeer](../computing/hugegraph-vermeer.md), the memory-first graph computing engine written in Go. The SDK wraps the REST API of the Vermeer master so you can list graphs, submit load and compute tasks, and read task state from Python. The import package is `pyvermeer`.
+
+The module does not pin a Vermeer server version. It talks to the Vermeer master over HTTP using the endpoints listed in [API Surface](#api-surface).
+
+## Requirements
+
+- Python 3.9 or later for the module on its own. The HugeGraph-AI repository as a whole requires Python 3.10 or later.
+- A running Vermeer master reachable over HTTP. The demo shipped with the module uses port `8688`.
+- `uv` (recommended) or `pip`
+
+Runtime dependencies: `requests`, `urllib3`, `python-dateutil`, `decorator`, `rich`, and `setuptools`.
+
+## Installation
+
+The distribution name in the packaging metadata is `vermeer-python-client` and the version is managed independently of the repository version. The package is not published on PyPI yet, so install it from source.
+
+From the root of the HugeGraph-AI repository, the `vermeer` extra installs it into the shared virtual environment:
+
+```bash
+git clone https://github.com/apache/hugegraph-ai.git
+cd hugegraph-ai
+uv sync --extra vermeer
+source .venv/bin/activate
+```
+
+`vermeer-python-client` is wired in as an editable path dependency rather than a `uv` workspace member, so a plain `uv sync` at the repository root does not install it. You have to ask for the extra (or for `--all-extras`).
+
+To install the module standalone:
+
+```bash
+git clone https://github.com/apache/hugegraph-ai.git
+cd hugegraph-ai/vermeer-python-client
+uv sync
+source .venv/bin/activate
+```
+
+## Connect to a Vermeer Master
+
+```python
+from pyvermeer.client.client import PyVermeerClient
+
+client = PyVermeerClient(
+ ip="127.0.0.1",
+ port=8688,
+ token="",
+ timeout=(0.5, 15.0),
+ log_level="INFO",
+)
+```
+
+Constructor parameters:
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `ip` | `str` | required | Host name or IP address of the Vermeer master |
+| `port` | `int` | required | REST port of the Vermeer master |
+| `token` | `str` | required | Sent verbatim as the `Authorization` request header |
+| `timeout` | `(float, float)` or `None` | `None` | Connect and read timeouts in seconds |
+| `log_level` | `str` | `"INFO"` | Level applied to the shared `VermeerClient` logger |
+
+Behavior worth knowing before you connect:
+
+- `token` may be an empty string when the master does not check authorization, but it cannot be `None`. The session raises `ValueError("Vermeer Token must be provided.")` in that case.
+- `timeout` is a `(connect, read)` pair. `VermeerConfig` has its own default of `(0.5, 15.0)`, but the client always forwards its own argument, so omitting `timeout` stores `None` and the request waits without a deadline. Pass the pair explicitly if you want one.
+- The base URL is always built as `http://{ip}:{port}/`, so the client speaks plain HTTP.
+- Every request sets `Content-Type: application/json` and serializes `params` into the request body, including for `GET` requests.
+- The underlying session retries up to 3 times with a backoff factor of `0.1` on HTTP 500, 502, and 504.
+- `log_level` sets the level of the shared logger named `VermeerClient`. Its console handler is fixed at `INFO`, so `DEBUG` records are not printed to the console today.
+
+## End-to-End Example
+
+The module ships a runnable demo at `vermeer-python-client/src/pyvermeer/demo/task_demo.py`. The version below adds the polling step and reads the HugeGraph password from the environment:
+
+```python
+import os
+
+from pyvermeer.client.client import PyVermeerClient
+from pyvermeer.structure.task_data import TaskCreateRequest
+
+client = PyVermeerClient(ip="127.0.0.1", port=8688, token="", log_level="INFO")
+
+# List the tasks the master knows about
+tasks = client.tasks.get_tasks()
+print(tasks.to_dict())
+
+# Load a graph from HugeGraph into Vermeer
+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_username": "admin",
+ "load.hugegraph_password": os.environ["HUGEGRAPH_PASSWORD"],
+ "load.parallel": "10",
+ "load.type": "hugegraph",
+ },
+ )
+)
+print(create_response.errcode, create_response.message)
+
+# Read the task back and check its state
+task_id = create_response.task.id
Review Comment:
⚠️ Important: This is a single task read, not polling. `create_task()` can return before the load finishes, but the example immediately calls `get_graph()` on the next lines, so it may inspect an unloaded or failed graph while claiming an end-to-end flow. Please loop until the task reaches a terminal success/failure state, handle failure, and mirror the fix in the Chinese page.
--
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: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org
Re: [PR] doc(ai): sync vermeer-python-client with main [hugegraph-doc]
Posted by "imbajin (via GitHub)" <gi...@apache.org>.
imbajin merged PR #484:
URL: https://github.com/apache/hugegraph-doc/pull/484
--
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: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org