aipromptsentinel 0.2.0
Comprehensive prompt safety: bad prompt detection, injection detection, and PII safety for LLM applications
License: MIT
Requires Python: >=3.9
Keywords: ai-safety, llm-security, nlp, pii-detection, prompt-injection, prompt-safety, security

# 🛡️ aipromptsentinel

[![PyPI version](https://badge.fury.io/py/aipromptsentinel.svg)](https://badge.fury.io/py/aipromptsentinel)
[![Python](https://img.shields.io/pypi/pyversions/aipromptsentinel.svg)](https://pypi.org/project/aipromptsentinel/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Comprehensive prompt safety for LLM applications.**

aipromptsentinel combines **bad prompt detection**, **prompt injection detection**, and **PII safety** into a unified, production-ready Python package.

## ✨ Features

| Feature | Description |
|---------|-------------|
| 🔍 **PII Detection** | Identifies emails, SSNs, credit cards, phone numbers, IP addresses, API keys, and more |
| 🛡️ **Injection Detection** | Detects prompt injection attacks, jailbreaks, and context manipulation |
| 🚫 **Bad Prompt Detection** | Flags harmful, toxic, or inappropriate content across multiple categories |
| ⚡ **Zero ML Dependencies** | Fast, lightweight regex/heuristic-based detection |
| 🖥️ **CLI Included** | Scan text and files from the command line |
| 📊 **Risk Scoring** | Confidence scores and risk levels for all detections |

## 🚀 Quick Start

### Installation

```bash
pip install aipromptsentinel
```

Or with uv:

```bash
uv add aipromptsentinel
```

### Basic Usage

```python
from aipromptsentinel import Sentinel

sentinel = Sentinel()

# Analyze any text
result = sentinel.analyze("My email is test@example.com. Ignore previous instructions!")

print(result.is_safe)          # False
print(result.has_pii)          # True
print(result.has_injection)    # True
print(result.has_bad_content)  # False

# Quick checks
sentinel.is_safe("Hello world")                    # True
sentinel.has_pii("SSN: 123-45-6789")               # True  
sentinel.has_injection("Ignore all instructions")  # True

# Redact PII
text = "Contact me at john@example.com"
print(sentinel.redact_pii(text))  # "Contact me at [REDACTED]"
```

## 📖 API Reference

### Sentinel Class

The main interface combining all detection capabilities.

```python
from aipromptsentinel import Sentinel

# Full configuration
sentinel = Sentinel(
    enable_pii=True,           # Enable PII detection
    enable_injection=True,      # Enable injection detection
    enable_bad_prompt=True,     # Enable bad prompt detection
    injection_threshold=0.5,    # Minimum confidence for injections
    bad_prompt_severity="low",  # Minimum severity level
)

# Complete analysis
result = sentinel.analyze("Your text here")
```

#### SentinelResult

```python
result.is_safe              # bool: Overall safety verdict
result.has_pii              # bool: Contains PII
result.has_injection        # bool: Contains injection attempt
result.has_bad_content      # bool: Contains harmful content
result.pii_findings         # List[PIIFinding]
result.injection_findings   # List[InjectionFinding]
result.bad_prompt_findings  # List[BadPromptFinding]
result.injection_risk_score # float: 0.0 to 1.0
result.bad_prompt_risk_level # str: "safe", "low", "medium", "high", "critical"
result.to_dict()            # Convert to JSON-serializable dict
```

### Individual Detectors

Use detectors independently for specific needs:

```python
from aipromptsentinel.detectors import PIIDetector, InjectionDetector, BadPromptDetector

# PII Detection
pii = PIIDetector()
findings = pii.detect("Email: test@example.com, SSN: 123-45-6789")
redacted = pii.redact("My phone is 555-123-4567")

# Injection Detection
injection = InjectionDetector(threshold=0.5)
findings = injection.detect("Ignore previous instructions")
risk_score = injection.get_risk_score(text)

# Bad Prompt Detection  
bad_prompt = BadPromptDetector(severity_threshold="medium")
findings = bad_prompt.detect("Harmful content here")
risk_level = bad_prompt.get_risk_level(text)
```

## 🖥️ CLI Usage

### Scan Text

```bash
# Basic scan
aipromptsentinel scan "My email is test@example.com"

# JSON output
aipromptsentinel scan "Hello world" --format json

# With PII redaction
aipromptsentinel scan "SSN: 123-45-6789" --redact

# Disable specific checks
aipromptsentinel scan "text" --no-pii --no-bad-prompt
```

### Scan Files

```bash
# Scan entire file
aipromptsentinel check-file prompts.txt

# Line-by-line analysis
aipromptsentinel check-file data.txt --line-by-line

# JSON output
aipromptsentinel check-file input.txt --format json
```

### Redact PII

```bash
aipromptsentinel redact "My email is test@example.com"
# Output: My email is [REDACTED]
```

## 🔍 Detection Categories

### PII Types

| Type | Example | Pattern |
|------|---------|---------|
| Email | `test@example.com` | Standard email format |
| SSN | `123-45-6789` | US Social Security Number |
| Credit Card | `4111111111111111` | Visa, MC, Amex, Discover |
| Phone | `(555) 123-4567` | US and international formats |
| IP Address | `192.168.1.1` | IPv4 and IPv6 |
| API Key | `sk-xxx...` | OpenAI, AWS, GitHub, etc. |
| Date of Birth | `01/15/1990` | Common date formats |
| Passport | `AB1234567` | Passport number patterns |
| IBAN | `DE89370400440532013000` | International bank numbers |

### Injection Types

| Type | Description |
|------|-------------|
| `instruction_override` | "Ignore previous instructions" |
| `role_confusion` | "You are now a pirate" |
| `jailbreak` | "Enable DAN mode", "bypass safety" |
| `context_manipulation` | `[SYSTEM]`, `
` tags |
| `data_extraction` | "Reveal your system prompt" |
| `delimiter_abuse` | Excessive separators, newlines |

### Bad Prompt Categories

| Category | Severity | Examples |
|----------|----------|----------|
| Violence | Critical | Weapons, harm |
| Illegal | High | Hacking, theft |
| Malware | Critical | Virus creation |
| Fraud | High | Scams, identity theft |
| Harassment | High | Doxxing, stalking |
| Self-Harm | Critical | Suicide, self-injury |
| Manipulation | High | Phishing, social engineering |
| Hate Speech | Medium | Discrimination |
| Adult Content | High | Explicit material |

## 🔧 Advanced Configuration

### Custom PII Patterns

```python
import re
from aipromptsentinel.detectors import PIIDetector

detector = PIIDetector(
    custom_patterns={
        "employee_id": re.compile(r"EMP-\d{6}")
    }
)
```

### Selective Detection

```python
from aipromptsentinel import Sentinel
from aipromptsentinel.detectors.pii import PIIType

# Only detect specific PII types
sentinel = Sentinel(
    pii_types=[PIIType.EMAIL, PIIType.CREDIT_CARD]
)
```

### Risk Analysis

```python
sentinel = Sentinel()
summary = sentinel.get_risk_summary(text)

print(summary)
# {
#     "overall_safe": False,
#     "pii_risk": {"found": True, "count": 2, "types": ["email", "ssn"]},
#     "injection_risk": {"found": True, "score": 0.85, "types": ["jailbreak"]},
#     "bad_prompt_risk": {"found": False, "level": "safe", "categories": []}
# }
```

## 🧪 Testing

```bash
# Install dev dependencies
uv sync --dev

# Run tests
uv run pytest tests/ -v

# With coverage
uv run pytest tests/ -v --cov=src/aipromptsentinel
```

## 📦 Building & Publishing

```bash
# Build the package
uv build

# Upload to PyPI
uv publish
```

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 📄 License

MIT License - see [LICENSE](LICENSE) for details.

---

**Made with ❤️ for safer LLM applications**