wedge-health 0.2.0

Python SDK for the authenticated Wedge Health clinical automation API

Wedge Health Python SDK

The supported application interface is intentionally small:

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:

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:

from wedge import Wedge

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

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:

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:

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:

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:

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:

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.

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:

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:

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