Metadata-Version: 2.1
Name: sentinel-guardrails-sdk
Version: 4.0.1
Summary: SENTINEL — Drop-in LLM Trust & Safety SDK. 19-agent parallel mesh: prompt injection, PII, jailbreak pattern detection, DAN attacks, cost anomaly detection, agentic loop breaking, hallucination, and compliance routing.
Author: SENTINEL Labs
License: MIT
Project-URL: Homepage, https://github.com/sentinel-ai/sentinel-sdk
Project-URL: Documentation, https://docs.sentinel-ai.dev
Project-URL: Repository, https://github.com/sentinel-ai/sentinel-sdk
Project-URL: Issues, https://github.com/sentinel-ai/sentinel-sdk/issues
Project-URL: Changelog, https://github.com/sentinel-ai/sentinel-sdk/blob/main/CHANGELOG.md
Keywords: llm,safety,trust,prompt-injection,pii,toxicity,jailbreak,hallucination,guardrails,ai-safety,security,enterprise,compliance,gdpr,hipaa,dpdp,agentic,dan-attack,jailbreak-detection,cost-anomaly,loop-detection,locale-compliance
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Security
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.7.0
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
Provides-Extra: llamaindex
Requires-Dist: llama-index-core>=0.10.0; extra == "llamaindex"
Provides-Extra: server
Requires-Dist: fastapi>=0.111.0; extra == "server"
Requires-Dist: uvicorn[standard]>=0.29.0; extra == "server"
Requires-Dist: pydantic-settings>=2.2.0; extra == "server"
Requires-Dist: python-dotenv>=1.0.1; extra == "server"
Requires-Dist: sqlalchemy>=2.0.30; extra == "server"
Requires-Dist: asyncpg>=0.29.0; extra == "server"
Requires-Dist: alembic>=1.13.1; extra == "server"
Requires-Dist: redis>=5.0.4; extra == "server"
Requires-Dist: python-jose[cryptography]>=3.3.0; extra == "server"
Requires-Dist: passlib[bcrypt]>=1.7.4; extra == "server"
Requires-Dist: python-multipart>=0.0.9; extra == "server"
Requires-Dist: orjson>=3.10.3; extra == "server"
Requires-Dist: websockets>=12.0; extra == "server"
Requires-Dist: prometheus-client>=0.20.0; extra == "server"
Provides-Extra: supabase
Requires-Dist: supabase>=2.4.0; extra == "supabase"
Requires-Dist: pydantic-settings>=2.2.0; extra == "supabase"
Requires-Dist: python-dotenv>=1.0.1; extra == "supabase"
Provides-Extra: ml
Requires-Dist: sentence-transformers>=2.7.0; extra == "ml"
Requires-Dist: faiss-cpu>=1.8.0; extra == "ml"
Requires-Dist: spacy>=3.7.4; extra == "ml"
Requires-Dist: transformers>=4.40.0; extra == "ml"
Requires-Dist: torch>=2.2.0; extra == "ml"
Requires-Dist: detoxify>=0.5.2; extra == "ml"
Requires-Dist: numpy>=1.26.4; extra == "ml"
Provides-Extra: kafka
Requires-Dist: aiokafka>=0.10.0; extra == "kafka"
Provides-Extra: full
Requires-Dist: sentinel-guardrails-sdk[kafka,langchain,llamaindex,ml,server]; extra == "full"
Requires-Dist: stripe>=9.5.0; extra == "full"
Provides-Extra: dev
Requires-Dist: pytest>=8.2.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.6; extra == "dev"
Requires-Dist: httpx>=0.27.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: mypy>=1.10.0; extra == "dev"

# SENTINEL — LLM Trust & Safety Infrastructure Layer

> Production-grade security middleware for enterprise AI deployments.
> Drop-in SDK · 19-agent parallel mesh · <72ms P99 · HIPAA/GDPR/SOC2/DPDP

[![PyPI version](https://img.shields.io/pypi/v/sentinel-guardrails-sdk.svg)](https://pypi.org/project/sentinel-guardrails-sdk/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

---

## Quick Start (3 lines)

```python
import openai, sentinel

client = sentinel.wrap(
    openai.OpenAI(api_key="sk-..."),
    tenant_id="my-org",
    api_key="sk-sentinel-...",
)

# All existing code works unchanged:
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Help me with this contract."}],
)
```

## Architecture

```
SDK (wrap) → FastAPI Gateway → 19-Agent Parallel Mesh → Risk Aggregator → Circuit Breaker → LLM API
                     ↓                    ↓                      ↓
               Postgres            Redis             FAISS Index         Kafka
            (audit trail)     (policy cache)     (attack vectors)   (event stream)
```

### The 19-Agent Mesh

#### v1 Core (7 agents)
| # | Agent | Technique | What it catches |
|---|-------|-----------|----------------|
| 1 | **InjectionScout** | FAISS ANN + regex | Prompt injection, delimiter attacks |
| 2 | **PIISentinel** | SpaCy NER + regex | PHI/PII leakage (HIPAA, GDPR, DPDP) |
| 3 | **JailbreakGuard** | Sliding window | Multi-turn escalation, persona attacks |
| 4 | **ToxicityScreener** | HF Detoxify | Toxicity, threats, hate speech |
| 5 | **HallucinationProbe** | DeBERTa NLI | Ungrounded factual claims in RAG |
| 6 | **ContextAnchor** | Cosine similarity | Semantic context drift |
| 7 | **ComplianceTagger** | Rule-based | HIPAA/GDPR/SOC2/PCI-DSS/DPDP tagging |

#### v2 Enterprise (5 agents)
| # | Agent | Technique | What it catches |
|---|-------|-----------|----------------|
| 8 | **ResponseSafetyLayer** | Pattern scan | Harmful LLM output, data leakage |
| 9 | **MultilingualGuard** | Multilingual embeddings | Cross-language jailbreaks |
| 10 | **ToolCallSafety** | Schema validation | Dangerous function calls |
| 11 | **BrandGuard** | Sentiment + patterns | Unauthorized promises, brand damage |
| 12 | **TokenAnomalyDetector** | Statistical analysis | Encoding attacks, token smuggling |

#### v3 Advanced (3 agents)
| # | Agent | Technique | What it catches |
|---|-------|-----------|----------------|
| 13 | **PromptLineage** | Session memory graph | Multi-turn escalation trajectories |
| 14 | **IntentClassifier** | DeBERTa zero-shot | Malicious intent classification |
| 15 | **AdversarialRephrasing** | Heuristic perturbation | Evasion via paraphrasing |

#### v4 Production (4 agents)
| # | Agent | Technique | What it catches |
|---|-------|-----------|----------------|
| 16 | **JailbreakPatternDetector** | DAN/roleplay patterns | DAN attacks, character bypass, social engineering |
| 17 | **LocaleComplianceRouter** | Locale-aware rules | Language-specific regulatory routing (DPDP, GDPR) |
| 18 | **CostAnomalyDetector** | Spend-rate analysis | Runaway token costs, inference bombs |
| 19 | **AgenticLoopBreaker** | Loop detection | Infinite tool-call loops in agentic frameworks |

### ML Models Used

| Component | Model | Size | Purpose |
|-----------|-------|------|---------|
| ML Risk Scorer | `ProtectAI/deberta-v3-base-prompt-injection-v2` | ~180MB | Primary injection detection |
| Intent Classifier | `MoritzLaurer/deberta-v3-base-zeroshot-v2.0` | ~440MB | Zero-shot intent classification |
| Hallucination Probe | `cross-encoder/nli-deberta-v3-small` | ~170MB | NLI grounding verification |
| Embedding | `sentence-transformers/all-MiniLM-L6-v2` | ~80MB | FAISS + cosine similarity |
| Toxicity | `detoxify/original` | ~450MB | Multi-dimension toxicity scoring |
| PII | `en_core_web_sm` (SpaCy) | ~12MB | Named entity recognition |

## Install

```bash
# SDK only (lightweight, for client-side integration)
pip install sentinel-guardrails-sdk

# Full gateway server with ML agents
pip install sentinel-guardrails-sdk[full]

# Server without ML (uses heuristic fallbacks)
pip install sentinel-guardrails-sdk[server]
```

## Free vs Pro Tiers

| Feature | Free | Pro (₹4,500/mo) |
|---------|------|-----------------|
| `screen()` — threat detection | ✅ | ✅ |
| `trust_score()` — risk scoring | ✅ | ✅ |
| `wrap()` — OpenAI/Claude proxy | ✅ | ✅ |
| All 19 agents | ✅ | ✅ |
| `analytics()` — dashboard data | ❌ | ✅ |
| `compliance_export()` — audit CSV/PDF | ❌ | ✅ |
| `configure_agents()` — live tuning | ❌ | ✅ |
| `audit_log()` — full event log | ❌ | ✅ |

## Multi-Language Integration

Sentinel's gateway exposes a standard REST API, making it accessible from any language:

### Node.js / TypeScript
```javascript
const response = await fetch('https://gateway.sentinel-ai.dev/v1/screen', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sntnl-your-key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    messages: [{ role: 'user', content: 'Check this prompt' }],
    tenant_id: 'my-org',
  }),
});
const result = await response.json();
```

### Java
```java
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://gateway.sentinel-ai.dev/v1/screen"))
    .header("Authorization", "Bearer sntnl-your-key")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
```

### React (Frontend)
```jsx
const screenPrompt = async (userMessage) => {
  const res = await fetch('/api/sentinel/screen', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ messages: [{ role: 'user', content: userMessage }] }),
  });
  return res.json();
};
```

## Deploy with Docker

```bash
# Full stack (Postgres + Redis + Kafka + Gateway + Dashboard)
cp .env.example .env        # set SECRET_KEY and OPENAI_API_KEY
docker compose up --build -d
curl http://localhost:8000/health

# Lightweight dev (just Postgres + Redis)
docker compose -f docker-compose.dev.yml up -d
python -m uvicorn sentinel.gateway.main:app --reload
```

## Run Locally (Development)

```bash
# 1. Start database + cache
docker compose -f docker-compose.dev.yml up -d

# 2. Install dependencies
pip install -e ".[full,dev]"
python -m spacy download en_core_web_sm

# 3. Start gateway
cp .env.example .env
python -m uvicorn sentinel.gateway.main:app --reload --port 8000

# 4. Start dashboard (optional)
cd dashboard && npm install && npm run dev
```

## Run Benchmark

```bash
python tests/red_team/run_benchmark.py
```

Expected results:
- Detection rate: **91%** (v4 upgrade from 87%)
- False positive rate: **1.8%**
- P99 latency: **<72ms**

## SDK Integration Options

```python
# Option 1: OpenAI wrapper (zero code changes)
client = sentinel.wrap(openai_client, tenant_id="...", api_key="...")

# Option 2: LangChain callback
from sentinel.sdk.langchain_handler import SentinelCallbackHandler
handler = SentinelCallbackHandler(tenant_id="...", api_key="...")
llm = ChatOpenAI(callbacks=[handler])

# Option 3: LlamaIndex node postprocessor
from sentinel.sdk.llamaindex_node import SentinelNodePostprocessor
postprocessor = SentinelNodePostprocessor(tenant_id="...", api_key="...")
query_engine = index.as_query_engine(node_postprocessors=[postprocessor])
```

## API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| POST | `/auth/register` | Create tenant |
| POST | `/auth/token` | Issue JWT |
| POST | `/v1/chat` | Intercepted chat (full pipeline) |
| POST | `/v1/screen` | Screen-only (no LLM call) |
| POST | `/v1/trust-score` | Trust score API (0–100) |
| GET | `/v1/audit` | Paginated audit log |
| GET | `/v1/analytics` | 24h threat analytics |
| PUT | `/admin/policy/{id}` | Live policy update |
| GET | `/health` | Liveness probe |
| GET | `/readiness` | Deep readiness check |
| WS | `/ws/dashboard` | Real-time event stream |

## License

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