SafeStaff AI is an agentic AI capstone prototype for emergency-room operations. It combines an XGBoost ER wait-time forecast, operational pressure modules, an operational memory layer, a local RAG policy/SOP knowledge base, a nurse registry, a shift schedule, a multi-agent shortage solver, human approval, and an audit log into one Streamlit control-tower workflow.
- Live Demo: https://safestaffai-production-dff0.up.railway.app/
- GitHub Repository: https://github.com/draculess99/SafeStaff_AI
- LinkedIn: https://www.linkedin.com/in/gammaconsult/
- Portfolio: https://draculess99.github.io/VET-VTO-Forecasting/
Prototype notice: SafeStaff AI is a demonstration and decision-support prototype. It is not clinically validated and must not be used for real patient-care or staffing decisions without hospital governance, validation, security review, and human supervision. The system is intended to support nurse managers and staffing coordinators, not replace clinical or operational judgment.
From ER wait-time forecasts to nurse-staffing decisions: an agentic AI control tower for hospital operations.
Emergency departments face changing demand: arrival surges, boarding delays, nurse fatigue, flu activity, staff call-outs, low-acuity bottlenecks, and limited specialist availability. A static staffing plan can miss these fast-moving pressures.
SafeStaff AI addresses two connected problems:
-
ER wait-time forecasting
An XGBoost model forecasts ER wait-time risk from structured operational features. -
Nurse-staffing decision support
A staffing workflow converts the wait-time prediction and operational pressure signals into an explainable additional-nurse recommendation.
The app is designed to show a complete decision path:
ER scenario inputs
↓
XGBoost wait-time forecast
↓
Operational pressure engine
↓
Operational memory / similar-event retrieval
↓
RAG policy/SOP retrieval
↓
Pressure-based staffing adjustment
↓
Multi-agent shortage solver
↓
Human approval / rejection / override
↓
Roster update + audit log
The screenshots below show the SafeStaff AI workflow from ER pressure detection through staffing recommendation, agentic review, human approval, roster update, and audit traceability.
The Control Tower provides the main operational dashboard, including ER status, pipeline readiness, backend connection, model status, and the current operational pressure state.
The demo scenario screen loads operational stress cases such as winter flu surge, staff call-outs, high boarding, high occupancy, fast-track pressure, and increased patient volume.
The shift schedule shows the active roster, assigned nurses, acuity level, predicted wait time, and staffing status before and after a recommended roster update.
The nurse registry provides the staffing pool used by the shortage solver, including nurse availability, department fit, fatigue limits, and credential matching.
Step 1 uses the XGBoost model to predict ER wait time and combines that forecast with operational pressure signals to classify the current staffing risk.
Step 2 separates the base wait-time staffing need from the operational adjustment, then produces the final additional-nurse recommendation.
The multi-agent workflow shows the staffing recommendation being reviewed by the planner, compliance guard, patient safety agent, financial auditor, final arbiter, and human approval checkpoint.
The final decision summary records whether the optimized roster was approved or rejected, confirms the roster update result, and shows whether the audit log was recorded.
The audit log stores a persistent record of each staffing decision, including predicted wait time, staffing need, selected nurses, cost impact, approval status, compliance warnings, and decision rationale.
The explainability and cost analytics screen shows the resolution history, LLM token usage audit, estimated API cost, local-vs-live reasoning mode, and decoded multi-agent explanation.
The primary workflow tab displays the operational staffing flow:
- Shift Schedule & Status
- Nurse Database Registry summary and expandable registry table
- 3-Step Shortage Resolution Workflow
- ER wait-time risk assessment
- Pressure-based staffing adjustment
- Multi-agent shortage solver
- Human approval and governance
- Final decision executive summary
This tab allows hospital administrators to run "what-if" simulations to stress-test the ER's resilience against sudden operational shocks:
- Environmental Scenario Presets: Quick-load predefined crisis scenarios such as a "Blizzard Emergency", "Viral Pandemic Outbreak", or "Standard Weekend Shift".
- Custom Stress Parameters: Manually adjust sliders for Patient Inflow Multipliers, Nurse Call-Out Rates (sick percentage), Acuity Shifts, and Specialist Availability.
- Real-Time KPI Deltas: Instantly displays the difference between the base predicted wait time and the stressed predicted wait time, alongside the updated risk level and estimated additional nurses needed.
- Cost vs. Risk Curve: A visual chart demonstrating the intersection of stressed roster costs and patient safety risk.
- Scenario Export: A one-click button to push the simulated stressed parameters directly into the primary Roster & Shortage Solver for AI resolution.
This tab adds Retrieval-Augmented Generation to the app. Operators can upload or paste hospital policy, staffing SOPs, overtime rules, union constraints, surge playbooks, fast-track rules, and triage guidance. The backend chunks those documents, stores them locally in database/rag_documents.json, retrieves the most relevant chunks with TF-IDF search, and injects the evidence into the AI committee/Gemini debate.
This keeps the demo lightweight: no Pinecone, Chroma server, paid vector database, or cloud embedding service is required. The retrieval layer is designed to ground the agents in local policy evidence while preserving the existing XGBoost, operational pressure, human approval, and audit-log workflow.
Where to see it in the running app:
📚 RAG Knowledge Base tab
Add, delete, reset, and search policy/SOP evidence.
Sidebar → 📚 RAG Policy Grounding
Turn RAG on/off and select how many evidence chunks to retrieve.
Roster & Shortage Solver / AI Committee Debate
Look for wording such as:
"RAG grounding retrieved X policy/SOP evidence chunks"
"Retrieved evidence"
"RAG evidence"
Good test searches:
winter surge nurse shortage boarding fast track overtime
ESI acuity ambulance offload float pool critical care
break relief meal coverage fatigue high occupancy
This tab lifts the hood on how the system reaches its conclusions and tracks the cost of AI reasoning:
- Resolution History Logs: A drop-down selection of historical staffing resolutions, showing the timestamp, status, and total staffing cost for each event.
- Narrative Explainability: A plain-English narrative detailing exactly why a specific recommendation was made, what constraints were applied, and why certain nurses were selected over others.
- Live API Token Usage & Analytics: Detailed cost tracking for the Live Gemini API calls, including the specific model used, fallback models attempted, total prompt/response tokens consumed, and the estimated API cost in USD.
The audit log provides a persistent, verifiable trail of all human-in-the-loop governance decisions across sessions:
- Comprehensive Event Tracking: Records every staffing event, including shift details, predicted wait times, risk levels, and the exact number of nurses recommended vs. approved.
- Human Override Logging: Captures any manual overrides made by the user, including the specific stage the override occurred, the reason provided by the user, and exactly which nurses were rejected.
- Compliance & Financial Tracking: Logs any compliance warnings triggered during the event, whether formal approval was required, and the final estimated cost.
- Exportable Records: Displays the full history in an interactive data table with a one-click option to download the raw
audit_log.csvfor external compliance reviews.
This tab serves as the technical documentation and validation center for the prototype:
- Intervention Frameworks: Details the specific research modules and operational frameworks powering the decision engine.
- Validation Checks: Documents the data provenance and logic checks to prove the system's reasoning is grounded in realistic hospital operations.
- Execution Paths: Explains the architecture differences between the Local Expert System fallback mode and the Live API execution paths.
This tab serves as the transparent "brain" of the system, showcasing the agentic reasoning layer that drives final staffing decisions. It features:
- Context & Risk Analysis Metrics: A breakdown of the XGBoost predicted wait, base staffing risk, individual pressure adjustments (ESI, Boarding, Arrival Surge, Fast-Track), and the final Adjusted Operational Risk score.
- Dynamic Agent Activation: A real-time audit of which specialized AI agents were activated for the scenario and their specific focus (e.g., Patient Safety, Financial Auditor).
- Committee Debate Summary: A detailed, multi-agent debate weighing the trade-offs of the recommendation. When running in Live Groq/Gemini API Mode, this section injects a rich, multi-paragraph LLM debate highlighting conflicting operational priorities (Staffing vs. Compliance, Safety vs. Cost).
- ER Staffing Intervention Planner: A costed, actionable list of alternative interventions (e.g., opening a fast-track area, floating a triage nurse) complete with target bottlenecks, expected wait reductions, formulas, and assumption sources.
- Financial Breakdown: Aggregated totals for roster staffing costs, intervention costs, and total estimated operational cost.
This tab provides visual proof of the underlying Machine Learning model's accuracy and reliability:
- Hero Metrics: Displays key performance indicators from the XGBoost training phase, including R² Score, Mean Absolute Error (MAE), and Risk Band Accuracy.
- Feature Importance: An interactive bar chart revealing which operational variables (e.g., patient volume, acuity levels) have the highest impact on wait-time predictions.
- Prediction Accuracy: An interactive scatterplot comparing the model's predicted wait times against actual historical wait times, demonstrating the model's precision across different clinical risk bands.
flowchart TD
A[ER Scenario Inputs] --> B[XGBoost Wait-Time Forecast]
A --> C[Operational Pressure Engine]
A --> M[Operational Memory / Similar-Event Retrieval]
A --> R[RAG Policy / SOP Retrieval]
C --> C1[Arrival Surge]
C --> C2[Bed Boarding]
C --> C3[Acuity / ESI]
C --> C4[Nurse Fatigue]
C --> C5[Fast-Track Bottleneck]
C --> C6[Staff Call-Outs]
B --> D[Pressure-Based Staffing Adjustment]
C --> D
M --> D
R --> E
D --> E[Multi-Agent Shortage Solver]
E --> E1[Staffing Planner]
E --> E2[Compliance Guard]
E --> E3[Patient Safety Agent]
E --> E4[Financial Auditor]
E --> E5[Final Arbiter]
E --> F[Human Approval / Reject / Override]
F --> G[Roster Update]
F --> H[Audit Log]
H --> I[Dashboard Evidence]
G --> I
H --> M
SafeStaff AI uses public/Kaggle-derived and simulated proxy data for demonstration. The project does not use real patient records, protected health information, or live hospital staffing data.
The main ER wait-time forecasting model is based on the Kaggle ER Wait Time dataset by Rivalytics:
Dataset source: Kaggle — ER Wait Time by Rivalytics
This dataset is used to train the XGBoost wait-time forecasting model. The model predicts ER wait-time risk from structured operational features such as acuity, timing, patient-flow patterns, and wait-time dynamics.
In addition to the main wait-time dataset, SafeStaff AI includes prototype operational pressure modules. These modules are not separate clinical prediction models. They are research-inspired lookup tables and rule-based pressure signals used to simulate common emergency department staffing pressures.
| Operational module | What it represents | Prototype source |
|---|---|---|
| ESI Seasonal Patterns | Acuity and urgency pressure | Mapped from Kaggle-derived ER urgency levels |
| Bed Boarding Pressure | Boarding and inpatient bed-flow pressure | Proxy generated from wait-time patterns by hour, day, and month |
| Arrival Surge Pressure | Patient volume surge pressure | Aggregated from visit counts and wait-time patterns |
| Fast-Track Flow | Low-acuity bottleneck and fast-track pressure | Aggregated from low-urgency visit counts and queue-size proxies |
| Nurse Fatigue / Call-Out Rules | Staffing safety and coverage pressure | Simulated operational rules for demo staffing constraints |
These modules are stored in the database/ folder and documented in the app’s Data Sources Registry. They help explain why the final nurse recommendation may be higher than the raw XGBoost wait-time prediction alone.
Because these are prototype research modules, they would need to be replaced, calibrated, and clinically validated with real hospital operational data before production use.
flowchart TD
A[Kaggle ER Wait-Time Dataset] --> B[XGBoost Training]
B --> C[Trained XGBoost Model]
S[Loaded Demo Scenario / ER Operational Inputs] --> C
C --> P[Wait-Time Prediction]
D[Kaggle-Derived / Simulated Pressure Modules] --> D1[Arrival Surge]
D --> D2[Bed Boarding]
D --> D3[ESI / Acuity]
D --> D4[Fast-Track Bottleneck]
D --> D5[Fatigue and Call-Out Rules]
S --> D1
S --> D2
S --> D3
S --> D4
S --> D5
R[Stored Prior ER States / Audit History] --> M[Operational Memory / Similar-Event Retrieval]
S --> M
P --> E[Pressure-Based Staffing Adjustment]
D1 --> E
D2 --> E
D3 --> E
D4 --> E
D5 --> E
M --> E
E --> F[Multi-Agent Shortage Solver]
F --> G[Human Approval]
G --> H[Roster Update]
G --> I[Audit Log]
This diagram separates the historical/proxy data used to train the XGBoost model from the current demo scenario loaded in the application. The loaded scenario represents the current ER operational state, while the Kaggle-derived data and prototype pressure modules provide the forecasting and decision-support logic used to produce the staffing recommendation. The operational memory layer compares the current scenario against stored prior ER states and audit history to provide similar-event context; it does not store real patient records or protected health information.
SafeStaff AI includes a local RAG layer that lets the agentic staffing workflow retrieve relevant policy evidence before producing a recommendation.
The included demo knowledge base contains 14 seeded policies:
- ED Surge Staffing Escalation SOP (Category: Staffing SOP)
- Policy text: Emergency Department surge staffing should be escalated when adjusted operational risk is High or Critical, when the waiting room exceeds 35 patients, when ambulance arrival pressure is High or Critical, or when the predicted wait-time gap exceeds the safety threshold. First actions should include opening fast-track if low-acuity volume is high, calling in qualified Emergency nurses, and notifying the nursing supervisor. Critical surge requires explicit human approval before roster changes are committed.
- Nurse Fatigue and Overtime Guardrails (Category: Compliance)
- Policy text: Nurses projected above 60 weekly hours should not be selected for additional shifts except under executive emergency authorization. Nurses already above 48 weekly hours should be treated as fatigue-sensitive and should be chosen only when safer alternatives are unavailable. Night-shift assignments should prefer nurses with Night or Flexible circadian preference when the skill match is equivalent.
- Boarding Gridlock Escalation Playbook (Category: Patient Flow)
- Policy text: Boarding pressure becomes severe when inpatient bed occupancy exceeds 95 percent, boarding count exceeds 15, or average boarding time exceeds 4 hours. Recommended actions include notifying bed management, prioritizing inpatient discharges, adding charge nurse coordination, and protecting ED nurse staffing for active emergency care rather than absorbing inpatient boarding work silently.
- Fast Track Activation Criteria (Category: Fast Track)
- Policy text: Fast-track should be opened or expanded when low-acuity patients exceed 35 percent of the waiting room and a qualified nurse or advanced practice provider is available. If fast-track is closed during a Friday night or winter surge, the staffing committee should consider one additional Emergency nurse plus operational support to reduce waiting-room crowding.
- Critical Care Skill-Match Requirement (Category: Skill Mix)
- Policy text: Critical-care, trauma, resuscitation, and high-acuity ED zones require nurses with documented Emergency, ICU, or critical-care competency. The staffing engine should not solve a critical shortage by assigning only general medical-surgical coverage when the scenario includes high acuity, ambulance surge, sepsis alerts, cardiac monitoring load, or resuscitation bay demand. When skill match is incomplete, the recommended action is to call a qualified specialist nurse, open charge-nurse review, or escalate to the house supervisor rather than silently filling the slot with an unqualified resource.
- Charge Nurse Command Center Escalation (Category: Command Center)
- Policy text: A charge nurse or nursing supervisor should be notified when any two of the following are present: waiting room above 30, ambulance pressure High or Critical, inpatient occupancy above 92 percent, predicted wait time above target by more than 30 minutes, or more than two nurse call-outs in the same shift. The command center should review staffing changes, float-pool calls, bed-flow constraints, and whether a temporary fast-track or discharge-lounge action is safer than simply adding overtime.
- Float Pool and Cross-Cover Utilization Rules (Category: Float Pool)
- Policy text: Float-pool nurses should be considered before agency or high-overtime assignments when their competency profile matches the shortage. Cross-cover assignments must respect department qualification, orientation status, and recent shift load. A float nurse can stabilize lower-acuity zones, observation support, discharge coordination, or fast-track intake, but should not be used as the sole replacement for critical-care ED coverage unless credentialed for that role.
- Agency Nurse Cost and Approval Policy (Category: Cost Control)
- Policy text: Agency nurse utilization should be treated as a last-line option when internal overtime, voluntary call-in, float pool, and schedule swaps cannot safely cover the shortage. If agency coverage is recommended, the decision summary should explain the patient safety trigger, expected wait-time reduction, estimated incremental cost, and why lower-cost options were insufficient. Agency use for more than one shift in a 24-hour period requires nursing leadership approval in this demo policy.
- ESI Acuity Surge Staffing Matrix (Category: Acuity Matrix)
- Policy text: When ESI 1-2 volume rises or the acuity mix shifts upward, staffing recommendations should prioritize experienced ED and critical-care nurses over generic headcount. Low-acuity surges should first trigger fast-track and intake redesign, while high-acuity surges should trigger resuscitation coverage, triage reinforcement, monitored-bed support, and charge nurse escalation. The model should distinguish between volume pressure and acuity pressure because the safest intervention may be different.
- Ambulance Offload Delay Escalation Rule (Category: EMS Offload)
- Policy text: If ambulance arrivals are high and offload delay risk is present, staffing decisions should protect triage, resuscitation, and monitored-bed turnover. Recommended interventions include adding an ED nurse with ambulance intake experience, notifying bed management, opening rapid assessment if possible, and avoiding actions that move experienced nurses away from triage during EMS surge periods. Persistent offload delay should be escalated to the house supervisor.
- Pediatric and Behavioral Health Coverage Safeguard (Category: Special Populations)
- Policy text: Pediatric, behavioral health, isolation, and one-to-one observation demand should be treated as special coverage constraints. The staffing engine should flag when a shortage affects these populations because normal adult ED staffing substitutions may be unsafe. If appropriate competency is unavailable, the recommendation should include leadership escalation, sitter-pool review, behavioral-health consult coordination, or temporary zone closure rather than pretending the gap is solved.
- Break Relief and Meal Coverage Compliance (Category: Compliance)
- Policy text: Staffing plans should preserve break relief and meal coverage whenever possible. A solution that fills a visible shortage but removes all break coverage should be marked as operationally fragile. During high-risk periods, the recommendation should explicitly state whether break coverage remains viable, whether charge nurse relief is needed, and whether the plan creates fatigue or compliance risk later in the shift.
- Winter Respiratory Surge Playbook (Category: Seasonal Surge)
- Policy text: During winter respiratory surge, ED staffing should anticipate higher arrival volatility, increased isolation-room turnover, respiratory therapy coordination, and longer inpatient boarding. The first response should combine nurse staffing, fast-track respiratory protocols for low-acuity cases, bed-flow escalation, and supply readiness for PPE and oxygen-related workflows. The staffing committee should avoid using historical average demand alone when current arrival pressure is rising rapidly.
- Human Approval and Audit Trail Requirement (Category: Governance)
- Policy text: AI-generated staffing recommendations are decision support only and require human approval before schedule changes are committed. The audit trail should capture scenario inputs, predicted wait-time risk, retrieved RAG policy evidence, agent debate summary, selected intervention, projected impact, and the approving supervisor. High-risk or high-cost decisions should include a short rationale explaining why the recommended plan is safer than available alternatives.
RAG does not change the raw XGBoost wait-time prediction. Instead, it improves the agent reasoning, explanation, recommendation, and audit trail by grounding the recommendation in policy/SOP evidence.
ER scenario inputs
↓
XGBoost wait-time prediction
↓
Operational pressure engine
↓
RAG retrieves relevant policy/SOP evidence
↓
Multi-agent staffing solver
↓
Human approval
↓
Audit log with retrieved evidence
The XGBoost model produces the base wait-time forecast. The model performance tab compares XGBoost against a naive mean baseline.
Example saved model metrics from backend/model_metrics.json:
| Metric | XGBoost | Naive Mean Baseline |
|---|---|---|
| MAE | 17.28 minutes | 54.51 minutes |
| RMSE | 26.18 minutes | 68.21 minutes |
| R² | 0.853 | -0.0002 |
The baseline predicts the average wait time for every case. XGBoost beating that baseline shows the model is learning useful operational patterns.
The operational pressure engine is loaded at startup and applies baseline pressure modules to adjust the staffing recommendation.
It considers signals such as:
- arrival surge multiplier
- bed boarding count and boarding hours
- ED occupancy
- patient acuity
- nurse call-out rate
- fast-track status and fast-track queue
- fatigue and maximum-hour constraints
- specialist availability
The sidebar uses a readiness indicator:
OPERATIONAL PRESSURE ENGINE
● READY
Baseline pressure inputs loaded
Recommendation adjustment enabled
When a demo preset is loaded, the app shows:
OPERATIONAL PRESSURE ENGINE
● PRESET LOADED
[preset name]
Recommendation adjustment enabled
SafeStaff separates the raw wait-time prediction from the operational adjustment:
Base wait-time staffing: +N
Operational adjustment: +M
Final recommendation: +K
This makes the recommendation easier to defend because users can see whether the nurse count came from the model, the operational rules, or both.
SafeStaff AI includes a lightweight operational memory layer that stores prior ER inflow states, staffing decisions, and similar historical events. When a new ER scenario is processed, the system can compare the current state against previous operational patterns to provide additional context for the staffing recommendation.
The memory layer is used for prototype decision support only. It does not store real patient records or protected health information. In the current capstone version, memory is stored in local JSON files and demonstrates how agentic systems can retrieve prior operational context before generating a recommendation.
In production, this memory state should be moved to a managed database with retention rules, access controls, audit logging, and clear separation between short-term session memory and long-term operational history.
The shortage solver represents a committee-style staffing workflow:
- Staffing Planner Agent — generates the initial staffing plan.
- Compliance Guard Agent — checks constraints such as safe hours and approval rules.
- Patient Safety Agent — evaluates risk escalation and safe coverage.
- Financial Auditor Agent — estimates staffing cost impact.
- Final Arbiter Agent — produces the final recommendation.
- Human Approval — supervisor approves, rejects, or overrides.
The app does not make autonomous clinical staffing decisions. High-risk recommendations are routed to a human approval step.
Supported actions:
- approve recommendation
- reject recommendation
- override recommendation
- save roster update
- record audit log
The audit log records decision traces such as:
- additional nurses needed
- base staffing need
- final recommendation
- active agents
- decision status
- approval requirement
- human decision
- token mode
- cost estimate
This supports governance, traceability, and demo explainability.
SafeStaff supports two reasoning modes. This is intentional: the app can run in low-token deterministic mode for reliability and cost control, while Live Gemini mode can add richer narrative reasoning when quota and API access are available.
Tokens: 0
Local deterministic expert system
No paid external LLM tokens used
This mode is reliable for demos because it does not depend on API quota.
Gemini LLM Calls: 1
Tokens: [tracked count]
Estimated Cost: [estimated cost]
Model Used: [successful model]
Live mode adds richer narrative reasoning and token/cost transparency. If quota, network access, or model availability fails, SafeStaff falls back to the local deterministic expert-system mode so the workflow remains demo-safe, cost-controlled, and explainable.
SafeStaff_AI/
├── backend/ # Flask API, XGBoost model logic, agents, pressure modules
├── frontend/ # Streamlit dashboard
├── database/ # Mock nurse registry, schedule, audit logs, demo data
├── assets/screenshots/ # Application walkthrough images
├── scripts/ # Data/module build scripts
├── requirements.txt # Python dependencies
└── server.py # Root backend entry point for deployment
git clone <your-repo-url>
cd SafeStaff_AI
python -m venv .venvActivate the environment.
Windows:
.venv\Scripts\activatemacOS/Linux:
source .venv/bin/activateInstall dependencies:
pip install -r requirements.txtBackend:
python server.pyor:
gunicorn backend.server:app --bind 0.0.0.0:5000 --timeout 180 --workers 1Frontend:
streamlit run frontend/dashboard.py --server.address 0.0.0.0 --server.port 8501Set the frontend backend URL if needed:
API_BASE_URL=http://localhost:5000
BACKEND_URL=http://localhost:5000Use two Railway services.
Custom start command:
sh -c "gunicorn backend.server:app --bind 0.0.0.0:$PORT --timeout 180 --workers 1"Set variables if using Live Gemini mode:
GOOGLE_API_KEY=<your-key>
GEMINI_API_KEY=<your-key>
GOOGLE_GENAI_API_KEY=<your-key>
Only one valid Gemini key is required, but the app checks multiple common variable names.
Custom start command:
sh -c "streamlit run frontend/dashboard.py --server.address 0.0.0.0 --server.port $PORT"Frontend variables:
API_BASE_URL=https://YOUR-BACKEND-RAILWAY-URL.up.railway.app
BACKEND_URL=https://YOUR-BACKEND-RAILWAY-URL.up.railway.app
GET /api/health
GET /api/nurses
GET /api/schedule
POST /api/reset
POST /api/predict_wait
POST /api/resolve_shortage
POST /api/approve_resolution
POST /api/reject_resolution
GET /api/audit_logs
GET /api/model-evaluation
POST /api/train
POST /api/retrain_and_reload
GET /api/inflow-memory
POST /api/inflow-forecast
POST /api/update_memory_on_save
GET /api/inflow-history
POST /api/find_similar_history
GET /api/gemini-config
GET /api/gemini-models
GET /api/rag/status
GET /api/rag/documents
POST /api/rag/documents
DELETE /api/rag/documents/<doc_id>
POST /api/rag/search
POST /api/rag/reset
Quick backend checks:
curl https://YOUR-BACKEND-URL.up.railway.app/api/health
curl https://YOUR-BACKEND-URL.up.railway.app/api/nurses
curl https://YOUR-BACKEND-URL.up.railway.app/api/schedule- Open the Streamlit dashboard.
- Confirm pipeline status is green.
- Confirm the Operational Pressure Engine is ready.
- Open 📚 RAG Knowledge Base and confirm the demo policies are loaded.
- In the sidebar, confirm 📚 RAG Policy Grounding is enabled.
- Load a demo scenario such as Winter Flu Surge + Staff Call-Out.
- Review the demo scenario inputs and operational pressures.
- Run Step 1: ER Wait-Time Risk Assessment.
- Review XGBoost wait-time prediction and ER operational pressure.
- Review the memory insight or similar prior ER state when available.
- Review Step 2: Pressure-Based Staffing Adjustment.
- Launch the Multi-Agent Shortage Solver.
- Look for wording such as RAG grounding retrieved X policy/SOP evidence chunks.
- Approve, reject, or override the staffing recommendation.
- Confirm the shift schedule updates when approved.
- Open the Audit Log and verify the decision was recorded.
- Optionally switch between Local Expert System and Live Gemini mode.
Targeted tests:
python backend/test_research_modules.py
python backend/smoke_test_app.py
python backend/test_inflow_memory_persistence.py
python backend/test_models.pyPytest examples:
pytest backend/test_inflow_memory_persistence.py -q
pytest backend/test_models.py -q
pytest backend/test_research_modules.py -qSafeStaff AI is agentic because it performs a multi-step decision workflow instead of returning a single prediction:
- Reads the current ER scenario.
- Runs an ML wait-time forecast.
- Applies operational pressure modules.
- Converts pressure into staffing adjustment.
- Retrieves relevant RAG policy/SOP evidence for the current scenario.
- Runs agent-style planning, compliance, safety, finance, and arbiter logic.
- Routes high-risk decisions to human approval.
- Retrieves similar prior ER operational states from memory to support context-aware recommendations.
- Saves schedule, nurse-hour, and audit updates.
- Provides explainability and token/cost transparency.
SafeStaff AI is a prototype and should not be used for real clinical staffing decisions without:
- clinical validation
- real hospital data review
- governance approval
- bias and safety testing
- monitoring for model drift
- security and privacy review
- integration with hospital staffing policy
- human supervisor accountability
Current limitations:
- Data is simulated or Kaggle-derived proxy data.
- The model is not clinically validated.
- Operational modules are prototype rules and lookup tables.
- RAG policies are seeded demo SOPs and should be replaced with real approved hospital policies before production use.
- Local TF-IDF retrieval is lightweight and demo-friendly, but production RAG should add source control, access control, document versioning, and stronger retrieval evaluation.
- Nurse-cost calculations are simplified.
- Gemini API usage depends on quota and API availability.
- The app is built for capstone/demo evaluation, not production deployment.
SafeStaff AI is currently designed as a capstone prototype that demonstrates ER wait-time forecasting, operational pressure adjustment, nurse staffing recommendations, human approval, and audit logging. To move this from a prototype into a production-grade healthcare operations system, several improvements would be required.
In short, productionizing SafeStaff AI would require replacing local JSON state with a managed database, adding authentication and role-based access, hardening security, validating the model on real hospital data, strengthening audit logs, and integrating with hospital scheduling, staffing, and operational data systems.
The current prototype uses local JSON-based state for mock nurses, shift schedules, memory, audit logs, and workflow history. In production, this should be moved to a managed database such as PostgreSQL, Cloud SQL, Firestore, or another healthcare-approved data store.
Production database improvements would include:
- Persistent nurse registry storage
- Persistent shift schedule history
- Persistent memory state across deployments
- Persistent audit logs and human approval records
- Transaction-safe roster updates
- Rollback support for failed approvals or overrides
- Role-based access to staffing, audit, and administrative records
- Backup and disaster recovery policies
This would make the system scalable, reliable, and safer across multiple users, departments, and hospital sites.
The current memory layer is useful for demonstrating agentic behavior, but production memory should not depend on local runtime files. Memory should be stored in a database with clear retention rules.
Future memory improvements:
- Store patient-flow memory, inflow history, staffing decisions, and prior operational states in a database
- Add timestamps, versioning, and source attribution for every memory record
- Separate short-term session memory from long-term operational memory
- Add memory expiration and retention policies
- Prevent unsafe memory reuse across unrelated hospitals, departments, or shifts
- Add audit trails showing when memory was read, written, or used by an agent
This would make the memory system more trustworthy and easier to govern.
The current RAG layer is intentionally lightweight and local so the capstone can run without a paid vector database. In production, the RAG knowledge base should be governed like an operational policy system.
Future RAG improvements:
- Replace demo policies with approved hospital SOPs and staffing policies
- Track document source, owner, approval date, expiration date, and version
- Add role-based access for uploading or deleting policies
- Add document review workflow before policies become active
- Add stronger retrieval evaluation and relevance testing
- Add citations/source display in every agent recommendation
- Add tamper-resistant audit logs showing which policy chunks were retrieved
- Consider a production vector database or managed retrieval service if the policy library becomes large
- Add prompt-injection protections for uploaded documents
This would make RAG safer, more defensible, and easier to validate in a real hospital governance environment.
The prototype should be hardened against common web security risks before production deployment.
Recommended security improvements:
- Add input validation on all API routes
- Sanitize user-entered text to reduce cross-site scripting risk
- Escape or clean any text rendered back into Streamlit
- Add schema validation for nurse, schedule, prediction, and approval payloads
- Add request size limits
- Add rate limiting on API endpoints
- Add authentication and role-based authorization
- Add CSRF protection if browser-based authenticated forms are used
- Add secure handling for API keys and secrets
- Add logging for suspicious or malformed requests
This would help protect the system from unsafe input, accidental misuse, and malicious requests.
The current agent workflow demonstrates staffing planner, compliance, patient safety, financial audit, and final arbiter behavior. In production, each agent would need stricter guardrails.
Future agent guardrails:
- Require every agent recommendation to cite the data used
- Prevent agents from overriding hospital staffing policy without human approval
- Add hard safety limits for nurse fatigue and maximum weekly hours
- Add compliance checks for credential matching and department qualification
- Add escalation rules for high-risk recommendations
- Require human approval before schedule changes are committed
- Separate advisory output from executable roster updates
- Log every agent decision, input, and output
- Add confidence scoring and uncertainty flags
- Add fallback behavior when LLM APIs fail or quota is unavailable
This ensures that agents support human decision-making rather than replacing it.
SafeStaff AI should remain a decision-support system, not an autonomous staffing authority. Production use would require stronger governance around approvals.
Production governance improvements:
- Require supervisor sign-off for staffing changes
- Add approval roles such as charge nurse, staffing coordinator, and administrator
- Track approve, reject, override, and escalate decisions
- Store decision rationale with each approval
- Add immutable audit logs
- Add downloadable decision reports
- Add notification workflows for approved roster changes
- Add review queues for high-risk staffing events
This would make the system safer and more accountable.
The current audit log demonstrates governance, but production audit logging should be more structured and tamper-resistant.
Future audit improvements:
- Store audit logs in a database rather than local files
- Add immutable append-only audit records
- Track user identity, timestamp, action, and affected schedule
- Track model version and agent version used in each decision
- Track whether the decision used local mode or Live Gemini mode
- Track token usage and external API calls
- Add exportable compliance reports
- Add search and filtering across audit history
This would improve transparency and support operational review.
The current XGBoost model demonstrates ER wait-time forecasting. Production deployment would require stronger model monitoring.
Recommended MLOps improvements:
- Track model version, training dataset, and feature set
- Monitor prediction drift over time
- Compare predicted wait times against actual wait times
- Add automated model performance dashboards
- Add retraining pipelines
- Add model rollback support
- Add baseline model comparison
- Add alerting when model error increases
- Add fairness and bias review for staffing recommendations
This would make the forecasting system more reliable over time.
The current system uses mock nurse registry and demo shift schedule data. A production system would need integration with real hospital systems.
Potential integrations:
- Electronic health record systems
- Staffing and scheduling platforms
- Bed management systems
- ER arrival and triage systems
- Nurse credentialing systems
- Timekeeping and fatigue tracking systems
- Hospital operations dashboards
These integrations would allow the operational pressure engine to work from live hospital data rather than simulated demo inputs.
The prototype is designed around a single workflow instance. Production use would require support for multiple users, departments, and hospitals.
Future scaling improvements:
- Multi-user login
- Multi-hospital configuration
- Department-specific staffing rules
- Site-specific nurse pools
- Per-shift access controls
- Concurrent approval workflows
- Database-backed session state
- Cloud-hosted persistent storage
- Environment-specific configuration for dev, staging, and production
This would allow SafeStaff AI to scale beyond a single demo environment.
SafeStaff AI supports local deterministic mode and Live Gemini mode. Production LLM use should include stronger controls.
Recommended LLM improvements:
- Keep local deterministic mode as the safe fallback
- Add quota and failure detection for live LLM calls
- Add model availability checks before running a workflow
- Add prompt injection protections
- Restrict LLMs from directly modifying schedules
- Store prompts, responses, token usage, and cost in audit logs
- Validate LLM outputs against schemas before using them
- Use LLM output as explanation and reasoning support, not as the sole decision authority
This keeps the system useful while reducing operational risk.
The current Railway deployment is appropriate for a prototype. A production deployment would need stronger infrastructure.
Production infrastructure improvements:
- Separate frontend and backend services
- Managed production database
- Secret management
- HTTPS-only traffic
- Health checks and uptime monitoring
- Centralized logging
- Error monitoring
- CI/CD pipeline
- Automated tests before deployment
- Staging environment before production
- Containerized deployment with Docker
- Backup and rollback strategy
This would make the application more reliable and easier to maintain.
Before production use, the system should include automated tests for the full staffing workflow.
Recommended tests:
- Unit tests for operational pressure rules
- Unit tests for nurse eligibility and fatigue constraints
- API tests for prediction, schedule, nurse registry, reset, approval, and audit routes
- Frontend workflow tests
- End-to-end approval tests
- Security tests for unsafe input
- Regression tests for cache invalidation
- Tests for local mode and Live Gemini fallback behavior
This would reduce the chance of workflow bugs during demos or deployment.
The current version of SafeStaff AI demonstrates the core idea: combining XGBoost wait-time forecasting, operational pressure rules, agentic staffing recommendations, human approval, and audit logging. The next stage would be to move state into a production database, strengthen security guardrails, add persistent memory, improve auditability, harden agent behavior, and integrate with real hospital data systems.
SafeStaff AI turns ER wait-time forecasts into explainable nurse-staffing decisions by combining XGBoost, operational pressure modules, operational memory, RAG policy/SOP grounding, agent-style reasoning, human approval, and audit logging.