Auddax Python SDK

Official Python client for the Auddax API: governed clinical intakes with streaming turns, batch evaluation, webhooks, and typed handoffs.

The Auddax sandbox is a research preview. Do not use it for real patient care, and do not send real patient data.

Install

pip install auddax

Python 3.10+. The client reads AUDDAX_API_KEY from the environment.

Three calls to a handoff

from auddax import Auddax

client = Auddax()  # or Auddax(api_key="adx_sb_...")

intake = client.intakes.create(demographics={"age_years": 58, "sex": "male"})
turn = client.intakes.send_turn(intake.encounter_id, "I have chest pressure and I'm sweating.")
if turn.terminal:
    print(turn.handoff.soap.assessment)   # typed handoff, embedded on terminal turns
print(turn.turns_remaining)               # from the x-auddax-turns-remaining header

Blocking turns run a real clinical reasoning pass (20-40 s). The SDK attaches an Idempotency-Key automatically, so transient failures retry safely without re-driving the engine.

Streaming

Use streaming for anything a person watches: first tokens arrive in seconds:

with client.intakes.stream_turn(intake.encounter_id, "It started an hour ago.") as stream:
    for fragment in stream.text():
        print(fragment, end="", flush=True)
print()
print(stream.turn.disposition)  # the completed Turn, populated after the loop

Or iterate the raw events (MessageDelta, MessageCompleted, HandoffCompiling, HandoffProgress, TurnCompleted).

Batch evaluation

Run scripted scenarios as a background job and get full transcripts back:

batch = client.batches.create(
    scenarios=[
        {"label": "benign", "messages": ["Mild sore throat since yesterday. No fever."]},
        {"label": "cannot-miss",
         "messages": ["Chest pressure for an hour, sweating, short of breath."],
         "demographics": {"age_years": 58, "sex": "male"}},
    ],
    label="smoke-test",
)
result = client.batches.wait(batch.batch_id)
for scenario in result.scenarios:
    last = scenario.turns[-1]
    print(scenario.label, last.disposition, last.safety_status)

Webhooks

hook = client.webhooks.create("https://example.com/hooks/auddax",
                              events=["intake.escalated", "batch.completed"])
# hook.secret is shown once - store it.

Verify deliveries in your receiver:

from auddax import verify_signature

ok = verify_signature(request_body, request.headers["auddax-signature"], secret)

Configuration

Configure the engine per intake. Read the catalog with client.config(); today it lists locale (en-US, es-AR, pt-BR). Every result echoes the resolved config and a hash, so two runs are comparable when their hashes match.

catalog = client.config()

intake = client.intakes.create(config={"locale": "es-AR"})
print(intake.config, intake.config_hash)

Errors and limits

Errors are typed: RateLimitedError (with .retry_after), QuotaExceededError, IntakeClosedError, NotFoundError, AuthenticationError, and so on. The SDK retries 429s automatically. client.usage() returns today's turn and intake counts against your quota.