# MedGemma StructCore Demo App

This is the implementation-focused demo app for:

**MedGemma StructCore: Local-First Clinical Structuring Engine for EHR**

## Run

```bash
python3 apps/challenge_demo/app_challenge.py
```

Open: `http://localhost:7863`

## Deploy to Hugging Face Spaces Zero

Prepare a minimal Space bundle:

```bash
bash scripts/prepare_hf_zero_challenge_space.sh
```

Bundle output:

```text
.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:

```bash
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.