Cavell Prism Client

Python client for Cavell Prism — extract structured FHIR resources from clinical notes and persist them to your own FHIR server.

Cavell never connects to your FHIR server. Your system sends clinical text to the Prism API, receives extracted resources back, and persists them locally with your own credentials. Cavell has no access to your database and stores no credentials: every request carries your own LLM Gateway key.

Installation

pip install cavell-prism-client

Or with uv:

uv add cavell-prism-client

The import name is cavell_client.

Quickstart

You need a Prism API URL (https://prd.prism.cavell.app/api) and an LLM Gateway key — contact your Cavell representative for a key. For a local FHIR server, docker compose up -d in this repo starts HAPI on http://localhost:8090.

from cavell_client import CavellClient, IngestionPipeline
from cavell_client import Organization, Patient, Document

with CavellClient(
    api_url="https://prd.prism.cavell.app/api",
    api_key="<your LLM Gateway key>",
    fhir_base_url="http://localhost:8090",
) as client:
    pipeline = IngestionPipeline(client, default_organization="CGH-001")

    # 1. Seed reference data and patients
    pipeline.seed(
        organizations=[Organization(identifier="CGH-001", name="City General")],
        patients=[Patient(identifier="MRN-1", managing_organization="CGH-001")],
    )

    # 2. Extract clinical notes (per patient, in date order) and persist
    outcomes = pipeline.extract(
        [
            Document(
                text="Patient diagnosed with type 2 diabetes...",
                patient_identifier="MRN-1",
                date="2024-01-15",
                document_id="note-001",
            ),
        ]
    )
    for outcome in outcomes:
        print(outcome)

Extraction is resume-safe (skip_processed=True by default), retries transient failures, and aborts cleanly on auth/gateway outages. A document older than the patient's newest already-extracted note is refused — extraction is context-aware and only moves forward in time. Refusal is per document: the offender comes back as a failed outcome with out_of_order=True having spent nothing, and the rest of the call is extracted as normal.

For a whole dataset, use pipeline.extract_all(documents, batch_size=500): it sorts every document by ascending date before splitting it into batches, so each patient's notes are extracted oldest-first even when they span batches. extract() makes a single pass and its limit caps that pass rather than chunking it.

Clinical validation

Every extracted resource carries an unvalidated meta tag. When a clinician has reviewed a resource, remove the tag; any later update re-adds it:

client.list_unvalidated_resources(patient_fhir_id, "Condition")  # review queue
client.mark_validated("Condition", condition_id)  # $meta-delete

Documentation

Setup guides, the pipeline walkthrough, and demo notebooks (synthetic data): polaris-health.github.io/cavell-prism-client

Contributing & security

See CONTRIBUTING.md for development setup and the release process, and SECURITY.md for how to report vulnerabilities.

License

MIT