Metadata-Version: 2.4
Name: ai-cost-guardrail
Version: 0.1.0
Summary: A lightweight Python utility to prevent cloud cost landmines by monitoring and intercepting sudden HTTP request spikes.
Author-email: Tal <tal.derie.td@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/infinityempire/ai-guardrail
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# AI GuardRail 🚨

A lightweight Python utility designed to prevent cloud cost landmines. It monitors HTTP requests and automatically intercepts and blocks sudden spikes or infinite loop request patterns (e.g., more than 50 calls to the same endpoint in 10 seconds), saving you from unexpected API bills.

## Features

- **In-Process Monkey Patching**: Zero-config protection for your existing Python applications. Instantly intercepts and blocks excessive requests using standard libraries (`urllib`, `urllib3`, `requests`).
- **Standalone Proxy Server**: Can run as a local proxy on any port, letting any application/environment route requests through it using `HTTP_PROXY`.
- **Dynamic Sliding Window**: Tracks request history using a thread-safe sliding window.
- **Customizable Thresholds**: Easily customize request rate limits and window sizes.

## Installation

```bash
pip install ai-cost-guardrail
```

## Usage

### 1. In-Process Monkey-Patcher (Python Apps)

Import `ai_guardrail` at the very beginning of your application entry point to intercept cost landmines:

```python
import ai_guardrail

# Block requests if an endpoint is called more than 30 times in 10 seconds
ai_guardrail.enable(max_calls=30, window_seconds=10)

import requests
# Any HTTP requests made via urllib, urllib3, requests, etc., are now automatically protected!
```

If a loop triggers, a `RuntimeError` is raised, blocking the request from hitting the cloud API and saving your budget.

### 2. Standalone Proxy Server

You can run the GuardRail proxy server locally and route any external application traffic through it.

Run via CLI:
```bash
ai-cost-guardrail-proxy --port 8090 --max-calls 50 --window 10
```

Or via Python:
```python
import ai_guardrail
ai_guardrail.run_proxy_server(port=8090)
```

Then configure your environment variables to use the proxy:
```bash
export HTTP_PROXY="http://127.0.0.1:8090"
export HTTPS_PROXY="http://127.0.0.1:8090"
```

## Running Tests

To run unit tests:
```bash
python -m unittest discover -s tests
```

## License

MIT
