add README

README.md

@@ -0,0 +1,113 @@
+# Mehd212/camembert-bio-morpho
+
+French biomedical **token-classification** model for detecting **morphological terms** (tumour / lesion morphology) in clinical oncology texts.
+
+- **Base model**: French biomedical CamemBERT-Bio  
+- **Fine-tuned on**: the **FRACCO** corpus (French Clinical Cases in Oncology), using the `morphologie` annotations  
+- **Task**: Named Entity Recognition (NER) with a single entity type `MORPHO`
+
+This model is intended for research and prototyping, for automatically extracting tumour / lesion morphology mentions from French oncology narratives.
+
+---
+
+## Usage with 🤗 Transformers
+
+```python
+from transformers import AutoTokenizer, AutoModelForTokenClassification, pipeline
+
+model = "Mehd212/camembert-bio-morpho"
+
+tokenizer = AutoTokenizer.from_pretrained(model)
+model = AutoModelForTokenClassification.from_pretrained(model)
+
+ner_pipe = pipeline(
+    "token-classification",
+    model=model,
+    tokenizer=tokenizer,
+    aggregation_strategy="simple",  # merge sub-tokens into full words/spans
+)
+
+text = """Anamnèse
+Patient âgé de 18 ans, traité pour un rétinoblastome bilatéral à 14 mois avec énucléation de l'œil gauche et chimiothérapie de l'œil droit. Après rechute locale, énucléation de l'œil droit à 32 mois. Etude génétique : mutation p.Arg455X dans l'exon 14 du gène Rb1. Elle présente une masse temporale droite évoluant depuis 3 mois.
+
+Examen physique
+État de performance (ECOG) de 1. Masse temporale droite de 4 cm, induration parotidienne et adénopathie latérocervicale droite de 2 cm.
+
+Examens complémentaires
+Une tomodensitométrie du corps entier a été réalisée : masse temporale droite de 4,6 cm. Masse parotidienne droite de 3,5 cm. Adénopathies latérocervicales droites, jusqu'à 1,9 cm.
+Une ponction-aspiration à l'aiguille fine a été effectuée, avec un rapport de néoplasme malin à cellules rondes bleues, compatible avec une récidive de rétinoblastome.
+Adressée au service d'oncologie médicale, une biopsie a été demandée, qui a révélé un néoplasme malin à cellules rondes bleues, mais compatible avec un rhabdomyosarcome embryonnaire, d'après le profil immunohistochimique (MyoD1+).
+
+Diagnostic
+Rhabdomyosarcome embryonnaire dans la zone irradiée ; stade III.
+
+Traitement
+Évalué conjointement avec la chirurgie maxillo-faciale et la radiothérapie, une chimiothérapie a été décidée (schéma VAIA avec une alternance de doxorubicine et de dactomycine) ; pour une chirurgie ultérieure à effort maximal.
+Il a progressé après 3 cycles et une deuxième ligne a été lancée avec du carboplatine et de l'étoposide, avec laquelle il a eu une réponse radiologique complète après 3 cycles, de sorte que la chirurgie a été rejetée et la radiothérapie a été administrée en même temps que les 3 derniers cycles (dose de 67,94 Gy). Elle s'est terminée en août 2011.
+
+Évolution
+En janvier 2012, un scanner a montré une lésion hépatique unique de 7,6 cm, avec un diagnostic différentiel entre un kyste hydatique et une métastase ; elle ne se prêtait pas à un diagnostic percutané en raison de sa localisation et de sa nature kystique. Une hépatectomie droite a été pratiquée, avec un rapport de métastase de rhabdomyosarcome.
+La tomodensitométrie post-chirurgicale a montré une progression métastatique multiple. Elle a présenté le PS 2, avec un syndrome général, des douleurs et de multiples nodules cervicaux bilatéraux.
+Elle a reçu un traitement palliatif par docétaxel-gemcitabine, avec une réponse clinique (rémission de la douleur, de l'asthénie et des lésions cervicales) et une réponse radiologique au scanner.
+Après 6 cycles, elle s'est présentée aux urgences pour un malaise général, un syndrome émétique et une insuffisance respiratoire. Un traitement symptomatique a été mis en place, mais elle est décédée quelques heures plus tard.
+"""  # noqa: E501
+
+entities = ner_pipe(text)
+for ent in entities:
+    print(ent)
+```
+
+---
+
+## Usage with medkit
+
+```python
+import torch
+from medkit.text.ner.hf_entity_matcher import HFEntityMatcher
+from medkit.core.text import TextDocument
+from medkit.text.segmentation import SentenceTokenizer
+
+DEVICE = 0 if torch.cuda.is_available() else -1
+
+morpho_matcher = HFEntityMatcher(
+    model="Mehd212/camembert-bio-morpho",
+    aggregation_strategy="simple",
+    device=DEVICE,
+)
+
+text = """Anamnèse
+Patient âgé de 18 ans, traité pour un rétinoblastome bilatéral...
+"""
+
+doc = TextDocument(text=text)
+
+sent_tok = SentenceTokenizer(
+    output_label="sentence",
+    split_on_newlines=True,
+    punct_chars=[".", "?", "!"],
+    keep_punct=True,
+)
+
+sentence_segs = sent_tok.run([doc.raw_segment])
+
+entities = morpho_matcher.run(sentence_segs)
+
+for ent in entities:
+    print(ent.label, repr(ent.text), [(s.start, s.end) for s in ent.spans])
+```
+
+---
+
+## Results on FRACCO (test set)
+
+Evaluation on the FRACCO **test** split (entity-level, seqeval):
+
+```text
+              precision    recall  f1-score   support
+
+      MORPHO     0.8882    0.9072    0.8976      3837
+
+   micro avg     0.8882    0.9072    0.8976      3837
+   macro avg     0.8882    0.9072    0.8976      3837
+weighted avg     0.8882    0.9072    0.8976      3837
+```