JessicaHerbert/sleep-screening

Sleep Screening

A note tab that appears on Sleep Intake visits and runs the three standard sleep screeners in one place: STOP-BANG (apnea risk), the Epworth Sleepiness Scale (daytime sleepiness), and the Insomnia Severity Index. Each screener scores itself at the point of care, commits to the note as a structured questionnaire result, and drives the next step - a staged diagnosis and a sleep-study task the clinician reviews and commits.

What it does

• Adds a "Sleep Screening" tab to a note, shown only when the note's structured reason for visit matches the configured trigger code.
• Renders all three instruments in-app. STOP-BANG pre-fills Age, Sex, and BMI from the chart (BMI is derived from the latest committed height and weight; if either is missing, that point is omitted and noted).
• Scores each instrument live. When the provider saves an instrument, its questionnaire commits to the note and a structured score result is written.
• Offers a curated menu of common sleep-medicine ICD-10 codes, with provisional codes pre-checked for positive screens. Selected diagnoses are staged (not committed) for clinician review.
• Stages a sleep-study task (in-clinic PSG or at-home HSAT) assigned to the queue.
• On completion the tab returns focus to the note so the provider can review and commit the staged items.

Problem it solves

Sleep practices screen nearly every patient with the same three validated instruments, and today those are scored by hand while ordering a study means bolting an order action onto a diagnosis. This plugin puts the three screeners in the note, scores them at the point of care, and turns a positive screen into a reviewed diagnosis and a sleep-study task, so the visit opens with risk already quantified and the next step one click away.

Who it's for

Sleep-medicine clinicians and any provider who runs sleep screening during a visit. It is built for in-visit charting on trial and demo instances, so it never touches the Patient Portal.

How to install

1. Install the plugin into your Canvas instance:

    canvas install --host <your-instance> /path/to/sleep_screening/sleep_screening
    ```

2. (Optional) Set the reason-for-visit trigger and diagnosis menu with `--variable`, or later via `canvas config set`:

```bash
    canvas config set sleep_screening RFV_TRIGGER_CODE=sleep-intake --host <your-instance>
    ```

3. Open a note whose structured reason for visit matches `RFV_TRIGGER_CODE` (default `sleep-intake`). The "Sleep Screening" tab appears on that note.

The three questionnaires install with the plugin, so they exist even if the instance has none configured.

### Screenshots or screen recordings

<img width="3058" height="1716" alt="screenshot-CleanShot07212026018015@2x" src="https://github.com/user-attachments/assets/1ed415b9-6968-4b63-9da1-edf3cfc1efe1" />

### Configuration (secrets)

| Secret                  | Default                | Purpose                                                                     |
|------------------------|-----------------------|-----------------------------------------------------------------------------|
| `RFV_TRIGGER_CODE`     | `sleep-intake`        | The reason-for-visit code that makes the tab appear.                       |
| `RFV_TRIGGER_SYSTEM`   | `INTERNAL`            | Informational; the tab matches on the code value.                          |
| `SLEEP_DX_CODES`       | (built-in list)       | Optional JSON array of `{"code": ..., "display": ...}` to override the diagnosis menu. |

### Structure

- `applications/sleep_screening_app.py` \- the note tab (NoteApplication), gated on the reason for visit.
- `handlers/sleep_screening_api.py` \- SimpleAPI serving the UI and the commit/stage endpoints.
- `handlers/scorer_handler.py` \- writes the structured score after each questionnaire commits.
- `scoring/` \- pure-function scorers for the three instruments.
- `questionnaires/` \- the three bundled questionnaire definitions (install regardless of instance config).
- `templates/sleep_screening.html` \- the in-app UI.