Metadata-Version: 2.4
Name: z-grc
Version: 0.0.32
Summary: Governance Engine by zeb labs
Author-email: Samrat Damodaran <samrat.damodaran@zeb.co>, Shriyokesh Thangavel <shriyokesh.thangavel@zeb.co>, Sid V <sid@zeb.co>, Madhavsrikrishna Sriram <madhavsrikrishna.sriram@zeb.co>, Noor Shekumohamed <noor.shekumohamed@zeb.co>, Arunachalam Gunasekaran <Arun.Gunasekaran@zeb.co>
Maintainer-email: Samrat Damodaran <samrat.damodaran@zeb.co>, Shriyokesh Thangavel <shriyokesh.thangavel@zeb.co>, Sid V <sid@zeb.co>, Madhavsrikrishna Sriram <madhavsrikrishna.sriram@zeb.co>, Noor Shekumohamed <noor.shekumohamed@zeb.co>, Arunachalam Gunasekaran <Arun.Gunasekaran@zeb.co>
License: MIT License
        
        Copyright (c) 2026 zeb labs
        
        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.
        
Project-URL: Homepage, https://github.com/zeb-ai/z-grc
Project-URL: Documentation, https://zeb-ai.github.io/z-grc/
Project-URL: Repository, https://github.com/zeb-ai/z-grc
Keywords: governance,llm,quota,policy,telemetry,observability
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.28.1
Requires-Dist: litellm>=1.83.0
Requires-Dist: mitmproxy>=11.1.3
Requires-Dist: opentelemetry-api>=1.39.1
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.39.1
Requires-Dist: opentelemetry-instrumentation>=0.60b1
Requires-Dist: opentelemetry-instrumentation-httpx>=0.60b1
Requires-Dist: opentelemetry-instrumentation-threading>=0.60b1
Requires-Dist: opentelemetry-sdk>=1.39.1
Requires-Dist: psutil>=6.1.1
Requires-Dist: pydantic>=2.13.3
Requires-Dist: rich>=14.3.3
Requires-Dist: tenacity>=9.1.4
Dynamic: license-file

<p align="center">
  <img src="https://readme-typing-svg.demolab.com?font=Fira+Code&weight=700&size=48&duration=1&pause=1000000&color=6366F1&center=true&vCenter=true&multiline=true&repeat=false&width=600&height=120&lines=Z-GRC" alt="Z-GRC">
</p>

<h2 align="center"><strong>Governance, Risk, and Control Engine for LLMs</strong></h2>
<p align="center">Built by <a href="https://zeb.ai">Zeb Labs</a></p>

<p align="center">
  <a href="https://zeb-ai.github.io/z-grc-application/"><img src="https://img.shields.io/badge/app_Z--GRC_Application-4F46E5?style=flat" alt="Z-GRC Application"></a>
  <a href="https://pypi.org/project/z-grc/"><img src="https://img.shields.io/badge/PyPI-z--grc-FFD700?style=flat&logo=pypi&logoColor=white" alt="PyPI"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/Python-3.14+-3776AB?style=flat&logo=python&logoColor=white" alt="Python Version"></a>
  <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/badge/Code_Style-Ruff-000000?style=flat&logo=ruff&logoColor=white" alt="Code Style: Ruff"></a>
  <a href="https://zeb.ai"><img src="https://img.shields.io/badge/Built_by-Zeb_Labs-blueviolet?style=flat" alt="Built by Zeb Labs"></a>
</p>

---

Enterprise-grade governance engine for Large Language Model applications. Provides automatic interception, policy enforcement, quota management, and comprehensive observability across multiple LLM providers with zero code changes.

## Installation

```bash
uv add z-grc
```

Or with auto-instrumentation:

```bash
uv add z-grc[auto-instrument]
```

## Quick Start

```python
import zgrc
import boto3
import json

# Initialize GRC
zgrc.init(api_key="your-zgrc-api-key")

# Use your LLM SDK normally - GRC handles everything
client = boto3.client("bedrock-runtime", region_name="us-east-1")

response = client.invoke_model(
    modelId="us.anthropic.claude-sonnet-4-5-20250929-v1:0",
    body=json.dumps({
        "anthropic_version": "bedrock-2023-05-31",
        "max_tokens": 1024,
        "messages": [{"role": "user", "content": "Hello!"}]
    })
)

# Z-GRC automatically:
# - Validates quota before requests
# - Tracks token usage
# - Enforces policies
# - Sends telemetry (traces, metrics, logs)
```

## Features

### Zero-Code Integration
Drop-in solution requiring only `zgrc.init()`. Works with existing code without modifications.

### Auto-Discovery
Automatically detects and intercepts installed LLM SDKs:
- AWS Bedrock (boto3)
- Anthropic (coming soon)
- OpenAI (coming soon)
- Azure OpenAI (coming soon)

### Policy Enforcement
Real-time quota validation and cost limit enforcement. Blocks requests when quota is exceeded.

```python
from zgrc.utils import QuotaExceededException

try:
    response = client.invoke_model(...)
except QuotaExceededException as e:
    print(f"Quota exceeded: ${e.used:.4f} used, ${e.remaining:.4f} remaining")
```

<p align="center">
  <img src="docs/assets/quota-exceeded.png" alt="Quota Exceeded Example" width="600">
</p>

### Auto-Instrumentation
Optional automatic instrumentation for HTTP clients, web frameworks, databases, and more:

```python
zgrc.init(
    api_key="your-zgrc-api-key",
    auto_instrument=True,
    app_name="my-app",
    environment="production"
)
```

### Framework Agnostic
Works with vanilla SDKs and popular frameworks:

```python
# PydanticAI
from pydantic_ai import Agent
agent = Agent("bedrock")
result = await agent.run("Your prompt")

# LangChain
from langchain_aws import ChatBedrock
llm = ChatBedrock(model_id="...")
response = llm.invoke("Your prompt")

# Strands Agents
from strands_agents import Agent
agent = Agent(provider="bedrock")
response = agent.execute("Your prompt")
```

### Streaming Support
Fully supports streaming responses with automatic token tracking:

```python
response = client.converse_stream(
    modelId="...",
    messages=[{"role": "user", "content": [{"text": "Tell me a story"}]}]
)

for event in response["stream"]:
    if "contentBlockDelta" in event:
        print(event["contentBlockDelta"]["delta"]["text"], end="")
```

## Configuration

```python
zgrc.init(
    api_key: str,                  # Your Z-GRC API key (required)
    auto_instrument: bool = False, # Enable auto-instrumentation
    app_name: str = None,          # Application name for telemetry
    environment: str = None,       # Environment (dev/staging/prod)
    log_level: int = logging.ERROR # Z-GRC internal log level
)
```

## Proxy Mode (Claude Code CLI)

For environments where code modification isn't possible (like Claude Code CLI), use the standalone proxy:

### Quick Start

**Background Mode (Recommended):**

In the same terminal, run both commands:

```bash
# Step 1: Start proxy in background and set environment variables
eval $(z-grc-proxy --api-key=your-key -d)

# Step 2: Run Claude Code in the same terminal
claude
```

<p align="center">
  <img src="docs/assets/proxy-running.png" alt="Claude Code Running with Z-GRC Proxy" width="600">
  <br>
  <em>Claude Code running with Z-GRC proxy in background mode</em>
</p>

> **Note:** You need to run the `eval $(z-grc-proxy ...)` command in every new terminal where you want to use Claude Code with Z-GRC. The environment variables only apply to the current terminal session.

**Foreground Mode:**

**Terminal 1** - Start the proxy (shows logs):
```bash
z-grc-proxy --api-key=your-key
```

<p align="center">
  <img src="docs/assets/proxy-foreground.png" alt="Z-GRC Proxy Running in Foreground" width="600">
  <br>
  <em>Proxy server running in foreground with request logs</em>
</p>

**Terminal 2** - Open another tab, set environment variables, and run Claude:
```bash
# Mac & Linux
export HTTPS_PROXY=http://127.0.0.1:8080
export NODE_EXTRA_CA_CERTS=~/.mitmproxy/mitmproxy-ca-cert.pem

# Windows
$env:HTTPS_PROXY = "http://127.0.0.1:8080"
$env:NODE_EXTRA_CA_CERTS = "$env:USERPROFILE\.mitmproxy\mitmproxy-ca-cert.pem"

# then run any cli application
claude
```

> **Note:** In foreground mode, the proxy runs in Terminal 1 and shows live logs. Claude Code runs in Terminal 2 with the environment variables set to use the proxy.

### Proxy Commands

```bash
# Mac & Linux Start in background (auto port detection)
eval $(z-grc-proxy --api-key=your-key -d)

# Windows Start in background (auto port detection)
z-grc-proxy --api-key=your-key -d | Out-String | Invoke-Expression

# Mac & Linux Start on specific port
eval $(z-grc-proxy --api-key=your-key --port=8085 -d)
# Windows
z-grc-proxy --api-key=your-key --port=8085 -d | Out-String | Invoke-Expression

# Check active proxy sessions
z-grc-proxy --status

# Kill all proxy servers
z-grc-proxy --kill-all

# Verbose logging
eval $(z-grc-proxy --api-key=your-key -d --verbose)
```

### How It Works

1. **Automatic Port Detection**: Finds available port (8080-8090)
2. **Session Management**: Reuses existing proxy for same API key
3. **mitmproxy Certificates**: Auto-generated in `~/.mitmproxy/` on first run
4. **Platform Independent**: Works on macOS, Linux, Windows

### Building Executables

Build standalone proxy binary with PyInstaller:

```bash
# Current platform only
make grpc-proxy-build
```

Output: `dist/z-grc-proxy`

### Test Binary
```bash
# Background mode
eval $(./dist/z-grc-proxy --api-key=your-key -d)

# Foreground mode
./dist/z-grc-proxy --api-key=your-key
```

## Installing Executor

### macOS / Linux
```bash
curl -fsSL https://raw.githubusercontent.com/zeb-ai/z-grc/main/install.sh | bash
```

### Windows (PowerShell)
```powershell
irm https://raw.githubusercontent.com/zeb-ai/z-grc/main/install.ps1 | iex
```
