Jump to section
Deployment & Integration Guide
One case record in. A panel of outcome models out. Deployed inside your walls.
This guide explains what the Hoopcare inference platform is, what it needs from your Epic environment, what hardware it runs on, how fast it scores your patients, and how we keep protected health information inside your tenancy while keeping our models private. It is written for the IT, informatics, and data teams who will install and operate it.
- Endpoints in the preview catalog
- 18
- Training & validation cases
- ≈1.3M
- PHI egress — closed topology
- 0
- GPU required (core models)
- None
- To first synthetic score
- < 1 day
Performance figures on this page are preliminary internal development estimates from an unlocked analysis — not final, externally validated, partner-authorized, or approved for citation or decision-making. Sizing, throughput, and cost figures are planning estimates from internal benchmarks, confirmed at site survey. Signed model cards will carry the reportable evidence.
1. Overview
What the platform does, and the three facts every reviewer asks about first.
Hoopcare is a preoperative risk-prediction platform. For every scheduled procedure it assembles a standardized preoperative case record from your EHR and is designed to return calibrated probability estimates for a panel of postoperative outcomes (18 endpoints in this preview catalog; more in development) — mortality, MACCE, acute kidney injury, pulmonary complications, sepsis, unexpected ICU admission, transfusion and RBC units, length of stay, ASC eligibility, VTE, delirium, pain, and more — plus a single calibrated 0–100 global procedure risk score.
Three facts orient everything else in this guide:
- Closed deployment by default. The platform ships as signed containers deployed in your cloud tenancy (AWS, Azure, GCP) or on-prem. Clinical data is read from your Epic reporting databases and scored locally; write-back to the EHR is a future authorized production mode (§7, §14). In the default closed topology, patient data stays in the customer-controlled environment; the only outbound traffic is an optional license heartbeat carrying the documented non-PHI fields, and it can be disabled for air-gapped sites (§15). Hybrid and hosted topologies transmit the specific fields shown in the topology table (§6) and require separate privacy, security, and contractual review.
- Same input, every model. All models read the same preoperative case record (§4). Adding an outcome model later is a license change rather than a new integration project — provided the deployed tier already covers its features and terminology; new models still pass local evaluation and governance (§13) before use.
- Core models are boosted-tree classifiers — CPU-only, milliseconds per case. The published implementation experience this architecture builds on ran comparable models on an ordinary institutional VM with no GPU or HPC resources (Wingert et al., Br J Anaesth 2026; §18). The optional Hybrid tier adds an LLM chart-review layer, which is the only component that ever needs a GPU — and it can instead use your existing BAA-covered LLM endpoint.
Evidence status
Models are being developed on approximately 1.3 million surgical cases from a partner academic health system, reported per TRIPOD+AI. Final cohort definitions, evaluation splits, performance estimates, subgroup analyses, and permitted public claims are pending completion of the locked analysis and partner authorization — no figure on this preview is an observed result unless linked to a signed model card. The deployment architecture follows an external precedent: the prospectively validated Epic implementation at UCLA (Wingert et al., BJA 2026 — warehouse-validated features on a fixed cadence, a lightweight scoring VM, HL7 write-back). That paper supports the feasibility of the integration pattern for a different, single-site mortality model; it does not validate Hoopcare's models, tiers, or software.
Status at a glance
Every claim on this page carries one of five maturity states: proposed → prototype → internally verified → partner-evaluated → production-supported. Where a section does not say otherwise, read it as proposed.
| Area | Status today |
|---|---|
| Model panel & performance figures | Internally trained, pre-final — locked-cohort analysis and partner authorization pending; figures illustrative |
| Containers, engine, console | Prototype |
| Epic / Clarity mapping workbook & FHIR layer | Proposed design with prototype components; not vendor-verified |
| Hybrid LLM chart-review (MedGemma) | Prototype — task-specific extraction validation is a release gate (§6) |
| EHR write-back & clinical display | Proposed future mode, subject to regulatory classification (§14) |
| Marketplace listings, support SLAs | Planned / targets — contractual at GA |
| Assurance (SOC 2, penetration test) | SOC 2 Type II audit in progress; first third-party pen test scheduled before GA |
| Payer configurations | Not evaluation-ready — separate payer guide planned (§6) |
Typical engagements
| Engagement | What runs | Wall-clock | Your effort |
|---|---|---|---|
| Retrospective validation most common first step | Batch scoring of 3–7 years of historical cases against locally built outcome labels; joint metrics report | 4–6 weeks (§13) | 1 DBA ~3–5 days; 1 infra engineer ~2 days |
| Prospective silent pilot | Nightly scoring of the upcoming schedule; scores held in dashboard only, no EHR write-back | 2–3 weeks after retro | Config only; no new interfaces |
| Future production pathway not currently offered | Scheduled scoring + HL7/FHIR write-back, Epic patient lists, clinician dashboard — subject to the intended-use and regulatory classification in §14 | Estimated 4–8 weeks once authorized | Interface analyst + clinical governance |
2. What you deploy
Signed containers and two stateful stores. In the closed topology, PHI never crosses the boundary.
Diagram description: inside the hospital tenancy boundary, Epic reporting databases feed the hoopcare-connect container, which writes to a FHIR staging store (Medplum with PostgreSQL) and to Parquet files; the hoopcare-engine scores case records and returns results to score consumers (HL7v2 or FHIR write-back to Epic, patient lists, the clinician console, and Parquet export). An optional hoopcare-reader LLM sidecar reads notes locally. The only connection crossing the boundary is optional TLS license traffic to the Hoopcare license service, which carries no PHI.
| Component | Image | Role | State |
|---|---|---|---|
| hoopcare-connect | registry.hoopcare.com/connect | Extracts from Clarity/Caboodle (or FHIR), assembles the case record, runs data-quality checks | Stateless; writes to feature store |
| hoopcare-engine | registry.hoopcare.com/engine | Scores case records against licensed models; serves REST API and batch jobs; emits Prometheus metrics | Stateless |
| hoopcare-reader | registry.hoopcare.com/reader | Optional (Hybrid tier). LLM chart review of preoperative notes into 16 bounded features — six acuity axes, composite gravity, cardiac findings, procedure interpretation, data sufficiency. Ships MedGemma (27B default, 4B small-GPU profile) served locally via vLLM — no external calls in the closed topology; note text and note-derived outputs follow the site-configured retention policy — or routes to your BAA-covered LLM endpoint | Stateless; GPU or external LLM endpoint |
| hoopcare-console | registry.hoopcare.com/console | Web console: schedule view, score explorer, QC and drift dashboards, audit log (SSO via OIDC/SAML) | Backed by PostgreSQL |
| hoopcare-fhir | registry.hoopcare.com/fhir | FHIR R4 staging store built on open-source Medplum (§6); serves the resource APIs and Subscriptions | Backed by PostgreSQL + Redis |
| PostgreSQL 15+ | yours or bundled | One instance by default, serving the FHIR store, feature store, job state, and audit log (separate instances optional) | ~50 GB typical |
| Redis 7+ | yours or bundled | Cache and queue for the FHIR layer and job scheduler | May transit PHI-bearing payloads; persistence (RDB/AOF) disabled by default — covered in the storage/retention table (planned) |
All images are signed (cosign) and ship with SBOMs; the public verification identity is published at GA. Verify signatures before first run; see §12.
Bill of materials by deployment mode
| Mode | Required | Optional | Stateful stores |
|---|---|---|---|
| Synthetic evaluation | engine, console | — | Bundled PostgreSQL |
| Retrospective (structured) | connect, engine, console | fhir | PostgreSQL + Parquet on object/file storage |
| Prospective silent | connect, fhir, engine, console | reader | PostgreSQL + Redis |
| Production HA future mode | connect, fhir, engine ×2, console | reader | Managed PostgreSQL + Redis |
| Hybrid tier add-on | reader (GPU) or BAA LLM endpoint | — | Note cache on encrypted volume |
Per-component digests, ports, data classification, volumes, backup requirements, health endpoints, and HA behavior ship in the release manifest with each build (planned diligence artifact, §18).
3. Models & outputs
One input record in; any licensed subset of models out. Outputs are defined per model.
Feature tiers
Every model is trained at nested feature tiers defined in a governed feature manifest — 2,198 candidate features, each carrying per-tier inclusion flags and a keep / coalesce / drop decision with rationale (139 candidates are excluded outright for leakage or validity). You pick a tier per deployment. Acceptable completeness varies by endpoint, tier, and site — the runtime validates inputs and returns machine-readable valid / degraded / out-of-scope / abstained states rather than silently coping (§4).
Super Light
No EHR21 fields
Manual or web entry — no EHR connection
- Rapid structured entry from a verified source — powers the hosted web calculator (try the live demo)
- Full field list published in §4
- 42-field Web+ variant available
EHR Standard
CPU only~1,357 features
Standard EHR extract incl. ICD-10 profile
- Demographics, vitals, labs, canonical comorbidity concepts
- Full ICD-10 diagnosis profile (1,273 categories)
- Default for retrospective validation
EHR Advanced
CPU only~1,421 features
Deep EHR extract — testing, meds, anesthesia
- Adds cardiac testing (echo, stress), PFTs, medication classes
- Anesthesia-evaluation fields, obstetric context
- Best structured-only performance
Max + Hybrid
GPU / LLM API~2,011 features
Full manifest + LLM chart review of notes
- 16 LLM-derived features: acuity axes, frailty, functional capacity, cardiac findings
- Targets precision (AUPRC) and reclassification gains on rare outcomes — incremental value to be confirmed in the locked analysis and per-site evaluation
- Notes read by a locally served MedGemma — or your BAA-covered LLM endpoint (§6)
Managed-platform (~1,358 features) and payer/claims (~1,454) tier variants also exist — ask us. The Super Light field list is published in §4; the full governed manifest is shared on demand under NDA.
Model catalog
| Model ID | Output | Tiers available | Illustrative performance* |
|---|---|---|---|
| risk-score-global | Composite 0–100 global procedure risk index + 5-tier band + top drivers | Standard · Advanced · Max± LLM | composite index — see Output contract |
| mortality-30d | Probability + risk tier | Standard · Advanced · Max± LLM | AUROC 0.97 · AUPRC 0.41 |
| mortality-90d | Probability + risk tier | Standard · Advanced · Max± LLM | AUROC 0.95 · AUPRC 0.42 |
| macce-30d | Probability + risk tier | Standard · Advanced · Max± LLM | AUROC 0.94 · AUPRC 0.66 |
| aki-kdigo2-30d | Probability + risk tier (KDIGO ≥2 or RRT) | Standard · Advanced · Max± LLM | AUROC 0.96 · AUPRC 0.24 |
| pulm-complication-30d | Probability + risk tier (pneumonia, resp. failure, vent >48 h) | Standard · Advanced · Max± LLM | AUROC 0.79 · AUPRC 0.67 |
| prolonged-vent-48h | Probability + risk tier | Standard · Advanced · Max± LLM | AUROC 0.92 |
| sepsis3-30d | Probability + risk tier (Sepsis-3) | Standard · Advanced · Max± LLM | AUROC 0.95 · AUPRC 0.50 |
| unexpected-icu | Probability + risk tier (unplanned ICU >4 h post-op) | Standard · Advanced · Max± LLM | AUROC 0.92 · AUPRC 0.30 |
| vte-30d | Risk tier + guideline prophylaxis flag directive — evaluation only | Standard · Advanced · Max± LLM | AUROC 0.85–0.87 |
| rbc-transfusion-72h | Probability + risk tier | Standard · Advanced · Max± LLM | AUROC 0.97 · AUPRC 0.69 |
| rbc-units | Predicted RBC units (Tweedie regression) + planning band | Advanced · Max± LLM | MAE 0.4 u · R² 0.58 |
| los-total-icu | Predicted total & ICU days | Standard · Advanced · Max — no notes needed | MAE 1.4 d · R² 0.63 |
| asc-eligibility | eligible / needs_review / inpatient + risk drivers directive — evaluation only | Advanced · Max± LLM | AUROC 0.91 |
| delirium-postop | Probability + risk tier | Advanced · Max± LLM | AUROC 0.96 · AUPRC 0.55 |
| high-pain-composite | Probability + risk tier | Standard · Advanced · Max± LLM | AUROC 0.83 · AUPRC 0.63 |
| stroke-30d | Probability + risk tier | Advanced · Max± LLM | AUROC 0.93 |
| new-onset-af-30d | Probability + risk tier | Advanced · Max± LLM | AUROC 0.87 |
*Preliminary internal development estimates from an unlocked analysis (temporal-holdout design, ≈300k cases, 2024+) — not final, externally validated, partner-authorized, or approved for citation or decision-making. Signed, versioned model cards (mapped to TRIPOD+AI and ONC predictive-DSI source attributes, with event counts, CIs, calibration, and subgroups) replace this table at release. Rare outcomes are reported with AUPRC against a prevalence baseline. Additional endpoints (pneumonia, sepsis/septic-shock NSQIP-style, and others) and the full benchmark tables vs. ASA-PS, RCRI, POSPOM, and ARISCAT are available on demand under partner agreement. Tiers: Standard = EHR Standard (~1,357 features) · Advanced = EHR Advanced (~1,421) · Max = full manifest (~2,011). ± LLM: the Hybrid notes-analysis layer can be enabled per endpoint at that tier; its incremental value is evaluated per site. Super Light web variants exist for every endpoint; expect reduced discrimination at 21 fields (per-tier metrics on request). Endpoints marked directive provide a specific care recommendation and carry a separate intended-use and regulatory review track (§14) before any production display — see the FDA CDS guidance on directive outputs.
Output contract
Classifiers return an isotonic-calibrated probability, a five-level risk tier, a binary flag at the site-configured operating point, and the top contributing factors. Regressors return a point estimate with an 80% interval. The global 0–100 score is a composite index, not a probability — a composite ranking over the outcome panel; its component weighting, tier derivation, stability across specialties, and the meaning of a point difference will be specified in its model card. Per-outcome probabilities are the model-specific evaluation outputs. Every response carries the exact model + calibration version for audit.
{
"case_id": "SC-2026-091441",
"record_version": "sha256:9f31…",
"scored_at": "2026-09-12T02:14:07Z",
"results": [
{ "model": "risk-score-global", "version": "0.9.0+cal.2026Q3",
"score": 65, "tier": "high", "top_drivers": [
"composite_acuity_additive", "primary_procedure", "heart_failure_90d"] },
{ "model": "mortality-30d", "version": "0.9.0+cal.2026Q3",
"probability": 0.041, "tier": "high", "flag": true,
"operating_point": "youden_0.82" },
{ "model": "los-total-icu", "version": "0.9.0+cal.2026Q3",
"los_days": 4.2, "icu_days": 0.3, "interval80": [2.1, 7.9] }
],
"warnings": ["labs.bnp missing — treated as informative missingness"]
}The operating_point shown is an example, not a clinical policy — production thresholds are selected against an explicit local harm/benefit and capacity review and approved by your governance (§13).
Design note
ASA-PS is deliberately not a model input — it is reserved as a benchmark, so your validation can compare the models head-to-head against ASA on your own cases. Race, ethnicity, language, and payer are never model inputs; they are used only in the subgroup-fairness report (§13).
4. Input specification
One canonical case record, assembled by the connector — or posted directly to the API.
Every model reads the Hoopcare CaseRecord, a versioned JSON document keyed
one-per-scheduled-procedure. In a standard deployment you never build it yourself —
hoopcare-connect
assembles it from Clarity/Caboodle (§5). Sites integrating from
a data lake or another EHR can post it directly.
{
"schema": "hoopcare.case-record/1.0",
"case_id": "SC-2026-091441",
"scheduled_start": "2026-09-14T07:30:00-05:00",
"patient": { "age": 67, "sex": "F", "bmi": 31.2 },
"procedure": { "code": "27447", "system": "CPT", "urgency": "elective",
"service": "orthopedics", "setting": "inpatient" },
"anesthesia":{ "planned_type": "general" },
"labs": [ { "loinc": "718-7", "value": 11.9, "unit": "g/dL", "observed": "2026-09-01" },
{ "loinc": "2160-0", "value": 1.4, "unit": "mg/dL","observed": "2026-09-01" } ],
"vitals": { "hr": 78, "sbp": 141, "dbp": 82, "spo2": 96, "observed": "2026-09-01" },
"medications": [ { "rxnorm": "197361", "class": "beta_blocker", "active": true } ],
"diagnoses": [ { "icd10": "I50.32", "recorded": "2025-11-02" } ],
"ecg": { "qtc": 452, "qrs": 96, "pr": 168, "rate": 78, "observed": "2026-08-30" },
"prior_utilization": { "surgeries_5y": 2, "admissions_1y": 1, "icu_1y": 0 },
"notes": [ { "type": "H&P", "authored_at": "2026-09-01T09:12:00-05:00", "text": "…" } ]
}The notes array applies to the Hybrid tier only; note availability is governed by the authoring/signing instant relative to the feature cutoff (date-only values are treated conservatively). The example is valid JSON as shown.
Super Light tier — the complete 21-field list
This is the entire input for the no-EHR tier (web calculator / manual entry) — designed for rapid structured entry from a verified source. Completion time and inter-rater reliability remain to be established in usability testing.
| Group | Fields |
|---|---|
| Demographics & vitals (4) | age_at_surgery · cc_sex_at_birth · preop_bmi · preop_spo2 |
| Labs, last 90 days (4) | preop_hgb_last90d · preop_alb_last90d · preop_creat_last90d · preop_hba1c_last90d |
| Function (2) | functional_status_category · cc_functional_capacity_mets |
| Procedure (2) | cc_planned_procedure_group · cc_urgency_category |
| Comorbidity status (9) | cc_diabetes_treatment_category · cc_cad_status · cc_heart_failure_status · cc_copd_severity · cc_recent_respiratory_infection_30d · cc_smoking_status · cc_cerebrovascular_history_status · cc_cancer_status · cc_renal_disease_status |
Feature counts by tier and source category
| Category | Super Light | EHR Std | EHR Adv | Max |
|---|---|---|---|---|
| Canonical clinical concepts | 13 | 39 | 48 | 1 |
| Demographics | 1 | 1 | 1 | 2 |
| Vitals | 2 | 6 | 6 | 11 |
| Laboratory | 4 | 13 | 34 | 100 |
| Medical history | 1 | 19 | 30 | 284 |
| Extended ICD-10 diagnosis profile | — | 1,273 | 1,273 | 1,273 |
| Cardiac testing (echo, stress, ECG) | — | 1 | 10 | 31 |
| Pulmonary function tests | — | — | 4 | 4 |
| Medication list | — | — | 6 | 203 |
| Anesthesia evaluation | — | — | 3 | 44 |
| Surgical history & utilization | — | — | 1 | 23 |
| Obstetrics | — | 5 | 5 | 12 |
| Procedure detail | — | — | — | 7 |
| LLM chart review Hybrid | — | — | — | 16 |
| Total | 21 | 1,357 | 1,421 | 2,011 |
Counts from the July 2026 governed manifest (2,198 candidates; 139 excluded for leakage or validity). Lean tiers use canonical coalesced concepts in place of raw source fields; Max uses the raw sources directly — which is why the canonical row shrinks as tiers grow. The full manifest — definitions, units, windows, expected missingness, and the per-feature keep/coalesce/drop rationale — is available on demand under NDA.
Missing data is expected — do not impute
The models treat missingness as informative and were trained on real-world completeness, where selective testing makes high missingness normal for some analytes (BNP, troponin, echo). Acceptable completeness bands and degradation/abstention rules are model-, tier-, and site-specific — they are evaluated during retrospective validation, and the runtime returns machine-readable valid / degraded / out-of-scope / abstained states. Send what you have; the QC report (§12) flags fields whose completeness falls outside the expected band. Never fill default values upstream.
5. Epic integration
Read-only against your reporting databases. No writes to production, no Hyperspace access.
The connector reads from a Clarity replica or Caboodle using a read-only
service account (db_datareader
on ~40 named tables/views — your DBA reviews and approves every query in the mapping workbook before anything
runs). Prospective deployments can instead — or additionally — use Epic's
FHIR R4 APIs (SMART Backend Services with private-key JWT and
resource-specific scopes — e.g. system/Observation.read,
system/Condition.read — never a blanket wildcard) for incremental refresh, mirroring the published UCLA pathway: bulk features on a fixed cadence, case
list on a fast cadence.
Source table map
| Feature layer | Clarity tables (typical) | Caboodle equivalent |
|---|---|---|
| Demographics | PATIENT, VALID_PATIENT | PatientDim |
| Encounters & ADT | PAT_ENC, PAT_ENC_HSP, CLARITY_ADT | EncounterFact, HospitalAdmissionFact |
| Surgical case & schedule | OR_LOG, OR_CASE, OR_LOG_ALL_PROC, OR_PROC, OR_LOG_CASE_TIMES | SurgicalCaseFact |
| Diagnoses | PAT_ENC_DX, PROBLEM_LIST, HSP_ACCT_DX_LIST, CLARITY_EDG | DiagnosisEventFact, DiagnosisDim |
| Laboratory results | ORDER_PROC, ORDER_RESULTS, CLARITY_COMPONENT | LabComponentResultFact |
| Vitals / flowsheets | IP_FLWSHT_REC, IP_FLWSHT_MEAS, IP_FLO_GP_DATA | FlowsheetValueFact |
| Medications | ORDER_MED, CLARITY_MEDICATION, PAT_ENC_CURR_MEDS | MedicationOrderFact |
| ECG scalar measurements | ORDER_RESULTS (ECG components) or MUSE export | — (interface) |
| Anesthesia preop evaluation | OR_LOG ASA fields, AN_* record tables | AnesthesiaRecordFact* |
| Preop notes Hybrid only | NOTE_ENC_INFO, HNO_INFO, HNO_NOTE_TEXT | ClinicalNoteFact + text |
| Outcome labels retro only | Labs (creatinine), flowsheets (ventilation), CLARITY_ADT (ICU), HSP_ACCT_DX_LIST, discharge disposition, death fields | label-builder SQL pack |
*Exact table names vary by Epic version and site build — the mapping workbook we ship is a starting point your Clarity team adapts, not a hard dependency. Sites on Cerner/Oracle Health or a lakehouse (Databricks, Snowflake) integrate via the FHIR bulk path or direct CaseRecord posts — ask us.
Refresh cadence & write-back
| Mode | Case list | Clinical features | Write-back |
|---|---|---|---|
| Retrospective | One-time historical extract (3–7 y) | Same extract | None — results stay in console + Parquet export |
| Prospective silent | Every 15 min (FHIR or OR_LOG delta) | Every 6 h (warehouse-validated) | None — console only |
| Production future mode | Every 15 min | Every 6 h (configurable 1–24 h) | HL7v2 ORU custom field (e.g. Hoopcare Risk: High) or FHIR RiskAssessment/Flag; drives an Epic dynamic patient list for the preop/float team |
The 6-h feature / 15-min case-list cadence and HL7 flag + dynamic patient list pattern follow the implementation prospectively validated at UCLA (Wingert et al., BJA 2026, §18) — an architectural precedent for the integration shape, not evidence for Hoopcare's models. Scores are re-sent only when the value changes (~10 messages/day at a large center).
6. Interoperability & standards — FHIR R4 · HL7v2 · LOINC · SNOMED
A FHIR-first integration layer built on the open-source Medplum platform, running inside your boundary.
The connector stages everything as FHIR R4 resources in an embedded, self-hostable FHIR server built on Medplum (Apache-2.0 open source; the hosted edition of the same stack is ONC-certified, HITRUST e1 and SOC 2 Type II audited). It is the same three-service footprint everywhere — server, PostgreSQL, Redis — deployed by our Compose/Helm bundles inside your tenancy, with open-source code available for your team’s inspection (inspection is not a security review or a support commitment; Medplum support terms are separate). Scoring inputs and outputs are therefore ordinary FHIR resources your analysts can query directly, not a proprietary schema. Third-party certifications apply only to the named vendor's product, service, and audit scope — they do not confer certification on Hoopcare or on a customer-operated self-hosted deployment.
Resource & terminology bindings
| CaseRecord section | FHIR R4 resource | Code systems |
|---|---|---|
| Patient, demographics | Patient | US Core profile; BMI as Observation (LOINC 39156-5) |
| Scheduled procedure & urgency | ServiceRequest / Procedure | CPT / HCPCS; SNOMED CT procedure hierarchy for grouping |
| Diagnoses & comorbidities | Condition | ICD-10-CM (1,273-category profile); SNOMED CT accepted and mapped |
| Laboratory results | Observation (laboratory) | LOINC — e.g. 718-7 Hgb, 1751-7 Alb, 2160-0 Creat, 4548-4 HbA1c; UCUM units |
| Vital signs | Observation (vital-signs) | LOINC — 8867-4 HR, 8480-6 / 8462-4 BP, 59408-5 SpO₂ |
| Medications | MedicationRequest / MedicationStatement | RxNorm; therapeutic classes via ATC mapping |
| Cardiac testing, PFTs, ECG scalars | Observation / DiagnosticReport | LOINC panels; scalar components only, no waveforms |
| Preop notes Hybrid | DocumentReference | LOINC document types — 34117-2 H&P, 11488-4 consult |
| Predictions (output) | RiskAssessment + Observation + Flag | Calibrated probability in prediction.probabilityDecimal; model+calibration version in method; tier as Flag. RiskAssessment is FHIR R4 maturity 1 (Trial Use) — a constrained profile is planned, with Observation/DiagnosticReport fallback for EHRs without consistent RiskAssessment support |
| Traceability (output) | Provenance + AuditEvent | Every score links model version, input-bundle hash, and requesting principal |
Event-driven scoring & HL7v2 connectivity
- Three trigger patterns — matched to what your EHR supports. (1) Warehouse polling: scheduled Clarity/Caboodle delta queries (the §5 cadence) — works everywhere, latency = the polling interval. (2) FHIR Subscription: a criteria-based Subscription on ServiceRequest/Appointment fires scoring on change — the event-driven pattern Medplum documents; requires a FHIR endpoint that supports it. (3) HL7v2 events: SIU/ADT feeds through the agent listener. Sites typically combine one event pattern with a reconciliation poll for missed events; per-pattern prerequisites, latency targets, and replay behavior ship in the integration guide (planned artifact, §18).
- HL7v2 without firewall holes. In agent mode the connector listens for HL7v2 over MLLP (SIU schedules, ORU results, ADT) inside your network and, in hybrid topology, maintains only an outbound TLS WebSocket — no inbound rules, no VPN — the on-prem agent pattern documented by Medplum for exactly this "legacy interfaces live inside the hospital" problem. On-prem topology needs no tunnel at all.
- Standard APIs on top. The staging store speaks plain FHIR REST (and the scoring API of §8 sits beside it), so your integration engine, Power BI, or research data lake can consume scores as RiskAssessment searches rather than a custom export.
Three deployment topologies
| Topology | Where things run | PHI boundary | Fits |
|---|---|---|---|
| Closed environment default | Everything — connector, FHIR store, engine, and the MedGemma LLM — inside your tenancy or data center; air-gap supported | Nothing leaves; optional 1 KB/day license heartbeat only | Hospitals & health systems; all tiers incl. Hybrid |
| Hybrid | On-prem agent (HL7v2/FHIR extract, tokenization, date-offsetting) → dedicated single-tenant scoring enclave in your region | Structured features only, identifiers tokenized and dates offset — tokenization alone is not HIPAA de-identification, so this topology requires its own privacy, security, and contractual review; notes never leave — Hybrid tier requires the LLM on-prem | Sites without spare compute; multi-hospital groups |
| External API | Hoopcare-hosted scoring API + web calculator (SMART Backend Services auth, BAA, US region) | Only the 21–42 Super Light / Web fields cross, de-identification option available | Evaluation, ASCs, payers, pre-visit screening |
A field-level egress inventory per topology (purpose, destination, region, encryption, retention, deletion, subprocessors, disable switch) is a planned diligence artifact (§18). Payer configurations are not evaluation-ready: a separate payer guide — data contract, claims-only evidence, and permitted uses that exclude coverage, payment, and prior-authorization decisions — is planned.
Closed-environment guarantee — including the LLM
In the default topology the entire system — ML engine and the LLM chart-review component — is installed in your closed environment. The Hybrid tier ships MedGemma (Google's open-weights, medically tuned Gemma; 27B default, 4B small-GPU profile) served locally via vLLM. In the closed topology no external LLM call is made; note text, transient caches, structured features, and any verbatim evidence spans all remain inside your environment and follow the documented, site-configured retention and deletion policy (a per-data-class storage/retention table ships with the trust center — planned artifact, §18). Status: prototype. Google positions MedGemma as a developer model requiring use-case validation, and we treat the reader as its own high-risk component: a locked configuration (model digest, quantization, prompts, decoding), an annotation protocol with per-feature operating characteristics for the 16 extracted features, prompt-injection handling for note text, and end-to-end regression tests are release gates before the Hybrid tier is offered beyond evaluation. A separate reader validation report and model card are planned artifacts (§18).
7. Surfacing results in the EHR — Epic · Oracle Health · SIS · athenahealth
Four standard mechanisms by which, in a future authorized production mode, the proposed score payload could be delivered to each system’s preoperative workspace.
Scores are pushed and displayed through standard mechanisms only — every interface still requires site configuration and lifecycle maintenance. Clinical display and write-back are future production modes, subject to the intended-use and regulatory classification in §14 — evaluation deployments keep scores in the console. Your interface analyst picks per system:
- HL7v2 ORU push — a results message carrying the risk tier and score; lands as a flowsheet/result field. A widely supported interface pattern — exact message profile, display location, acknowledgement behavior, and product/version compatibility require site verification.
- FHIR write — RiskAssessment / Flag / Observation created via the EHR's FHIR R4 API where write scopes are enabled.
- SMART on FHIR panel — our embedded app launches with patient context inside the preop workspace and renders the full panel (score, drivers, trend) without leaving the chart.
- CDS Hooks card — a patient-view / order-select card for in-workflow nudges where the EHR supports the hook.
| EHR / periop system | Preoperative surface | Recommended path | Also supported |
|---|---|---|---|
| Epic | Pre-op navigator section; OR schedule / patient-list risk column; Storyboard | HL7v2 ORU → preop flowsheet row → dynamic patient list + navigator display, optional BPA on the flowsheet value — the pathway prospectively validated in the BJA reference (§18) | SMART on FHIR app (Epic on FHIR, R4; backend-services JWT auth; Showroom/Connection Hub listing); CDS Hooks; FHIR write where enabled |
| Oracle Health (Cerner) | PowerChart pre-anesthesia / perioperative MPage | SMART on FHIR app embedded as an MPage component (Ignite R4 APIs) | Native CDS Hooks; HL7v2 ORU via Millennium interfaces |
| SIS (Surgical Information Systems) | SIS preop documentation / AIMS chart; ASC preop checklist (SIS Complete) | HL7 ORU results interface into the preop assessment; SIU keeps the case list in sync | Context link-out to the Hoopcare panel |
| athenahealth | athenaOne pre-visit / surgical workflow | Marketplace partner app: FHIR R4 APIs + embedded SSO panel | Score filed as clinical document / result via athena APIs |
Effort guide: an ORU interface is standard interface-analyst work (days); SMART/Marketplace app enablement follows each vendor's app-review timeline (weeks, once per organization). Display is configuration — the score payload and the audit trail (§6) are identical on every path. Conformance status: every row is a standards-based design; none is yet vendor-program listed, lab-verified, or backed by a production reference. A per-EHR compatibility matrix (product/version, scopes, write support, limitations, verification date) is a planned artifact (§18).
8. Proposed API contract (v0.1)
Illustrative, not a production interface. The sanitized OpenAPI 3.1 contract (v0.2.0) is downloadable at /openapi.json and at the immutable path /contracts/scoring-api/0.2.0/openapi.json (checksum alongside). Production compatibility will be guaranteed by the release compatibility matrix once a production release exists.
| Endpoint | Purpose |
|---|---|
| POST /v1/score | Score one CaseRecord against all licensed models, or a models[] subset |
| POST /v1/batch | Submit a batch job (NDJSON or Parquet manifest); returns job_id |
| GET /v1/jobs/{id} | Job status, throughput, QC summary, output location |
| GET /v1/models | Licensed models, versions, calibration cohort tags |
| GET /v1/models/{id}/card | Model card mapped to TRIPOD+AI and ONC predictive-DSI source attributes: intended use, cohort, metrics, subgroups, limitations |
| POST /v1/connect/run | Trigger an extract/refresh cycle (retro backfill or incremental) |
| GET /healthz · /readyz · /metrics | Liveness, readiness, Prometheus metrics |
# OAuth2 client-credentials (or mTLS) — tokens minted by your IdP or the bundled issuer
curl -s https://hoopcare.internal.yourhospital.org/v1/score \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d @case-record.json | jq '.results[] | {model, probability, tier}'Rate limits default to 50 req/s interactive per node (far above clinical need — see §11); batch jobs run under per-tenant concurrency and daily-volume quotas, contract-configurable. Scoring accepts an Idempotency-Key header; errors use RFC 9457 application/problem+json with correlation IDs and never carry PHI or stack traces; responses carry a status of valid · degraded · stale · out_of_scope · abstained · failed plus prediction-index and feature-cutoff timestamps — full semantics — including per-operation OAuth scopes, tenant-scoped job authorization, payload and note-size caps, safe batch storage references, and machine-readable status_reasons codes — are in the OpenAPI file. All calls are written to the tamper-evident audit log (§14).
9. Deployment — AWS · Azure · GCP · on-prem
Same containers everywhere; only provisioning differs. Self-service, or our engineers install under your supervised access.
AWS
Planned v1.0 distribution target: a private offer on AWS Marketplace (container product), routing procurement through your existing AWS bill — subject to marketplace acceptance and release qualification. Preview evaluators receive a contract-scoped package through the agreed delivery channel. Deploy on a single EC2 instance with Docker Compose, or on ECS/EKS with our Terraform module for HA. Batch retro jobs read/write Parquet on S3 within your VPC.
# single-node evaluation / retro (after Marketplace subscribe or registry access)
aws ec2 run-instances --instance-type m6i.2xlarge --image-id ami-<al2023> …
cosign verify registry.hoopcare.com/engine:<preview-build> --certificate-identity-regexp hoopcare
docker compose -f hoopcare-compose.yaml up -dAzure
Most Epic shops already run reporting workloads in Azure — the platform deploys next to them: a single D8s_v5 VM with Compose, or AKS via Helm. An Azure Marketplace managed application is a planned v1.0 distribution target for one-click provisioning into a resource group you control; Private Link keeps all traffic off the public internet.
helm install hoopcare oci://registry.hoopcare.com/charts/platform \
--version <contracted-preview-version> --namespace hoopcare --create-namespace \
--set license.mode=online --set connect.source=caboodleGoogle Cloud
A GCP Marketplace listing (GKE app or single n2-standard-8 GCE VM) is a planned v1.0 distribution target. Batch IO on GCS; Private Service Connect for registry pulls if you disallow public egress.
On-prem / air-gapped
RHEL 9 or Ubuntu 22.04+ with Docker/Podman Compose, or your VMware estate via OVA. For air-gapped sites we deliver a signed offline bundle (images + encrypted models + sealed license file, renewed quarterly); the license heartbeat is disabled and nothing dials out (§15).
Who does the install
Both delivery paths are offered to evaluation partners, with no price difference by who installs: self-service (your team runs the runbook in §12; we join checkpoint calls) or white-glove (Hoopcare engineers execute inside your tenancy under just-in-time, screen-shared, audited access that you grant per session and can revoke at any time). Most sites choose white-glove for the first environment and self-service thereafter. We never require standing credentials to your environment.
Network requirements
| Flow | Direction | Protocol | Required? |
|---|---|---|---|
| Clarity/Caboodle replica → connector | internal | TDS 1433 / ODBC over TLS | Yes (or FHIR) |
| Epic FHIR endpoint → connector | internal | HTTPS 443 | Prospective modes |
| Engine API ← your consumers | internal | HTTPS 443 (mTLS optional) | Yes |
| Interface engine (HL7 write-back) | internal | MLLP / HTTPS | Production mode only |
| registry.hoopcare.com (image pulls, updates) | outbound | HTTPS 443 | No — offline bundle available |
| license.hoopcare.com (heartbeat, no PHI) | outbound | HTTPS 443, ~1 KB/day | No — sealed offline license available |
| Status feed / support case creation | outbound | HTTPS 443 | No — optional, connected preset only |
| External BAA LLM endpoint (non-closed Hybrid config) | outbound | HTTPS 443 | No — closed topology serves the LLM locally |
Egress presets
| Preset | What leaves the tenancy |
|---|---|
| air-gapped | Nothing. Offline images, sealed license, quarterly media updates; support by export you review. |
| restricted | License heartbeat + signed image pulls only (both pinned DNS names, TLS, no PHI). |
| connected | Adds status feed, automatic support cases, and aggregate-only operational telemetry (each individually disableable). |
DNS names, ports, payload schemas, size caps, certificate validation, proxy support, retry behavior, and no-PHI log evidence ship in the egress inventory (planned diligence artifact, §18). The preset applies across normal, failure, update, and support modes.
10. Machine requirements
Core inference is boosted trees on CPU — the footprint is a reporting-tier VM, not an AI cluster.
| Profile | vCPU / RAM / disk | AWS | Azure | GCP | Use |
|---|---|---|---|---|---|
| EVAL synthetic only | 4 / 16 GB / 100 GB | m6i.xlarge | D4s_v5 | n2-standard-4 | Smoke test, API exploration — no PHI |
| STANDARD | 8 / 32 GB / 256 GB SSD | m6i.2xlarge | D8s_v5 | n2-standard-8 | Prospective scoring for a multi-site health system; silent pilot; production API |
| BATCH | 16 / 64 GB / 1 TB SSD | m6i.4xlarge | D16s_v5 | n2-standard-16 | Retrospective backfill (millions of cases); scale out ×N nodes for deadline runs |
| HYBRID GPU optional | +1× 48–80 GB GPU, 500 GB NVMe | g6e.4xlarge (L40S) | NC A100 v4 | a2-highgpu-1g | Local MedGemma serving for Hybrid chart review: 27B on 1× 80 GB (A100/H100) or 2× L40S; 4B pilot profile on 1× 24 GB (L4). Skip entirely by routing to your Azure OpenAI / Bedrock / Vertex BAA endpoint |
- Database: PostgreSQL 15+ — bundled container for pilots; your managed instance (RDS / Azure Database / Cloud SQL) for production. ~50 GB covers a 1M-case feature store.
- Storage planning: structured features ≈ 2 KB/case (1.25M cases ≈ 2.5 GB Parquet); cached preop note text for Hybrid ≈ 70 KB/case (1.25M ≈ 90 GB raw, ~25 GB compressed — retro Hybrid only).
- HA production: 2× STANDARD nodes behind your load balancer; the engine is stateless, so failover is connection-level. RPO for the feature store follows your Postgres backup policy.
- Indicative cloud cost (list price, region-dependent, excludes Hoopcare license): STANDARD 24/7 ≈ $250–350/mo; STANDARD in a 4 h nightly window ≈ $50–80/mo; BATCH for a one-week retro ≈ $150–300 total; GPU ≈ $2–4/hr only while Hybrid retro runs.
11. Throughput & scheduling
How many patients per hour, and how many hours per day the platform actually needs to run.
Throughput planning figures
| Workload | Planning figure | Bound by |
|---|---|---|
| Interactive scoring (one case, all licensed models) | p95 < 150 ms · 50 req/s/node | network + feature lookup |
| Batch scoring, features already assembled | ≈ 1.5M cases/hour/BATCH node | CPU |
| End-to-end retro (extract → assemble → score), structured tiers | ≈ 40–60k cases/hour/BATCH node | Clarity/Caboodle extract SQL |
| Hybrid LLM chart review — local GPU (MedGemma-27B, vLLM) | ≈ 800–1,200 charts/hour/GPU | GPU tokens (~70k chars/chart) |
| Hybrid LLM chart review — your BAA LLM endpoint | ≈ 2–5k charts/hour | provider quota |
Worked examples
- Retrospective, 1.25M cases, structured EHR tiers: historical extract 1–3 days elapsed (DBA-paced, off-hours against the replica) → assembly + scoring ≈ 24–30 h on one BATCH node, or overnight on four. Plan < 1 week wall-clock, dominated by extract review, not compute.
- Retrospective, Hybrid tier: full-history LLM review of 1.25M charts is GPU-weeks — by design we instead run Hybrid on a stratified subsample (e.g., 100k cases ≈ 4–5 days on one GPU), which is statistically sufficient to demonstrate the LLM layer's incremental AUPRC/NRI on your population.
- Prospective, ~350 cases/day health system: nightly full rescore of the 7-day schedule (~3–5k case-scorings) completes in < 10 minutes on STANDARD; 6-hourly incremental refreshes take ~1 minute. Daily volume uses under 1% of a single node's capacity.
Operating windows — the engine runs when you say it runs
| Mode | Runtime/day | Fits | Infra note |
|---|---|---|---|
| Always-on API | 24 h | Production write-back + interactive use | 2× STANDARD for HA |
| Scheduled window | 2–6 h (e.g. 02:00–06:00) | Silent pilots, nightly-batch production | VM deallocated outside the window → ~80% infra cost reduction; scores persist in Postgres and remain queryable |
| Burst | days, then off | Retro backfills, recalibration runs | Spin up N BATCH nodes, tear down after; license supports temporary burst nodes |
Licensing is per scored case (retro) or per annual surgical volume band (prospective) — never per node or per hour, so right-sizing and windowing your infrastructure never conflicts with the license. Runtime scheduling is a first-class config (schedule.window in the Helm values / compose env).
12. Installation runbook
From signed containers to a validated first score. Times assume the STANDARD profile.
-
01
Agreements & site survey week 0
BAA, DUA/research agreement for retro, and license order form. You return a one-page site survey (Epic version, Clarity vs Caboodle, cloud target, network policy) that fixes the deployment profile and final sizing.
-
02
Provision & verify day 1 · ~2 h
Stand up the VM/namespace, pull images from the Marketplace or registry.hoopcare.com, verify signatures and SBOMs with cosign.
-
03
License & doctor day 1 · ~30 min
hoopcare license apply <key-or-sealed-file> binds the encrypted model bundle to this node, then hoopcare doctor checks resources, clock, connectivity, and bundle integrity.
-
04
Synthetic smoke test day 1 · ~15 min
The image ships with 1,000 synthetic cases. hoopcare smoke scores them and asserts against golden outputs — your proof the engine is healthy before any PHI is touched. First real score target: < 1 day from VM availability.
-
05
Source mapping weeks 1–2 · DBA 3–5 days
Adapt the Clarity/Caboodle mapping workbook (§5) with your Clarity team; every SQL statement is plain text for review. hoopcare map validate dry-runs row counts per table without moving data.
-
06
Data-quality gate week 3
hoopcare validate --sample 50k produces the QC report: completeness vs expected missingness bands, unit and range checks, temporal sanity. The engine refuses a production run while red checks remain — fail-closed by design.
-
07
Dry run, then full run weeks 3–4
hoopcare backfill --since 2019 --dry-sample 10k, joint review, then the full retro (§11 worked example) or the start of the prospective silent window.
-
08
Review & next phase weeks 4–6
Metrics workshop on the retro report (§13), then decision to proceed to silent pilot or production wiring (HL7/FHIR write-back + Epic patient list with your interface analyst).
# day one, end to end
cosign verify registry.hoopcare.com/engine:<preview-build> …
docker compose -f hoopcare-compose.yaml up -d
hoopcare license apply HOOP-XXXX-XXXX
hoopcare doctor # resources · clock · bundle integrity · endpoints
hoopcare smoke # 1,000 synthetic cases vs golden outputs
# integration phase
hoopcare map validate --source caboodle
hoopcare validate --sample 50k
hoopcare backfill --since 2019-01-0113. Retrospective validation program
The standard first engagement for academic partners: evaluate the licensed models on your own historical cases, entirely inside your walls.
The program answers one question with your data: how do the models perform on our population, against the tools we use today? Your team keeps full control — the outcome labels are built locally by your analysts from our open, reviewable SQL label pack, so the evaluation is auditable end-to-end (vendor-provided tooling is auditable, not automatically independent — your team reviews and can replace any of it). Each engagement runs under a pre-specified protocol signed before scoring: frozen cohort and label definitions, chart-review label validation on a sample, locked model + threshold versions, a statistical analysis plan with minimum event counts, and predefined go / recalibrate / no-go acceptance gates per model.
-
01
Scope week 0
Pick the cohort window (typically 3–7 years), populations (all-comers and/or NSQIP-eligible), and endpoints. Your institution — with its IRB, privacy, and compliance leadership — determines whether the activity is research, quality improvement, or operations before any data processing begins; the platform runs on identified or de-identified extracts equally well.
-
02
Extract & label weeks 1–3
Historical extract per §5; your analysts run the label-builder SQL pack (creatinine trajectories for AKI, ventilation hours, unplanned ICU transfers, disposition/death, coded events) and keep the labels.
-
03
Score week 4
Structured tiers over the full cohort (< 1 week wall-clock at 1M+ cases, §11); Hybrid on a stratified subsample if licensed.
-
04
Evaluate weeks 4–5
The bundled evaluation notebook (source-available, Apache-2.0) joins scores to your labels and produces per-outcome AUROC/AUPRC with bootstrap CIs, calibration curves, decision-curve analysis, and head-to-head comparisons vs ASA-PS, RCRI, POSPOM, ARISCAT computed on the same cases — plus the subgroup-fairness report (sex, age, race & ethnicity, specialty, urgency).
-
05
Joint review week 6
Metrics workshop; decision on silent pilot. If the site wishes to publish, we support co-authored external-validation manuscripts — your cohort, your labels, TRIPOD+AI reporting.
Governance defaults
Nothing leaves your tenancy by default. If you opt into a joint report, only aggregate metrics with a minimum cell size of 10 are exported, after your sign-off. Exported aggregates follow your institution-approved disclosure rules; model privacy is handled separately through threat modeling, not cell-size analogies.
14. Security & compliance
Short version: your tenancy, your keys, your audit trail.
The controls below are design commitments at prototype maturity; each will carry its own state (planned / implemented / internally verified / independently assessed) with linked evidence in the trust center (planned artifact, §18).
- HIPAA. Standard BAA available for execution where Hoopcare acts as a business associate — the role varies by topology, and a counsel-reviewed role table per topology is a planned artifact. In the closed topology PHI is processed only inside your environment; no PHI in logs, telemetry, or license traffic (logging schema and redaction tests are part of the trust-center evidence). Optional telemetry is aggregate-only and off by default.
- Encryption. TLS 1.2+ in transit (mTLS optional); AES-256 at rest via your cloud KMS / disk encryption; model bundle separately encrypted (§15).
- Identity. Console SSO via your OIDC/SAML IdP; API via OAuth2 client-credentials or mTLS; RBAC with least-privilege roles (viewer / analyst / operator / admin). EHR-side connections use SMART on FHIR: EHR launch with scoped user context for the embedded panel, and SMART Backend Services (asymmetric private-key JWT per the SMART profile, resource-specific least-privilege scopes per endpoint — never a blanket wildcard) for machine-to-machine access; no shared secrets in interface configs.
- Fine-grained FHIR access control. The staging store enforces FHIR AccessPolicies: per-resource-type CRUD rules, criteria-based filtering, field-level hiddenFields/readonlyFields, and patient-compartment scoping — so an integration account can read exactly the resources it scores and nothing else (least privilege by construction, not by convention).
- Prediction traceability. Every score writes a FHIR Provenance (model + calibration version, input-bundle hash) and AuditEvent (who/what/when) alongside the RiskAssessment — your compliance team can reconstruct any prediction end-to-end from standard resources.
- Hybrid-topology minimization. When scoring runs in the single-tenant enclave (§6), identifiers are tokenized and dates offset before egress, note text never leaves your network, and the re-identification map stays on your side of the boundary.
- LLM isolation & retention. The chart-review LLM (MedGemma) is served locally with no internet egress in the closed topology. Extractions carry verbatim evidence spans so every LLM-derived feature is reviewable against the source note — evidence spans are note-derived PHI and, like the note cache, are stored inside your environment under the site-configured retention and deletion policy. A per-data-class storage/retention table (source text, prompt buffers, features, evidence spans, queue payloads, logs, backups) is a planned trust-center artifact; until it ships, treat retention as site policy, not "zero".
- Audit. Tamper-evident (hash-chained) audit log of every scoring call, config change, and data access; exportable to your SIEM (syslog/CEF).
- Assurance — stated precisely. SOC 2 Type II audit in progress (report shared under NDA when issued, with exact system and period scope); first third-party penetration test scheduled before GA (attestation with assessor, date, and scope to follow); signed containers + SBOMs per release with the public verification identity published at GA; CVE patch target — critical ≤ 7 days. Each control is tracked in the trust center as planned, implemented, internally verified, or independently assessed (planned artifact, §18).
- Regulatory posture. This preview describes research-evaluation functionality only. The current build is not FDA-cleared and is not authorized for clinical decision-making, site-of-service determination, benefit/coverage, payment, or prior-authorization decisions; institutions must not expose scores to end users or act on them outside an approved protocol and contract. Separate counsel-approved intended-use statements are in progress for (1) retrospective research, (2) silent prospective evaluation, (3) clinical decision support if and when authorized, and (4) payer/care management — assessed against the FDA CDS guidance criteria (including independent-review-basis expectations for directive outputs such as ASC eligibility or a prophylaxis flag). Future clinical display would run as passive risk presentation under institutional governance, following the UCLA precedent (§18).
15. Model privacy — how the models stay ours while running on yours
You get full operational control and full auditability of behavior — without us shipping readable weights.
Hospitals reasonably ask how an on-prem deployment coexists with vendor IP. The answer is an appliance model: model weights are never delivered in readable form, and never leave Hoopcare in the clear.
- Encrypted at rest, decrypted only in memory. Models ship inside the engine image as an AES-256-GCM encrypted bundle. Keys are released per-node by the license service (or embedded in a sealed offline license for air-gap) and bound to the node identity; decryption happens in engine memory at startup. No plaintext model file ever exists on your disk, and there is no pickle/ONNX artifact to lift.
- No export surface. The API exposes predictions, calibrated probabilities, and top-k grouped drivers — not raw margins, trees, or embeddings. There is no model-download or introspection endpoint; bulk scoring is licensed and audited, which also bounds extraction-style querying.
- Signed & sealed. Containers are cosign-signed; the engine refuses tampered bundles; licenses are node-locked with quarterly re-key (air-gap sites get renewed sealed bundles on the same cadence).
- Contractual layer. The license prohibits reverse engineering, weight extraction, and training surrogate models on outputs ("distillation"), with audit rights — standard terms your counsel will recognize from other clinical-software appliances.
- What you can audit — everything that matters clinically: per-model TRIPOD+AI cards, full metric reproduction on your own labels (§13), the source-available evaluation notebook and label-builder SQL, per-prediction drivers, SBOMs, and the complete audit log. You verify behavior, not weights — the same posture as any other regulated clinical software you run.
Why not weights-on-request?
The models are the product of a 1.3M-case development program and are licensed, not sold. The appliance design is what lets us deploy inside your network — the strongest possible privacy posture for your patients — while keeping the IP defensible. Sites that require escrow for continuity can add a standard source/artifact escrow rider.
16. Operations, updates & monitoring
Built to be run by a hospital ops team, not by us.
- Monitoring. Prometheus metrics on every component; bundled Grafana dashboards (scoring latency, job throughput, extract freshness, QC status). Alerts fail loudly: a stale extract or failed refresh marks affected scores stale in every consumer rather than serving silently old risk.
- Drift surveillance. Population-drift and calibration-drift monitors run continuously against the expected distributions from your own retro baseline; alarms open a support case automatically (published experience shows calibration drift, not discrimination, is what degrades first).
- Model updates. Semantic versioning per model; quarterly recalibration (+cal.2026Q4). New versions run in shadow mode against live traffic, and are promoted only after the side-by-side report clears your governance. Rollback is one config change — previous bundles stay installed.
- Platform updates. Monthly container releases; security patches out-of-band. Air-gapped sites get quarterly offline bundles.
- Support targets. P1 (scoring down) 4-hour response 24/7 · P2 next business day · named TAM for the first 90 days; a status page and release-notes feed accompany production service. These are targets — contractual SLAs and service credits are set at GA.
- Model-change protocol. Major/minor/patch definitions, required evidence, whether local re-evaluation is triggered, shadow duration and acceptance criteria, customer approval windows, rollback, and version display in the EHR — governed per the NIST AI RMF lifecycle (govern / map / measure / manage). Published with the trust center (§18). Calibration cannot be monitored in real time before outcomes mature, so monitoring distinguishes leading indicators (population drift, missingness) from delayed outcome-based checks.
- Release qualification. Every release must pass, on the exact tagged build: golden-fixture scoring parity, per-outcome metric regression gates (AUROC/AUPRC/calibration within tolerance of the validation baseline), leakage audit re-run, input-schema compatibility check, container signing + SBOM, and a fail-closed readiness decision. A skipped gate blocks the release.
17. FAQ for hospital IT
The questions every security and informatics review asks, answered up front.
Do you need access to our production Epic?+
No. Reads come from your Clarity replica or Caboodle with a read-only account you provision; prospective refresh can use FHIR Backend Services with read-only scopes. Write-back, if and when you enable production mode, goes through your interface engine like any other HL7 feed — we never touch Hyperspace.
Does any patient data leave our environment?+
In the closed topology, no: scoring, storage, dashboards, and evaluation all run in your tenancy, and the only outbound traffic is an optional ~1 KB/day license heartbeat (node ID and case counts, no PHI) which a sealed offline license replaces. The hybrid and hosted topologies do transmit the specific fields listed in §6 and carry their own privacy, security, and contractual review — see the egress presets in §9.
Do we get the model weights?+
No — models are licensed as an encrypted runtime (§15). You get every instrument needed to audit behavior: TRIPOD+AI model cards, full metric reproduction on your own labels with source-available tooling, per-prediction drivers, and a complete audit log. Escrow riders are available for continuity.
What does our team actually have to build?+
One read-only database account, one VM (or namespace), and a review of the mapping workbook — typically 3–5 DBA days and ~2 infra days for a retro. Production adds one HL7/FHIR interface and an Epic patient-list build, both standard interface-analyst work.
How long until we see scores on our own data?+
Synthetic scores on day 1; first scores on your historical data as soon as the mapping and QC gate pass — typically week 3–4; full retro report by week 6 (§12–13).
Do we need GPUs?+
Not for the core models — they are gradient-boosted trees and score millions of cases per hour on CPU. GPUs (or your existing BAA LLM endpoint) are needed only for the optional Hybrid tier's chart-review layer, and only while it runs.
Can it run air-gapped?+
Yes: offline image bundle, sealed node-locked license, quarterly renewals, telemetry disabled. The trade-off is manual quarterly updates instead of pull-based ones.
What happens when Epic upgrades?+
The connector pins to the mapping workbook, not to an Epic version; Clarity/Caboodle schema changes surface in hoopcare map validate as row-count/type diffs before they can affect scoring, and QC fails closed. Mapping updates are covered under support.
Is this a medical device? Who is accountable for decisions?+
The current build is research-evaluation software only: not FDA-cleared, and not to be used for patient-care, site-of-service, coverage, payment, or prior-authorization decisions. Counsel-reviewed intended-use statements per mode, and the regulatory classification for any future clinical display, are in progress (§14); we share the roadmap under NDA.
Our data scientists want to validate independently. Can they?+
Encouraged. Labels are built by your team from open SQL; the evaluation notebook is source-available; scores export to Parquet. Independent re-analysis needs nothing from us.
18. Resources & further reading
What to hand your clinicians, DBAs, and security reviewers.
| Resource | What it is | Access |
|---|---|---|
| Reference implementation (architecture) | Wingert T, et al. Prospective validation and real-time implementation of an automated machine learning postoperative mortality prediction model. Br J Anaesth 2026;136:1822–32 — the Epic integration pattern this design follows (data-mart cadence, CPU-only VM, HL7 flag, patient list), with accompanying editorial (King & Fritz). Evidence boundary: a different, single-site 32-feature mortality model (prospective AUROC 0.874); it does not validate Hoopcare's models or software. | doi.org ↗ |
| Development & validation manuscript | Hybrid ML–LLM preoperative chart-review system, ~1.3M cases, six primary outcomes, TRIPOD+AI — multicenter temporal validation. | Draft in preparation |
| Model cards (per outcome) | Intended use, cohort, metrics with CIs, subgroups, limitations | Planned — populated after the locked analysis |
| Full data dictionary | 2,198 candidate features with per-tier flags, definitions, units, windows, expected missingness, and per-feature keep/coalesce/drop rationale (leakage audit included) | Available under agreement (NDA) |
| Security whitepaper & pen-test attestation | Controls detail for your security review; first third-party penetration test is scheduled before GA | Planned (trust center) |
| Live demo — Surgery Risk Calculator | Interactive demonstration of the Super Light web tier (synthetic logic, not for clinical use) | Available now — /demo ↗ |
| Live demo — Doctor dashboard (PEC console) | Pre-Anesthesia Evaluation Center readiness workspace: case queue, readiness checklist, copilot actions (synthetic worklist, not for clinical use) | Available now — /dashboard ↗ |
| Synthetic dataset + Postman collection | 1,000 synthetic cases, golden outputs, ready-made API calls | In preparation — ships with the evaluation package |
| Label-builder SQL pack & evaluation notebook | Outcome-label SQL and metrics tooling used in §13 (Apache-2.0 at release) | Draft under review — released with the protocol template |
| TRIPOD+AI statement | Reporting guideline our model cards map to (alongside ONC predictive-DSI source attributes) | BMJ 2024 ↗ |
| Proposed OpenAPI 3.1 contract (v0.2.0) | Sanitized machine-readable contract: per-operation OAuth scopes + mTLS scheme, strict schemas, request-side cutoff semantics, size caps with 413 behavior, safe batch storage references, status-reason codes, RFC 9457 errors, idempotency — illustrative, not a production interface | Available now — /openapi.json ↗ · immutable ↗ |
| Planned diligence artifacts | Trust center with evidence-linked controls · signed model cards + evidence-status registry · component release manifest (BOM, digests) · field-level egress inventory per topology · FHIR implementation guide (CapabilityStatement, profiles) · EHR compatibility matrix · retrospective-protocol template with acceptance gates · clinical hazard log / safety case · MedGemma reader validation report · deployment responsibility matrix · payer guide | In preparation |
| Medplum documentation | The open-source FHIR platform inside the connector (§6): self-hosting, agent (HL7v2/MLLP), subscriptions/bots, access policies, compliance | medplum.com/docs ↗ |
| Epic on FHIR · SMART · CDS Hooks | Vendor developer programs and standards behind §7 and §14: Epic on FHIR, SMART Backend Services, FHIR R4 RiskAssessment, FDA CDS guidance, ONC DSI test method, OWASP API Top 10 | Linked |
19. Release notes
Versioned like the software it documents.
Documentation preview v0.9 — August 2026 current · preview
- Preview catalog of 18 outcome endpoints with illustrative pre-final figures; global composite score defined in §3.
- Proposed architecture: connector + FHIR staging layer (Medplum) + CPU scoring engine + console; BOM per mode in §2.
- Proposed Epic integration patterns (§5, §7) and a sanitized OpenAPI 3.1 contract v0.1 (§8, /openapi.json).
- Prototype Hybrid chart-review sidecar (MedGemma, local vLLM) — extraction validation is a release gate (§6).
- Egress presets and topology-scoped data-boundary statements (§6, §9); status taxonomy in §1.
Planned for v1.0 GA — release gates
- Locked-cohort analysis complete and partner-authorized; signed model cards replace all illustrative figures.
- Release qualification passed on the tagged build: golden fixtures, metric regression gates, leakage audit re-run, schema compatibility, signing + SBOM with published verification identity, fail-closed readiness decision (§16).
- Counsel-approved intended-use statements per mode; regulatory classification memos (§14).
- MedGemma reader validation report; FHIR implementation guide; EHR compatibility matrix; trust center live.
- Marketplace listings (AWS private offer, Azure managed application, GCP) and contractual support SLAs.