Metadata-Version: 2.4
Name: kerneva-runtime-trust
Version: 0.3.1
Summary: Behavioral safety for financial AI agents
License-Expression: MIT
Project-URL: Homepage, https://github.com/vaibhavdedhia/runtime-trust
Project-URL: Documentation, https://github.com/vaibhavdedhia/runtime-trust#readme
Project-URL: Repository, https://github.com/vaibhavdedhia/runtime-trust.git
Project-URL: Changelog, https://github.com/vaibhavdedhia/runtime-trust/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/vaibhavdedhia/runtime-trust/issues
Keywords: ai-safety,llm,financial-agents,compliance
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
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
License-File: LICENSE
Dynamic: license-file

# Kerneva Runtime Trust

Behavioral safety for financial AI agents.

```python
from kerneva_runtime_trust import guard, RuntimeTrustBlock

@guard(action_type="refund")
def process_refund(amount, customer_id):
    return billing_api.refund(customer_id, amount)

try:
    process_refund(amount=150.0, customer_id="cust_123")
except RuntimeTrustBlock as e:
    print(f"Blocked: {e}")
```

`guard` (also available as `with_runtime_trust`) evaluates every call through
Kerneva's `/evaluate` before the function body runs. On `BLOCK` the function
never executes and `RuntimeTrustBlock` is raised.

## Install

```bash
pip install kerneva-runtime-trust
```

## Setup

```bash
export KERNEVA_API_KEY="krv_test_abc123"
export KERNEVA_API_URL="https://api.kerneva.com"   # or http://localhost:8080
```

## Getting good signals

Kerneva reasons over an agent's *trajectory* — within a session and across your
end-customers. A single function call doesn't carry that context, so declare it.
The two that matter most:

- **`action_type`** — match a configured threshold (e.g. `"refund"`). If it has
  no threshold the call is observation-only; the SDK logs a warning so you know.
- **`customer_id`** — the end-customer, so one customer's trajectory doesn't
  bleed into another's.

Set them per-call, or ambiently for a whole interaction with `session(...)`:

```python
import kerneva_runtime_trust as kerneva

with kerneva.session(session_id=ticket_id, agent_id="refund-bot",
                     customer_id="cust_123"):
    process_refund(amount=40.0, customer_id="cust_123")
    process_refund(amount=75.0, customer_id="cust_123")   # shares one trajectory
```

Without a session, each call gets its own session id (so unrelated calls are
never merged) and the SDK warns once that session-scoped analysis is off.

## Handling REVIEW

By default a `REVIEW` decision emits a Python warning and proceeds. To route it
to a human (hold, queue, escalate), pass an `on_review` hook — it may raise to
halt execution:

```python
def hold_for_approval(ctx):
    if ctx.recommended_decision == "REVIEW":
        raise NeedsApproval(ctx.reason)   # stops the wrapped function

@guard(action_type="refund", on_review=hold_for_approval)
def process_refund(amount, customer_id): ...
```

## Reliability

- **Fail-closed by default:** if the API is unreachable the action does not run.
  Pass `fail_open=True` for non-critical workflows.
- **`strict=True`** turns integration warnings (misconfiguration) into a raised
  `KernevaConfigError` — useful in development/CI to catch a broken integration.
- **Async:** decorating an `async def` returns an async wrapper.

## Low-level client

```python
from kerneva_runtime_trust import KernevaClient

client = KernevaClient(api_key="krv_test_abc123")
result = client.evaluate(
    agent_id="refund-bot", session_id="ticket-8842",
    action_type="refund", amount=82.0, customer_id="cust_123",
)
# In Observation Mode nothing is blocked; recommended_decision is the shadow
# verdict — what enforcement WOULD do.
print(result.decision, result.recommended_decision, result.warnings)
```

See https://github.com/kerneva/runtime-trust for full documentation.
