# How Configuration Management Works in Apache HugeGraph AI

> Learn how Apache HugeGraph AI manages configurations with immutable data classes ensuring thread-safe, predictable request formation for your Python projects.

- Repository: [The Apache Software Foundation/incubator-hugegraph-ai](https://github.com/apache/incubator-hugegraph-ai)
- Tags: internals
- Published: 2026-02-24

---

**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`](https://github.com/apache/incubator-hugegraph-ai/blob/main/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`](https://github.com/apache/incubator-hugegraph-ai/blob/main/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`](https://github.com/apache/incubator-hugegraph-ai/blob/main/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`](https://github.com/apache/incubator-hugegraph-ai/blob/main/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.

```python

# 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', …)

```

```python

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

```

```python

# 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`](https://github.com/apache/incubator-hugegraph-ai/blob/main/huge_config.py) and [`vermeer_config.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/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`](https://github.com/apache/incubator-hugegraph-ai/blob/main/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`](https://github.com/apache/incubator-hugegraph-ai/blob/main/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`](https://github.com/apache/incubator-hugegraph-ai/blob/main/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`](https://github.com/apache/incubator-hugegraph-ai/blob/main/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.