File size: 7,551 Bytes
613af80
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
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
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
"""Final system: routing, two opinions (RAG and LLM) and rank fusion."""
from __future__ import annotations

from dataclasses import dataclass, field

import numpy as np

from .config import Settings, get_secret
from .embeddings import EntityLinker
from .knowledge_base import KnowledgeBase
from .llm import LLMClient
from .observability import Tracer
from .rag import HierarchicalRAG

DISCLAIMER = "Research tool to support reasoning, not a medical device and not a diagnosis."


def rrf_fusion(rag: list[str], llm_sets: list[set[str]], llm_weight: float, c: int = 1) -> list[str]:
    """Reciprocal Rank Fusion: score = 1 / (c + rank RAG) + w / (c + rank LLM)."""
    score: dict[str, float] = {}
    for r, x in enumerate(rag, 1):
        score[x] = score.get(x, 0) + 1 / (c + r)
    for r, s in enumerate(llm_sets, 1):
        for x in s:
            score[x] = score.get(x, 0) + llm_weight / (c + r)
    return sorted(score, key=score.get, reverse=True)


@dataclass
class Diagnosis:
    ranking: list[str]                       # disease groups, most likely first
    rag: list[str]
    llm_names: list[str]
    llm_sets: list[set[str]]
    metabolic_share: float
    llm_weight: float
    extra: dict = field(default_factory=dict)


class DiagnosticSystem:
    def __init__(self, kb: KnowledgeBase, rag: HierarchicalRAG, linker: EntityLinker, llm: LLMClient,
                 settings: Settings, tracer: Tracer | None = None):
        self.kb, self.rag, self.linker, self.llm, self.settings = kb, rag, linker, llm, settings
        self.tracer = tracer or Tracer(enabled=False)
        # Each step becomes a Langfuse span when observability is enabled
        self.search_rag = self.tracer.wrap(self.search_rag, "RAG : recherche hiérarchique")
        self.llm_diagnoses = self.tracer.wrap(self.llm_diagnoses, "LLM : 10 diagnostics")
        self.diagnose = self.tracer.wrap(self.diagnose, "diagnostic")
        self.understand_note = self.tracer.wrap(self.understand_note, "note -> symptômes HPO")

    # ---- the two opinions ----
    def search_rag(self, codes: list[str]) -> list[str]:
        return self.rag.search(codes, k=self.settings.n_candidates)

    def llm_diagnoses(self, codes: list[str]) -> list[str]:
        return self.llm.diagnoses([self.kb.term_name(h) for h in codes])

    def llm_sets(self, names: list[str], by_family: bool | None = None) -> list[set[str]]:
        """LLM disease names -> ordered list of sets of disease groups (no repetition)."""
        by_family = self.settings.by_family if by_family is None else by_family
        result, seen = [], set()
        for name in names:
            s = set()
            code = self.linker.disease_to_code(name)
            if code:
                s.add(self.kb.group(code))
            if by_family:
                s |= self.linker.family(name)
            s -= seen
            if s:
                result.append(s)
                seen |= s
        return result

    # ---- routing and fusion ----
    def metabolic_share(self, codes: list[str]) -> float:
        return float(np.mean([self.kb.is_metabolic(h) for h in codes])) if codes else 0.0

    def llm_weight(self, codes: list[str]) -> float:
        s = self.settings
        return s.llm_weight_metabolic if self.metabolic_share(codes) >= s.metabolic_threshold else s.llm_weight_clinical

    def fuse(self, rag: list[str], llm_sets: list[set[str]], codes: list[str]) -> list[str]:
        return rrf_fusion(rag, llm_sets, self.llm_weight(codes), self.settings.rrf_constant)

    def diagnose(self, codes: list[str]) -> Diagnosis:
        """HPO codes -> final ranking, with the RAG and LLM opinions."""
        rag = self.search_rag(codes)
        names = self.llm_diagnoses(codes)
        sets = self.llm_sets(names)
        ranking = self.fuse(rag, sets, codes)
        share = self.metabolic_share(codes)
        top5_llm = set().union(*sets[:5]) if sets else set()
        self.tracer.update_span(input={"symptomes": [self.kb.term_name(h) for h in codes]},
                                output={"top5": [self.kb.disease_name(g) for g in ranking[:5]]})
        self.tracer.score("part_metabolique", share)
        self.tracer.score("noms_llm_relies",
                          sum(self.linker.disease_to_code(n) is not None for n in names) / len(names) if names else 0.0)
        self.tracer.score("accord_rag_llm_top5", len(set(rag[:5]) & top5_llm) / 5)
        return Diagnosis(ranking, rag, names, sets, share, self.llm_weight(codes))

    # ---- free text ----
    def understand_note(self, note: str) -> list[tuple[str, str, float]]:
        """Free-text note -> [(HPO code, name, similarity)]; low similarity = "to verify"."""
        found: list[tuple[str, str, float]] = []
        phrases = self.llm.extract_symptoms(note)
        for p in phrases:
            r = self.linker.to_hpo(p)
            if r and r[0] not in [c for c, _, _ in found]:
                found.append(r)
        self.tracer.score("symptomes_reconnus", len(found) / len(phrases) if phrases else 0.0)
        self.tracer.score("symptomes_a_verifier",
                          sum(s < self.settings.to_verify_threshold for _, _, s in found) / len(found) if found else 0.0)
        return found

    # ---- explanation ----
    def shared_symptoms(self, group: str, codes: list[str]) -> list[str]:
        known = set()
        for d in self.kb.diseases_by_group.get(group, []):
            for s in d["symptoms"]:
                known |= self.kb.ancestors(s["hpo"])
        return [self.kb.term_name(h) for h in codes if h in known]

    def explain(self, ranking: list[str], codes: list[str], k: int = 10) -> list[dict]:
        return [{"rank": r, "code": g, "name": self.kb.disease_name(g),
                 "shared_symptoms": self.shared_symptoms(g, codes)[:6]}
                for r, g in enumerate(ranking[:k], 1)]

    def format_ranking(self, ranking: list[str], codes: list[str], k: int = 10) -> str:
        lines = [f"Metabolic share: {self.metabolic_share(codes):.0%} -> LLM weight = {self.llm_weight(codes)}"]
        for item in self.explain(ranking, codes, k):
            lines.append(f"{item['rank']:2d}. {item['name']} ({item['code']})")
            if item["shared_symptoms"]:
                lines.append("     shared symptoms: " + ", ".join(item["shared_symptoms"]))
        lines.append("\n" + DISCLAIMER)
        return "\n".join(lines)


def build_system(settings: Settings | None = None, download: bool = True, tracer: Tracer | None = None,
                 encoder=None, completion_fn=None) -> DiagnosticSystem:
    """Download the data if needed and assemble the full system."""
    from .data_loader import download_public_data
    from .embeddings import load_encoder

    settings = settings or Settings()
    tracer = tracer or Tracer()
    if download:
        download_public_data(settings.data_dir)
    kb = KnowledgeBase.from_dir(settings.data_dir, decontaminate=settings.decontaminate)
    rag = HierarchicalRAG(kb, alpha=settings.alpha)
    linker = EntityLinker(kb, encoder or load_encoder(settings.embedding_model), cache_dir=settings.data_dir,
                          hpo_threshold=settings.hpo_threshold, name_threshold=settings.name_threshold,
                          decontaminated=settings.decontaminate)
    llm = LLMClient(settings.llm_model, api_key=get_secret("GROQ_API_KEY"),
                    cache_path=settings.data_dir / "cache_llm.json", completion_fn=completion_fn, tracer=tracer)
    return DiagnosticSystem(kb, rag, linker, llm, settings, tracer)