hebrah

Official Python SDK for the hebrah Isolated Health Environments & Connectivity Control Plane (hebrah-api).

Install

pip install hebrah

Requires Python 3.10+.

Quick start (Isolated Health Environments)

HebrahClient automatically resolves HEBRAH_API_KEY, HEBRAH_ENVIRONMENT_ID, HEBRAH_CONNECTION_ID, and HEBRAH_API_BASE_URL from environment variables when omitted.

from hebrah import HebrahClient

# Automatically reads HEBRAH_API_KEY and HEBRAH_ENVIRONMENT_ID from os.environ
with HebrahClient() as client:
    # 1. Inspect attached database module schema (PostgreSQL 16, SQLite, etc.)
    schema = client.db.schema()

    # 2. Execute a credential-blind parameterized SQL query
    result = client.db.query(
        "SELECT id, first_name, last_name, mrn FROM patients WHERE status = $1 LIMIT 10",
        params=["active"],
    )
    print(f"Returned {result['row_count']} rows:")
    for row in result["rows"]:
        print(row)

    # 3. Read FHIR R4 resources directly using your API key or SMART token
    bundle = client.fhir.search("Patient", {"_count": 5})

    # 4. Inspect environment EHR summary & hash-chained audit logs
    ehr = client.environments.get_ehr_summary()
    logs = client.environments.logs(limit=20)

Webhook verification

from hebrah import verify_webhook_signature

payload = verify_webhook_signature(
    request.get_data(),
    request.headers.get("X-Hebrah-Signature"),
    webhook_secret,
)

Security

• Store HEBRAH_API_KEY and HEBRAH_WEBHOOK_SECRET in server-side environment variables or a secrets manager only — never expose them to browsers or commit .env files.
• The SDK does not persist credentials; they live in memory for the lifetime of each HebrahClient instance.
• base_url (and HebrahAgentHarness endpoints) must use https:// in production, or http://localhost / http://127.0.0.1 for local dev — other http:// hosts are rejected at construction to prevent API-key exfiltration.
• All dynamic URL path segments are validated against path-traversal sequences (., .., control characters) and percent-encoded.
• Treat HebrahApiError.detail as operator-only diagnostics. Do not log or return it to end users — it may contain internal paths or sensitive API error payloads. Set include_error_detail=False on HebrahClient to omit detail from errors.

See SECURITY.md for supported versions and vulnerability reporting.

API surface (v0.9)

Isolated Health Environments (client.environments)

Credential-Blind Database Queries (client.db)

FHIR R4 & SMART on FHIR (client.fhir, client.smart)

Scoped Connections & Audit (client.connections)

Agent Wallet & Metering (client.agent)

Sandbox, HL7 & Webhooks (client.sandbox, client.webhooks)

Configuration

Docs

Full integrator reference: hebrah-app /docs/sdk.

Examples

Runnable Python snippets live in examples/:

• catalog.py — fetch the sandbox catalog
• verify_webhook.py — verify an X-Hebrah-Signature
• trigger_mock_event.py — fire a mock event

License

MIT