Metadata-Version: 2.5
Name: auddax
Version: 0.2.0
Summary: Official Python SDK for the Auddax API: governed clinical intakes, streaming turns, batches, and webhooks.
Project-URL: Homepage, https://www.auddax.ai
Project-URL: Documentation, https://www.auddax.ai/docs
Author: Auddax
License: Apache-2.0
License-File: LICENSE
Keywords: api,auddax,clinical,intake,sdk
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.5
Description-Content-Type: text/markdown

# Auddax Python SDK

Official Python client for the [Auddax API](https://www.auddax.ai/docs): 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

```bash
pip install auddax
```

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

## Three calls to a handoff

```python
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:

```python
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:

```python
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

```python
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:

```python
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.

```python
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.
