Metadata-Version: 2.4
Name: quantumcatena-sentinel
Version: 0.1.0
Summary: Real-time security layer for AI agents — intercept, evaluate, audit with post-quantum proof
Author-email: Joffrey Catena <contact@quantumcatena.io>
License: Apache-2.0
Project-URL: Homepage, https://quantumcatena.io
Project-URL: Repository, https://github.com/quantumcatena/sentinel
Project-URL: Dashboard, https://quantumcatena.github.io/openclaw-shield
Project-URL: API-Docs, https://sentinel-t26z.onrender.com/docs
Keywords: ai-agents,security,post-quantum,NIS2,RGPD,sentinel,langchain
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28
Provides-Extra: langchain
Requires-Dist: langchain>=0.1; extra == "langchain"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: mypy; extra == "dev"

# QuantumCatena Sentinel SDK

**Real-time security layer for AI agents.**  
Intercept, evaluate, and audit every action before execution —  
with post-quantum cryptographic proof (Dilithium-3 NIST FIPS 204).

[![PyPI](https://img.shields.io/pypi/v/quantumcatena-sentinel)](https://pypi.org/project/quantumcatena-sentinel)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![NIS2 Ready](https://img.shields.io/badge/NIS2-Ready-green)]()
[![FIPS 204](https://img.shields.io/badge/NIST-FIPS%20204-blue)]()

---

## Install

```bash
pip install quantumcatena-sentinel
```

## Quickstart — 3 lines

```python
from sentinel import SentinelClient, BlockedBySentinel

sentinel = SentinelClient(api_key="sk-...", agent_id="my-agent")

@sentinel.protect(action_type="send_data", data_class="pii")
def send_email(recipient: str, subject: str, body: str) -> str:
    return smtp.send(recipient, subject, body)   # only runs if Sentinel allows it

try:
    send_email("unknown@external.com", "Client export", "PII data...")
except BlockedBySentinel as e:
    print(f"Blocked. Risk: {e.risk_score}. Reason: {e.reasoning}")
```

That is all. Your agent cannot bypass Sentinel.

---

## How it works

```
Your Agent
    |
    v
sentinel.protect()  <-- SDK intercepts here, BEFORE execution
    |
    v
Sentinel API  -->  Policy Engine  -->  Risk Scoring  -->  PQC Proof
    |
    v
ALLOW / REVIEW / BLOCK
    |
    v
Your function executes (or BlockedBySentinel is raised)
```

---

## Usage

### Decorator pattern

```python
sentinel = SentinelClient(api_key="...", agent_id="invoice-agent")

@sentinel.protect(action_type="read_data", data_class="general")
def read_file(path: str) -> str:
    with open(path) as f:
        return f.read()

@sentinel.protect(action_type="transfer_funds")
def wire_transfer(amount: float, iban: str) -> str:
    return bank.transfer(amount, iban)
```

### Low-level check (inspect before acting)

```python
decision = sentinel.check(
    action_type="transfer_funds",
    target="https://api.stripe.com",
    payload={"amount": 50000, "iban": "DE89..."},
)
print(decision["decision"])     # allow | review | block
print(decision["risk_score"])   # 0.0 - 1.0
print(decision["pqc_proof"])    # Dilithium-3 proof (Enterprise)
```

### SentinelToolkit — for multi-tool agents

```python
from sentinel import SentinelClient, SentinelToolkit

sentinel = SentinelClient(api_key="...", agent_id="my-agent")
toolkit  = SentinelToolkit(sentinel)

@toolkit.tool(action_type="send_data", data_class="internal")
def send_email(recipient: str, subject: str) -> str:
    """Send an internal email."""
    return smtp.send(recipient, subject)

# Pass to Anthropic agent
response = client.messages.create(
    tools=toolkit.anthropic_tools,   # auto-generated schemas
    ...
)
```

### LangChain integration

```python
from sentinel.middleware import SentinelToolkit

toolkit  = SentinelToolkit(sentinel)
lc_tools = toolkit.wrap_langchain([search, email, file_reader])

agent = initialize_agent(lc_tools, llm, ...)
```

---

## Action types

| action_type       | Typical use                          |
|-------------------|--------------------------------------|
| `read_data`       | File read, DB query                  |
| `send_data`       | Email, SMS, Slack, webhook           |
| `call_api`        | External HTTP call                   |
| `execute_code`    | Shell, Python exec, subprocess       |
| `transfer_funds`  | Payment, bank wire, crypto transfer  |
| `write_data`      | File write, DB insert/update         |
| `delete_data`     | File delete, DB delete               |

## Data classes

| data_class     | Examples                                 |
|----------------|------------------------------------------|
| `general`      | Public info, logs, system metadata       |
| `internal`     | Internal docs, employee emails           |
| `pii`          | Names, emails, IDs, medical data         |
| `confidential` | Trade secrets, keys, financial records   |

---

## Configuration

```python
sentinel = SentinelClient(
    api_key   = "sk-...",         # or SENTINEL_API_KEY env var
    agent_id  = "prod-agent-1",
    api_url   = "https://sentinel.yourdomain.com",  # self-hosted / Enterprise
    fail_open = True,             # allow if Sentinel unreachable (default)
    verbose   = True,             # print decisions to stdout
)
```

---

## Pricing

| Tier          | Price      | Decisions/month | PQC Layer          |
|---------------|------------|-----------------|-------------------|
| **Free**      | 0 EUR      | 10,000          | Ed25519 (sim)     |
| **Pro**       | 149 EUR/mo | Unlimited        | Dilithium-3       |
| **Enterprise**| Custom     | Unlimited        | Dilithium-3 + HSM |

[Get your API key](https://quantumcatena.io) | [Docs](https://sentinel-t26z.onrender.com/docs)

---

## Open source

The SDK is Apache 2.0.  
The Sentinel backend is source-available for self-hosted Enterprise.  
The Openclaw Shield dashboard is MIT.

**Live demo:** https://quantumcatena.github.io/openclaw-shield  
**API docs:** https://sentinel-t26z.onrender.com/docs  
**Contact:** contact@quantumcatena.io
