Python SDK

Status

First-party Python SDK
Status: Beta
Package: haltstate-sdk
Version: 0.7.0
Install: pip install haltstate-sdk

Client

from haltstate import HaltStateClient

client = HaltStateClient(
    tenant_id=os.environ["HALTSTATE_TENANT_ID"],
    api_key=os.environ["HALTSTATE_API_KEY"],
)

Context manager guard

with client.guard("refund.create", params={"amount": 89, "currency": "USD"}, idempotency_key="refund:lge_123"):
    ledger.execute_refund()

Service pattern

Long-running workers should claim work, mark it as guarding, call the guard path, execute only when allowed or later approved, create proof evidence before final success, and report success or error back to HaltState. If HaltState is unavailable for a high-risk action, the worker should fail closed.

Sync check and report

from haltstate import HaltStateClient

client = HaltStateClient(
    tenant_id='your_tenant_id',
    api_key='hs_xyz',
    base_url='https://haltstate.ai',
    fail_open=False,
)

decision = client.check(
    action='refund.create',
    params={'amount': 126, 'currency': 'USD'},
    agent_id='retail-refund-agent',
)

if decision.allowed:
    result = execute_refund_once()
    client.report(decision, status='success', result=result, action='refund.create', agent_id='retail-refund-agent')
elif decision.requires_approval:
    mark_pending()
else:
    mark_denied(decision.reason)

Async check pattern

from haltstate import AsyncHaltStateClient

async def process_payment(invoice_id: str, amount: int):
    async with AsyncHaltStateClient(tenant_id='acme', api_key='hs_xxx', base_url='https://haltstate.ai') as client:
        decision = await client.check(
            action='payment.process',
            params={'invoice_id': invoice_id, 'amount': amount},
            agent_id='payment-bot',
        )
        if decision.allowed:
            result = await execute_payment(amount)
            await client.report(decision, status='success', result={'ok': True}, action='payment.process', agent_id='payment-bot')
            return result
        if decision.requires_approval:
            return {'status': 'pending'}
        return {'status': 'denied', 'reason': decision.reason}

Decorators

from haltstate import HaltStateClient, haltstate_guard

client = HaltStateClient(tenant_id='acme', api_key='hs_xxx', base_url='https://haltstate.ai')

@haltstate_guard(client, action='email.send', agent_id='email-bot')
def send_email(to, subject, body):
    return mailer.send(to, subject, body)

Use decorators for small service methods where the action name and idempotency key are obvious. Use explicit guard blocks for workers that need ledger transitions, Proof Packs, and multi-step reporting.

Exception imports

from haltstate import (
    HaltStateError,
    HaltStateAuthError,
    HaltStateConnectionError,
    HaltStateRateLimitError,
    ApprovalPending,
    ActionDenied,
    ActionExpired,
)

Legacy namespace

Existing code using the legacy import namespace can continue to work, but new integrations should use from haltstate import .... The compatibility path is for migration, not for new public examples.

Implementation notes

Keep the HaltState call as close as possible to the side effect. The agent may plan and draft freely, but the wrapper around the actual action should be the place where authority is checked. That wrapper should send only the context required for policy evaluation: safe identifiers, normalized amounts, action names, risk flags, schedule windows, and redaction status. Raw customer payloads and secrets should stay in the business system or protected operator tooling.

Operational evidence

For each action, preserve the decision, the worker outcome, the idempotency key, safe resource references, latency, proof status, and redaction status. This evidence supports incident response and control narratives because it shows what the system did at runtime rather than only describing what the policy document intended. HaltState supports alignment work; it is not a substitute for legal advice or a compliance certification.