Merge pull request #1434 from guardrails-ai/hub-import-tlc

Migrate to Dynamic Hub Imports

Author: CalebCourier

.gitignore

@@ -48,4 +48,5 @@ mlartifacts
 .idea
 .pytest_cache
 .ruff_cache
-.vscode
+.vscode
+docs/examples/.guardrails/hub_registry.json

docs/examples/input_validation.ipynb

@@ -10,14 +10,14 @@
      "output_type": "stream",
      "text": [
       "Installing hub:\u001b[35m/\u001b[0m\u001b[35m/guardrails/\u001b[0m\u001b[95mtwo_words...\u001b[0m\n",
-      "✅Successfully installed guardrails/two_words!\n",
+      "✅Successfully installed guardrails/two_words version \u001b[1;36m0.0\u001b[0m.\u001b[1;36m0\u001b[0m!\n",
       "\n",
       "\n"
      ]
     }
    ],
    "source": [
-    "!guardrails hub install hub://guardrails/two_words --quiet"
+    "! guardrails hub install hub://guardrails/two_words --quiet"
    ]
   },
   {
@@ -38,7 +38,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 1,
+   "execution_count": 2,
    "metadata": {
     "is_executing": true
    },
@@ -76,7 +76,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": 3,
    "metadata": {
     "is_executing": true
    },
@@ -85,9 +85,7 @@
      "name": "stderr",
      "output_type": "stream",
      "text": [
-      "/Users/dtam/dev/guardrails/guardrails/validator_service/__init__.py:85: UserWarning: Could not obtain an event loop. Falling back to synchronous validation.\n",
-      "  warnings.warn(\n",
-      "/Users/dtam/dev/guardrails/guardrails/validator_service/__init__.py:85: UserWarning: Could not obtain an event loop. Falling back to synchronous validation.\n",
+      "/Users/calebcourier/Projects/guardrails/docs/.venv/lib/python3.10/site-packages/guardrails/validator_service/__init__.py:75: UserWarning: Could not obtain an event loop. Falling back to synchronous validation.\n",
       "  warnings.warn(\n"
      ]
     }
@@ -114,7 +112,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 5,
+   "execution_count": 4,
    "metadata": {},
    "outputs": [
     {
@@ -123,14 +121,6 @@
      "text": [
       "Validation failed for field with errors: Value must be exactly two words\n"
      ]
-    },
-    {
-     "name": "stderr",
-     "output_type": "stream",
-     "text": [
-      "/Users/dtam/dev/guardrails/guardrails/validator_service/__init__.py:85: UserWarning: Could not obtain an event loop. Falling back to synchronous validation.\n",
-      "  warnings.warn(\n"
-     ]
     }
    ],
    "source": [
@@ -158,7 +148,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "litellm",
+   "display_name": ".venv (3.10.16)",
    "language": "python",
    "name": "python3"
   },
@@ -172,7 +162,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.3"
+   "version": "3.10.16"
   }
  },
  "nbformat": 4,

guardrails/cli/hub/list.py

@@ -1,7 +1,5 @@
-import os
-import re
-
 from guardrails.cli.hub.hub import hub_command
+from guardrails.hub.registry import get_registry
 from guardrails.hub_telemetry.hub_tracing import trace
 from .console import console
 
@@ -10,22 +8,14 @@
 @trace(name="guardrails-cli/hub/list")
 def list():
     """List all installed validators."""
-    from guardrails.hub.validator_package_service import ValidatorPackageService
-
-    site_packages = ValidatorPackageService.get_site_packages_location()
-    hub_init_file = os.path.join(site_packages, "guardrails", "hub", "__init__.py")
-
-    installed_validators = []
+    registry = get_registry()
 
-    if os.path.isfile(hub_init_file):
-        with open(hub_init_file, "r") as file:
-            content = file.read()
-            matches = re.findall(r"from .* import (\w+)", content)
-            installed_validators.extend(matches)
-
-    if installed_validators:
-        console.print("Installed Validators:")
-        for validator in installed_validators:
-            console.print(f"- {validator}")
-    else:
+    validators = registry.validators
+    if not validators:
         console.print("No validators installed.")
+        return
+
+    console.print("Installed Validators:")
+    for validator_id, entry in sorted(validators.items()):
+        exports = ", ".join(entry.exports)
+        console.print(f"- {validator_id} ({exports})")

guardrails/cli/hub/uninstall.py

@@ -79,15 +79,14 @@ def uninstall(
     # Prep
     with console.status("Fetching manifest", spinner="bouncingBar"):
         module_manifest = get_validator_manifest(module_name)
-        site_packages = ValidatorPackageService.get_site_packages_location()
 
     # Uninstall
     with console.status("Removing module", spinner="bouncingBar"):
         uninstall_hub_module(module_manifest)
 
     # Cleanup
     with console.status("Cleaning up", spinner="bouncingBar"):
-        remove_from_hub_inits(module_manifest, site_packages)
+        ValidatorPackageService.unregister_validator(module_name)
 
     console.print("✅ Successfully uninstalled!")  # type: ignore
     logger.log(level=LEVELS.get("SPAM"), msg="✅ Successfully uninstalled!")  # type: ignore

guardrails/hub/__init__.py

@@ -1,2 +1,60 @@
-# Should contain imports for all validators
-# Will be auto-populated by the installation script
+"""guardrails.hub - Dynamic import resolution from hub_registry.json.
+
+Validators registered in .guardrails/hub_registry.json are resolved lazily
+on first attribute access and cached for subsequent imports.
+"""
+
+import importlib
+
+from guardrails.hub.registry import get_registry
+
+
+_export_map_cache = None
+
+
+def _build_export_map() -> dict:
+    """Build mapping from export name to import path.
+
+    Returns a dict mapping export names (e.g. "DetectPII") to their
+    module import paths (e.g. "guardrails_grhub_detect_pii").
+    """
+    registry = get_registry()
+    export_map = {}
+    for entry in registry.validators.values():
+        import_path = entry.import_path
+        for export_name in entry.exports:
+            export_map[export_name] = import_path
+    return export_map
+
+
+def _get_export_map() -> dict:
+    """Return cached export map, building it on first access."""
+    global _export_map_cache
+    if _export_map_cache is None:
+        _export_map_cache = _build_export_map()
+    return _export_map_cache
+
+
+def __getattr__(name: str):
+    export_map = _get_export_map()
+    if name in export_map:
+        import_path = export_map[name]
+        try:
+            module = importlib.import_module(import_path)
+            attr = getattr(module, name)
+            globals()[name] = attr
+            return attr
+        except (ModuleNotFoundError, AttributeError) as e:
+            raise ImportError(
+                f"Cannot import '{name}' from hub registry. "
+                f"Module '{import_path}' not found. "
+                f"Try reinstalling: guardrails hub install "
+                f"hub://<org>/<validator>"
+            ) from e
+    raise AttributeError(f"module 'guardrails.hub' has no attribute '{name}'")
+
+
+def __dir__():
+    base = list(globals().keys())
+    base.extend(_get_export_map().keys())
+    return base

guardrails/hub/install.py

@@ -135,7 +135,6 @@ def install(
             msg="Skipping post install, models will not be "
             "downloaded for local inference.",
         )
-    ValidatorPackageService.add_to_hub_inits(module_manifest, site_packages)
     ValidatorPackageService.register_validator(module_manifest)
 
     # 5. Get Validator Class for the installed module

guardrails/hub/registry.py

@@ -0,0 +1,23 @@
+import json
+import os
+from pathlib import Path
+
+from guardrails.types.validator_registry import ValidatorRegistry
+from guardrails.logger import logger
+
+
+def get_registry_path() -> Path:
+    """Return the project-level registry path."""
+    return Path(os.getcwd()) / ".guardrails" / "hub_registry.json"
+
+
+def get_registry() -> ValidatorRegistry:
+    registry_file = get_registry_path()
+    try:
+        registry_str = registry_file.read_text()
+        registry_dict = json.loads(registry_str)
+        registry = ValidatorRegistry.model_validate(registry_dict)
+        return registry
+    except (json.JSONDecodeError, OSError):
+        logger.warning("Failed to read hub registry at %s", registry_file)
+        return ValidatorRegistry()

guardrails/hub/validator_package_service.py

@@ -1,4 +1,5 @@
 import importlib
+import importlib.util
 import json
 import os
 from datetime import datetime, timezone
@@ -11,6 +12,7 @@
 
 from typing import List, Literal, Optional
 from types import ModuleType
+from guardrails.hub.registry import get_registry_path
 from packaging.utils import canonicalize_name  # PEP 503
 
 from guardrails.logger import logger as guardrails_logger
@@ -23,6 +25,7 @@
 from guardrails_hub_types import Manifest
 from guardrails.cli.server.hub_client import get_validator_manifest
 from guardrails.settings import settings
+from guardrails.types.validator_registry import ValidatorRegistry
 
 
 json_format: Literal["json"] = "json"
@@ -72,11 +75,6 @@ def detect_installer() -> str:
             return "uv"
         return "pip"
 
-    @staticmethod
-    def get_registry_path() -> Path:
-        """Return the project-level registry path."""
-        return Path(os.getcwd()) / ".guardrails" / "hub_registry.json"
-
     @staticmethod
     def get_manifest_and_site_packages(module_name: str) -> tuple[Manifest, str]:
         module_manifest = get_validator_manifest(module_name)
@@ -131,10 +129,28 @@ def get_validator_from_manifest(manifest: Manifest) -> ModuleType:
         # Reload or import the module
         return ValidatorPackageService.reload_module(import_line)
 
+    @staticmethod
+    def rewrite_stub_file(registry: ValidatorRegistry):
+        stub_file = (
+            Path(ValidatorPackageService.get_site_packages_location())
+            / "guardrails"
+            / "hub"
+            / "__init__.pyi"
+        )
+
+        import_statements = []
+        for v in registry.validators.values():
+            if v.exports and v.import_path and importlib.util.find_spec(v.import_path):
+                import_statements.extend(
+                    [f"from {v.import_path} import {e} as {e}" for e in v.exports]
+                )
+
+        stub_file.write_text("\n".join(import_statements))
+
     @staticmethod
     def register_validator(manifest: Manifest):
         """Register a validator in the project-level JSON registry."""
-        registry_file = ValidatorPackageService.get_registry_path()
+        registry_file = get_registry_path()
         registry_file.parent.mkdir(parents=True, exist_ok=True)
 
         registry = {"version": 1, "validators": {}}
@@ -168,6 +184,35 @@ def register_validator(manifest: Manifest):
 
         registry_file.write_text(json.dumps(registry, indent=2))
 
+        ValidatorPackageService.rewrite_stub_file(
+            ValidatorRegistry.model_validate(registry)
+        )
+
+    @staticmethod
+    def unregister_validator(validator_id: str):
+        """Remove a validator from the project-level JSON registry."""
+        registry_file = get_registry_path()
+        if not registry_file.exists():
+            return
+
+        try:
+            registry = json.loads(registry_file.read_text())
+        except (json.JSONDecodeError, OSError):
+            guardrails_logger.debug(
+                "Registry at %s is unreadable; skipping unregister",
+                registry_file,
+            )
+            return
+
+        validators = registry.get("validators", {})
+        if validator_id in validators:
+            del validators[validator_id]
+            registry["validators"] = validators
+            registry_file.write_text(json.dumps(registry, indent=2))
+            ValidatorPackageService.rewrite_stub_file(
+                ValidatorRegistry.model_validate(registry)
+            )
+
     @staticmethod
     def add_to_hub_inits(manifest: Manifest, site_packages: str):
         validator_id = manifest.id

guardrails/types/validator_registry.py

@@ -0,0 +1,15 @@
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class ValidatorRegistryEntry(BaseModel):
+    import_path: Optional[str] = Field(default=None)
+    exports: list[str] = Field(default_factory=list)
+    installed_at: Optional[str] = Field(default=None)
+    package_name: Optional[str] = Field(default=None)
+
+
+class ValidatorRegistry(BaseModel):
+    version: int = Field(default=1)
+    validators: dict[str, ValidatorRegistryEntry] = Field(default_factory=dict)