Metadata-Version: 2.4
Name: veratum
Version: 0.1.0
Summary: Cryptographic evidence receipts for AI decisions
Project-URL: Homepage, https://veratum.ai
Project-URL: Documentation, https://docs.veratum.ai
Project-URL: Dashboard, https://app.veratum.ai
Project-URL: Repository, https://github.com/Alithecoder1/veratum
Author: Veratum
License: Apache-2.0
Keywords: ai,anthropic,audit,compliance,evidence,langchain,openai,receipts
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
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
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-json-logger>=2.0.0
Provides-Extra: all
Requires-Dist: anthropic>=0.20.0; extra == 'all'
Requires-Dist: langchain>=0.2.0; extra == 'all'
Requires-Dist: litellm>=1.0.0; extra == 'all'
Requires-Dist: openai>=1.0.0; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.20.0; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: respx>=0.21.0; extra == 'dev'
Provides-Extra: langchain
Requires-Dist: langchain>=0.2.0; extra == 'langchain'
Provides-Extra: litellm
Requires-Dist: litellm>=1.0.0; extra == 'litellm'
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == 'openai'
Description-Content-Type: text/markdown

# Veratum Python SDK

Cryptographic evidence receipts for every AI decision.

One line of code. Every AI call gets a tamper-evident receipt stored in a WORM
evidence vault — auditable, verifiable, compliance-ready.

```bash
pip install veratum
```

## Quickstart

```python
import veratum
import openai

sdk = veratum.init(api_key="vrtm_live_...")
client = sdk.wrap(openai.OpenAI())

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Approve this loan?"}],
)

print(response.veratum_receipt)
# Receipt(id=019d8ed6..., status=committed)
```

That's the whole integration. `sdk.wrap()` wraps any OpenAI or Anthropic
client; every subsequent chat/message call emits a receipt attached as
`response.veratum_receipt`. If Veratum is unreachable, the AI call still
returns — the receipt is just `None`.

## Explicit mode

For custom pipelines or non-wrapped code paths, submit receipts directly:

```python
receipt = sdk.record(
    input_hash=veratum.hash(my_input),
    output_hash=veratum.hash(my_output),
    model_id="gpt-4o",
    agent_id="loan-officer-agent",
    decision_type="credit-approval",
    metadata={"applicant_id": "A-12345"},
)

print(receipt.record_id)
```

## Verify a receipt

```python
result = veratum.verify(record_id="019d8ed6-...")
assert result.valid
```

## Configuration

| Parameter      | Env var                | Default                                               |
|----------------|------------------------|-------------------------------------------------------|
| `api_key`      | `VERATUM_API_KEY`      | *(required)*                                          |
| `base_url`     | `VERATUM_BASE_URL`     | `https://aagjipqk93.execute-api.us-east-2.amazonaws.com` |
| `environment`  | `VERATUM_ENVIRONMENT`  | `production`                                          |
| `timeout`      | `VERATUM_TIMEOUT`      | `5` (seconds)                                         |
| `async_submit` | `VERATUM_ASYNC`        | `true`                                                |

## Supported integrations

### OpenAI

```python
import openai
client = sdk.wrap(openai.OpenAI())
# or async:
client = sdk.wrap(openai.AsyncOpenAI())
```

Install with: `pip install "veratum[openai]"`

### Anthropic

```python
import anthropic
client = sdk.wrap(anthropic.Anthropic())
```

Install with: `pip install "veratum[anthropic]"`

### LangChain

```python
from langchain_openai import ChatOpenAI
from veratum.integrations.langchain import VeratumCallbackHandler

handler = VeratumCallbackHandler(sdk, decision_type="rag")
llm = ChatOpenAI(callbacks=[handler])
```

Records one receipt per LLM call. With `record_tools=True` (default) also
records each tool invocation in a chain.

Install with: `pip install "veratum[langchain]"`

### LiteLLM (140+ providers)

```python
import litellm
from veratum.integrations.litellm import install_litellm_callback

install_litellm_callback(sdk, decision_type="general")

# Every litellm.completion() call now emits a receipt.
response = litellm.completion(
    model="bedrock/anthropic.claude-3-sonnet",
    messages=[{"role": "user", "content": "hi"}],
)
```

Install with: `pip install "veratum[litellm]"`

## Error handling

The SDK **never blocks an AI call** on Veratum failure. When using `wrap()`,
if the Veratum API is down or rejects the request, the AI response returns
normally with `response.veratum_receipt = None`.

For explicit `record()` / `verify()` calls, errors surface as exceptions:

| Exception              | When                            |
|------------------------|---------------------------------|
| `VeratumConfigError`   | Missing API key or required arg |
| `VeratumAuthError`     | 401/403 from the server         |
| `VeratumTimeoutError`  | Submission timed out            |
| `VeratumAPIError`      | Other non-2xx response          |

## Hashing

All hashes are SHA-256 over canonical JSON (sorted keys, compact separators,
UTF-8). This means two logically identical payloads always produce the same
hash regardless of dict key order or serialization style.

```python
veratum.hash("hello")              # hex digest of UTF-8 bytes
veratum.hash({"b": 2, "a": 1})     # canonicalized JSON
veratum.hash(b"raw bytes")         # SHA-256 of the bytes
veratum.hash_messages(messages)    # OpenAI-format chat messages
veratum.hash_response(response)    # OpenAI / Anthropic response objects
```

## Links

- Dashboard: https://app.veratum.ai
- Docs: https://docs.veratum.ai
- API reference: https://docs.veratum.ai/api
- Repository: https://github.com/Alithecoder1/veratum

## License

Apache-2.0
