Metadata-Version: 2.4
Name: piiguardrails
Version: 2.0.6
Summary: Enterprise PII Guardrail Studio
Project-URL: Homepage, https://github.com/piiguardrails/piiguardrails
Project-URL: Repository, https://github.com/piiguardrails/piiguardrails
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

<div align="center">

# 🛡️ Enterprise PII Guardrails Studio (v2.0.6)

**High-Performance, Zero-Leak AI Privacy Gateway & Management Studio for Enterprise LLM Pipelines**

[![PyPI Version](https://img.shields.io/pypi/v/piiguardrails?color=blue&label=PyPI%20Package)](https://pypi.org/project/piiguardrails/)
[![PyPI Downloads](https://img.shields.io/pepy/dt/piiguardrails?color=blue&label=PyPI%20Downloads&logo=pypi&logoColor=white)](https://pypi.org/project/piiguardrails/)
[![GitHub Downloads](https://img.shields.io/github/downloads/piiguardrails/piiguardrails/total?color=blue&label=GitHub%20Downloads&logo=github)](https://github.com/piiguardrails/piiguardrails)
[![Docker Pulls](https://img.shields.io/docker/pulls/piiguardrails/enterprise-pii-guardrail?color=blue&label=Docker%20Pulls&logo=docker&logoColor=white)](https://hub.docker.com/r/piiguardrails/enterprise-pii-guardrail)
[![GitHub Stars](https://img.shields.io/github/stars/piiguardrails/piiguardrails?style=flat&logo=github&color=gold)](https://github.com/piiguardrails/piiguardrails)

[![Python Version](https://img.shields.io/badge/python-%3E%3D%203.8-3776AB?logo=python&logoColor=white)](https://pypi.org/project/piiguardrails/)
[![Security](https://img.shields.io/badge/Security-AES--256%20SQLCipher%20%7C%20Ed25519-blueviolet)](https://github.com/piiguardrails/piiguardrails)
[![Performance](https://img.shields.io/badge/Latency-%3C25ms%20In--Memory-brightgreen)](https://github.com/piiguardrails/piiguardrails)
[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20x64-0078D4?logo=linux&logoColor=white)](https://pypi.org/project/piiguardrails/)
[![License](https://img.shields.io/badge/License-Commercial%20%2F%20Evaluation-orange)](https://github.com/piiguardrails/piiguardrails/blob/main/LICENSE)

<br/>

[**PyPI Package**](https://pypi.org/project/piiguardrails/) • [**GitHub Repository**](https://github.com/piiguardrails/piiguardrails) • [**API Reference**](https://github.com/piiguardrails/piiguardrails/blob/main/docs/API_REFERENCE.md) • [**Licensing Guide**](https://github.com/piiguardrails/piiguardrails/blob/main/LICENSING_GUIDE.md) • [**Report Issue**](https://github.com/piiguardrails/piiguardrails/issues)

</div>

---

## 📸 The Enterprise Studio in Action

### Interactive PII Playground (Live Detection with Visual Highlight Pills)
Inspect, scrub, and redact sensitive entities with sub-25ms latency. Visual badge pills pinpoint exactly what the engine detected before it ever leaves your network.

![Interactive PII Playground](https://raw.githubusercontent.com/piiguardrails/piiguardrails/main/docs/assets/hero_playground.png)

<br/>

<details>
<summary><b>🔍 Expand to View Additional Studio Screenshots</b></summary>

<br/>

#### 1. Deterministic Safe Payload Output (`/mask`)
Transformed prompt ready for LLM consumption with reversible placeholder tokens (`<PERSON_1>`, `<SSN_1>`, `<CREDIT_CARD_1>`).

![Safe Payload View](https://raw.githubusercontent.com/piiguardrails/piiguardrails/main/docs/assets/safe_payload_view.png)

#### 2. Node-Locked Enterprise Licensing & Hardware ID Management
Cryptographically bound to your server hardware using Ed25519 signatures with zero external network phone-home requirement.

![License Management](https://raw.githubusercontent.com/piiguardrails/piiguardrails/main/docs/assets/license_management.png)

#### 3. 30+ Entity Recognizers & Rule Engine
Granular toggles for Financial, Healthcare, IT Security, and Core PII with configurable replacement strategies (Replace, Mask, Hash, Redact).

![Guardrail Profiles](https://raw.githubusercontent.com/piiguardrails/piiguardrails/main/docs/assets/guardrail_profiles.png)

#### 4. Real-Time Threat Intelligence & IoC Shield
Interception firewall blocking malicious IP addresses, phishing domains, and credential leaks before evaluation.

![Threat Intelligence](https://raw.githubusercontent.com/piiguardrails/piiguardrails/main/docs/assets/threat_intelligence.png)

#### 5. Enterprise Authentication Portal
Encrypted session management, role-based access control, and customizable enterprise branding.

![Login Screen](https://raw.githubusercontent.com/piiguardrails/piiguardrails/main/docs/assets/login_screen.png)

</details>

---

## ⚡ Overview

**Enterprise PII Guardrails Studio** is an ultra-fast, defense-in-depth privacy gateway designed to intercept, detect, mask, and pseudonymize Personally Identifiable Information (PII) before it reaches third-party LLM APIs (OpenAI, Anthropic, Google Gemini, Azure OpenAI) or internal vector databases.

### Key Highlights:
- **Sub-25ms Live Masking**: In-memory LRU authorization cache and non-blocking asynchronous audit pipeline.
- **Zero-Leak Guarantee at Rest**: Database, API keys, and audit logs are encrypted using **SQLCipher AES-256-CBC**.
- **SHA-256 Cryptographic Verification**: Every downloaded runtime engine is verified on the fly against official SHA-256 hashes prior to execution.
- **Node-Locked Licensing (v4)**: Commercial licenses are cryptographically locked to the host's **Server Hardware ID** via Ed25519 asymmetric signatures—operating 100% offline with zero cloud dependency.
- **Bi-Directional Token Restoration**: Effortlessly restore LLM responses (`/unmask`) back to original values for authorized end users.

---

## 🔄 How It Works (Zero-Trust Pipeline)

```mermaid
sequenceDiagram
    autonumber
    actor User as Client / App
    participant GW as PII Guardrail Gateway
    participant Cache as In-Memory Auth Cache
    participant Engine as Multi-Tier PII Recognizer
    participant DB as SQLCipher AES-256
    participant LLM as External LLM (OpenAI / Anthropic)

    User->>GW: POST /mask (Prompt with sensitive PII)
    GW->>Cache: Verify X-API-Key (< 0.1ms)
    GW->>Engine: Scan regex rules + NLP entities
    Engine->>DB: Asynchronously store reversible tokens & mapping
    GW-->>User: Return Safe Payload (<PERSON_1>, <SSN_1>)
    
    User->>LLM: Send sanitized payload
    LLM-->>User: Return completion with tokens
    
    User->>GW: POST /unmask (LLM output + mapping vault)
    GW-->>User: Return restored response with real entity values
```

---

## 🚀 Quickstart

### Method 1: Using `pip` (Recommended)

```bash
# 1. Install from PyPI
pip install piiguardrails

# 2. Launch the studio
piiguardrails
```

On first launch, `piiguardrails` automatically streams the core binary, verifies its **SHA-256 cryptographic checksum**, provisions your encrypted database, and opens the studio dashboard on:
👉 **`http://localhost:8000`**

---

### Method 2: Using `uv` (Instant Sandbox — Zero Setup)

Run directly in a self-contained, isolated environment without polluting global Python:

```bash
uv run --with piiguardrails piiguardrails
```

---

### Method 3: Standalone Pre-Compiled Executable

For restricted air-gapped environments without Python installed, download the standalone binary directly from [GitHub Releases](https://github.com/piiguardrails/piiguardrails/releases):

- **Windows x64**: `EnterprisePIIGuardrail-v2.0.6-windows-x64.exe`
  - *SHA-256*: `1f910b35635edb8ceebffe999513e77d037ca3a918724c1fb0ebc939da8a1e4e`
- **Linux x86_64**: `EnterprisePIIGuardrail-v2.0.6-linux-x86_64`
  - *SHA-256*: `50c7f948d724082ad007eab30c7f53b391ed8a5249237e8e1bc3d535eceadc4f`

Run directly:
```bash
# Linux
chmod +x EnterprisePIIGuardrail-v2.0.6-linux-x86_64
./EnterprisePIIGuardrail-v2.0.6-linux-x86_64

# Windows
.\EnterprisePIIGuardrail-v2.0.6-windows-x64.exe
```

---

### Method 4: Docker / Podman Deployment

```bash
docker run -d \
  -p 8000:8000 \
  -v $(pwd)/data:/app/data \
  -e SQLCIPHER_PASSPHRASE="your-secure-passphrase-min-32-chars!" \
  --name pii-guardrail-studio \
  piiguardrails/enterprise-pii-guardrail:latest
```

---

### 🎁 Community Launch Promo: 6 Months Free Enterprise

To celebrate our v2.0 release, early adopters can unlock full **Enterprise Tier** features (unlimited API requests, unrestricted payload length, and custom regex policies) through **March 31, 2027**:

```text
ED3-AMBGXK7UVD777777-GRYXEUYUZ432JOHY-UWVDBHXRLAXU4U47-7MBK2DQGIUV4JQT6-UJNRXNTHI3JPBGIS-P66HGKVYNLMQXHHS-M3N4RF3XDN6LZILT-WQNCGJ4KEY6ONIIM
```

**To activate:**
1. Open the studio dashboard (`http://localhost:8000`).
2. Go to **Settings > License & Quota** in the sidebar.
3. Paste the key above and click **Activate License**.

---

## 🧩 Python Integration Example

Once the studio is running, integrate it directly into your LangChain, LlamaIndex, or raw API pipeline:

```python
import requests

API_KEY = "your-api-key-here"  # Generated in the Studio UI
headers = {"X-API-Key": API_KEY, "Content-Type": "application/json"}

# 1. Mask sensitive input before sending to LLM
payload = {
    "text": "Hello Alice Smith, your verification code was sent to alice.smith@acme.corp. Call us at 415-555-2671."
}

mask_response = requests.post("http://localhost:8000/mask", json=payload, headers=headers).json()
print("Masked text for LLM:", mask_response["masked_text"])
# Output: "Hello <PERSON_1>, your verification code was sent to <EMAIL_1>. Call us at <PHONE_1>."

# 2. Query your LLM with safe, masked prompt...
# simulated_llm_reply = "We contacted <PERSON_1> at <EMAIL_1> regarding the ticket."

# 3. Unmask the LLM response back to real entities for your user
unmask_payload = {
    "text": "We contacted <PERSON_1> at <EMAIL_1>.",
    "mapping": mask_response["mapping"]
}
unmask_response = requests.post("http://localhost:8000/unmask", json=unmask_payload, headers=headers).json()
print("Restored response:", unmask_response["unmasked_text"])
# Output: "We contacted Alice Smith at alice.smith@acme.corp."
```

---

## 🛡️ Enterprise Feature Matrix

| Capability | Community Promo / Trial | Standard Tier | Enterprise Tier |
| :--- | :---: | :---: | :---: |
| **Masking Latency** | **< 25ms** | **< 25ms** | **< 25ms** |
| **Pre-built Entity Recognizers** | 30+ Included | 30+ Included | 30+ Included |
| **Custom Regex Engine** | 2 Patterns | 5 Patterns | **Unlimited** |
| **Max Payload Size** | 5,000 chars | 50,000 chars | **Unrestricted** |
| **Monthly API Quota** | 1,000 reqs | 20,000 reqs | **Unlimited** |
| **Storage Security** | SQLCipher AES-256 | SQLCipher AES-256 | **SQLCipher AES-256** |
| **Licensing Mode** | Version 3 Floating | Version 3 Floating | **Version 4 Node-Locked (`--hwid`)** |
| **Threat Intelligence Shield** | ✅ Included | ✅ Included | ✅ Included |
| **Audit Logging & Retention** | ✅ Included | ✅ Included | ✅ Included |

---

## 📚 Complete Documentation Index

- 📖 **[API Reference Specification](https://github.com/piiguardrails/piiguardrails/blob/main/docs/API_REFERENCE.md)**: Full OpenAPI / REST documentation with request/response schemas for `/mask`, `/unmask`, `/health`, and Admin endpoints.
- 🔑 **[Customer Licensing Guide](https://github.com/piiguardrails/piiguardrails/blob/main/LICENSING_GUIDE.md)**: Guide on tiers, obtaining your Server Hardware ID, and activating enterprise keys offline.
- 💾 **[Backup & Disaster Recovery Guide](https://github.com/piiguardrails/piiguardrails/blob/main/docs/BACKUP_AND_DISASTER_RECOVERY.md)**: Database persistence, `.env` encryption passphrase management, and server migration.

---

## 📋 System Requirements

- **Operating System**: Windows 10/11/Server (64-bit) or Linux (Ubuntu, Debian, RHEL, CentOS, Rocky, WSL2 x86_64)
- **Python**: `>= 3.8` (if running via `pip` / `uv`)
- **Memory**: Minimum 2 GB RAM (4 GB recommended for high throughput)
- **Network Port**: Default `8000` (configurable via `--port` or `.env`)

---

## 📄 License

This software is governed by the [Enterprise Evaluation and Commercial License Agreement](https://github.com/piiguardrails/piiguardrails/blob/main/LICENSE). All rights reserved.
