doc(ai): sync vermeer-python-client with main - #484
Conversation
Add the missing vermeer-python-client quick start page in en and cn. The module was referenced from the HugeGraph-AI index and the introduction page but had no page of its own. Covers requirements, the uv --extra vermeer and standalone install routes, the PyVermeerClient constructor and its session behavior, an end-to-end load task example based on the shipped demo, the graph and tasks API groups with the Vermeer endpoints they call, the response objects, and the exception types.
imbajin
left a comment
There was a problem hiding this comment.
Blocking: no. Summary: The new guide has two runnable-example issues that can mislead users during installation and task execution. Evidence: verified against the exact-head docs and the HugeGraph-AI client source.
| print(create_response.errcode, create_response.message) | ||
|
|
||
| # Read the task back and check its state | ||
| task_id = create_response.task.id |
There was a problem hiding this comment.
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.
| After installing the module you can also run the shipped demo as is: | ||
|
|
||
| ```bash | ||
| python vermeer-python-client/src/pyvermeer/demo/task_demo.py |
There was a problem hiding this 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.
Adds the missing
vermeer-python-clientquick start page (en and cn). The module is referenced by name incontent/*/docs/quickstart/hugegraph-ai/_index.md:16andcontent/*/docs/introduction/_index.md:89, but had no page anywhere incontent/.The page sits in the
hugegraph-aisection atweight: 6, afterrest-api.md. Section navigation is Hugo weight-driven, so no_index.mdorSUMMARY.mdchange is needed. Layout and frontmatter followcontent/*/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.pyvermeer; no Vermeer server version is pinnedvermeer-python-client/README.md:3,vermeer-python-client/pyproject.toml:50requests,urllib3,python-dateutil,decorator,rich,setuptoolsvermeer-python-client/pyproject.toml:27,29-39,pyproject.toml:27,.../demo/task_demo.py:26vermeer-python-client, version managed independently, not yet on PyPI;uv sync --extra vermeerfrom the repo root; editable path dependency, not a uv workspace member; standaloneuv syncinside the module dirvermeer-python-client/pyproject.toml:19-20,vermeer-python-client/README.md:7-15,22-27,pyproject.toml:41,91,93-97PyVermeerClient(ip, port, token, timeout=None, log_level="INFO")parameter table, plus the behaviour notes: token cannot beNoneand is sent asAuthorization; omittingtimeoutstoresNone, because the client always forwards its own argument over the(0.5, 15.0)default inVermeerConfig; the base URL is always plainhttp://{ip}:{port}/;paramsis 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, soDEBUGis 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,47loadtask 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-45client.graph:get_graphs()toGET /graphs,get_graph(name)toGET /graphs/{name}.client.tasks:get_tasks()toGET /tasks,get_task(id)toGET /task/{id},create_task(req)toPOST /tasks/create.client.send_request()as the shared escape hatch. Master and worker API groups are unimplemented placeholders, even thoughMasterResponseandWorkersResponseexist.../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-111TaskCreateRequest(task_type, graph_name, params)serializesgraph_nameasgraph; all responses exposeerrcode/message/to_dict()with 0 ok, 1 error, -1 absent;VermeerGraphandTaskInfofield lists; timestamps parsed bypython-dateutil, empty string becomesNone.../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-28params; 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-156ConnectError,TimeOutError,JsonDecodeError,UnknownErrorwith their trigger conditions; the HTTP status code is never checked, so callers must readerrcode.../utils/exception.py:19-44,.../utils/vermeer_requests.py:91-107./style/code_format_and_analysis.shfrom the repo root; source undervermeer-python-client/src/pyvermeer/; the module ships no test suitevermeer-python-client/README.md:80Follow-up left out on purpose
content/*/docs/quickstart/hugegraph-ai/_index.mdhas a "Next Steps" list that links every sibling page in the section. Addingvermeer-python-client.mdthere 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.