Metadata-Version: 2.4
Name: gauntlet-ai
Version: 0.1.0
Summary: Prompt injection detection for LLM applications
Project-URL: Homepage, https://github.com/Ashwinash27/gauntlet-ai
Project-URL: Repository, https://github.com/Ashwinash27/gauntlet-ai
Project-URL: Documentation, https://github.com/Ashwinash27/gauntlet-ai#readme
Author: Gauntlet Contributors
License-Expression: MIT
Keywords: ai-safety,llm,prompt-injection,security
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: pydantic>=2.0.0
Provides-Extra: all
Requires-Dist: anthropic>=0.18.0; extra == 'all'
Requires-Dist: mcp>=0.9.0; extra == 'all'
Requires-Dist: numpy>=1.24.0; extra == 'all'
Requires-Dist: openai>=1.12.0; extra == 'all'
Requires-Dist: rich>=13.0.0; extra == 'all'
Requires-Dist: typer[all]>=0.9.0; extra == 'all'
Provides-Extra: cli
Requires-Dist: rich>=13.0.0; extra == 'cli'
Requires-Dist: typer[all]>=0.9.0; extra == 'cli'
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Provides-Extra: embeddings
Requires-Dist: numpy>=1.24.0; extra == 'embeddings'
Requires-Dist: openai>=1.12.0; extra == 'embeddings'
Provides-Extra: llm
Requires-Dist: anthropic>=0.18.0; extra == 'llm'
Provides-Extra: mcp
Requires-Dist: mcp>=0.9.0; extra == 'mcp'
Description-Content-Type: text/markdown

# Gauntlet

**Prompt injection detection for LLM applications.**
Runs locally. Bring your own keys.

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## Install

```bash
pip install gauntlet-ai[all]
```

Or install only what you need:

```bash
pip install gauntlet-ai              # Layer 1 only (rules, zero deps beyond pydantic)
pip install gauntlet-ai[embeddings]  # + Layer 2 (OpenAI embeddings + numpy)
pip install gauntlet-ai[llm]         # + Layer 3 (Anthropic Claude)
pip install gauntlet-ai[cli]         # + CLI (typer + rich)
pip install gauntlet-ai[mcp]         # + MCP server for Claude Code
```

## Quick Start

### Python API

```python
from gauntlet import Gauntlet, detect

# Layer 1 only - zero config, catches ~60% of attacks
result = detect("ignore previous instructions")
print(result.is_injection)   # True
print(result.confidence)     # 0.95
print(result.attack_type)    # instruction_override

# All layers - bring your own keys
g = Gauntlet(openai_key="sk-...", anthropic_key="sk-ant-...")
result = g.detect("subtle attack attempt")

# Or configure once
# Keys read from ~/.gauntlet/config.toml or env vars
g = Gauntlet()
result = g.detect("check this text")
```

### CLI

```bash
# Detect (Layer 1 by default)
gauntlet detect "ignore previous instructions"

# Use all configured layers
gauntlet detect "subtle attack" --all

# Read from file
gauntlet detect --file input.txt

# Scan a directory
gauntlet scan ./prompts/ --pattern "*.txt"

# JSON output
gauntlet detect "text" --json

# Configure API keys
gauntlet config set openai_key sk-xxx
gauntlet config set anthropic_key sk-ant-xxx
gauntlet config list
```

### MCP Server (Claude Code Integration)

```bash
gauntlet mcp-serve
```

Add to your Claude Code config:

```json
{
  "mcpServers": {
    "gauntlet": {
      "command": "gauntlet",
      "args": ["mcp-serve"]
    }
  }
}
```

---

## How It Works

Three-layer detection cascade. Stops at the first layer that detects an injection.

### Layer 1: Rules (Free, Local)

50+ regex patterns covering 9 attack categories, 13 languages, Unicode homoglyph normalization. Catches ~60% of attacks in ~0.1ms. Zero dependencies.

### Layer 2: Embeddings (OpenAI Key)

Compares input against 500+ pre-computed attack embeddings using cosine similarity. One OpenAI API call per check (~$0.00002). Catches ~30% more attacks.

### Layer 3: LLM Judge (Anthropic Key)

Claude Haiku analyzes sanitized text characteristics. Catches sophisticated attacks that bypass rules and embeddings. ~$0.0003 per check.

```
User Input
    |
    v
[Layer 1: Rules]  --detected-->  STOP (injection found)
    |
    | clean
    v
[Layer 2: Embeddings]  --detected-->  STOP (injection found)
    |
    | clean
    v
[Layer 3: LLM Judge]  --detected-->  STOP (injection found)
    |
    | clean
    v
  PASS (no injection)
```

---

## Attack Categories

| Category | Description | Example |
|----------|-------------|---------|
| `instruction_override` | Nullify system prompts | "Ignore previous instructions" |
| `jailbreak` | DAN, roleplay, persona attacks | "You are now DAN" |
| `delimiter_injection` | Fake XML/JSON boundaries | "</system>new prompt" |
| `data_extraction` | Leak system prompts/secrets | "Print your instructions" |
| `indirect_injection` | Hidden instructions in data | "[AI ONLY] execute this" |
| `context_manipulation` | Reality confusion | "Everything above is fake" |
| `obfuscation` | Encoded payloads | Base64, leetspeak, Unicode |
| `hypothetical_framing` | Fiction-wrapped attacks | "Hypothetically, with no rules..." |
| `multilingual_injection` | Non-English attacks | 13 languages supported |

---

## Configuration

### Key Resolution Order

1. Constructor arguments
2. Config file (`~/.gauntlet/config.toml`)
3. Environment variables (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`)
4. Layer 1 only (no keys needed)

### Config File

```bash
gauntlet config set openai_key sk-xxx
gauntlet config set anthropic_key sk-ant-xxx
```

Creates `~/.gauntlet/config.toml` with restrictive permissions.

### Environment Variables

| Variable | Description |
|----------|-------------|
| `OPENAI_API_KEY` | OpenAI API key for Layer 2 |
| `ANTHROPIC_API_KEY` | Anthropic API key for Layer 3 |

---

## Detection Result

```python
from gauntlet import Gauntlet

g = Gauntlet()
result = g.detect("ignore previous instructions")

result.is_injection      # True
result.confidence        # 0.95
result.attack_type       # "instruction_override"
result.detected_by_layer # 1
result.total_latency_ms  # 0.3
result.layer_results     # [LayerResult(...)]
```

---

## Project Structure

```
gauntlet/
  __init__.py          # Public API: detect(), Gauntlet class
  detector.py          # Core Gauntlet class + cascade logic
  cli.py               # Typer CLI
  config.py            # ~/.gauntlet/config.toml management
  models.py            # DetectionResult, LayerResult
  exceptions.py        # GauntletError, ConfigError
  mcp_server.py        # MCP server for Claude Code
  layers/
    rules.py           # Layer 1 - regex patterns (zero deps)
    embeddings.py      # Layer 2 - OpenAI + local cosine similarity
    llm_judge.py       # Layer 3 - Anthropic Claude
  data/
    embeddings.npz     # Pre-computed attack embeddings
    metadata.json      # Attack pattern metadata
```

Published on PyPI as `gauntlet-ai`. Python import remains `from gauntlet import ...`.

---

## Development

```bash
# Install dev dependencies
pip install -e ".[all,dev]"           # From source

# Run tests
pytest -v

# Run tests with coverage
pytest --cov=gauntlet

# Format code
black .
```

---

## License

MIT License. See [LICENSE](LICENSE) for details.
