Metadata-Version: 2.4
Name: velaru-sdk
Version: 0.1.2
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
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.2.0; extra == "langchain"
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)
```

## OpenAI middleware (15-minute integration)

Wrap your existing OpenAI client — every completion gets Velaru signed receipts:

```python
pip install "velaru-sdk[openai]"
```

```python
from openai import OpenAI
from velaru import VelaruAuditedOpenAI

audited = VelaruAuditedOpenAI(
    OpenAI(),
    domain="hiring",
    api_key="YOUR_VELARU_KEY",
    session_id="prod-customer-123",
)

result = audited.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": user_message}],
)

print(result.text)
print(result.input_verify_url)   # permanent receipt URL
print(result.output_verify_url)  # assistant reply receipt (if audit_output=True)
```

Blocked inputs raise `VelaruBlockedError` with the receipt attached — verify at `/verify` without trusting Velaru.

See `examples/openai_audited_chat.py` in the repo.

## 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
