zerohal-sdk 0.1.0

Python SDK for ZeroHal — decision verification for AI agents

ZeroHal Python SDK

The official Python SDK for ZeroHal — the decision verification layer for AI agents.

Your AI agent decides. ZeroHal certifies.

Installation

pip install zerohal-sdk

Quick Start

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

# 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

# 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

# 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

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