stinger-guardrails-alpha 0.1.0a5
AI Guardrails Framework - Comprehensive LLM safety toolkit (Alpha)
License: MIT
Requires Python: >=3.8
Keywords: ai, llm, guardrails, safety, security, content-moderation, prompt-injection, pii-detection

# 🚀 Stinger - AI Guardrails Framework

A powerful, easy-to-use Python framework for safeguarding LLM applications with comprehensive content filtering and moderation capabilities.

> **Alpha Release Available!** Install with `pip install stinger-guardrails-alpha`

## ✨ Features

- **🛡️ Comprehensive Guardrails**: Toxicity detection, PII protection, code generation prevention, and more
- **🔒 Security Audit Trail**: Complete logging of all security decisions for compliance and forensics
- **🎯 Simple API**: Get started in 3 lines of code
- **🌐 REST API**: Language-agnostic HTTP/REST interface for non-Python integration
- **⚡ High Performance**: Async-ready with synchronous convenience wrapper
- **🔧 Configurable**: YAML-based configuration with runtime updates
- **🧪 Production Ready**: Comprehensive testing and error handling
- **📚 Well Documented**: Complete API reference and examples

## 🚀 Quick Start

### Installation

```bash
# Install the alpha release
pip install stinger-guardrails-alpha

# Or install from source for development
pip install .
```

### Basic Usage

```python
from stinger import GuardrailPipeline
from stinger.core import audit

# Enable security audit trail (zero-config)
audit.enable()  # Tracks all security decisions

# Create a pipeline from preset
pipeline = GuardrailPipeline.from_preset("customer_service")

# Check input content
result = pipeline.check_input("My credit card is 4532-1234-5678-9012")
if result['blocked']:
    print(f"Input blocked: {result['reasons']}")
    # Audit trail automatically logs: user input, guardrail decision, reasons

# Check output content
result = pipeline.check_output("Here's the code: import os; os.system('rm -rf /')")
if result['blocked']:
    print(f"Output blocked: {result['reasons']}")
```

## 🤔 Python Library vs REST API

Choose the right approach for your use case:

| Feature | Python Library | REST API |
|---------|---------------|----------|
| **Setup** | `import stinger` | `stinger-api` server |
| **Performance** | ⚡ Fastest (no network) | 🚀 Fast (adds ~1-5ms) |
| **Language Support** | 🐍 Python only | 🌐 Any language |
| **Deployment** | 📦 Part of your app | 🖥️ Separate service |
| **Scaling** | 📈 Scale with your app | 🔄 Independent scaling |
| **Use When** | Building Python apps | Non-Python apps, microservices |

**Quick Decision**: Building a Python app? Use the library. Building anything else? Use the REST API.

## 🖥️ Command Line Interface (CLI)

After installing Stinger, you can use the CLI:

```sh
stinger demo
stinger check-prompt "My SSN is 123-45-6789."
stinger check-response "Here is your password: hunter2"
```

## 🌐 REST API Service

Stinger provides a REST API for language-agnostic integration, browser extensions, and microservices:

### Starting the API Server

```bash
# Install with API support
pip install stinger-guardrails-alpha[api]

# Start the server
stinger-api

# Or start in background
stinger-api --detached

# Custom port
stinger-api --port 8080
```

### API Endpoints

- `GET /health` - Service health check
- `POST /v1/check` - Check content against guardrails
- `GET /v1/rules` - Get active guardrail configuration

### Quick Example

```bash
# Check content via API
curl -X POST http://localhost:8888/v1/check \
  -H "Content-Type: application/json" \
  -d '{
    "text": "My SSN is 123-45-6789",
    "kind": "prompt",
    "preset": "customer_service"
  }'

# Response
{
  "action": "block",
  "reasons": ["pii_check: PII detected (regex): ssn"],
  "warnings": [],
  "metadata": {"processing_time_ms": 12}
}
```

### Use Cases

- 🌐 **Browser Extensions**: CORS-enabled for Chrome/Firefox extensions
- 🔗 **Microservices**: Language-agnostic guardrail service
- 📱 **Mobile Apps**: REST API for iOS/Android integration
- 🚀 **Non-Python Apps**: Use Stinger from any language

See [REST API example](./examples/getting_started/12_rest_api_usage.py) for detailed usage.

## 🌟 Interactive Demos

### Web Demo - Real-Time Guardrail Visualization

Experience Stinger's power through our interactive web interface that shows guardrails in action:

```bash
# Start the web demo (simplest method)
cd demos/web_demo
python start_demo.py

# Or run in background mode (useful for tools with timeouts)
python start_demo.py --detached

# Open http://127.0.0.1:8000 in your browser (use HTTP, not HTTPS)
```

**Features:**
- 💬 Interactive chat interface with real-time guardrail feedback
- 🚦 Visual indicators showing which guardrails triggered
- 📊 Live audit trail visualization
- 🔄 Switch between presets (customer service, medical, financial)
- ⚡ See guardrails activate as you type

### Management Console - System Monitoring Dashboard

Monitor your Stinger deployment with our real-time management console:

```bash
# Start the management console (simplest method)
cd management-console
./start_console.sh

# Or run in background mode (useful for tools with timeouts)
./start_console.sh --detached

# Open http://localhost:3001 in your browser
```

**Features:**
- 📈 Real-time metrics and performance monitoring
- 🔍 Active conversation tracking
- 📊 Guardrail trigger statistics
- 🏥 System health monitoring
- 📉 Historical data visualization

## 🛡️ Available Guardrails

Stinger offers multiple levels of protection with both fast regex-based and sophisticated AI-powered guardrails:

### 🚀 Simple/Fast Guardrails (No API Key Required)
- **Simple PII Detection**: Regex-based detection of SSNs, credit cards, emails, phone numbers
- **Simple Toxicity Detection**: Keyword-based profanity and hate speech filtering  
- **Simple Code Generation**: Pattern-based code snippet detection
- **Keyword Blocking**: Block specific words or phrases
- **URL Filtering**: Block or allow specific domains
- **Length Limiting**: Control input/output length
- **Regex Filtering**: Custom pattern matching

### 🤖 AI-Powered Guardrails (Requires OpenAI API Key)
- **AI PII Detection**: Context-aware PII detection using language models
- **AI Toxicity Detection**: Nuanced understanding of harmful content
- **AI Code Generation**: Sophisticated code pattern recognition
- **Content Moderation**: General inappropriate content detection
- **Topic Filtering**: AI-based allowed/blocked topic enforcement

### 🔐 Prompt Injection Protection (Three Levels)
1. **Quick/Local Detection**: Fast pattern matching for common injection attempts
2. **AI-Powered Detection**: Single-turn analysis using language models
3. **Conversation-Aware AI**: Multi-turn context analysis for sophisticated attacks
   - Configurable strategies: 'recent', 'suspicious', or 'mixed' context
   - Risk levels: low, medium, high, critical

### 🎯 Usage Examples
```python
# Use simple guardrails for speed (no API key needed)
pipeline = GuardrailPipeline.from_preset("customer_service")  # Uses simple versions

# Enable AI guardrails for better accuracy (requires API key)
export OPENAI_API_KEY="sk-..."
pipeline = GuardrailPipeline.from_preset("medical")  # Uses AI versions

# Mix and match as needed
config = {
    "input": [
        {"type": "simple_pii_detection"},     # Fast PII check
        {"type": "ai_toxicity_detection"},    # AI toxicity check
        {"type": "prompt_injection",          # Multi-turn injection detection
         "config": {"conversation_aware": True}}
    ]
}
```

## 🔒 Security Audit Trail

Stinger provides comprehensive security audit logging for compliance and forensic analysis:

### Zero-Config Audit Trail
```python
from stinger.core import audit

# Enable with smart defaults (just works!)
audit.enable()

# Or specify destination
audit.enable("./logs/security.log")

# With PII redaction for compliance
audit.enable("./logs/audit.log", redact_pii=True)
```

### Complete Security Tracking
- **User Prompts**: All user inputs logged with attribution
- **LLM Responses**: All AI responses tracked with context
- **Guardrail Decisions**: Every security decision with full reasoning
- **Conversation Flow**: Complete conversation reconstruction
- **User Attribution**: IP, session, user ID tracking for forensics

### Compliance-Standard Ready
- **PII Redaction Capabilities**: Automatically redact sensitive data while preserving audit value (useful for GDPR, HIPAA, and other privacy regulations)
- **Complete Audit Trail**: Comprehensive logging suitable for enterprise security reviews
- **Data Retention Controls**: Configurable retention policies for different data types
- **Forensic Analysis**: Full incident reconstruction capabilities
- **Export Formats**: Generate compliance-ready reports in standard formats

### Audit Trail Features
- **Smart Environment Detection**: Auto-configures for dev/prod/docker
- **Async Buffering**: Background processing with <10ms latency impact
- **Query Tools**: Easy audit trail searching and analysis
- **Export Capabilities**: CSV/JSON export for compliance reporting
- **Cannot be disabled in production**: Ensures audit trail integrity

## 📋 Configuration

Stinger uses YAML configuration files:

```yaml
version: "1.0"

pipeline:
  input:
    - name: toxicity_check
      type: simple_toxicity_detection
      enabled: true
      confidence_threshold: 0.7
      categories: [hate_speech, harassment, threats]
    
    - name: pii_check
      type: simple_pii_detection
      enabled: true
      confidence_threshold: 0.8
      categories: [credit_card, ssn, email]
  
  output:
    - name: code_generation_check
      type: simple_code_generation
      enabled: true
      confidence_threshold: 0.6
      categories: [programming_keywords, code_blocks]
```

## 🎯 API Reference

### GuardrailPipeline

The main class for using Stinger guardrails.

```python
# Initialize
pipeline = GuardrailPipeline("config.yaml")

# Check content
result = pipeline.check_input(content)
result = pipeline.check_output(content)

# Get status
status = pipeline.get_guardrail_status()

# Dynamic configuration
pipeline.enable_guardrail("toxicity_check")
pipeline.disable_guardrail("pii_check")
pipeline.update_guardrail_config("toxicity_check", {"confidence_threshold": 0.9})
```

### Result Format

```python
{
    'blocked': bool,           # Whether content was blocked
    'warnings': List[str],     # List of warning messages
    'reasons': List[str],      # List of blocking reasons
    'details': Dict[str, Any], # Detailed results from each guardrail
    'pipeline_type': str       # Type of pipeline ("input" or "output")
}
```

### Audit Trail API

```python
from stinger.core import audit

# Enable audit trail
audit.enable("./logs/audit.log")

# Query audit trail
records = audit.query(
    conversation_id="conv_123",
    user_id="user_456",
    last_hour=True
)

# Export for compliance
audit.export_csv("./logs/audit.log", "compliance_report.csv")

# Get performance stats
stats = audit.get_stats()
print(f"Queued: {stats['queued']}, Written: {stats['written']}")
```

## 📖 Examples

### Basic Usage
```python
from stinger import GuardrailPipeline

pipeline = GuardrailPipeline("config.yaml")

# Simple content checking
result = pipeline.check_input("User input here")
if result['blocked']:
    print(f"Blocked: {result['reasons']}")
elif result['warnings']:
    print(f"Warnings: {result['warnings']}")
else:
    print("Content approved")
```

### Advanced Usage
```python
from stinger import GuardrailPipeline, audit

# Enable security audit trail
audit.enable("./logs/audit.log", redact_pii=True)

# Initialize with custom config
pipeline = GuardrailPipeline("my_config.yaml")

# Get pipeline status
status = pipeline.get_guardrail_status()
print(f"Pipeline has {status['total_enabled']} enabled guardrails")

# Dynamically configure guardrails
pipeline.disable_guardrail("pii_check")
pipeline.enable_guardrail("toxicity_check")

# Update configuration
pipeline.update_guardrail_config("toxicity_check", {
    'confidence_threshold': 0.9
})

# Process content with detailed results
result = pipeline.check_input("Test content")
print(f"Blocked: {result['blocked']}")
print(f"Reasons: {result['reasons']}")
print(f"Warnings: {result['warnings']}")
print(f"Details: {result['details']}")

# All security decisions automatically logged to audit trail
```

## 🧪 Testing

Run the demo to see Stinger in action:

```bash
# Run the tech support demo
cd demos/tech_support
python3 demo.py

# Run the simple example
python3 examples/getting_started/01_basic_installation.py
```

## 📚 Learning Resources

### Examples (`/examples`)
**Start here** - Minimal, focused code examples that mirror the Getting Started guide:
- `01_basic_installation.py` - Installation and basic setup
- `02_simple_guardrail.py` - Simple guardrail usage
- `03_global_rate_limiting.py` - Rate limiting configuration
- `04_conversation_api.py` - Conversation-based filtering
- `05_conversation_rate_limiting.py` - Conversation rate limiting
- `06_health_monitoring.py` - Health monitoring and status
- `07_cli_and_yaml_config.py` - CLI and YAML configuration
- `08_security_audit_trail.py` - Security audit trail setup and usage
- `09_troubleshooting_and_testing.py` - Testing and debugging

**Run examples:**
```bash
cd examples/getting_started
python 01_basic_installation.py
```

### Demos (`/demos`)
Advanced demonstrations showcasing specific features and scenarios:
- `conversation_aware_prompt_injection_demo.py` - Advanced prompt injection detection
- `global_rate_limiting_demo.py` - Rate limiting demonstrations
- `topic_filter_demo.py` - Topic-based filtering
- `tech_support/` - Complete tech support scenario with audit trail

**Run demos:**
```bash
cd demos
python conversation_aware_prompt_injection_demo.py
```

### Learning Path
1. **Start with examples** - Run through the numbered examples in order
2. **Explore demos** - Try the advanced demonstrations
3. **Check the tech support scenario** - See a complete real-world implementation
4. **Review API docs** - Deep dive into the complete API reference

## 🔧 Development

> **Note:** Stinger uses a modern `src/` layout. All package code is under `src/stinger/`.

### Installation from Source

```bash
git clone https://github.com/virtualsteve-star/stinger.git
cd stinger
pip install -e .
```

### Running Tests

```bash
pytest tests/
```

### Project Structure

```
src/
  └── stinger/
      ├── core/           # Core components and high-level API
      ├── guardrails/     # Guardrail implementations
      ├── data/           # Keyword lists and data files
      ├── scenarios/      # Pre-configured scenarios
      ├── utils/          # Utilities and exceptions
      ├── adapters/       # Model adapters
      ├── cli.py          # CLI entry point
      └── ...
```

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🆘 Support

- 📖 [Documentation](docs/)
- 🐛 [Issues](https://github.com/virtualsteve-star/stinger/issues)

---

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