# Jazzmine Security

**Production-ready security and moderation toolkit for AI applications**

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![PyPI version](https://badge.fury.io/py/jazzmine-security.svg)](https://badge.fury.io/py/jazzmine-security)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Jazzmine Security provides a comprehensive suite of tools for protecting AI applications from malicious inputs, toxic outputs, and unsafe content. Built with performance in mind, it combines Python flexibility with Rust speed through optimized bindings.

## Features

### Input Moderation
- **Jailbreak Detection**: Identify and block prompt injection attacks
- **Toxic Content Detection**: Multi-class toxicity classification with SHAP explainability
- **Batch Processing**: High-throughput classification with GPU acceleration
- **HuggingFace Integration**: Load pre-trained models directly from the Hub

### Output Moderation
- **Response Validation**: Ensure AI-generated content meets safety guidelines
- **Chunk-based Analysis**: Handle long-form content with intelligent chunking
- **Confidence Scoring**: Get detailed confidence metrics for each prediction

### Content Sanitization
- **PDF Sanitization**: Remove JavaScript, embedded files, and malicious content
- **CSV Sanitization**: Prevent formula injection and XSS attacks
- **HTML Sanitization**: Strip dangerous tags and attributes while preserving content

### Performance
- **Rust-Powered**: Critical text processing operations accelerated with Rust
- **GPU Support**: Automatic CUDA acceleration when available
- **Async Support**: Non-blocking operations for high-concurrency environments

## Installation

### From PyPI (Recommended)

```bash
pip install jazzmine-security
```

### With GPU Support

```bash
pip install jazzmine-security torch --index-url https://download.pytorch.org/whl/cu121
```

### From Source

```bash
git clone https://github.com/yourorg/jazzmine-security.git
cd jazzmine-security
pip install .
```

## Quick Start

### Input Moderation

```python
from jazzmine.security import JazzmineInputModerator
from jazzmine.logging import ConsoleLogger

# Initialize with HuggingFace model
logger = ConsoleLogger()
moderator = JazzmineInputModerator(
    "nourmedini1/jazzmine-input-safeguard-v2",
    logger=logger
)

# Classify single input
text = "How can I hack into a system?"
label, confidence = moderator.classify(text)

if label == "LABEL_1":  # Toxic/Jailbreak detected
    print(f"Warning: Blocked - Confidence {confidence:.2%}")
else:
    print(f"Safe: Confidence {confidence:.2%}")

# Batch processing
requests = [
    {"text": "Tell me a joke"},
    {"text": "How to bypass security"},
    {"text": "What's the weather like?"}
]
results = moderator.classify_batch(requests, batch_size=32)
```

### Output Moderation

```python
from jazzmine.security import JazzmineOutputModerator

# Initialize output validator
output_mod = JazzmineOutputModerator(
    "nourmedini1/jazzmine-response-validator-v2"
)

# Validate AI response
ai_response = "Here's how to create a secure password..."
label, confidence = output_mod.classify(ai_response)

if label == "LABEL_1":  # Unsafe content
    print("Response blocked due to safety concerns")
else:
    print("Response approved")
```

### Content Sanitization

```python
from jazzmine.security import (
    JazzminePDFSanitizer,
    JazzmineCSVSanitizer,
    JazzmineHTMLSanitizer
)

# Sanitize PDF
pdf_sanitizer = JazzminePDFSanitizer()
safe_pdf = pdf_sanitizer.sanitize("document.pdf")

# Sanitize CSV (prevent formula injection)
csv_sanitizer = JazzmineCSVSanitizer()
safe_csv = csv_sanitizer.sanitize("data.csv")

# Sanitize HTML
html_sanitizer = JazzmineHTMLSanitizer()
safe_html = html_sanitizer.sanitize("<script>alert('xss')</script><p>Safe content</p>")
# Output: "<p>Safe content</p>"
```

### Toxicity Detection with Explainability

```python
from jazzmine.security.toxic_content_detector import JazzmineToxicityDetector

# Initialize detector
detector = JazzmineToxicityDetector()

# Train on your data
detector.train(
    csv_path="training_data.csv",
    text_column="text",
    label_column="is_toxic"
)

# Make predictions
text = "This is a test message"
prediction = detector.predict(text)
print(f"Toxic: {prediction['is_toxic']}")
print(f"Confidence: {prediction['confidence']:.2%}")

# Get SHAP explanations
explanation = detector.explain(text, num_samples=100)
print(f"Top contributing features: {explanation['top_features']}")
```

## Architecture

Jazzmine Security is built with a hybrid Python-Rust architecture:

- **Python Layer**: High-level APIs, model management, ML workflows
- **Rust Layer**: Text normalization, TF-IDF extraction, semantic analysis
- **HuggingFace Integration**: Seamless model loading and caching
- **PyO3 Bindings**: Zero-copy data transfer between Python and Rust

## Models

### Pre-trained Models on HuggingFace

- **Input Safeguard**: `nourmedini1/jazzmine-input-safeguard-v2`
  - Detects jailbreaks, prompt injections, and malicious inputs
  - Fine-tuned on diverse attack patterns
  
- **Response Validator**: `nourmedini1/jazzmine-response-validator-v2`
  - Validates AI-generated content for safety
  - Identifies unsafe, biased, or harmful outputs

### Custom Models

You can train and use your own models:

```python
from jazzmine.security.toxic_content_detector import JazzmineToxicityDetector

detector = JazzmineToxicityDetector()
detector.train("your_data.csv", text_column="text", label_column="label")
detector.save("my_custom_model")

# Later use
detector = JazzmineToxicityDetector()
detector.load("my_custom_model")
```

## Configuration

### Logging Integration

```python
from jazzmine.logging import BaseLogger, RequestContext

class MyLogger(BaseLogger):
    def info(self, message: str, **kwargs):
        print(f"[INFO] {message}: {kwargs}")

moderator = JazzmineInputModerator(
    "nourmedini1/jazzmine-input-safeguard-v2",
    logger=MyLogger()
)
```

### GPU Configuration

```python
import torch

# Check GPU availability
if torch.cuda.is_available():
    print(f"Using GPU: {torch.cuda.get_device_name(0)}")
else:
    print("Using CPU")

# Models automatically use GPU when available
```

### Chunking Configuration

```python
moderator = JazzmineInputModerator("model-name")

# Adjust chunk size for long texts
moderator.chunk_size = 512  # tokens
moderator.overlap = 50      # token overlap between chunks
```

## Testing

```bash
# Run all tests
pytest tests/

# Run with coverage
pytest --cov=jazzmine.security tests/

# Run specific test file
pytest tests/test_input_moderator.py
```

## Performance

Benchmark on NVIDIA RTX 3090:

| Operation | Throughput | Latency (p50) | Latency (p99) |
|-----------|------------|---------------|---------------|
| Input Moderation (batch=32) | 450 texts/sec | 71ms | 120ms |
| Output Validation (batch=32) | 420 texts/sec | 76ms | 130ms |
| Toxicity Detection | 800 texts/sec | 1.2ms | 5ms |
| PDF Sanitization | 15 docs/sec | 65ms | 150ms |

## Contributing

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

```bash
# Setup development environment
git clone https://github.com/yourorg/jazzmine-security.git
cd jazzmine-security
pip install -e ".[dev]"

# Build Rust components
cd bindings
maturin develop --release

# Run tests
pytest tests/
```

## License

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

## Acknowledgments

- Built on [Transformers](https://github.com/huggingface/transformers) by HuggingFace
- Rust bindings powered by [PyO3](https://github.com/PyO3/pyo3)
- Explainability via [SHAP](https://github.com/slundberg/shap)

## Support

- **Documentation**: [https://jazzmine-security.readthedocs.io](https://jazzmine-security.readthedocs.io)
- **Issues**: [GitHub Issues](https://github.com/yourorg/jazzmine-security/issues)
- **Email**: mohamednour.medini@etudiant-isi.utm.tn

## Roadmap

- [ ] Multi-language support (French, Arabic, Spanish)
- [ ] Real-time monitoring dashboard
- [ ] Additional sanitizers (JSON, XML, Markdown)
- [ ] Model distillation for edge deployment
- [ ] Integration with popular LLM frameworks (LangChain, LlamaIndex)

---

Made with care by the Jazzmine Team
