apps/challenge_demo/README.md

MedGemma StructCore Demo App

This is the implementation-focused demo app for:

MedGemma StructCore: Local-First Clinical Structuring Engine for EHR

Run

python3 apps/challenge_demo/app_challenge.py

Open: http://localhost:7863

Deploy to Hugging Face Spaces Zero

Prepare a minimal Space bundle:

bash scripts/prepare_hf_zero_challenge_space.sh

Bundle output:

.dist/hf_zero_challenge_demo_space/

Push that directory to your HF Space repository. The bundle includes:

• Space entrypoint app.py
• minimal requirements.txt
• demo code (apps/challenge_demo)
• parser/risk dependencies (kvt_utils.py, Analysis_Readmission/readmission_risk_engine.py, config JSONs)

Note: in HF Space, default mode should remain mock. pipeline mode requires external Stage1/Stage2 servers reachable from the Space.

Two-stage model artifacts on HF

Model repo (source-of-truth artifacts):

• https://huggingface.co/DocUA/medgemma-1.5-4b-it-gguf-q5-k-m-two-stage

Upload/update artifacts:

python3 scripts/hf_upload_two_stage_models.py \
  --repo-id DocUA/medgemma-1.5-4b-it-gguf-q5-k-m-two-stage \
  --stage1-file /absolute/path/to/stage1.gguf \
  --stage2-file /absolute/path/to/stage2.gguf

Space should be configured via env vars:

• STRUCTCORE_STAGE1_URL, STRUCTCORE_STAGE1_MODEL
• STRUCTCORE_STAGE2_URL, STRUCTCORE_STAGE2_MODEL
• optional: STRUCTCORE_BACKEND_MODE=mock|pipeline

Modes

• mock:

  • offline deterministic extraction (fast, no model server required),
  • useful for demo recording and UI development.

• pipeline:

  • runs real Stage1/Stage2 using existing runners,
  • requires local OpenAI-compatible model servers.

If pipeline mode fails and fallback is enabled, app falls back to mock mode.

Architecture

• app_challenge.py: Gradio UI and orchestration glue.
• services/structcore_service.py: execution modes, normalization, risk scoring.
• services/case_library.py: synthetic demo cases.
• services/evidence_service.py: claim/evidence board data.
• config/evidence_claims.json: status-labeled claims.
• data/synthetic_cases.json: synthetic note samples.

Notes

• This demo is extraction-first.
• Readmission risk is presented as a downstream use case.
• Public demos should use synthetic notes only.