# Ped-AI Ped-AI is a pediatric clinical documentation, education, and bedside decision-support app. This fork has moved well beyond the original scribe app: it now combines encounter documentation, clinical workflows, private teaching material, admin controls, MCP-backed clinical assistant integration, Redis-backed operational state, and hardened deployment defaults. The app runs as an authenticated Express/Postgres service with a browser frontend and optional integrations for LiteLLM, AWS, OpenAI-compatible APIs, Nextcloud WebDAV, S3-compatible storage, OpenBao, Redis, OIDC, TOTP, and Cloudflare Turnstile. ## Current Scope ### Clinical Documentation - Live encounter capture with structured pediatric HPI generation. - Dictation cleanup for narrative notes. - SOAP, sick visit, well visit, hospital course, chart review, precharting, and ED encounter workflows. - Parent-facing education handouts generated from clinician notes, with diagnosis, medication, emergency-care guidance, and preferred-language support. - Pediatric developmental milestone tooling. - Templates, physician memory, and per-tab model overrides. - Server-side speech-to-text routing through configured providers. ### Bedside Tools - Pediatric calculators and emergency dosing helpers. - PE guide and clinical reference content. - Vaccines, catch-up schedules, growth/vitals, bilirubin, BSA, GCS, equipment, and resuscitation helpers. - Mobile-friendly PWA layout for bedside use. - Per-user phone extension and pager directory with soft-delete, search, ZIP export, and JSON/ZIP import for handoff between users. ### My Resources - Private teaching material any signed-in user can generate for themselves — nobody else sees it. - Presentations are designed as slide decks (comparisons, tables, callouts, figures beside text), not written as markdown for a parser to guess at. - Grounded in the indexed clinical library, and optionally PubMed and the web, each admin-enabled. - Optional illustrations, several per resource, placed through the deck. - Revise in place, and download as PowerPoint, Word or PDF. See [docs/my-resources.md](docs/my-resources.md). ### Clinical Assistant - Optional MCP-backed clinical assistant integration. - Prompt suggestions backed by Redis operational cache. - No clinical answer response caching. - Designed to retrieve from indexed clinical material while keeping provider selection explicit. ### Admin And Security - Sign in with a password or a six-digit code emailed to you — offered side by side, because a code depends on mail arriving and a password does not. - Role-based access, TOTP 2FA, OIDC/SSO, email verification, and optional Turnstile. Passwords are argon2id, with bcrypt rows rehashed on their next sign-in. - Registration can be open, closed, or invite-only with generated codes. A code can be revoked while live, and deleted only once it is spent. - Admin panel for users, settings, prompts, models, and logs. - Audit, API, access, and client-error logs with redaction hardening. - OpenBao secret loading support at container startup. - S3-compatible document storage support. ## Removed Browser STT Browser Whisper has been removed from the runtime. The app should not ship browser Whisper workers, browser-local Whisper model downloads, Transformers.js browser STT, or Browser Whisper setup docs. Speech-to-text is handled server-side through configured providers such as Google/Gemini, AWS Transcribe, LiteLLM, or OpenAI Whisper. Browser-native Web Speech remains gated behind an explicit user setting when present in the browser — it is off unless a user turns it on, because Chrome and Edge send that audio to Google. ## Quick Start ```bash cp .env.example .env ./scripts/build-image.sh docker compose up -d --no-build ``` The default compose exposes the app on `127.0.0.1:3552` and starts: - `pediatric-ai-scribe` for the Node app. - `pedscribe-db` for Postgres with pgvector. - `ped-ai-redis` for operational Redis state. Health check: ```bash curl -fsS http://127.0.0.1:3552/api/health ``` Prometheus metrics are exposed at `GET /metrics` with the `ped_ai_` metric prefix. The first registered user becomes an admin unless registration has already been configured differently. ## Core Environment Set real values in `.env` before production use. ```env APP_URL=https://your-domain.example JWT_SECRET=<64-char-random-secret> DB_PASSWORD= AI_PROVIDER=litellm LITELLM_API_BASE=https://your-litellm.example/v1 LITELLM_API_KEY= TRANSCRIBE_PROVIDER=litellm LITELLM_STT_MODEL=whisper-1 REDIS_URL=redis://ped-ai-redis:6379 ``` Supported text AI providers are LiteLLM, OpenRouter, AWS Bedrock, and Azure OpenAI. Speech-to-text and text-to-speech both route through LiteLLM, so the upstream speech vendor is a gateway configuration choice rather than an app one; browser-native Web Speech stays off unless a user opts in. ## Admin CLI ```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 ``` ## Maintenance The app checks Postgres collation drift on startup and can reindex text indexes after image or OS-library changes. ```bash docker exec pediatric-ai-scribe npm run maint:check docker exec pediatric-ai-scribe npm run maint:reindex ``` Run the reindex command after major Postgres image changes, restoring a dump from another distro, or seeing lookup behavior that suggests collation/index drift. ## Testing Run the Node test suite: ```bash npm test ``` Run syntax checks for touched files when doing focused backend work: ```bash node --check server.js node --check src/routes/transcribe.js ``` Run the Playwright smoke suite against the e2e compose stack: ```bash docker compose -f docker-compose.yml -f docker-compose.e2e.yml up -d pediatric-scribe-e2e npm run e2e ``` ## Deployment Notes - Put the app behind HTTPS before clinical use. - Use only AI/STT/TTS providers covered by your BAA and data-processing requirements. - Configure OIDC/SSO and 2FA for production users. - Keep `JWT_SECRET`, database credentials, provider keys, S3 keys, SMTP credentials, and OpenBao tokens out of git. - Treat logs as sensitive operational data even with redaction enabled. - Use the Caddy/reverse-proxy layer to expose only intended public routes. ## Documentation Primary references: - `docs/architecture.md` — system map, repository layout, request pipeline, and service boundaries. - `docs/developer-guide.md` — day-to-day code-change workflow, route and module reference. - `docs/module-conventions.md` — CommonJS, ESM, globals, and rendering rules. - `docs/features-explained.md` — what each feature is, in plain terms. - `docs/api-reference.md` — API routes. - `docs/configuration.md` — environment variables and live `app_settings`. - `docs/database.md` — every table, its columns, and what is encrypted. - `docs/migrations.md` — how schema changes are made and applied. - `docs/authentication.md` — auth, OIDC, sign-in codes, invites, rate limits. - `docs/ai-providers.md` — provider selection, prompts, injection hardening. - `docs/clinical-assistant.md` — MCP-backed assistant behavior and safety rules. - `docs/retrieval-tuning.md` — how much corpus each feature retrieves, and what it costs. - `docs/global-prompt-administration.md` — prompt overrides and the conversation budget. - `docs/speech.md` — STT, TTS, recording, and audio backups. - `docs/my-resources.md` — private teaching material, the slide renderer, and search sources. - `docs/deployment.md` — production deployment. - `docs/scaling.md` — scaling priorities and readiness work. - `docs/openid-setup.md` — OIDC provider setup. - `docs/ops-docs-ped-ai-and-milvus.md` — operational notes for the retrieval stack. - `docs/improvements.md` — the running list of what to improve next. - `docs/logic/README.md` — the deeper code walkthrough. Some deep `docs/logic/` files still describe historical implementation details. Prefer runtime code and tests when documentation conflicts with current behavior. ## Clinical Safety Ped-AI is documentation and education support software. It does not replace clinical judgment, local policy, medication verification, or attending review. Validate generated notes, calculations, and recommendations before use in patient care.