Imene-ee commited on
Commit
a6f151c
·
verified ·
1 Parent(s): dab7db2

Upload README.md

Browse files
Files changed (1) hide show
  1. README.md +123 -5
README.md CHANGED
@@ -1,15 +1,133 @@
1
  ---
2
  title: LabLens
3
- emoji: 🌖
4
- colorFrom: indigo
5
- colorTo: pink
6
  sdk: gradio
7
  sdk_version: 6.31.0
8
- python_version: '3.12'
9
  app_file: app.py
10
  pinned: false
11
  license: mit
12
  short_description: Explain your blood test in English, French, Arabic, Darija
13
  ---
14
 
15
- Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
  ---
2
  title: LabLens
3
+ emoji: 🔬
4
+ colorFrom: green
5
+ colorTo: blue
6
  sdk: gradio
7
  sdk_version: 6.31.0
 
8
  app_file: app.py
9
  pinned: false
10
  license: mit
11
  short_description: Explain your blood test in English, French, Arabic, Darija
12
  ---
13
 
14
+ # 🔬 LabLens
15
+
16
+ **Snap a photo of your blood test and understand it in plain language — in English, French, Arabic or Tunisian Darija.**
17
+
18
+ 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.
19
+
20
+ ## How it works
21
+
22
+ ```mermaid
23
+ flowchart LR
24
+ A[Photo or PDF] --> B[Text layer or OCR<br/>with table-rule removal]
25
+ B --> C[Line parser<br/>name · value · H/L · unit · range]
26
+ C --> D[Catalog matching<br/>EN / FR / AR aliases,<br/>OCR-tolerant, HDL≠LDL margin]
27
+ D --> E[You check & edit<br/>the table]
28
+ E --> F[Deterministic flagger<br/>range · critical values ·<br/>plausibility · lab marker cross-check]
29
+ F --> G[Urgent banner<br/>fixed text, 4 languages]
30
+ F --> H[Hosted open LLM<br/>numbers + KB notes only]
31
+ H --> I[Guardrails<br/>no diagnosis, no dosing]
32
+ I -->|fails| J[Template fallback]
33
+ ```
34
+
35
+ ## Design decisions
36
+
37
+ **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:
38
+
39
+ 0. Physically impossible values (a dropped decimal: HbA1c 436%) become **CHECK**: never "normal", never an alarm.
40
+ 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).
41
+ 2. Otherwise, the report's own reference range decides low/high.
42
+ 3. No printed range → generic adult range, labelled as such.
43
+ 4. Unknown unit → no critical escalation (we can't be sure), printed range only.
44
+ 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.
45
+
46
+ **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.
47
+
48
+ **Human in the loop.** OCR misreads digits. Instead of hiding that, LabLens shows exactly what it read in an editable table before explaining anything.
49
+
50
+ **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.
51
+
52
+ ## Benchmark
53
+
54
+ 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.
55
+
56
+ Results on a held-out set of **200 reports (seeds 2000–2199)** that was not used during development:
57
+
58
+ | split | reports | rows | recall | precision | value_acc | unit_acc | range_acc | flag_acc | critical_recall | dangerous_misses |
59
+ |---|---|---|---|---|---|---|---|---|---|---|
60
+ | pdf/all | 200 | 1989 | 100.0% | 100.0% | 100.0% | 100.0% | 100.0% | 100.0% | 100.0% | 0 |
61
+ | pdf/en | 101 | 1009 | 100.0% | 100.0% | 100.0% | 100.0% | 100.0% | 100.0% | 100.0% | 0 |
62
+ | pdf/fr | 99 | 980 | 100.0% | 100.0% | 100.0% | 100.0% | 100.0% | 100.0% | 100.0% | 0 |
63
+ | photo/all | 200 | 1989 | 93.2% | 100.0% | 96.0% | 97.1% | 96.9% | 89.2% | 84.8% | 2 |
64
+ | photo/en | 101 | 1009 | 92.2% | 100.0% | 96.2% | 98.0% | 97.5% | 88.5% | 88.0% | 1 |
65
+ | photo/fr | 99 | 980 | 94.2% | 100.0% | 95.7% | 96.2% | 96.2% | 90.0% | 82.3% | 1 |
66
+
67
+ - **recall / precision**: rows found / rows extracted that are real
68
+ - **flag_acc**: end-to-end status equals ground truth (missed rows count as wrong)
69
+ - **critical_recall**: critical values that triggered the urgent path
70
+ - **dangerous_misses**: abnormal results shown as *normal* — the number that matters most
71
+
72
+ 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.
73
+
74
+ Reproduce:
75
+
76
+ ```bash
77
+ python -m lablens.synth.generator --out benchmark/reports -n 200 --seed 2000
78
+ python -m lablens.evaluate --bench benchmark/reports
79
+ ```
80
+
81
+ ## Run locally
82
+
83
+ ```bash
84
+ sudo apt-get install tesseract-ocr tesseract-ocr-fra tesseract-ocr-ara poppler-utils
85
+ pip install -r requirements.txt
86
+ export HF_TOKEN=hf_... # optional: enables AI explanations
87
+ python app.py # http://127.0.0.1:7860
88
+ pytest -q # 47 tests, no network needed
89
+ ```
90
+
91
+ Without a token the app still works and uses the knowledge-base templates.
92
+
93
+ | Variable | Default | Purpose |
94
+ |---|---|---|
95
+ | `HF_TOKEN` or `LLM_API_KEY` | – | Key for any OpenAI-compatible endpoint |
96
+ | `LLM_BASE_URL` | `https://router.huggingface.co/v1` | Hugging Face Inference Providers router |
97
+ | `LLM_MODEL` | `Qwen/Qwen2.5-72B-Instruct` | Open model used for explanations |
98
+
99
+ ## Deploy to Hugging Face Spaces
100
+
101
+ 1. Create a new Space (SDK: Gradio) and push this repo to it. `packages.txt` installs Tesseract and Poppler.
102
+ 2. In the Space settings, add `HF_TOKEN` as a secret (a fine-grained token with Inference Providers permission).
103
+
104
+ ## Project layout
105
+
106
+ ```
107
+ lablens/
108
+ data/catalog.yaml 23 tests: aliases (en/fr/ar), units, ranges, critical & plausible bounds, KB notes
109
+ catalog.py name + unit resolution, OCR-tolerant fuzzy matching
110
+ extract.py PDF text / OCR (OpenCV clean-up) -> structured rows
111
+ flagger.py deterministic flags and urgent escalation
112
+ explain.py hosted LLM + guardrails + template fallback
113
+ i18n.py fixed safety text in EN / FR / AR / Darija
114
+ synth/generator.py synthetic benchmark generator
115
+ evaluate.py benchmark metrics
116
+ app.py Gradio app
117
+ tests/ safety-critical unit tests
118
+ ```
119
+
120
+ ## Roadmap
121
+
122
+ - [ ] Vision-language model for photo extraction, compared head-to-head with OCR on this benchmark
123
+ - [ ] Arabic-language report layouts in the generator
124
+ - [ ] Knowledge base expanded from MedlinePlus (public domain) with retrieval
125
+ - [ ] Explanation-quality eval: faithfulness to KB notes, Darija fluency rated by native speakers
126
+ - [ ] On-device mode (in-browser model) so nothing leaves the phone
127
+ - [ ] Publish the benchmark as a Hugging Face dataset
128
+
129
+ ## Disclaimer
130
+
131
+ 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.
132
+
133
+ Built by [Imene Guizani](https://linkedin.com/in/imene-guizani). MIT licensed.