Metadata-Version: 2.4
Name: uv-guard
Version: 0.1.2
Summary: uv-guard is a CLI tool that harmonizes the uv package manager with the Guardrails AI ecosystem.
Author-email: Florian Bacho <f.bacho@outlook.fr>
License: MIT License
        
        Copyright (c) 2026 Florian Bacho
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: cli,guardrails,guardrails-ai,llm,python-packaging,uv,validation
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: <4.0,>=3.10
Requires-Dist: guardrails-ai>=0.8.0
Requires-Dist: rich>=14.3.2
Requires-Dist: tomlkit>=0.12.0
Requires-Dist: typer>=0.19.2
Description-Content-Type: text/markdown

# uv-guard

**uv-guard** is a CLI tool that harmonizes the [uv](https://docs.astral.sh/uv/) package manager with the [Guardrails AI](https://guardrailsai.com/) 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:**

```toml
[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](https://docs.astral.sh/uv/getting-started/installation/)

## Installation

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

```bash
# 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.

```bash
uv-guard init
```
The command passes all arguments and options to `uv init`. For example:
```bash
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](https://guardrailsai.com/hub).

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

```bash
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.

```bash
# 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`.

```bash
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.

```bash
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:

```bash
# 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`, `run`, `version`, `lock`, `export`, `tree`, `format`, `tool`, `python`, `pip`, `venv`, `build`, `publish`, `cache`, and `self`.*
