HealthCloud SDK for Python

Typed Python SDK for HealthCloud services and the HealthCloud Connectors gateway.

Installation

pip install healthcloud-sdk

For local development:

pip install -e ./packages/pip

Python 3.9 or newer is required.

Create and authenticate a client

The current API uses typed request objects. Authentication returns typed response objects; after registration or login, explicitly share the access token with the whole SDK by calling set_access_token.

from healthcloud import HCSDK, LoginRequest, RegisterPatientRequest

sdk = HCSDK(environment="dev", tenant_id="your-tenant-id")

registration = sdk.auth.register(RegisterPatientRequest(
    first_name="Jane",
    last_name="Doe",
    email="patient@example.com",
    password="SecurePassword123!",
    date_of_birth="1990-06-15",
    sex_at_birth="female",
))

token = registration.access_token
if not token:
    login = sdk.auth.login(LoginRequest(
        email="patient@example.com",
        password="SecurePassword123!",
    ))
    token = login.access_token

sdk.set_access_token(token)

In UAT and production, complete email verification before login when the register response reports that verification is required.

from healthcloud import VerifyOtpRequest

sdk.auth.verify_email(VerifyOtpRequest(
    user_id=registration.cognito_sub,
    otp="123456",
))

Service clients

One HCSDK instance exposes these clients:

sdk.auth
sdk.patient
sdk.vitals
sdk.diagnostics
sdk.assistant
sdk.communications
sdk.fieldagent
sdk.mcp
sdk.connectivity
sdk.graph

# Service clients whose public SDK surface is currently connect-only:
sdk.appointments
sdk.ehr
sdk.provider
sdk.rppg
sdk.session
sdk.telehealth

Graph API

sdk.graph exposes 19 public methods, one for each Graph API route. The eight Search/Cypher methods use the rag field already present on their request models. Setting rag=True calls the same POST endpoint and returns a typed GraphRagResponse; there are no separate rag_* wrapper methods.

from healthcloud import CypherQueryRequest, ProviderSearchRequest

# Standard structured response
providers = sdk.graph.search_providers(ProviderSearchRequest(
    phrase="cardiology",
    state_code="CA",
    limit=20,
))

# Same endpoint, Graph-RAG response
provider_answer = sdk.graph.search_providers(ProviderSearchRequest(
    phrase="cardiology",
    state_code="CA",
    limit=20,
    rag=True,
))

concept_answer = sdk.graph.search_medical_concepts_cypher(CypherQueryRequest(
    query="How many medical concepts are available?",
    limit=20,
    rag=True,
))

Search/Cypher methods:

• search_providers, search_providers_cypher
• search_health_plans, search_health_plans_cypher
• search_document_summaries, search_document_summaries_cypher
• search_medical_concepts, search_medical_concepts_cypher

Additional GET-backed methods:

• search_medical_concepts_faceted, list_medical_concept_vocabularies
• list_medical_concepts, get_medical_concept
• list_medical_concept_relationships, list_medical_concept_ancestors, list_medical_concept_descendants
• list_policy_documents, search_policy_documents, get_policy_document

Together with connect, this is 19 public SDK methods. The live suite executes 29 scenarios because it tests all eight POST methods both with and without RAG, and runs faceted medical-concept search for SNOMED, RXNORM, and MESH.

All typed methods accept the request model shown in their signature and return a typed response model. Examples:

from healthcloud import SubmitVitalsRequest, UpdatePhoneRequest

patient = sdk.patient.get_patient("patient-id")

phone = sdk.patient.set_phone(
    "patient-id",
    UpdatePhoneRequest(phone="+15550001234"),
)

vitals = sdk.vitals.submit(
    "patient-id",
    SubmitVitalsRequest(
        heart_rate=72,
        systolic=120,
        diastolic=80,
    ),
)

history = sdk.vitals.get_vitals("patient-id")
tools = sdk.mcp.list_tools("patient")

Use sdk.set_access_token(new_token) whenever a token changes. This updates every authenticated service client and every connector client on the SDK instance.

Connectors

Connector methods are called through sdk.connectors; they are not raw HTTP helpers. The package contains 33 connector clients.

Architecture

Connector clients are created in three explicit steps:

1. Configure HealthCloud once through HCSDK (environment, tenant, access token).
2. Create an isolated connector client with that connector's vendor credentials via sdk.connectors.<name>.create_client(...).
3. Call typed operation methods with operation-specific parameters only.

The connector gateway URL is resolved internally from the HealthCloud environment; applications never pass connector base URLs or the HealthCloud bearer token again when creating a connector client. Each client holds its vendor credentials only on that instance and forwards them to the HealthCloud Connectors gateway (POST /connectors/<slug>/<operation>) with every request. Connector-scoped secrets cannot be overridden by operation input, and gateway errors are redacted before being raised.

Create a credential-scoped connector client explicitly. The SDK never reads connector credentials implicitly; applications can load them from their own secret manager or the local .env used by integration tests. Do not hardcode credentials in source code and do not create connector clients in client-side code.

Usage

import os

from healthcloud import HCSDK

sdk = HCSDK(
    environment="dev",
    tenant_id="your-tenant-id",
    access_token="cognito-access-token",
)

athena = sdk.connectors.athena_health.create_client(
    secret_key=os.environ["HC_ATHENA_SECRET_KEY"],
    practice_id=os.environ["HC_ATHENA_PRACTICE_ID"],
    department_id=os.environ["HC_ATHENA_DEPARTMENT_ID"],
    provider_id=os.environ["HC_ATHENA_PROVIDER_ID"],
)
patients = athena.search_patients(
    last_name="Smith",
    limit=5,
)

stripe = sdk.connectors.stripe.create_client(api_key=os.environ["HC_STRIPE_API_KEY"])
stripe_status = stripe.verify_connection()

# Public connector — no vendor credentials required
nppes = sdk.connectors.nppes.create_client()
provider = nppes.verify_provider(npi="1234567890")

# OAuth-style connector
whoop = sdk.connectors.whoop.create_client(
    client_id=os.environ["HC_WHOOP_CLIENT_ID"],
    client_secret=os.environ["HC_WHOOP_CLIENT_SECRET"],
)

Pass mode="live" only when required; mode="sandbox" is the default for mode-aware connectors. Calling sdk.set_access_token(...) propagates the new HealthCloud token to every connector client already created.

Available connectors

The table lists each connector's required credential keyword arguments and the conventional HC_* environment variable names used by the live test suite (names only — never commit values). Parameters marked mode? accept "sandbox" (default) or "live".

Note: the single quest connector covers both the REST-style order/results/catalog operations and the HL7 message-based operations, all routing to the gateway's quest slug with the same credentials.

Errors and cleanup

from healthcloud import HealthCloudHTTPError, HealthCloudNetworkError

try:
    stripe.verify_connection()
except HealthCloudHTTPError as exc:
    print(exc.status_code, str(exc))
except HealthCloudNetworkError as exc:
    print(str(exc))
finally:
    sdk.close()

Verification

From packages/pip:

.\.venv\Scripts\python.exe -m pytest -q -m "not live"

Live integration tests are opt-in and use package methods:

$env:HC_RUN_INTEGRATION="true"
$env:HC_ALLOW_REGISTER="true"
.\.venv\Scripts\python.exe -m pytest -q -m live

Do not commit .env files or connector credentials.