MedRec Sentinel

An audit-first medication reconciliation prototype for discharge review.

MedRec Sentinel turns an unstructured discharge note into a structured medication list, applies deterministic safety checks, and produces a draft review note with citations and verification questions. The model is used for extraction; the safety rules remain explicit and inspectable, and a clinician or pharmacist makes the final decision.

The project was developed as a solo submission to the MedGemma Impact Challenge, targeting the Agentic Workflow Prize.

Workflow

Discharge note
    -> baseline or MedGemma extraction
    -> strict schema validation
    -> bounded repair and retry
    -> deterministic medication-safety rules
    -> risk flags with citations
    -> draft pharmacist note and verification questions

The implementation includes:

• a deterministic baseline extractor that runs without model weights;
• an optional google/medgemma-4b-it extraction path;
• Pydantic contracts for medications, allergies, and renal data;
• bounded repair when model output does not satisfy the JSON contract;
• curated checks for duplicate drug classes, interaction risk, renal risk, and allergy conflicts;
• cited risk flags and a pharmacist-facing draft note;
• an agent trace showing the stages and timing of a run;
• a Gradio demonstration interface;
• a synthetic evaluation set and Pytest coverage.

Reproducible baseline result

The repository includes a small synthetic dataset at data/synth/cases.jsonl. On that dataset, the recorded baseline evaluation produced:

Metric	Result
Successful cases	100%
Medication extraction micro-F1	0.5857
Risk-flag micro-precision	0.5714
Risk-flag micro-recall	1.0000
Risk-flag micro-F1	0.7273

These figures describe the included synthetic cases, not clinical performance. MedGemma results are not reported because reproducing that path requires gated model access and the repository does not preserve a verified result set for it.

Run locally

git clone https://github.com/roivroberto/medrec-sentinel.git
cd medrec-sentinel
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt -r requirements-dev.txt

Run the baseline evaluation without model weights:

python3 -m medrec_sentinel.eval.run_eval \
  --data data/synth/cases.jsonl \
  --mode baseline

Launch the Gradio interface:

python3 demo/gradio_app.py

Run the test suite:

pytest -q

The optional MedGemma path requires access to the gated model weights and the dependencies listed in requirements-gpu.txt. The baseline path remains available for inspecting the complete workflow without those weights.

Challenge material

• Three-minute submission video
• docs/kaggle_writeup.md - submission summary and technical path
• docs/writeup_3pager.md - problem, architecture, evaluation, and safety scope

Project scope

MedRec Sentinel is a research and workflow prototype. Its rules cover a deliberately small set of synthetic scenarios, and its output requires professional review. Deployment with real clinical data would require institutional validation, governance, privacy controls, and broader medication knowledge.

License

Licensed under the MIT License.