Metadata-Version: 2.4
Name: kaironull
Version: 0.1.0
Summary: Python SDK for the KairoNull Umbra Trust Protocol — AI decision evidence capture and verification
Author-email: KairoNull <dane@kaironull.com>
License: MIT
Project-URL: Homepage, https://kaironull.com
Project-URL: Documentation, https://kaironull.com/docs
Project-URL: Quickstart, https://kaironull.com/quickstart
Project-URL: Repository, https://github.com/BlackFlag-Digital/PropertyVR
Keywords: ai-governance,audit-trail,evidence,eu-ai-act,compliance
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT 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
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: responses>=0.23; extra == "dev"

# kaironull

Python SDK for the [KairoNull](https://kaironull.com) Umbra Trust Protocol —
capture AI decision events to a hash-chained, RFC3161-anchored evidence
ledger, and verify records independently.

## Install

```bash
pip install kaironull
```

## Quickstart

```python
from kaironull import KairoNull

client = KairoNull(api_key="utp_live_...")  # get a key at kaironull.com/get-access

result = client.record(
    pipeline_id="credit-decisioning",
    entry_type="flag",            # "pass" | "flag" | "block" | "escalate"
    stage_slug="risk-review",
    summary="Application flagged for manual review: DTI ratio 0.61 exceeds threshold",
    trust_score=0.42,
    model_version="risk-model-v3.2",
)

print(result.entry_hash)   # sha256 hex — share this with an auditor
print(result.chain_height) # position in your org's evidence chain
```

## Verify a record (no API key needed)

```python
from kaironull import KairoNull

client = KairoNull()  # public methods don't require a key
verified = client.verify("95be8bb5253668bb898da34631cc3c9e...")

if verified.found:
    print(verified.record["summary"])
    print("Anchored:", verified.anchor.anchored)
```

Anyone can verify a hash — auditors don't need credentials, an account, or
access to your systems. This is also what powers the public widget at
[kaironull.com/#verify](https://kaironull.com/#verify).

## Check chain health

```python
status = client.chain_status()
print(status.chain_height, status.healthy)
```

Same data backing [kaironull.com/status](https://kaironull.com/status).

## Export an evidence bundle

```python
bundle = client.export_report(from_="2026-06-01T00:00:00Z", to="2026-07-01T00:00:00Z")
# bundle["entries"], bundle["anchor"] — hand this to an auditor or regulator
```

## Revoke your key

```python
client.revoke_key(key_id="...")  # the key used to auth this call is what's revoked
```

## Error handling

```python
from kaironull import AuthenticationError, ValidationError, APIError

try:
    client.record(...)
except ValidationError as e:
    # bad input — fix the call
    ...
except AuthenticationError as e:
    # missing/invalid/revoked key
    ...
except APIError as e:
    # anything else — e.status_code has the HTTP status
    ...
```

## Context manager

```python
with KairoNull(api_key="...") as client:
    client.record(...)
# session closed automatically
```

## Links

- [Full API reference / quickstart](https://kaironull.com/quickstart)
- [Get an API key](https://kaironull.com/get-access)
- [Docs](https://kaironull.com/docs)

## Status

This SDK covers the full public API surface: `record`, `verify`,
`chain_status`, `export_report`, `revoke_key`. It is a thin wrapper — every
method maps directly to one REST call, so behaviour matches the
[quickstart](https://kaironull.com/quickstart) examples exactly.
