Implementation:Guardrails ai Guardrails ValidatorPackageService

Knowledge Sources	Guardrails
Domains	Package Management, Validator Hub
Last Updated	2026-02-14 00:00 GMT

Overview

ValidatorPackageService is a static utility class that manages the installation, loading, and module resolution of validator packages from the Guardrails Hub PyPI registry.

Description

The ValidatorPackageService class provides a comprehensive set of static methods for interacting with the Guardrails Hub ecosystem. It handles the full lifecycle of validator packages: parsing hub URIs (e.g., hub://namespace/validator_name), resolving PEP 503 normalized package names, installing packages from the Guardrails Hub PyPI server with fallback to the public PyPI index, running post-install scripts defined in package manifests, dynamically reloading installed modules, and updating the guardrails.hub.__init__.py file to expose newly installed validator exports.

The module also defines several custom exception classes:

FailedPackageInspection -- raised when a package cannot be inspected.
FailedToLocateModule -- raised when a module cannot be found in the current Python environment.
FailedPackageInstallation -- raised on general installation failures.
FailedPackageInstallationPostInstall -- raised specifically when a post-install script fails.
InvalidHubInstallURL -- raised when a hub URI does not follow the required hub:// format.

Additionally, a ValidatorModuleType protocol type is defined, extending ModuleType with a __validator_exports__ attribute.

Usage

Use ValidatorPackageService when you need to programmatically install or manage validator packages from the Guardrails Hub. This is primarily used by the Guardrails CLI hub install command and the internal Guard initialization logic that auto-installs referenced validators.

Code Reference

Source Location

Repository: Guardrails
File: guardrails/hub/validator_package_service.py
Lines: 1-307

Signature

class ValidatorPackageService:
    @staticmethod
    def get_manifest_and_site_packages(module_name: str) -> tuple[Manifest, str]: ...

    @staticmethod
    def get_site_packages_location() -> str: ...

    @staticmethod
    def reload_module(module_path: str) -> ModuleType: ...

    @staticmethod
    def get_validator_from_manifest(manifest: Manifest) -> ModuleType: ...

    @staticmethod
    def add_to_hub_inits(manifest: Manifest, site_packages: str) -> None: ...

    @staticmethod
    def get_module_path(package_name: str) -> str: ...

    @staticmethod
    def get_validator_id(validator_uri: str) -> tuple[str, Optional[str]]: ...

    @staticmethod
    def run_post_install(manifest: Manifest, site_packages: str, logger=...) -> None: ...

    @staticmethod
    def get_normalized_package_name(validator_id: str) -> str: ...

    @staticmethod
    def get_import_path_from_validator_id(validator_id: str) -> str: ...

    @staticmethod
    def install_hub_module(
        validator_id: str,
        validator_version: Optional[str] = "",
        quiet: bool = False,
        upgrade: bool = False,
        logger=...,
    ) -> None: ...

Import

from guardrails.hub.validator_package_service import ValidatorPackageService

I/O Contract

Inputs

get_validator_id

Name	Type	Required	Description
validator_uri	`str`	Yes	A hub URI string starting with `hub://`, optionally including a version specifier (e.g., `hub://namespace/validator>=1.0`).

install_hub_module

Name	Type	Required	Description
validator_id	`str`	Yes	The namespace/name identifier of the validator (e.g., `guardrails/regex_match`).
validator_version	`Optional[str]`	No	A PEP 440 version specifier string. Defaults to empty string (latest).
quiet	`bool`	No	Suppress pip output. Defaults to `False`.
upgrade	`bool`	No	Pass `--upgrade` to pip. Defaults to `False`.
logger	logger	No	Logger instance for output. Defaults to `guardrails_logger`.

run_post_install

Name	Type	Required	Description
manifest	`Manifest`	Yes	The package manifest containing post-install script reference.
site_packages	`str`	Yes	Path to the site-packages directory.
logger	logger	No	Logger instance for output.

Outputs

Method	Return Type	Description
get_manifest_and_site_packages	`tuple[Manifest, str]`	Returns the validator manifest and the site-packages path.
get_validator_id	`tuple[str, Optional[str]]`	Returns a tuple of (validator_id, version_string).
get_normalized_package_name	`str`	Returns a PEP 503 canonicalized package name.
get_import_path_from_validator_id	`str`	Returns a Python import path with hyphens replaced by underscores.
reload_module	`ModuleType`	Returns the dynamically loaded or reloaded module object.
get_validator_from_manifest	`ModuleType`	Returns the validator module imported from the manifest metadata.

Usage Examples

from guardrails.hub.validator_package_service import ValidatorPackageService

# Parse a hub URI into validator ID and version
validator_id, version = ValidatorPackageService.get_validator_id(
    "hub://guardrails/regex_match>=1.0"
)

# Install a validator from the hub
ValidatorPackageService.install_hub_module(
    validator_id="guardrails/regex_match",
    validator_version=">=1.0",
    quiet=True,
)

# Get normalized package name for pip
package_name = ValidatorPackageService.get_normalized_package_name(
    "guardrails/regex_match"
)
# Returns: "guardrails-grhub-regex-match"

# Get Python import path
import_path = ValidatorPackageService.get_import_path_from_validator_id(
    "guardrails/regex_match"
)
# Returns: "guardrails_grhub_regex_match"

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment