bitflicker64 commented on code in PR #557:
URL: https://github.com/apache/hugegraph-doc/pull/557#discussion_r4440454429
##########
content/en/docs/quickstart/toolchain/hugegraph-hubble.md:
##########
@@ -218,23 +218,55 @@ Input footers show model generation time and query
request time separately. Asyn
## Built-in algorithms: explore with parameter forms
-Use **Built-in Algorithms** when you prefer a form to writing traversal code.
Search for an algorithm and supply its parameters.
-Neighbor exploration answers what surrounds a vertex, path algorithms connect
two vertices, and similarity/ranking algorithms compare or select vertices.
-Start with a known vertex ID and limit direction, edge labels, depth, and
result size before attempting broader computation.
+Hubble cleanly separates algorithm execution into two dedicated workflows:
**OLTP online exploration** and **OLAP batch computing**.
+
+### OLTP online algorithms
+
+Use **Built-in Algorithms** when you prefer parameter forms to writing manual
Gremlin traversals for real-time queries:
+- **Neighbor exploration**: answers what surrounds a vertex (e.g. K-neighbor,
K-hop).
+- **Paths**: discovers connections between two vertices (e.g. shortest path,
all paths).
+- **Similarity & ranking**: compares or ranks vertices within local subgraphs.
Forms provide parameter guidance and documentation links, and restore common
parameters when navigating away and back.
-Results use graph or algorithm-specific panels. Consult the help and
documentation links beside the algorithm title for definitions and parameters.
While the parameter form is focused, `Ctrl` / `Command` + `Enter` runs the
current algorithm.
-OLAP batch algorithms require external compute services such as Computer or
Vermeer.
-The two containers in this example provide online graph operations, not those
compute services.
-
For example, select K-neighbor (GET) with `source=1:marko`, `max_depth=1`, and
`limit=20`.
After parameter validation, use the run button on the card or the form
shortcut to explore one-hop neighbors.
{width="1600" height="1000"}
+### Native Vermeer OLAP integration
+
+For large-scale, whole-graph analytical algorithms, Hubble integrates natively
with the high-performance **Vermeer** graph computing engine.
+Hubble prefers Vermeer for OLAP workloads by default, while Computer remains
available as an opt-in alternative.
+
+#### Configuration in `hugegraph-hubble.properties`
+
+Enable direct Vermeer communication in `conf/hugegraph-hubble.properties`:
+
+```properties
+# Direct Vermeer integration endpoint
+vermeer.url=http://vermeer-master:8888
+# Protected file containing the Vermeer service bearer token
+vermeer.token_file=/path/to/vermeer-service.token
+```
+
+> [!NOTE]
+> When `vermeer.url` is empty, Hubble falls back to the legacy Server proxy
path. Direct Vermeer integration requires PD/Store cluster mode;
+> it is disabled in standalone mode.
+
+#### Supported OLAP algorithms and execution lifecycle
+
+Vermeer executes batch algorithms over in-memory graph partitions:
+- **Supported algorithms**: PageRank, Personalized PageRank, Weakly Connected
Components (WCC), Louvain community detection, Betweenness Centrality,
Review Comment:
R4 status at `723899ec`: **fixed**. The list now matches the
`DirectVermeerService` set; Louvain and LCC are gone, and LPA, K-Core and SSSP
are added.
##########
content/en/docs/quickstart/hugegraph-ai/hugegraph-llm-sdk.md:
##########
@@ -0,0 +1,226 @@
+---
+title: "HugeGraph-LLM SDK Quick Start"
+linkTitle: "HugeGraph-LLM SDK"
+weight: 8
+description: "Standalone Python SDK for schema design, entity/relation
extraction, graph validation, and reviewed graph construction from text."
+search_keywords: [HugeGraph-LLM SDK, hugegraph_llm_sdk, schema design, graph
extraction, knowledge graph, Python SDK]
+---
+
+`hugegraph-llm-sdk` is a lightweight, standalone Python SDK for
programmatically designing schemas, extracting property graphs from
unstructured text,
+validating schemas against HugeGraph rules, and performing iterative model
review and bounded repair.
+
+Unlike the full `hugegraph-llm` application, the SDK is completely headless
and does not require HugeGraph Server, Gradio Web UI, FastAPI, or a vector
+database. Its core runtime depends only on `pydantic>=2.14,<3`.
+
+[Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0.html) · [Ask
DeepWiki](https://deepwiki.com/apache/hugegraph-ai)
+
+## Requirements and Installation
+
+- **Python**: `>=3.12` (tested and supported on Python 3.12, 3.13, and 3.14).
+- **Package name**: `hugegraph-llm-sdk`
+- **Import name**: `hugegraph_llm_sdk`
+
+### Install with pip or uv
+
+Install the package directly from PyPI or your local source checkout:
+
+```bash
+# Install via pip
+pip install hugegraph-llm-sdk
Review Comment:
R4 status at `723899ec`: **fixed**. The page says the SDK is not yet
published to a public index, and installs from a checkout or a wheel. The
extras match `pyproject.toml`.
##########
content/en/docs/quickstart/hugegraph-ai/hugegraph-llm-sdk.md:
##########
@@ -0,0 +1,226 @@
+---
+title: "HugeGraph-LLM SDK Quick Start"
+linkTitle: "HugeGraph-LLM SDK"
+weight: 8
+description: "Standalone Python SDK for schema design, entity/relation
extraction, graph validation, and reviewed graph construction from text."
+search_keywords: [HugeGraph-LLM SDK, hugegraph_llm_sdk, schema design, graph
extraction, knowledge graph, Python SDK]
+---
+
+`hugegraph-llm-sdk` is a lightweight, standalone Python SDK for
programmatically designing schemas, extracting property graphs from
unstructured text,
+validating schemas against HugeGraph rules, and performing iterative model
review and bounded repair.
+
+Unlike the full `hugegraph-llm` application, the SDK is completely headless
and does not require HugeGraph Server, Gradio Web UI, FastAPI, or a vector
+database. Its core runtime depends only on `pydantic>=2.14,<3`.
+
+[Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0.html) · [Ask
DeepWiki](https://deepwiki.com/apache/hugegraph-ai)
+
+## Requirements and Installation
+
+- **Python**: `>=3.12` (tested and supported on Python 3.12, 3.13, and 3.14).
+- **Package name**: `hugegraph-llm-sdk`
+- **Import name**: `hugegraph_llm_sdk`
+
+### Install with pip or uv
+
+Install the package directly from PyPI or your local source checkout:
+
+```bash
+# Install via pip
+pip install hugegraph-llm-sdk
+
+# Or install in editable mode from local repository source
+pip install -e /path/to/hugegraph-ai/hugegraph-llm-sdk
+
+# Using uv in your own project
+uv add --editable /path/to/hugegraph-ai/hugegraph-llm-sdk
+```
+
+### Provider Extras
+
+The base SDK does not bundle specific LLM provider client libraries. If you
want ready-to-use provider clients, install the corresponding extras:
+
+```bash
+# Install with OpenAI adapter
+pip install "hugegraph-llm-sdk[openai]"
+# Or with uv: uv add --editable /path/to/hugegraph-ai/hugegraph-llm-sdk
--extra openai
+
+# Install with Ollama adapter
+pip install "hugegraph-llm-sdk[ollama]"
+
+# Install with LiteLLM adapter (multi-provider routing)
+pip install "hugegraph-llm-sdk[litellm]"
+```
+
+## Quick Start: Minimal Example
+
+Here is a complete example demonstrating schema design, schema validation, and
reviewed graph extraction using a custom model function:
+
+```python
+from hugegraph_llm_sdk import (
+ FunctionModel,
+ design_schema,
+ validate_schema,
+ extract_graph,
+)
+
+# 1. Define or wrap your LLM caller
+model = FunctionModel(generate=lambda prompt:
my_agent_model.invoke(prompt).content)
+
+# 2. Design a graph schema from sample texts and target questions
+draft = design_schema(
+ texts=["Alice works for Acme Corp. Bob reports to Alice."],
+ questions=["Which company does each person work for? Who reports to
whom?"],
+ model=model,
+)
+
+# Inspect any structural or conceptual issues flagged during design
+if draft.issues:
+ print(f"Schema draft issues: {draft.issues}")
+
+schema = draft.schema
+
+# 3. Validate schema structure against HugeGraph rules
+validation_issues = validate_schema(schema)
+assert not validation_issues, f"Validation failed: {validation_issues}"
+
+# 4. Extract property graph from text
+result = extract_graph(
Review Comment:
R4 status at `723899ec`: **fixed**. The examples use `texts=` and `schema=`,
and the signature table matches `api.py` and `schema.py`, including the
keyword-only arguments.
##########
content/en/docs/config/config-option.md:
##########
@@ -233,6 +233,7 @@ Basic Config Options and Backend Config Options correspond
to configuration file
|-------------------------------------------------|--------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| backend |
| Must be set to `rocksdb`.
|
| serializer |
| Must be set to `binary`.
|
+| rocksdb.provider | default | RocksDB engine provider implementation. Allowed
values: `default` (or `rocksdb`) and `topling`. |
Review Comment:
R4 status at `723899ec`: **fixed**. The default is `rocksdb`, and the
allowed values are `rocksdb` and `topling` (EN and CN).
##########
content/en/docs/quickstart/hugegraph/hugegraph-pd.md:
##########
@@ -557,4 +561,46 @@ The two `log` endpoints take a time range as
`{"startTime": "...", "endTime": ".
PD registers its own meters under the `hg` prefix, so `/actuator/prometheus`
exposes `hg_up`, `hg_graphs`, `hg_stores` and `hg_terms` alongside the standard
JVM metrics, plus per-graph partition and size meters once graphs exist.
+It also exposes Raft membership gauges for monitoring and alerting on quorum
loss:
+- `hg_raft_leader`: `1` if this PD node is the elected Raft leader, `0`
otherwise.
+- `hg_raft_has_leader`: `1` if this PD node observes an active Raft leader
(i.e. is part of a quorum), `0` when quorum is lost.
+- `hg_raft_alive_peers`: Number of active Raft peers (including itself) that
the leader has heard from within the leader lease timeout;
+ reported as `NaN` on non-leader follower nodes.
+
+> [!NOTE]
+> **Quorum Loss Alerting**: Cluster quorum is lost when `sum(hg_raft_leader)
== 0` or `hg_raft_has_leader == 0` across all members. Alert rules should
+> configure a `for:` window longer than the Raft election timeout (e.g. `for:
30s`) to avoid false positives during expected leader transitions.
+> To alert on peer degradation from Prometheus, query `hg_raft_alive_peers and
on(instance) (hg_raft_leader == 1)`.
+
In versions after 1.7.0, PD also exports, for each registered store,
`hg_store_state{store="<id>",state="<state>"}`, which is `1` for the store's
current state (`Unknown`, `Pending`, `Up`, `Offline`, `Exiting` or `Tombstone`)
and `0` for the others, and `hg_store_leader_count{store="<id>"}`, the number
of shard groups whose leader is on that store. A rebuilt Store reports `0`
leaders until leadership moves back to it. Every PD member reads the same
replicated metadata, so select one instance before aggregating these series.
+
+#### 7.6 Store Decommissioning and Drain Lifecycle
+
+Decommissioning a Store node follows a state machine to safely drain partition
replicas without service interruption:
+
+1. **State Machine Overview**:
+ - `Up`: The Store is online, healthy, and accepting new shard allocations
and leader roles.
+ - `Exiting`: The Store is actively draining. While in `Exiting`, the Store
continues renewing its heartbeat lease, but PD excludes it from new
+ replica allocation and partition migration targets.
+ - Partition Migration: PD schedules background tasks to migrate all shard
replicas off the draining store to other eligible active Stores.
+ - `Tombstone`: The Store is permanently retired. Once marked `Tombstone`,
management updates cannot return the Store to an active state.
+
+2. **Draining Invocation**:
+ Initiate store draining via:
+ ```bash
+ curl -X POST http://<pd-host>:8620/v1/store/{storeId} \
+ -H "Authorization: Basic <credentials>" \
+ -H "Content-Type: application/json" \
+ -d '{"storeState": "Exiting"}'
+ ```
+
+3. **Capacity Constraints & Retirement Checks**:
+ - **Capacity Check**: Draining checks that remaining eligible active stores
satisfy `minStoreCount` (`pd.initial-store-count`). If remaining
Review Comment:
R4 status at `723899ec`: **fixed**. The check now names
`pd.min-store-count`, which also has a table row, and the text says a rejected
drain is refused before any state change. The PD `cd` glob thread is fixed too:
it now has a trailing `/`.
--
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]
