Skip to content

doc(ai): sync vermeer-python-client with main - #484

Open
bitflicker64 wants to merge 1 commit into
apache:masterfrom
bitflicker64:doc-sync/ai-vermeer-python-client
Open

doc(ai): sync vermeer-python-client with main#484
bitflicker64 wants to merge 1 commit into
apache:masterfrom
bitflicker64:doc-sync/ai-vermeer-python-client

Conversation

@bitflicker64

Copy link
Copy Markdown
Contributor

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.

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 imbajin left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ 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.

After installing the module you can also run the shipped demo as is:

```bash
python vermeer-python-client/src/pyvermeer/demo/task_demo.py

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants