pediatric-ai-scribe-v3/README.md

# 🩺 Pediatric AI Scribe v3

AI-powered clinical documentation platform for pediatric medicine. Generates HPIs, hospital courses, chart reviews, SOAP notes, and developmental milestone assessments from voice recordings or dictation — in seconds, in plain copy-ready text.

## Features

- **Live Encounter → HPI** — record a live doctor-patient conversation, AI generates a structured OLDCARTS HPI
- **Voice Dictation → HPI / SOAP** — dictate your narrative, AI cleans and restructures it
- **Hospital Course Generator** — paste progress notes, AI generates prose, day-by-day, organ-system (ICU), or psych format summaries
- **Chart Review / Precharting** — summarize outpatient, subspecialty, and ED notes into a precharting brief
- **SOAP Note Generator** — full SOAP or subjective-only from dictation
- **Well Visit / Preventive Care** — AAP 2025 Bright Futures periodicity; vaccines, screenings, billing codes; By Visit Age, Milestones, SSHADESS (12+), and Visit Note subtabs
- **Sick Visit Note** — quick documentation with auto-suggested ROS and PE systems from chief complaint
- **Developmental Milestones** — AAP/Nelson milestone tracker (birth–11 years) with narrative, structured list, or 3-sentence summary; copy to Visit Note
- **SSHADESS Assessment** — adolescent psychosocial screening for ages 12+; auto-fills into Visit Note
- **Vaccine Schedule** — full AAP immunization schedule reference
- **Catch-Up Schedule** — catch-up immunization guide
- **Plain text output** — all documents generated without markdown, ready to paste into any EHR
- **Read Aloud** — browser TTS reads generated documents; ElevenLabs (Adam voice) supported
- **Copy & Export** — one-click copy or export to Nextcloud
- **Refine & Shorten** — edit any document with plain-language AI instructions
- **Per-tab model selector** — choose fast vs. smart vs. reasoning models per task
- **Collapsible sidebar** — desktop sidebar collapses to icon rail, state persisted
- **Save & Resume** — encounters saved with unique IDs; persist across page refresh
- **Admin Panel** — user management, registration control, audit logs
- **2FA** — TOTP-based two-factor authentication
- **Multi-provider AI** — OpenRouter, AWS Bedrock, or Azure OpenAI

---

## Quick Start (Docker)

### 1. Clone and configure

```bash
git clone https://github.com/ifedan-ed/pediatric-ai-scribe-v3.git
cd pediatric-ai-scribe-v3
cp .env.example .env
```

Edit `.env` — at minimum set:

```env
OPENROUTER_API_KEY=sk-or-v1-...
OPENAI_API_KEY=sk-...          # for Whisper transcription
JWT_SECRET=<64-char random string>
DB_PASSWORD=<strong password>
APP_URL=https://your-domain.com
```

Generate a strong JWT secret:
```bash
openssl rand -hex 32
```

### 2. Start

```bash
docker compose up -d
```

App runs on **port 3552** by default. The first user to register becomes admin automatically.

### 3. Admin CLI (inside container)

```bash
docker exec pediatric-ai-scribe node admin-cli.js list-users
docker exec pediatric-ai-scribe node admin-cli.js create-admin admin@example.com password123 "Dr. Admin"
docker exec pediatric-ai-scribe node admin-cli.js make-admin user@example.com
docker exec pediatric-ai-scribe node admin-cli.js reset-password user@example.com newpassword
docker exec pediatric-ai-scribe node admin-cli.js toggle-registration
docker exec pediatric-ai-scribe node admin-cli.js stats
```

---

## Docker Hub

```bash
docker pull danielonyejesi/pediatric-ai-scribe-v3:latest
```

### Minimal docker-compose without building

```yaml
services:
  app:
    image: danielonyejesi/pediatric-ai-scribe-v3:latest
    ports:
      - "3552:3000"
    env_file: .env
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: pedscribe
      POSTGRES_USER: pedscribe
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - pgdata:/var/lib/postgresql/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U pedscribe"]
      interval: 10s
      retries: 5

volumes:
  pgdata:
```

---

## AI Provider Configuration

Switch providers by changing `AI_PROVIDER` in `.env`. No code changes needed.

### OpenRouter (default — cheapest, NOT HIPAA)

```env
AI_PROVIDER=openrouter
OPENROUTER_API_KEY=sk-or-v1-...
```

### AWS Bedrock (HIPAA compliant with BAA)

```env
AI_PROVIDER=bedrock
AWS_BEDROCK_REGION=us-east-1
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...
```

Or use an IAM role (no keys needed when running on EC2/ECS — just set the region).

Available Bedrock models (auto-selected when `AI_PROVIDER=bedrock`):
- vendor model Opus 4.6 — best language nuance (`anthropic.agent-config-opus-4-6-20251001-v1:0`)
- vendor model Sonnet 4.6 — recommended (`anthropic.agent-config-sonnet-4-6-20251001-v1:0`)
- vendor model Sonnet 4 (`anthropic.agent-config-sonnet-4-20250514-v1:0`)
- vendor model 3.5 Sonnet (`anthropic.agent-config-3-5-sonnet-20241022-v2:0`)
- vendor model 3 Haiku — cheapest (`anthropic.agent-config-3-haiku-20240307-v1:0`)
- Llama 3.1 70B / 8B
- Mistral Large

### Azure OpenAI (HIPAA compliant with BAA)

```env
AI_PROVIDER=azure
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
AZURE_OPENAI_API_KEY=...
AZURE_DEPLOYMENT_NAME=gpt-4o-mini
AZURE_OPENAI_API_VERSION=2024-02-01
```

---

## Transcription (Speech-to-Text)

Two providers supported. The app auto-selects AWS Transcribe when `AWS_BEDROCK_REGION` is set, otherwise falls back to OpenAI Whisper.

### Amazon Transcribe (recommended for clinical use — HIPAA eligible)

Uses your existing Bedrock AWS credentials. No S3 bucket required — audio streams directly to AWS.

**Requires `ffmpeg` installed on the server** (handles audio format conversion from browser WebM to PCM). The Docker image includes ffmpeg automatically.

```env
# Auto-enabled when AWS_BEDROCK_REGION is set.
# To force it explicitly:
TRANSCRIBE_PROVIDER=aws

# Amazon Transcribe Medical — trained on clinical speech.
# Knows drug names, diagnoses, procedures. Recommended.
AWS_TRANSCRIBE_MEDICAL=true
AWS_TRANSCRIBE_SPECIALTY=PRIMARYCARE
# Other specialty options: CARDIOLOGY, NEUROLOGY, ONCOLOGY, RADIOLOGY, UROLOGY
```

Install ffmpeg on non-Docker servers:
```bash
# Ubuntu/Debian
sudo apt-get install -y ffmpeg

# Amazon Linux / RHEL
sudo yum install -y ffmpeg

# macOS
brew install ffmpeg
```

### OpenAI Whisper (default fallback)

```env
OPENAI_API_KEY=sk-...
# Optionally force Whisper even when AWS is configured:
# TRANSCRIBE_PROVIDER=openai
```

---

## OpenID Connect / SSO (optional — PocketID, Keycloak, Azure AD, etc.)

Enable Single Sign-On authentication with any OpenID Connect provider. Users can log in with their SSO provider, and existing accounts are automatically linked by email.

**Supported providers:** PocketID, Keycloak, Azure AD / Entra ID, Okta, Google Workspace, and any OIDC-compliant provider.

### Quick Setup

1. Register this app with your OIDC provider using callback URL:
   ```
   https://your-domain.com/api/auth/oidc/callback
   ```

2. Log into the app as admin and navigate to **Admin Panel** → **Settings**

3. Configure OIDC settings:
   - Enable OIDC
   - Set Issuer URL (e.g., `https://id.example.com`)
   - Enter Client ID and Client Secret from your provider
   - Customize the button label (e.g., "Sign in with PocketID")

4. Save and test the login

**Detailed setup guide with examples for all providers:** [OPENID_SETUP.md](OPENID_SETUP.md)

### Linking Existing Users

When a user signs in via SSO, the system automatically links their account if the email matches an existing user. No manual intervention needed.

For advanced scenarios (manual linking, CLI commands, troubleshooting), see [OPENID_SETUP.md](OPENID_SETUP.md).

---

## Email (optional — for verification & password reset)

Without SMTP configured, email verification is skipped and users are auto-verified on registration.

```env
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password
SMTP_FROM=noreply@yourdomain.com
```

---

## Environment Variables Reference

| Variable | Required | Description |
|---|---|---|
| `OPENROUTER_API_KEY` | If using OpenRouter | OpenRouter API key |
| `AI_PROVIDER` | No | `openrouter` (default), `bedrock`, or `azure` |
| `AWS_BEDROCK_REGION` | If using Bedrock | e.g. `us-east-1` |
| `AWS_ACCESS_KEY_ID` | If using Bedrock (no IAM role) | AWS access key |
| `AWS_SECRET_ACCESS_KEY` | If using Bedrock (no IAM role) | AWS secret key |
| `AZURE_OPENAI_ENDPOINT` | If using Azure | Azure OpenAI endpoint URL |
| `AZURE_OPENAI_API_KEY` | If using Azure | Azure API key |
| `AZURE_DEPLOYMENT_NAME` | If using Azure | Deployment name, e.g. `gpt-4o-mini` |
| `OPENAI_API_KEY` | For Whisper transcription | OpenAI key (Whisper fallback) |
| `TRANSCRIBE_PROVIDER` | No | `aws` or `openai` — auto-detected from AWS config |
| `AWS_TRANSCRIBE_MEDICAL` | No | `true` to use Transcribe Medical (clinical accuracy) |
| `AWS_TRANSCRIBE_SPECIALTY` | No | `PRIMARYCARE` (default), `CARDIOLOGY`, `NEUROLOGY`, etc. |
| `ELEVENLABS_API_KEY` | No | ElevenLabs TTS (optional) |
| `JWT_SECRET` | **Yes** | Random 64-char string — keep secret |
| `DATABASE_URL` | No | PostgreSQL URL (auto-set by docker-compose) |
| `DB_PASSWORD` | **Yes** | PostgreSQL password |
| `APP_URL` | Recommended | Public URL e.g. `https://scribe.example.com` (used for CORS, emails) |
| `PORT` | No | Internal port, default `3000` |
| `SMTP_HOST` | No | SMTP server for email |
| `SMTP_PORT` | No | Default `587` |
| `SMTP_USER` | No | SMTP username |
| `SMTP_PASS` | No | SMTP password / app password |
| `SMTP_FROM` | No | From address for emails |

---

## HIPAA Notice

This application processes data through third-party AI APIs.

- ✅ All connections use HTTPS/TLS
- ✅ Authentication required for all AI endpoints
- ✅ 2FA available
- ✅ No patient data stored on server (only audit logs)
- ⚠️ **OpenRouter does not offer a BAA** — do not use with real PHI
- ✅ **AWS Bedrock** and **Azure OpenAI** offer BAAs — suitable for PHI with proper configuration

**Recommendation:** Do not enter real patient data until your organization has executed BAAs with all AI providers in use.

---

## Development

```bash
npm install
cp .env.example .env   # edit with your keys
# Requires a running PostgreSQL instance (see DATABASE_URL in .env)
node server.js
```