How Configuration Management Works in Apache HugeGraph AI

Apache HugeGraph AI centralizes connection settings in lightweight, immutable data classes consumed by Python client libraries to ensure thread-safe, predictable request formation.

Apache HugeGraph AI provides specialized Python clients for interacting with graph databases and AI services. The configuration management in Apache HugeGraph AI relies on immutable dataclasses that encapsulate server endpoints, authentication credentials, and graph-space routing, ensuring consistent behavior across the HugeGraph and Vermeer client ecosystems.

Configuration Architecture Overview

The codebase maintains strict separation of concerns between connection settings and request logic. Both the HugeGraph and Vermeer Python clients instantiate immutable configuration objects—HGraphConfig and VermeerConfig—that are passed to dedicated request handlers. This immutability guarantees thread-safety and prevents runtime mutation of critical connection parameters.

HugeGraph Python Client Configuration

The primary client for HugeGraph server interactions uses a dataclass-based approach to manage server URLs, authentication, and graph-space resolution.

The HGraphConfig Dataclass

Located in hugegraph-python-client/src/pyhugegraph/utils/huge_config.py, the HGraphConfig dataclass stores the server URL, user credentials, target graph name, optional graph-space identifier, and request timeout. The constructor accepts these parameters and creates an immutable configuration object that is subsequently injected into HGraphSession for HTTP request management.

Automatic Version Detection and Graph-Space Handling

When the graphspace parameter is omitted, HGraphConfig automatically contacts <url>/versions to detect the server's API version (see lines 48‑62). If the major version is 3 or higher, the configuration enables graph-space support and defaults the space to "DEFAULT". This automatic detection ensures compatibility with both legacy HugeGraph instances and modern graph-space-enabled deployments without manual intervention.

Request URL Resolution

The HGraphSession utilizes the configuration object to construct valid endpoints. In hugegraph-python-client/src/pyhugegraph/utils/huge_requests.py, the resolve method (lines 12‑20) builds complete request URLs by concatenating the base URL, an optional graph-space prefix, and the target graph name. This centralized URL formation prevents path construction errors across the client library.

Vermeer Python Client Configuration

For AI-specific operations, the Vermeer client employs a similar but distinct configuration strategy focused on token-based authentication.

The VermeerConfig Class

Defined in vermeer-python-client/src/pyvermeer/utils/vermeer_config.py, the VermeerConfig class holds connection details including IP address, port, authentication token, optional factor, username, and graph-space. Unlike HGraphConfig, this class does not perform automatic version detection; instead, it simply records the provided values. The surrounding VermeerClient (in vermeer-python-client/src/pyvermeer/client/client.py) forwards this configuration instance to VermeerRequests for request handling.

Practical Configuration Examples

The following examples demonstrate how to instantiate clients with explicit or auto-detected configurations.

# Example 1 – Using the HugeGraph client with explicit graphspace

from pyhugegraph.client import PyHugeClient

client = PyHugeClient(
    url="http://localhost:8080",
    graph="demo_graph",
    user="admin",
    pwd="admin123",
    graphspace="my_space",          # optional – enables graph‑space support

    timeout=(1.0, 20.0)            # (connect timeout, read timeout)

)

# The client now holds an HGraphConfig instance

print(client)   # → HGraphConfig(url='http://localhost:8080', …)

# Example 2 – Letting the client auto‑detect the API version and graphspace

client = PyHugeClient(
    url="http://localhost:8080",
    graph="demo_graph",
    user="admin",
    pwd="admin123"
)

# Internally, HGraphConfig contacts /versions, detects a version ≥ 3,

# sets graphspace="DEFAULT", and enables graph‑space routing.

# Example 3 – Using the Vermeer client

from pyvermeer.client import VermeerClient

vermeer = VermeerClient(
    ip="127.0.0.1",
    port=9000,
    token="my_secret_token"
)

# VermeerConfig stores the supplied values.

print(vermeer.cfg)   # → VermeerConfig(ip='127.0.0.1', port=9000, …)

Summary

• Immutable dataclasses (HGraphConfig and VermeerConfig) centralize connection settings in huge_config.py and vermeer_config.py respectively.
• Automatic version detection in HGraphConfig contacts /versions to enable graph-space support for HugeGraph server versions 3 and above.
• URL resolution occurs in huge_requests.py, where the resolve method constructs endpoints by combining base URLs, optional graph-space prefixes, and graph names.
• High-level entry points (PyHugeClient and VermeerClient) abstract configuration instantiation, requiring users to provide only essential connection parameters.

Frequently Asked Questions

How does Apache HugeGraph AI handle graph-space configuration automatically?

When graphspace is omitted from HGraphConfig, the constructor contacts the <url>/versions endpoint during instantiation. If the detected major version is 3 or higher, it automatically enables graph-space support and defaults the space to "DEFAULT" according to the implementation in hugegraph-python-client/src/pyhugegraph/utils/huge_config.py (lines 48‑62).

Where is the configuration class defined for the HugeGraph Python client?

The HGraphConfig dataclass is defined in hugegraph-python-client/src/pyhugegraph/utils/huge_config.py. This file contains the logic for storing server URLs, credentials, target graph names, timeout values, and the automatic version detection mechanism that determines graph-space availability.

What makes the configuration objects thread-safe in HugeGraph AI?

The configuration objects are implemented as immutable dataclasses created upon client instantiation. Once constructed, these objects cannot be modified, guaranteeing thread-safety and predictable request formation across concurrent operations in multi-threaded environments.

How does the Vermeer client differ from the HugeGraph client in configuration management?

While both clients use immutable configuration classes, VermeerConfig (located in vermeer-python-client/src/pyvermeer/utils/vermeer_config.py) focuses on IP/port/token-based authentication without automatic version detection. In contrast, HGraphConfig automatically discovers API versions and manages graph-space routing based on server capabilities.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}