File size: 7,576 Bytes
8dea2e3 a6f151c 8dea2e3 3b67e5e 8dea2e3 a6f151c | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 | ---
title: LabLens
emoji: 🔬
colorFrom: green
colorTo: blue
sdk: gradio
sdk_version: 6.31.0
app_file: app.py
pinned: false
license: mit
short_description: Explain your blood test in English, French, Arabic, Darija
---
# 🔬 LabLens
**Snap a photo of your blood test and understand it in plain language — in English, French, Arabic or Tunisian Darija.**
Millions of people receive lab results they can't read. Across North Africa that usually means waiting days for an appointment, or searching online in a language you only half understand. LabLens reads the report, flags what is out of range using fixed medical rules, explains each result calmly, and prepares the questions to ask your doctor. It never diagnoses.
## How it works
```mermaid
flowchart LR
A[Photo or PDF] --> B[Text layer or OCR<br/>with table-rule removal]
B --> C[Line parser<br/>name · value · H/L · unit · range]
C --> D[Catalog matching<br/>EN / FR / AR aliases,<br/>OCR-tolerant, HDL≠LDL margin]
D --> E[You check & edit<br/>the table]
E --> F[Deterministic flagger<br/>range · critical values ·<br/>plausibility · lab marker cross-check]
F --> G[Urgent banner<br/>fixed text, 4 languages]
F --> H[Hosted open LLM<br/>numbers + KB notes only]
H --> I[Guardrails<br/>no diagnosis, no dosing]
I -->|fails| J[Template fallback]
```
## Design decisions
**The LLM never decides what is abnormal or urgent.** Flags come from `lablens/flagger.py`, a few dozen lines of plain rules you can read in two minutes:
0. Physically impossible values (a dropped decimal: HbA1c 436%) become **CHECK**: never "normal", never an alarm.
1. Critical values (e.g. potassium > 6.2 mmol/L) trigger an urgent banner, after unit conversion (French labs report glucose in g/L, white cells in G/L).
2. Otherwise, the report's own reference range decides low/high.
3. No printed range → generic adult range, labelled as such.
4. Unknown unit → no critical escalation (we can't be sure), printed range only.
5. If the lab printed an **H/L marker that contradicts** the numbers we read, the result becomes CHECK. A misread value must never come out reassuring.
**Privacy by construction.** The hosted model only receives test names, values, units, ranges and flags. The image, patient name, lab and dates never leave the extraction step.
**Human in the loop.** OCR misreads digits. Instead of hiding that, LabLens shows exactly what it read in an editable table before explaining anything.
**Guardrails with a safe fallback.** Model output is parsed as JSON, unknown tests are dropped, and any diagnosis or dosing language ("you have diabetes", "take 1000 mg") swaps in a deterministic explanation from the knowledge base.
## Benchmark
There is no public benchmark of multilingual lab reports, so LabLens ships a generator for one: realistic English and French reports (three layouts, decimal commas, `g/L` vs `mg/dL`, `< 2,00` / `[4,00 – 5,60]` range styles, optional H/L markers), each rendered as a clean PDF and as a degraded "phone photo" (rotation, blur, low contrast, grain), with ground-truth JSON. All patients and labs are fictional.
Results on a held-out set of **200 reports (seeds 2000–2199)** that was not used during development:
| split | reports | rows | recall | precision | value_acc | unit_acc | range_acc | flag_acc | critical_recall | dangerous_misses |
|---|---|---|---|---|---|---|---|---|---|---|
| pdf/all | 200 | 1989 | 100.0% | 100.0% | 100.0% | 100.0% | 100.0% | 100.0% | 100.0% | 0 |
| pdf/en | 101 | 1009 | 100.0% | 100.0% | 100.0% | 100.0% | 100.0% | 100.0% | 100.0% | 0 |
| pdf/fr | 99 | 980 | 100.0% | 100.0% | 100.0% | 100.0% | 100.0% | 100.0% | 100.0% | 0 |
| photo/all | 200 | 1989 | 93.2% | 100.0% | 96.0% | 97.1% | 96.9% | 89.2% | 84.8% | 2 |
| photo/en | 101 | 1009 | 92.2% | 100.0% | 96.2% | 98.0% | 97.5% | 88.5% | 88.0% | 1 |
| photo/fr | 99 | 980 | 94.2% | 100.0% | 95.7% | 96.2% | 96.2% | 90.0% | 82.3% | 1 |
- **recall / precision**: rows found / rows extracted that are real
- **flag_acc**: end-to-end status equals ground truth (missed rows count as wrong)
- **critical_recall**: critical values that triggered the urgent path
- **dangerous_misses**: abnormal results shown as *normal* — the number that matters most
PDFs with a text layer are read perfectly. Photos are the hard part. Of the 59 critical values in the photo set, 50 triggered the urgent banner, 4 were shown as "please check this value", 2 rows were not read at all (visible as missing in the review table), 1 could not be judged and 1 was shown as high/low rather than critical. One critical value and one other abnormal value came out as *normal* (OCR misread a digit, and the lab printed no H/L marker to cross-check against). Across all ~590 abnormal photo rows, that is 2 false reassurances: the number this project exists to push to zero. It is why the review table exists, and why a vision model is next on the roadmap.
Reproduce:
```bash
python -m lablens.synth.generator --out benchmark/reports -n 200 --seed 2000
python -m lablens.evaluate --bench benchmark/reports
```
## Run locally
```bash
sudo apt-get install tesseract-ocr tesseract-ocr-fra tesseract-ocr-ara poppler-utils
pip install -r requirements.txt
export HF_TOKEN=hf_... # optional: enables AI explanations
python app.py # http://127.0.0.1:7860
pytest -q # 47 tests, no network needed
```
Without a token the app still works and uses the knowledge-base templates.
| Variable | Default | Purpose |
|---|---|---|
| `HF_TOKEN` or `LLM_API_KEY` | – | Key for any OpenAI-compatible endpoint |
| `LLM_BASE_URL` | `https://router.huggingface.co/v1` | Hugging Face Inference Providers router |
| `LLM_MODEL` | `Qwen/Qwen2.5-72B-Instruct` | Open model used for explanations |
## Deploy to Hugging Face Spaces
1. Create a new Space (SDK: Gradio) and push this repo to it. `packages.txt` installs Tesseract and Poppler.
2. In the Space settings, add `HF_TOKEN` as a secret (a fine-grained token with Inference Providers permission).
## Project layout
```
lablens/
data/catalog.yaml 23 tests: aliases (en/fr/ar), units, ranges, critical & plausible bounds, KB notes
catalog.py name + unit resolution, OCR-tolerant fuzzy matching
extract.py PDF text / OCR (OpenCV clean-up) -> structured rows
flagger.py deterministic flags and urgent escalation
explain.py hosted LLM + guardrails + template fallback
i18n.py fixed safety text in EN / FR / AR / Darija
synth/generator.py synthetic benchmark generator
evaluate.py benchmark metrics
app.py Gradio app
tests/ safety-critical unit tests
```
## Roadmap
- [ ] Vision-language model for photo extraction, compared head-to-head with OCR on this benchmark
- [ ] Arabic-language report layouts in the generator
- [ ] Knowledge base expanded from MedlinePlus (public domain) with retrieval
- [ ] Explanation-quality eval: faithfulness to KB notes, Darija fluency rated by native speakers
- [ ] On-device mode (in-browser model) so nothing leaves the phone
- [ ] Publish the benchmark as a Hugging Face dataset
## Disclaimer
LabLens is an educational project. It explains lab results in plain language; it does not diagnose and does not replace a doctor. Critical thresholds are conservative values from commonly published hospital lists and every lab sets its own.
Built by [Imene Guizani](https://linkedin.com/in/imene-guizani). MIT licensed.
|