guardrail-ai 0.1.8

A CLI tool that generates and runs tests for changed Python functions before executing commands

GuardRail

A CLI tool that automatically generates and runs tests for changed Python functions before executing commands. GuardRail uses AI to analyze your code changes, generate comprehensive tests, and blocks execution if tests fail.

Features

• 🔍 Automatic Change Detection - Detects changed Python functions using git diff
• 🧠 AI-Powered Test Generation - Uses OpenAI to generate comprehensive pytest tests
• 🛡️ Side-Effect Detection - Automatically skips functions with side effects (network, DB, file I/O)
• ✅ Test Execution - Runs generated tests automatically before your command
• 🚫 Execution Blocking - Prevents command execution if tests fail
• 🔧 Fix Prompts - Provides detailed fix prompts when tests fail

Installation

Quick Install (from Git)

# Clone the repository
git clone https://github.com/yourusername/GuardRail.git
cd GuardRail

# Install in editable mode
pip install -e .

Install from Local Directory

If you have the GuardRail folder:

cd /path/to/GuardRail
pip install -e .

Install from PyPI (when published)

pip install guardrail

See INSTALLATION.md for detailed installation instructions.

Quick Start

1. Initialize GuardRail

guardrail init

This will:

• Create .guardrail/config.toml - Configuration file
• Create .guardrail/cache.sqlite - Cache database
• Prompt you for your OpenAI API key (or set OPENAI_API_KEY environment variable)

2. Run Commands with GuardRail

guardrail run -- pytest
guardrail run -- python main.py
guardrail run -- uvicorn app:app

GuardRail will:

1. Detect changed Python functions
2. Classify them (pure vs side-effect)
3. Generate tests for pure functions
4. Run the tests
5. Block execution if tests fail
6. Execute your command if tests pass

3. Manual Check (without running command)

guardrail check

Runs the same detection and test generation flow without executing a command at the end.

How It Works

1. Change Detection

GuardRail uses git diff to detect unstaged changes in Python files and identifies which functions were modified.

2. Function Analysis

• Parses Python files using AST
• Extracts function definitions with line numbers
• Maps changed lines to specific functions

3. Side-Effect Classification

Automatically detects and skips functions with:

• Network calls (requests, httpx, aiohttp)
• Database operations (sqlite3, psycopg2, pymongo, redis)
• File I/O (open(), file operations)
• System calls (subprocess, os.system)

4. Test Generation

For pure functions, GuardRail:

• Generates a SpecCard (function specification) using AI
• Generates comprehensive pytest tests based on the SpecCard
• Saves tests to tests/guardrail_generated/

5. Test Execution

• Runs pytest on generated tests
• Blocks command execution if tests fail
• Provides detailed fix prompts for failing tests

Configuration

Configuration is stored in .guardrail/config.toml:

version = "0.1.0"
test_dir = "tests/guardrail_generated"
cache_enabled = true
openai_api_key = "sk-..."  # Stored securely

Environment Variables

• OPENAI_API_KEY - OpenAI API key (alternative to storing in config)

Example Workflow

# Make changes to a Python function
$ vim my_module.py

# Run your command with GuardRail
$ guardrail run -- python main.py

🔍 Detecting changed files...
📝 Found 1 changed Python file(s):
  📄 my_module.py (lines: 10-15)

🔎 Analyzing changed functions...
  📄 my_module.py
    Functions touched: 1
      ✅ calculate_total - Pure-ish

🤖 Generating tests for 1 pure function(s)...
  📝 Generating spec for calculate_total...
  ✅ Spec generated (confidence: high)
  🧪 Generating tests...
  ✅ Test saved: tests/guardrail_generated/test_my_module_calculate_total.py

✅ Generated 1 test file(s)

🧪 Running generated tests...
✅ All tests passed!

🚀 Running: python main.py
[Your command output...]

Requirements

• Python 3.8+
• Git repository (for change detection)
• OpenAI API key
• pytest (for running tests)

Development Status

✅ V1 Complete - All core features implemented

Completed Features

• ✅ Change detection (git diff)
• ✅ AST function locator
• ✅ Side-effect classifier
• ✅ AI-powered test generation
• ✅ Test execution and blocking
• ✅ Fix prompt generation
• ✅ Manual check command
• ✅ Caching system

Troubleshooting

"OpenAI API key not found"

Run guardrail init to configure your API key, or set the OPENAI_API_KEY environment variable.

"pytest not found"

Install pytest: pip install pytest

"Not a git repository"

GuardRail requires a git repository for change detection. Initialize git: git init

Tests failing but function seems correct

The generated tests might be too strict. Check the test file in tests/guardrail_generated/ and adjust if needed.

License

MIT