afd_plugin/config.py: the AFD config schema and parser

Code version: afd-plugin @ 7452d52 · 2026-10-27 · vLLM @ ced6857

Purpose#

The module turns a raw mapping into a validated AFDConfig. It is CPU-safe, so local tests parse a config without vLLM.

Where it sits#

Who calls it#

Every part that needs the AFD config parses it here. The config patch parses it to decide the worker and the NPU path (afd_plugin/compat/patches/config_validation.py:160-172). The runtime validators parse it with an expected role (afd_plugin/validation.py:93).

What it calls#

It calls the three coercers in config_utils.py for the typed fields (afd_plugin/config.py:147-174). It imports validate_p2p_topology lazily, only for the P2P connector (afd_plugin/config.py:335-338).

Key classes and functions#

Walk through the main methods#

AFDConfig and its aliases#

The dataclass is frozen, so a config cannot change after it is built. Each old afd_* name is a read-only property that returns the short field (afd_plugin/config.py:75-89).

    @property
    def afd_connector(self) -> str:
        return self.connector

    @property
    def afd_role(self) -> AFDRole:
        return self.role

    @property
    def afd_port(self) -> int:
        return self.port

    @property
    def afd_host(self) -> str:
        return self.host

_normalize_mapping#

This function does the rename, the split and the coercion in one pass.

    for key, value in raw.items():
        normalized_key = _ALIASES.get(key, key)
        if normalized_key == "connector_extra_config":
            if not isinstance(value, Mapping):
                raise TypeError(f"{key} must be a mapping")
            connector_extra_config = dict(value)
            continue
        if normalized_key not in valid_fields:
            raise ValueError(
                "unknown AFD config field "
                f"{key!r}; put connector-specific values under "
                "'connector_extra_config'",
            )
        if normalized_key in normalized:
            raise ValueError(
                f"duplicate AFD config field for {normalized_key!r}: "
                f"both alias and canonical key were provided",
            )
        normalized[normalized_key] = value

1. Line 128. It maps the key through _ALIASES, so an alias becomes its short name.
2. Lines 129-133. It pulls connector_extra_config aside and checks it is a mapping.
3. Lines 134-139. An unknown field raises, with a message that points to connector_extra_config.
4. Lines 140-144. An alias and its canonical key together raise a duplicate error.

After the loop, it coerces the boolean and integer fields (afd_plugin/config.py:147-174).

validate_afd_config#

The validator runs on the built config. It raises a clear error for each broken rule (afd_plugin/config.py:311-350). For the P2P connector it also checks the topology (afd_plugin/config.py:335-338).

config_utils.coerce_extra_int#

The integer coercer rejects a bool or a float before it calls int(), so a wrong type cannot be truncated silently (afd_plugin/config_utils.py:35-45).

def coerce_extra_int(value: object, *, field_name: str) -> int:
    """Parse an integer option without truncating floats."""

    if isinstance(value, bool | float):
        raise TypeError(f"{field_name} must be an integer, got {value!r}")
    try:
        return int(value)
    except (TypeError, ValueError, OverflowError) as exc:
        raise TypeError(
            f"{field_name} must be an integer, got {value!r}",
        ) from exc

Deep dive#

Related concepts#

• AFD configuration: additional_config["afd"]
• Worker selection: choosing the role worker
• AFD config reference: the additional_config["afd"] keys
• afd_plugin/validation.py: runtime wiring checks