Metadata-Version: 2.4
Name: zerohal-sdk
Version: 0.1.0
Summary: Python SDK for ZeroHal — decision verification for AI agents
Project-URL: Homepage, https://zerohal.ai
Project-URL: Documentation, https://docs.zerohal.ai
Project-URL: Repository, https://github.com/Pankajmanglik/ZeroHal
Author-email: ZeroHal <sdk@zerohal.ai>
License-Expression: Apache-2.0
Keywords: ai,decision,proof,verification,zerohal
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.24.0
Description-Content-Type: text/markdown

# ZeroHal Python SDK

The official Python SDK for [ZeroHal](https://zerohal.ai) — the decision verification layer for AI agents.

Your AI agent decides. ZeroHal certifies.

## Installation

```bash
pip install zerohal-sdk
```

## Quick Start

```python
from zerohal_sdk import ZeroHalClient

client = ZeroHalClient(api_key="zh_live_your_api_key")

# Submit evidence (purchase order, invoice, receipt)
po = client.create_evidence("sap", "purchase_order", {
    "po_number": "PO-2026-001",
    "supplier": "Acme Corp",
    "total_amount": 15000.00,
    "currency": "USD",
    "line_items": [{"item": "Widget A", "quantity": 100, "unit_price": 150.00}],
})

invoice = client.create_evidence("email", "invoice", {
    "invoice_number": "INV-5001",
    "po_reference": "PO-2026-001",
    "supplier": "Acme Corp",
    "total_amount": 14850.00,
    "currency": "USD",
    "line_items": [{"item": "Widget A", "quantity": 100, "unit_price": 148.50}],
})

receipt = client.create_evidence("warehouse", "receipt", {
    "receipt_number": "REC-8001",
    "po_reference": "PO-2026-001",
    "supplier": "Acme Corp",
    "line_items": [{"item": "Widget A", "quantity_received": 100}],
})

# Verify the invoice with a three-way match
decision = client.three_way_match(invoice_evidence_id=invoice["evidence_id"])

print(decision["conclusion"])       # "approved"
print(decision["proof_object"])     # Full proof object with observations, rules, constraints
```

## Claims Adjudication

```python
# Verify a healthcare claim in one step
decision = client.verify_claim({
    "claim_id": "CLM-2026-001",
    "patient_id": "PT-1234",
    "provider_npi": "1234567890",
    "date_of_service": "2026-03-15",
    "diagnosis_codes": ["J06.9"],
    "procedures": [
        {"cpt_code": "99213", "units": 1, "billed_amount": 150.00},
    ],
    "place_of_service": "11",
    "claim_type": "practitioner",
})

print(decision["conclusion"])  # "approved" or "rejected"
```

## Domain Accelerator Templates

```python
# List available templates
templates = client.list_templates()
for t in templates["templates"]:
    print(f"{t['template_id']}: {t['name']} ({t['vertical']})")

# Activate a template for your tenant
activation = client.activate_template("claims_adjudication", config={
    "amount_tolerance_pct": 5.0,
})
```

## Decision Replay

```python
# Replay a decision to verify deterministic output
replay = client.replay_decision(decision["decision_id"])
print(replay["match"])        # True — same inputs, same outputs
print(replay["differences"])  # [] — no differences
```

## API Reference

### `ZeroHalClient(api_key, base_url="https://api.zerohal.ai", timeout=30)`

Create a client instance.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `api_key` | `str` | required | Your ZeroHal API key (starts with `zh_live_` or `zh_test_`) |
| `base_url` | `str` | `"https://api.zerohal.ai"` | API base URL |
| `timeout` | `int` | `30` | Request timeout in seconds |

### Evidence

- **`create_evidence(source_system, evidence_type, payload, source_id=None)`** — Create an evidence record
- **`get_evidence(evidence_id)`** — Retrieve an evidence record by ID

### Decisions

- **`three_way_match(invoice_evidence_id=None, invoice_number=None)`** — Trigger a three-way invoice match
- **`verify_claim(claim_data)`** — Submit and adjudicate a healthcare claim
- **`get_decision(decision_id)`** — Retrieve a decision by ID
- **`replay_decision(decision_id)`** — Replay a decision for deterministic verification
- **`analyze_and_route(invoice_evidence_id)`** — Full AP pipeline: match + discrepancies + routing
- **`list_decisions(limit=50, offset=0, workflow_type=None, conclusion=None)`** — List decisions

### Templates

- **`list_templates()`** — List available Domain Accelerator Templates
- **`get_template(template_id)`** — Get template details
- **`activate_template(template_id, config=None)`** — Activate a template

### Other

- **`analyze_discrepancies(invoice_evidence_id)`** — Analyze invoice discrepancies
- **`route_exceptions(invoice_evidence_id)`** — Route discrepancies to handler queues
- **`get_usage(period_start=None, period_end=None)`** — Get usage summary
- **`health()`** — Check API health

## Error Handling

```python
from zerohal_sdk import ZeroHalClient, ZeroHalError

client = ZeroHalClient(api_key="zh_live_...")

try:
    decision = client.three_way_match(invoice_evidence_id="invalid-id")
except ZeroHalError as e:
    print(e.status_code)  # 400
    print(e.detail)       # "Invalid UUID format for evidence_id"
    print(e.request_id)   # Request ID for support
```

## License

Apache License 2.0
