This repository is a fork of OpenEMR extended with an AI clinical co-pilot for primary care physicians, built for the Gauntlet AI Austin admission sprint.
Week 2 final demo video: link landing here once recorded — see W2_DEMO_SCRIPT.md for the 5:00 walkthrough
The MVP passed Wednesday with the note "harden the UX and reliability, and stronger visibility into the retrieval architecture, eval coverage, and worker orchestration." Everything below shipped after that grade in direct response, plus the two surprise-challenge additions:
| Area | Shipped | Where |
|---|---|---|
| Visibility | /visibility page — corpus inspector, ASCII supervisor graph, deterministic routing rule table, eval coverage with locked-baseline rates, recent supervisor decisions, live retrieval inspector showing BM25 / dense / rerank scores per chunk before any LLM sees them |
https://copilot-agent-production-ba87.up.railway.app/visibility |
| UX hardening | Retry button on every error / refusal message in the chat panel; per-status friendly HTTP error copy (502/503/504/401/403/429 each get specific actionable text instead of "Server returned 502") | interface/modules/custom_modules/oe-module-clinical-copilot/public/js/copilot-chat.js |
| Multi-format ingestion (W2 surprise #1) | HL7 v2 ORU + ADT (structured parse, zero LLM cost), DOCX referral letters, XLSX patient workbooks, TIFF fax packets — all routed through /agent/extract with the appropriate doc_type. Cohort 5 W2 asset pack is committed as fixtures + a smoke runner |
agent-service/src/copilot/extraction/{hl7v2,docx,xlsx,tiff}.py |
| Modern dashboard (W2 surprise #2) | Next.js 15 + Auth.js v5 OIDC against OpenEMR's existing OAuth flow. Six clinical cards + bidirectional cross-app navigation. Defense in PATIENT_DASHBOARD_MIGRATION.md | dashboard/ |
| Cookbook stages 3-5 (production-evals reference) | Replay harness (--record / --replay JSONL), LLM-as-judge tier (judge_yes_no on Haiku for clinical-quality binary checks), A/B experiment diff (compare two recordings side-by-side) |
agent-service/evals/w2/{replay,judge,experiments}.py |
| Eval gate | Locked at 63 cases / 11 categories / 6 rubrics / 100% baseline. PR-blocking GitHub Action enforces ≥95% per category (5pp regression delta) | .github/workflows/eval-gate.yml |
| Document | Purpose |
|---|---|
| SETUP.md | Bring the stack up locally (docker compose up -d) |
| AUDIT.md | Security / performance / architecture / data-quality / compliance audit of the OpenEMR codebase |
| USERS.md | Target user (PCP, 20-patient day) and the use cases the agent addresses |
| W1_ARCHITECTURE.md | Week 1 AI integration plan — verification, observability, failure modes, scaling |
| W2_ARCHITECTURE.md | Week 2 multimodal evidence agent — schemas, vision pipeline, hybrid RAG, supervisor + worker graph, eval gate |
| THREAT_MODEL.md | Week 3 attack surface map for the adversarial platform — 6 categories, highest-risk findings, coverage prioritization |
| ARCHITECTURE.md | Week 3 multi-agent adversarial-platform architecture — Orchestrator / Red Team / Judge / Documentation agents, inter-agent comms, regression harness, observability |
| PATIENT_DASHBOARD_MIGRATION.md | Week 2 surprise port — defense of Next.js 15 + Auth.js v5 framework choice for the FHIR-backed patient dashboard |
| W1_COSTS.md | W1 cost & scale projections (100 → 100K users) |
| W2_COSTS.md | Week 2 cost & latency report — vision / RAG / multi-format / cookbook tier / dashboard, p50/p95, bottleneck analysis |
| COSTS.md | Week 3 adversarial-platform cost analysis — per-attempt decomposition, dev spend, projections at 100/1K/10K/100K runs/day, architectural changes per scale |
| DEMO_SCRIPT.md / W2_DEMO_SCRIPT.md | W1 / W2 demo video scripts |
| INTERVIEW_PREP.md | AI-interview talking points keyed to repo artifacts |
| W2_PRESEARCH.md | W2 architectural-discovery checklist (16 questions) — design rationale for the Clinical Co-Pilot |
| PRESEARCH.md | Week 3 architectural-discovery checklist (11 sections × 3 phases) — design rationale for the adversarial platform that attacks the W2 target |
| EVIDENCE.md | Week 3 — one finding traced end-to-end (Orchestrator decision → Red Team attack → target response → Judge verdict → Documentation Agent → trust gate → W2 eval gate). Each step links to the deployed URL where the artifact can be inspected directly. |
W3 hard gate — deployed target URL (the live system the adversarial platform attacks; required with every checkpoint per the W3 PRD):
https://copilot-agent-production-ba87.up.railway.app
Health check: GET /healthz → {"status":"ok"}. The Red Team Agent's
httpx.AsyncClient (agent-service/src/redteam/target.py) points at
this base URL by default; every attempt in
agent-service/evals/redteam_runs/ records the real status code +
response body from this endpoint. Nothing is mocked.
Deployed apps:
- Embedded co-pilot (PHP module rendered into the patient chart): https://openemr-production-0996.up.railway.app/
- Modern dashboard (Next.js port of the patient chart): https://openemr-dashboard-production.up.railway.app/
- System visibility page (W2: corpus, routing, eval coverage, live retrieval inspector): https://copilot-agent-production-ba87.up.railway.app/visibility
- Adversarial platform dashboard (W3: coverage, vuln pipeline, recent campaigns with Orchestrator rationale, attempts trend): https://copilot-agent-production-ba87.up.railway.app/adversarial
- Standalone agent UI (token-less demo / fallback): https://copilot-agent-production-ba87.up.railway.app/
Reviewer entry points:
- No login required:
- /visibility — W2 agent introspection (corpus, routing, eval coverage, live retrieval inspector)
- /adversarial — W3 platform operator view (92 attempts of evidence, 3 live + 7 pending vulns, Orchestrator rationale per campaign)
- The standalone agent UI (token-less /demo/chat)
- OpenEMR login required:
- The embedded co-pilot panel (Farrah Rolle is a good demo patient with rich data)
- OAuth flow on first hit:
- The Next.js dashboard (signs in against OpenEMR's existing OIDC server)
Stack:
- OpenEMR (PHP 8.2 + Apache + MariaDB) →
interface/modules/custom_modules/oe-module-clinical-copilot/embedded chat panel agent-service/— Python (FastAPI + Anthropic Claude) → Redis context cache → Langfuse traces. Hybrid RAG (BM25 + Voyage + Cohere Rerank) over a 24-chunk USPSTF / ADA / ACIP / ACC-AHA / CDC guideline corpus- Multi-format ingestion: PDF (vision), HL7 v2 ORU + ADT (structured parse), DOCX referral letters, XLSX workbooks, TIFF fax packets
dashboard/— Next.js 15 (App Router, React 19 server components)- Auth.js v5 OIDC against OpenEMR's
/oauth2/defaultendpoint
- Auth.js v5 OIDC against OpenEMR's
- Four+1 Railway services: OpenEMR + agent + Redis + MySQL + dashboard
Quick start (local):
docker compose up -d # OpenEMR + MariaDB + phpMyAdmin
docker compose logs -f openemr # watch first-boot install (~5 min)
# then open http://localhost:8080 (admin / pass)Quick start (Railway deploy):
railway login
railway init # create a new project
railway add --plugin mysql # provision the MariaDB plugin
railway up # build + deploy from this Dockerfile
# then configure env vars in the Railway dashboard (see Dockerfile header)
OpenEMR is a Free and Open Source electronic health records and medical practice management application. It features fully integrated electronic health records, practice management, scheduling, electronic billing, internationalization, free support, a vibrant community, and a whole lot more. It runs on Windows, Linux, Mac OS X, and many other platforms.
OpenEMR is a leader in healthcare open source software and comprises a large and diverse community of software developers, medical providers and educators with a very healthy mix of both volunteers and professionals. Join us and learn how to start contributing today!
Already comfortable with git? Check out CONTRIBUTING.md for quick setup instructions and requirements for contributing to OpenEMR by resolving a bug or adding an awesome feature 😊.
Community and Professional support can be found here.
Extensive documentation and forums can be found on the OpenEMR website that can help you to become more familiar about the project 📖.
Report these on the Issue Tracker. If you are unsure if it is an issue/bug, then always feel free to use the Forum and Chat to discuss about the issue 🪲.
Check out SECURITY.md
Check out API_README.md
Check out DOCKER_README.md
Check out FHIR_README.md
If using OpenEMR directly from the code repository, then the following commands will build OpenEMR (Node.js version 24.* is required) :
composer install --no-dev
npm install
npm run build
composer dump-autoload -oThis project exists thanks to all the people who have contributed. [Contribute].
Thanks to our ONC Certification Major Sponsors!