Metadata-Version: 2.4
Name: cavell-prism-client
Version: 0.3.0.dev202608010612
Summary: Python client for Cavell FHIR extraction API
Project-URL: Homepage, https://cavell.ai
Project-URL: Documentation, https://polaris-health.github.io/cavell-prism-client
Project-URL: Repository, https://github.com/polaris-health/cavell-prism-client
Project-URL: Changelog, https://github.com/polaris-health/cavell-prism-client/blob/main/CHANGELOG.md
Author-email: Cavell <support@cavell.ai>
License-Expression: MIT
License-File: LICENSE
Keywords: clinical,ehr,extraction,fhir,healthcare,nlp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Healthcare Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Provides-Extra: notebook
Requires-Dist: ipywidgets>=8.0; extra == 'notebook'
Requires-Dist: notebook>=7.6.1; extra == 'notebook'
Requires-Dist: tqdm>=4.70.0; extra == 'notebook'
Description-Content-Type: text/markdown

# Cavell Prism Client

[![CI](https://github.com/polaris-health/cavell-prism-client/actions/workflows/ci.yml/badge.svg?branch=develop)](https://github.com/polaris-health/cavell-prism-client/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/cavell-prism-client)](https://pypi.org/project/cavell-prism-client/)
[![Python](https://img.shields.io/pypi/pyversions/cavell-prism-client)](https://pypi.org/project/cavell-prism-client/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

Python client for [Cavell Prism](https://cavell.ai) — 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

```bash
pip install cavell-prism-client
```

Or with [uv](https://docs.astral.sh/uv/):

```bash
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`.

```python
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 up front
with `OutOfOrderDocumentError` — extraction is context-aware and only moves
forward in time.

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:

```python
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](https://polaris-health.github.io/cavell-prism-client)

## Contributing & security

See [CONTRIBUTING.md](https://github.com/polaris-health/cavell-prism-client/blob/main/CONTRIBUTING.md) for development setup and the release
process, and [SECURITY.md](https://github.com/polaris-health/cavell-prism-client/blob/main/SECURITY.md) for how to report vulnerabilities.

## License

MIT
