36cb742ce7
Three things, one subject: making CI say the truth about this repo.
## The red on every run was ours, not the runners'
Every docker-build run came back success, success, failure — the same
shape for weeks. The failing job was `deploy`, and it was failing to
*not run*:
if: ${{ github.event.inputs.deploy == 'true' }}
On a push there is no github.event.inputs at all. This Forgejo does not
treat that as false and skip; it dispatches the job, the runner cannot
resolve it, and the task ends in "Early termination". The runners were
never at fault, and nothing about them needed changing.
The `'runs-on' key not defined` line is a red herring: the `build` job
prints it too and succeeds. It names the job's *needs* target, not the
job, and the old android-apk workflow used `needs:` happily for months.
Deploy is now its own workflow with only workflow_dispatch — no
condition to evaluate, so nothing can be dispatched by mistake. No job
in either file now carries a job-level `if`. The one conditional left is
a *step* (push to registry), and step conditions are evaluated by the
runner once the job is already running, which is why that one has always
worked.
## dev and main
docker-build now runs on `dev` as well. Both branches prove the same two
things — tests pass, image builds — and only `main` publishes the image,
so nothing on `dev` can be mistaken for something deployable. Deploying
stays a person pressing a button after looking at the change.
CONTRIBUTING.md documents the flow.
## Android
Removed: the mobile/ Capacitor project, docs/mobile-build.md, and the
Android bits of scripts/release.sh. All of it is in git history — 4613a278
is the last commit that had it — for when it is rebuilt.
src/utils/platform.js stays. isMobileClient only decides token lifetime,
it is twelve lines, and it is the contract a future app would come back
to; deleting it would be a change to auth for no gain.
.github/workflows/ went too — all five. There is no GitHub remote on
this repository, so none of them has ever run, and two of them wrote
into mobile/ paths that no longer exist.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Dv6sqaY6Vq3ChZHMem3cnU
186 lines
8.5 KiB
Markdown
186 lines
8.5 KiB
Markdown
# 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=<strong-database-password>
|
|
|
|
AI_PROVIDER=litellm
|
|
LITELLM_API_BASE=https://your-litellm.example/v1
|
|
LITELLM_API_KEY=<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.
|