uv-guard 0.1.0

uv-guard is a CLI tool that harmonizes the uv package manager with the Guardrails AI ecosystem.

uv-guard

uv-guard is a CLI tool that harmonizes the uv package manager with the Guardrails AI ecosystem.

While uv excels at strict environment locking, its synchronization process often identifies and removes Guardrails' static assets as extraneous files. uv-guard resolves this conflict by wrapping both tools into a unified workflow. It maintains a persistent record of installed validators, tracks their dependencies, and automatically triggers post-installation scripts whenever the environment is updated—ensuring your validation logic remains intact without manual intervention.

Configuration & Persistence

To track Guardrails Hub URIs, uv-guard extends the standard pyproject.toml configuration. When a validator is added, uv-guard creates a dedicated guardrails list within the configuration file, functioning alongside standard dependencies.

This ensures that the pyproject.toml file remains the project's source of truth, tracking both standard Python packages and Guardrails Hub URIs in one place.

Example pyproject.toml structure:

[project]
name = "my-project"
dependencies = [
    "guardrails-ai",
    "guardrails-grhub-regex-match",  # The underlying Python package resolved by uv-guard
]
# uv-guard tracks the specific Hub URIs here
guardrails = [
    "hub://guardrails/regex_match"
]

Prerequisites

• Python: 3.10+
• uv: See the uv installation page

Installation

You can install uv-guard using pip, pipx, or uv tool:

# Recommended: Install as a standalone tool via uv
uv tool install uv-guard

Usage

uv-guard mirrors the uv commands but extends them to support Guardrails Hub URIs (hub://).

Initialize a Project

Initializes a new uv project and automatically adds the guardrails-ai core dependency.

uv-guard init

The command passes all arguments and options to uv init. For example:

uv-guard init --name my-project

forwards the --name my-project option.

Configure Guardrail AI

Configure Guardrails AI. You can get your API key from the Guardrails Hub website.

Guardrails has to be configured to add Guardrails validators from the Hub.

uv-guard configure

Passes all arguments and options to guardrails configure.

Add Dependencies

Adds a package to the project. This command intelligently handles both standard PyPI packages and Guardrails Hub URIs.

When adding a Guardrails Hub URI:

1. It adds the URI to the guardrails list in pyproject.toml.
2. It resolves the underlying Python package required by the validator and adds it to the standard dependencies.
3. It executes the Guardrails post-installation script to set up the validator.

# Add a standard Python package
uv-guard add pandas

# Add a Guardrails validator
uv-guard add hub://guardrails/regex_match

Passes all arguments and options to uv add.

Remove Dependencies

Uninstall the guardrails, removes the package from the uv environment and cleans up the pyproject.toml.

uv-guard remove hub://guardrails/regex_match

Passes all arguments and options to uv remove.

Sync Environment

Updates the project environment. This is the critical operation that ensures compatibility.

When syncing, uv-guard:

1. Reads the guardrails list from pyproject.toml.
2. Ensures underlying Python packages are present in the uv dependency tree.
3. Executes uv sync to update the environment.
4. Re-runs Guardrails installation scripts to restore any assets removed during the sync process.

uv-guard sync

Passes all arguments and options to uv sync.

Other uv Commands

All other uv commands are explicitly forwarded to the underlying uv executable. This allows you to use uv-guard as a drop-in replacement for uv in your daily workflow.

Examples:

# Update the lockfile
uv-guard lock

# View the dependency tree
uv-guard tree

# Manage python versions
uv-guard python install 3.12

Supported commands include: auth, lock, export, tree, format, tool, python, pip, venv, build, publish, cache, and self.