Metadata-Version: 2.4
Name: wedge-health
Version: 0.2.0
Summary: Python SDK for the authenticated Wedge Health clinical automation API
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: google-auth<3,>=2.29
Requires-Dist: requests<3,>=2.31

# Wedge Health Python SDK

The supported application interface is intentionally small:

```python
from wedge import Wedge

client = Wedge()
patient = client.read_patient(patient_id, id_type="mrn")
```

The older `from wedge_api_client import WedgeApiClient` import remains
available for compatibility.

The SDK provides a small, typed interface to the authenticated Wedge Health
clinical automation API. Access is provisioned only to approved callers.

The client contains the fixed 22-action to 18-capability staging map. JWTs live
for 240 seconds and are refreshed 30 seconds early under a lock. Request and
response bodies, patient identifiers, API keys, and JWTs are never logged. The
client performs no automatic HTTP retries.

Infrastructure authorization is not operational approval. Public-Gateway
writes and durable exports have not been live-tested and must not be invoked
without action-specific approval and the required idempotency controls.

## Install

Python 3.11 or newer is required. The canonical distribution name is
`wedge-health`:

```console
python3 -m pip install wedge-health
```

The `wedgehealth` and `wedge-ai` distributions are compatibility installers.
They contain no import packages and depend on the matching `wedge-health`
release, so all three installation names provide the same supported import:

```python
from wedge import Wedge
```

Prefer `wedge-health` in new dependency files and documentation. From this
repository checkout:

```console
python3 -m venv .venv-wedge-api
./.venv-wedge-api/bin/python -m pip install --upgrade pip
./.venv-wedge-api/bin/python -m pip install -e ./clients/python
```

From another private Git repository, pin the dependency to a reviewed commit
instead of a moving branch:

```text
wedge-health @ git+https://github.com/wedge-health/wedge-api.git@REVIEWED_COMMIT_SHA#subdirectory=clients/python
```

The package has two runtime dependencies: `google-auth>=2.29,<3` and
`requests>=2.31,<3`.

## Configure approved access

Set the restricted key supplied by a Wedge API administrator in the process
environment:

```console
export WEDGE_API_KEY="..."
```

The current staging service also uses short-lived Google identity credentials
discovered through Application Default Credentials. Approved deployed callers
must use their attached workload identity; downloaded service-account keys are
not supported. Contact the API administrator to authorize a caller and its
required capabilities.

Never put credentials in source code, committed environment files, command-line
arguments, logs, tickets, or documentation.

## Read one patient

The function argument comes from the calling application's approved workflow;
there is deliberately no example patient identifier:

```python
from typing import Any

from wedge import Wedge


client = Wedge()


def read_one_patient(patient_id: str) -> dict[str, Any]:
    return client.read_patient(patient_id=patient_id, id_type="mrn")
```

Reuse one client instance so its short-lived per-capability JWT cache is useful,
then call `client.close()` during shutdown. The exact convenience signature is:

```python
client.read_patient(
    patient_id,
    *,
    id_type="mrn",
    include_appointments=False,
    include_disability_info=False,
    timeout_seconds=None,
)
```

## Call another typed action

Use the action name and request schema from the public OpenAPI contract:

```python
result = client.call("classify_orders", approved_request_body)
```

For an action whose contract requires idempotency, generate and durably retain
one canonical UUID, put the same value in the body `operation_id`, and pass it
as `idempotency_key`. Reuse that value only to reconcile the same unknown
outcome. The client rejects a missing or mismatched key for required actions.

```python
result = client.call(
    approved_action_name,
    approved_request_body,
    idempotency_key=operation_id,
)
```

## Safe errors

All public exceptions derive from `WedgeApiError`. HTTP failures expose only
`status_code` and a sanitized `request_id`; response bodies, credentials, and
request bodies are never included:

```python
from wedge import WedgeApiError

try:
    result = client.call(approved_action_name, approved_request_body)
except WedgeApiError as error:
    status_code = error.status_code
    request_id = error.request_id
```

Logging those two fields is safe. Do not log the request, response, exception
locals, client instance, or environment.

## Run tests

Tests use injected fake HTTP sessions and never contact Google, the Gateway, or
either clinical portal:

```console
cd clients/python
../../.venv-wedge-api/bin/python -m unittest discover -s tests -v
```
