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

---

## 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
```