Download lablens/explain.py from Imene-ee/LabLens: direct link, hf CLI and curl.
- Browser
- Download file 9.31 kB
-
https://huggingface.co/spaces/Imene-ee/LabLens/resolve/main/lablens/explain.py
- Command line
-
hf download hf://spaces/Imene-ee/LabLens/lablens/explain.py
-
curl -L -o explain.py https://huggingface.co/spaces/Imene-ee/LabLens/resolve/main/lablens/explain.py
9.31 kB
| """Plain-language explanations: hosted open LLM, grounded and guarded, with a template fallback. | |
| Privacy by construction: the model only ever receives test names, values, units, ranges and | |
| the deterministic flags. The report image, patient name, lab, dates and any other text on | |
| the page never leave the extraction step. | |
| Safety by construction: the model does not decide what is abnormal or urgent. Flags and the | |
| urgent banner are computed by `flagger.py` and rendered from fixed strings in `i18n.py`. | |
| The model's output is checked for diagnosis/treatment claims and replaced by the template | |
| if it fails. | |
| """ | |
| from __future__ import annotations | |
| import json | |
| import os | |
| import re | |
| from .catalog import load_catalog | |
| from .i18n import FLAG_LABEL, HEADINGS, LANGS, TEMPLATE_QUESTION, t | |
| from .models import Analysis, Flag | |
| DEFAULT_BASE_URL = "https://router.huggingface.co/v1" | |
| DEFAULT_MODEL = "Qwen/Qwen2.5-72B-Instruct" | |
| LANG_INSTRUCTIONS = { | |
| "en": "Write in simple English, at the level of a 12-year-old reader.", | |
| "fr": "Écris en français simple, compréhensible par quelqu'un sans formation médicale.", | |
| "ar": "اكتب بالعربية الفصحى المبسّطة التي يفهمها أي شخص.", | |
| "darija": ("Write in Tunisian Arabic (Darija/Tounsi) in Arabic script, the way people speak in Tunis or " | |
| "Sousse. Keep common French medical words as Tunisians say them (analyse, cholestérol). " | |
| "Do not write Modern Standard Arabic."), | |
| } | |
| SYSTEM_PROMPT = """You are LabLens, a careful assistant that explains blood test results to patients in plain language. | |
| Hard rules: | |
| 1. You do NOT diagnose. Never say the person "has" a disease. Use "can be linked to", "is sometimes seen with". | |
| 2. You do NOT recommend medicines, doses, supplements or stopping any treatment. | |
| 3. The status of each result (within range, low, high, very low/high, check) is FINAL and given to you. Never contradict it or re-judge a value yourself. | |
| 4. Only talk about the tests listed in the input. Base explanations on the provided knowledge notes; do not add other medical claims. | |
| 5. Be calm and kind. Abnormal results are common and often minor, but do not dismiss them. | |
| 6. Keep it short: one or two sentences per result. | |
| Return ONLY valid JSON with this shape: | |
| {"summary": "2-3 sentences", "results": [{"key": "<test key>", "explanation": "..."}], "questions": ["3 to 5 short questions to ask a doctor"]} | |
| """ | |
| # Patterns that indicate diagnosis or treatment advice; any hit triggers the template fallback. | |
| BANNED = [ | |
| r"\byou have (?:a |an )?(?:diabetes|anemia|anaemia|cancer|leukemia|kidney disease|hypothyroidism|hyperthyroidism|infection)\b", | |
| r"\byou are (?:diabetic|anemic|anaemic)\b", | |
| r"\bvous (?:avez|êtes) (?:le |un |une |du )?(?:diabète|diabétique|anémie|anémique|cancer|leucémie|infection)\b", | |
| r"\b(?:take|prenez|prends)\s+\d+\s*(?:mg|g|µg|ui|iu)\b", | |
| r"\b(?:stop|arrêtez|arrête)\s+(?:taking|your|votre|ton|de prendre)\b", | |
| r"\bdiagnos(?:is|ed)\s+(?:of|with)\b", | |
| ] | |
| def _payload(analysis: Analysis, lang: str) -> list[dict]: | |
| catalog = load_catalog() | |
| items = [] | |
| for r in analysis.results: | |
| td = catalog.get(r.test_key or "") | |
| if not td: | |
| continue | |
| items.append({ | |
| "key": td.key, | |
| "name": td.display.get(lang) or td.display["en"], | |
| "value": r.value, "unit": r.unit, | |
| "reference_range": [r.ref_low, r.ref_high], | |
| "range_is_generic": r.ref_source == "catalog", | |
| "status": r.flag.value, | |
| "knowledge": {"what": td.kb["what"], | |
| "if_low": td.kb["low"] if r.flag in (Flag.LOW, Flag.CRITICAL_LOW) else None, | |
| "if_high": td.kb["high"] if r.flag in (Flag.HIGH, Flag.CRITICAL_HIGH) else None}, | |
| }) | |
| return items | |
| def violates_guardrails(text: str) -> str | None: | |
| low = text.lower() | |
| for pat in BANNED: | |
| if re.search(pat, low): | |
| return pat | |
| return None | |
| def llm_available() -> bool: | |
| return bool(os.getenv("LLM_API_KEY") or os.getenv("HF_TOKEN")) | |
| def explain_with_llm(analysis: Analysis, lang: str, timeout: float = 45.0) -> dict: | |
| from openai import OpenAI | |
| client = OpenAI( | |
| base_url=os.getenv("LLM_BASE_URL", DEFAULT_BASE_URL), | |
| api_key=os.getenv("LLM_API_KEY") or os.getenv("HF_TOKEN"), | |
| timeout=timeout, | |
| ) | |
| items = _payload(analysis, lang) | |
| user = (f"Language: {LANGS.get(lang, 'English')}. {LANG_INSTRUCTIONS.get(lang, '')}\n\n" | |
| f"Results (JSON):\n{json.dumps(items, ensure_ascii=False)}") | |
| kwargs = dict( | |
| model=os.getenv("LLM_MODEL", DEFAULT_MODEL), | |
| messages=[{"role": "system", "content": SYSTEM_PROMPT}, {"role": "user", "content": user}], | |
| temperature=0.2, | |
| max_tokens=3000, # Arabic/Darija text uses many tokens; truncated JSON can't be parsed | |
| ) | |
| try: # JSON mode where the provider supports it, plain request otherwise | |
| resp = client.chat.completions.create(response_format={"type": "json_object"}, **kwargs) | |
| except Exception as e: | |
| if "response_format" not in str(e) and "json" not in str(e).lower(): | |
| raise | |
| resp = client.chat.completions.create(**kwargs) | |
| text = resp.choices[0].message.content or "" | |
| m = re.search(r"\{.*\}", text, re.S) | |
| if not m: | |
| raise ValueError("model did not return JSON") | |
| data = json.loads(m.group(0)) | |
| valid_keys = {i["key"] for i in items} | |
| data["results"] = [x for x in data.get("results", []) if x.get("key") in valid_keys] | |
| flat = " ".join([data.get("summary", "")] + [x.get("explanation", "") for x in data["results"]] | |
| + list(data.get("questions", []))) | |
| hit = violates_guardrails(flat) | |
| if hit: | |
| raise ValueError(f"guardrail: {hit}") | |
| return data | |
| def explain_with_template(analysis: Analysis, lang: str) -> dict: | |
| """Deterministic fallback. Explanations come straight from the knowledge base (English).""" | |
| catalog = load_catalog() | |
| abnormal = [r for r in analysis.results if r.flag not in (Flag.NORMAL, Flag.UNKNOWN)] | |
| results, questions = [], [] | |
| for r in analysis.results: | |
| td = catalog.get(r.test_key or "") | |
| if not td: | |
| continue | |
| parts = [td.kb["what"]] | |
| if r.flag in (Flag.LOW, Flag.CRITICAL_LOW): | |
| parts.append(td.kb["low"]) | |
| elif r.flag in (Flag.HIGH, Flag.CRITICAL_HIGH): | |
| parts.append(td.kb["high"]) | |
| results.append({"key": td.key, "explanation": " ".join(parts)}) | |
| if r in abnormal and r.flag != Flag.CHECK and len(questions) < 5: | |
| questions.append(t(TEMPLATE_QUESTION, lang).format( | |
| name=td.display.get(lang) or td.display["en"], | |
| flag_lower=t(FLAG_LABEL[r.flag.value], lang).lower(), | |
| value=f"{r.value:g}", unit=r.unit or "")) | |
| n_ab = len([r for r in abnormal if r.flag != Flag.CHECK]) | |
| summary = { | |
| "en": f"{len(results)} results read, {n_ab} outside the reference range.", | |
| "fr": f"{len(results)} résultats lus, dont {n_ab} en dehors des valeurs de référence.", | |
| "ar": f"تمت قراءة {len(results)} نتيجة، منها {n_ab} خارج المعدل المرجعي.", | |
| "darija": f"قريت {len(results)} نتيجة، منهم {n_ab} برّا المعدل.", | |
| } | |
| return {"summary": t(summary, lang), "results": results, "questions": questions} | |
| def explain(analysis: Analysis, lang: str) -> tuple[dict, str]: | |
| """Returns (explanation dict, source) where source is 'llm' or 'template:<reason>'.""" | |
| if not llm_available(): | |
| return explain_with_template(analysis, lang), "template:no-api-key" | |
| try: | |
| return explain_with_llm(analysis, lang), "llm" | |
| except Exception as e: # network, JSON, or guardrail failure -> safe fallback | |
| print(f"[LabLens] AI explanation failed, using template: {type(e).__name__}: {e}", flush=True) | |
| return explain_with_template(analysis, lang), f"template:{type(e).__name__}: {str(e)[:160]}" | |
| def render_markdown(analysis: Analysis, exp: dict, lang: str) -> str: | |
| catalog = load_catalog() | |
| by_key = {x["key"]: x["explanation"] for x in exp.get("results", [])} | |
| lines = [f"### {t(HEADINGS['summary'], lang)}", exp.get("summary", ""), "", | |
| f"### {t(HEADINGS['details'], lang)}"] | |
| order = {Flag.CRITICAL_HIGH: 0, Flag.CRITICAL_LOW: 0, Flag.CHECK: 1, Flag.HIGH: 2, Flag.LOW: 2, | |
| Flag.UNKNOWN: 3, Flag.NORMAL: 4} | |
| normal_names = [] | |
| for r in sorted(analysis.results, key=lambda r: order[r.flag]): | |
| td = catalog.get(r.test_key or "") | |
| if not td: | |
| continue | |
| name = td.display.get(lang) or td.display["en"] | |
| if r.flag == Flag.NORMAL: | |
| normal_names.append(name) | |
| continue | |
| label = t(FLAG_LABEL[r.flag.value], lang) | |
| lines.append(f"- **{name}: {r.value:g} {r.unit or ''}** — _{label}_. {by_key.get(td.key, '')}") | |
| if normal_names: | |
| lines += ["", f"**{t(HEADINGS['normal_list'], lang)}:** " + ", ".join(normal_names)] | |
| if exp.get("questions"): | |
| lines += ["", f"### {t(HEADINGS['questions'], lang)}"] + [f"{i}. {q}" for i, q in enumerate(exp["questions"], 1)] | |
| return "\n".join(lines) | |