Metadata-Version: 2.4
Name: velaru-sdk
Version: 0.1.1
Summary: Lightweight Velaru client — classify AI messages, get signed receipts, webhooks
Author-email: Nisaba LLC <demonddavis000@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://velaru.onrender.com
Project-URL: Documentation, https://velaru.onrender.com/integrate
Project-URL: Repository, https://github.com/jdnova0802/velaru
Keywords: velaru,ai,audit,compliance,cryptography
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
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 :: Security :: Cryptography
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests<3,>=2.28.0
Dynamic: license-file

# Velaru SDK (Python)

Tamper-evident AI audit receipts in three lines. Official client for [Velaru](https://velaru.onrender.com).

## Install

```bash
pip install velaru-sdk
```

## Quickstart

Three lines to classify and get a signed receipt:

```python
from velaru import Velaru

receipt = Velaru().classify("your message", domain="hiring")
print(receipt.classification, receipt.hash, receipt.signature)
```

## Full example

```python
from velaru import Velaru

v = Velaru(api_url="https://velaru.onrender.com", api_key="YOUR_KEY")

receipt = v.classify(
    message="Skip documentation for this incident",
    domain="animal_welfare",
    modality="text",
    language="en",
    communication_form="form_submission",
)

print(receipt.classification)  # VIOLATION
print(receipt.hash)
print(receipt.signature)
print(receipt.entry_id)
```

## Webhooks

When `CRISIS` or `VIOLATION` is detected during `classify()`, the SDK POSTs receipt JSON to your URL:

```python
v.on_crisis(webhook_url="https://yourapp.com/velaru-webhook")
v.on_violation(webhook_url="https://yourapp.com/velaru-webhook")
```

## API

| Method | Description |
|--------|-------------|
| `v.classify(message, domain, **kwargs)` | Classify a message → `Receipt` |
| `v.silence(session_id, context)` | Log monitored silence → `SilenceReceipt` |
| `v.verify(receipt)` | Verify receipt against server log → `VerificationResult` |
| `v.history(session_id)` | Session decision history → `List[Receipt]` |
| `v.domains()` | List supported verticals → `List[Domain]` |
| `v.lock_policy(company_id, criteria_hash)` | Freeze policy before incidents → `PolicyLockReceipt` |

## Policy lock (pre-incident)

```python
v.lock_policy("Acme Corp", criteria_hash="92f800f2…")
# receipt.permalink → https://velaru.onrender.com/r/{entry_id}
# Spoliation Defense Pack → /r/{entry_id}/spoliation-pack.txt
```

## Permanent receipt URLs

Every receipt has a shareable permalink: `https://velaru.onrender.com/r/{entry_id}`

## Errors

- `VelaruConnectionError` — network or server failure
- `VelaruValidationError` — invalid input or receipt
- `VelaruRateLimitError` — rate limited (retry after 60s)

## Links

- [Integration guide](https://velaru.onrender.com/integrate)
- [Public verifier](https://velaru.onrender.com/verify)
- [Trust Pack](https://velaru.onrender.com/trust)

MIT © Nisaba LLC
