[bug] Cannot get guardrails working with given documentation

[ta-dr0aid]

Describe the bug
I cannot successfully call guardrails with the given information to set them up.

To Reproduce
Steps to reproduce the behavior:

Using these commands to install the guardrails environment within a cloned repo version 0.6.2.

Copyright (C) Microsoft Corporation. Alle Rechte vorbehalten.

PS <snip>\guardrails-0.6.2> python -m venv venv
PS <snip>\guardrails-0.6.2> .\venv\Scripts\activate
(venv) PS <snip>\guardrails-0.6.2> pip list
Package    Version
---------- -------
pip        24.0
setuptools 65.5.0

[notice] A new release of pip is available: 24.0 -> 24.3.1
[notice] To update, run: python.exe -m pip install --upgrade pip
(venv) PS <snip>\guardrails-0.6.2> python.exe -m pip install --upgrade pip
(venv) PS <snip>\guardrails-0.6.2> pip install --upgrade setuptools

<snip>

Successfully installed MarkupSafe-3.0.2 PyYAML-6.0.2 aiohappyeyeballs-2.4.4 aiohttp-3.11.11 aiosignal-1.3.2 annotated-types-0.7.0 anyio-4.8.0 arrow-1.3.0 attrs-24.3.0 boto3-1.35.99 botocore-1.35.99 certifi-2024.12.14 charset-normalizer-3.4.1 click-8.1.8 colorama-0.4.6 coloredlogs-15.0.1 deprecated-1.2.15 di
ff-match-patch-20230430 distro-1.9.0 faker-25.9.2 filelock-3.16.1 fqdn-1.5.1 frozenlist-1.5.0 fsspec-2024.12.0 googleapis-common-protos-1.66.0 griffe-0.36.9 grpcio-1.69.0 guardrails-ai-0.6.2 guardrails-api-client-0.4.0a1 guardrails-hub-types-0.0.4 h11-0.14.0 httpcore-1.0.7 httpx-0.27.2 huggingface-hub-0.27.
1 humanfriendly-10.0 idna-3.10 importlib-metadata-8.5.0 isoduration-20.11.0 jinja2-3.1.5 jiter-0.8.2 jmespath-1.0.1 jsonpatch-1.33 jsonpointer-3.0.0 jsonref-1.1.0 jsonschema-4.23.0 jsonschema-specifications-2024.10.1 langchain-core-0.3.29 langsmith-0.2.10 litellm-1.58.2 lxml-4.9.4 markdown-it-py-3.0.0 mdurl
-0.1.2 multidict-6.1.0 openai-1.59.7 opentelemetry-api-1.29.0 opentelemetry-exporter-otlp-proto-common-1.29.0 opentelemetry-exporter-otlp-proto-grpc-1.29.0 opentelemetry-exporter-otlp-proto-http-1.29.0 opentelemetry-proto-1.29.0 opentelemetry-sdk-1.29.0 opentelemetry-semantic-conventions-0.50b0 orjson-3.10.
14 packaging-24.2 propcache-0.2.1 protobuf-5.29.3 pydantic-2.10.5 pydantic-core-2.27.2 pydash-7.0.7 pygments-2.19.1 pyjwt-2.10.1 pyreadline3-3.5.4 python-dateutil-2.9.0.post0 python-dotenv-1.0.1 referencing-0.35.1 regex-2024.11.6 requests-2.32.3 requests-toolbelt-1.0.0 rfc3339-validator-0.1.4 rfc3987-1.3.8 
rich-13.9.4 rpds-py-0.22.3 rstr-3.2.2 s3transfer-0.10.4 semver-3.0.2 shellingham-1.5.4 six-1.17.0 sniffio-1.3.1 tenacity-9.0.0 tiktoken-0.8.0 tokenizers-0.21.0 tqdm-4.67.1 typer-0.12.5 types-python-dateutil-2.9.0.20241206 typing-extensions-4.12.2 uri-template-1.3.0 urllib3-2.0.7 webcolors-24.11.1 wrapt-1.17.2 yarl-1.18.3 zipp-3.21.0
(venv) PS <snip>\guardrails-0.6.2> where guardrails
(venv) PS <snip>\guardrails-0.6.2> guardrails configure
Enable anonymous metrics reporting? [Y/n]: n
Do you wish to use remote inferencing? [Y/n]:

Enter API Key below leave empty if you want to keep existing token 
👉 You can find your API Key at https://hub.guardrailsai.com/keys

API Key:

            Login successful.

            Get started by installing our RegexMatch validator:
            https://hub.guardrailsai.com/validator/guardrails_ai/regex_match

            You can install it by running:
            guardrails hub install hub://guardrails/regex_match

            Find more validators at https://hub.guardrailsai.com

(venv) PS <snip>\guardrails-0.6.2> guardrails hub install hub://guardrails/regex_match
Installing hub://guardrails/regex_match...
✅Successfully installed guardrails/regex_match!


Import validator:
from guardrails.hub import RegexMatch

Get more info:
https://hub.guardrailsai.com/validator/guardrails/regex_match

(venv) PS <snip>\guardrails-0.6.2> 

Using this code snippet:

from guardrails import Guard, OnFailAction
from guardrails.hub import RegexMatch

guard = Guard().use(
    RegexMatch, regex="\(?\d{3}\)?-? *\d{3}-? *-?\d{4}", on_fail=OnFailAction.EXCEPTION
)

guard.validate("123-456-7890")  # Guardrail passes

try:
    guard.validate("1234-789-0000")  # Guardrail fails
except Exception as e:
    print(e)

gives

snip\guardrails-0.6.2\venv\Scripts\python.exe <snip>\guardrails-0.6.2\local_files\quickscript.py 
Traceback (most recent call last):
  File "<snip>\guardrails-0.6.2\local_files\quickscript.py", line 2, in <module>
    from guardrails.hub import RegexMatch
ImportError: cannot import name 'RegexMatch' from 'guardrails.hub' (<snip>\guardrails-0.6.2\guardrails\hub\__init__.py)

Process finished with exit code 1

where <snip> is the correct folder, snipped for confidentiality reasons.

System Metadata:

• Ryzen 9 5950x
• RTX 4090
• Win 11 23H2 (Build 22631.4602)
• PyCharm 2023.2.2 (Community Edition)
• Guardrails-AI 0.6.2

Expected behavior
From the readme I'd expect this output in the console:
Validation failed for field with errors: Result must match \(?\d{3}\)?-? *\d{3}-? *-?\d{4}

Library version:
Version 0.6.2, downloaded from the releases page

Additional context
So far, I have not been able to get any guardrails working. If I understand the console report correctly, the guardrails get installed correctly from the hub. I can verify that within the virtual environment, pip list returns guardrails-grhub-regex-match.

where guardrails does not return anything. Likewise, guardrails-0.6.2\guardrails\hub\__init__.py is empty, in guardrails-0.6.2\venv\Lib\site-packages\guardrails\hub\__init__.py, I see from guardrails_grhub_regex_match import RegexMatch.

[CalebCourier]

@ta-dr0aid, just so I understand your local setup correctly, are you trying to run the code snippet in the same directory where you cloned/downloaded the guardrails-ai source code?

[ta-dr0aid]

Hi @CalebCourier, thanks for your prompt response. I think I got the snips messed up, I updated them. My path /guardrails-0.6.2 is the path where I can see the whole guardrails git repo. The call happens from within Pycharm with running "Current File" and the code snippet is activated as the current file. The current file is located under /guardrails-0.6.2/local_files/quickscript.py

[CalebCourier]

@ta-dr0aid, thanks for the clarification! This issue has to do with how python's module system resolves imports. Basically it doesn’t understand the difference between a pip installed module named guardrails and a directory or file named guardrails and will often try to use the closest one in the python path which can vary based on where the file you are running is located, where you start the process from, or sometimes even your operating system.

For example, if I follow your setup method where the code snipped is located in guardrails-0.6.2/local_files/quickscript.py, everything works as expected because the module system correctly identifies the guardrails module at .venv/lib/python3.12/site-packages/guardrails. However, if I move the code snippet to guardrails-0.6.2/quickscript.py, I encounter the same error you are seeing: ImportError: cannot import name 'RegexMatch' from 'guardrails.hub' (/guardrails-0.6.2/guardrails/hub/__init__.py) because the module system sees the adjacent guardrails directory from the source code and tries to use that.

The solution here is to install the downloaded version using pip in a directory separate from guardrails-0.6.2 using the relative or absolute path. For example, if you have the below file directory,

Downloads
  |_ guardrails-0.6.2
  |_ my-app

You can create the virtual environment within my-app and pip install /Downloads/guardrails-0.6.2

[ta-dr0aid]

@CalebCourier Yes, that works. No ImportErrors as of now anymore. Thanks a bunch for your help :)