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: [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]
