Metadata-Version: 2.4
Name: sentinelseed
Version: 1.1.0
Summary: AI safety guardrails using Sentinel alignment seeds. Add safety to any LLM with one line of code.
Project-URL: Homepage, https://sentinelseed.dev
Project-URL: Documentation, https://sentinelseed.dev/docs
Project-URL: Repository, https://github.com/sentinel-seed/sentinel
Project-URL: Issues, https://github.com/sentinel-seed/sentinel/issues
Author-email: Sentinel Team <team@sentinelseed.dev>
License: MIT
Keywords: agents,ai,alignment,anthropic,autogpt,claude,crewai,gpt,guardrails,jailbreak,langchain,langgraph,llm,openai,red-teaming,safety,sentinel,solana,system-prompt
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Security
Requires-Python: >=3.8
Provides-Extra: all
Requires-Dist: crewai>=0.1.0; extra == 'all'
Requires-Dist: langchain>=0.1.0; extra == 'all'
Requires-Dist: langgraph>=0.0.1; extra == 'all'
Provides-Extra: crewai
Requires-Dist: crewai>=0.1.0; extra == 'crewai'
Provides-Extra: langchain
Requires-Dist: langchain>=0.1.0; extra == 'langchain'
Provides-Extra: langgraph
Requires-Dist: langgraph>=0.0.1; extra == 'langgraph'
Description-Content-Type: text/markdown

# sentinelseed

Add AI safety to any LLM with one line of code.

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

## Installation

```bash
pip install sentinelseed
```

## Quick Start

```python
from sentinelseed import SentinelGuard

# Create a guard with default settings (v2/standard)
guard = SentinelGuard()

# Wrap your messages with the safety seed
messages = guard.wrap_messages([
    {"role": "user", "content": "Hello, how can you help me?"}
])

# Use with OpenAI
response = openai.chat.completions.create(
    model="gpt-4",
    messages=messages
)
```

## Features

- **Zero dependencies** - Works with any LLM provider
- **Type hints** - Full typing support
- **Multiple seed versions** - Choose the right balance of safety vs latency
- **THSP Protocol** - Four-gate validation (Truth, Harm, Scope, Purpose)
- **Heuristic analysis** - Basic safety checking without API calls

## Seed Versions

| Version | Variant | Tokens | Best For |
|---------|---------|--------|----------|
| v2 | minimal | ~350 | Chatbots, low latency |
| v2 | **standard** | ~1,000 | General use (recommended) |
| v1 | minimal | ~500 | Legacy support |

### v1 vs v2

- **v1 (THS)**: Three gates - Truth, Harm, Scope
- **v2 (THSP)**: Four gates - adds Purpose gate (requires actions to serve legitimate benefit)

## Usage Examples

### Basic Usage

```python
from sentinelseed import SentinelGuard, get_seed

# Option 1: Use the guard class
guard = SentinelGuard(version="v2", variant="standard")
messages = guard.wrap_messages([
    {"role": "user", "content": "Help me with something"}
])

# Option 2: Get seed directly
seed = get_seed("v2", "standard")
messages = [
    {"role": "system", "content": seed},
    {"role": "user", "content": "Help me with something"}
]
```

### With OpenAI

```python
from openai import OpenAI
from sentinelseed import SentinelGuard

client = OpenAI()
guard = SentinelGuard()

def chat(user_message: str):
    messages = guard.wrap_messages([
        {"role": "user", "content": user_message}
    ])

    return client.chat.completions.create(
        model="gpt-4",
        messages=messages
    )
```

### With Anthropic

```python
from anthropic import Anthropic
from sentinelseed import SentinelGuard

client = Anthropic()
guard = SentinelGuard()

def chat(user_message: str):
    seed = guard.get_seed()

    return client.messages.create(
        model="claude-3-opus-20240229",
        system=seed,
        messages=[{"role": "user", "content": user_message}]
    )
```

### Analyze Content

```python
guard = SentinelGuard()

# Check if content is safe
analysis = guard.analyze("How do I hack a computer?")
print(analysis)
# THSPAnalysis(
#     safe=False,
#     gates={"truth": "pass", "harm": "fail", "scope": "pass", "purpose": "unknown"},
#     issues=["Potential harm detected"],
#     confidence=0.85
# )

# Quick check
if not guard.is_safe(user_input):
    print("Potentially unsafe content detected")
```

### Custom Seed

```python
guard = SentinelGuard(custom_seed="Your custom system prompt here...")
```

## API Reference

### `SentinelGuard`

```python
class SentinelGuard:
    def __init__(
        self,
        version: str = "v2",      # "v1" or "v2"
        variant: str = "standard", # "minimal" or "standard"
        custom_seed: str = None    # Override with custom seed
    ): ...

    def get_seed(self) -> str: ...
    def get_metadata(self) -> dict: ...
    def wrap_messages(self, messages: list, append_to_existing: bool = False) -> list: ...
    def analyze(self, content: str) -> THSPAnalysis: ...
    def is_safe(self, content: str) -> bool: ...
```

### Helper Functions

```python
# Create a guard
guard = create_guard(version="v2", variant="standard")

# Get seed directly
seed = get_seed("v2", "standard")

# Access seeds dict
from sentinelseed import SEEDS
print(SEEDS["v2_standard"])
```

## Benchmark Results

Tested across 6+ models with 97%+ average safety rate:

| Benchmark | Safety Rate |
|-----------|-------------|
| HarmBench | 98.2% |
| JailbreakBench | 97.3% |
| GDS-12 | 92% |

## Links

- **Website**: [sentinelseed.dev](https://sentinelseed.dev)
- **Documentation**: [sentinelseed.dev/docs](https://sentinelseed.dev/docs)
- **GitHub**: [github.com/sentinel-seed](https://github.com/sentinel-seed)
- **npm Package**: [npmjs.com/package/sentinelseed](https://npmjs.com/package/sentinelseed)
- **HuggingFace**: [huggingface.co/sentinelseed](https://huggingface.co/sentinelseed)

## License

MIT License - Sentinel Team
