pyprocessors-coreference 1.6.18__tar.gz → 1.6.22__tar.gz

{pyprocessors_coreference-1.6.18 → pyprocessors_coreference-1.6.22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pyprocessors-coreference
-Version: 1.6.18
+Version: 1.6.22
 Summary: Processor grouping the mentions of the same entity
 Project-URL: Homepage, https://bitbucket.org/kairntech/pyprocessors_coreference
 Author-email: Olivier Terrier <olivier.terrier@kairntech.com>
@@ -58,8 +58,8 @@ Pour chaque document, entre mentions de même famille de labels :
 - **un label dont le nom finit par un autre label regroupé est de sa famille** : le
   `location` du NER et l'`afplocation` des lexiques AFP annotent le même span, et vont
   dans le même groupe (de même `organization` et `afporganization`) ;
-- **tous les labels de personne forment une seule famille** (`person`, `afpperson`, ou
-  ceux de `person_labels`) ;
+- **tous les labels de personne forment une seule famille** : ceux de la famille
+  `person_family` (`person`, `afpperson`, ou `PER` déclaré dans `label_families`) ;
 - **un nom partiel de personne rejoint le nom complet dont il est la fin**, que le
   nom complet soit avant ou après lui dans le document : « Macron » et « M. Macron »
   rejoignent « Emmanuel Macron » ;
@@ -118,8 +118,8 @@ document = Document(
 | Paramètre | Défaut | Description |
 |-----------|--------|-------------|
 | `labels` | vide | Labels des mentions à regrouper. Vide : tous les labels. |
-| `person_labels` | vide | Labels de personne : ils forment une seule famille, et la règle du nom partiel s'y applique. Vide : tout label dont le nom contient « person » (`person`, `afpperson`…). |
-| `label_families` | vide | Familles de labels regroupés comme un seul, une famille par ligne, ses labels séparés par des virgules (`organization,afporganization,loc_org`). Un label non déclaré rejoint la famille du label le plus court qui termine son nom. |
+| `label_families` | vide | Familles de labels regroupés comme un seul, chaque label associé à sa famille, les labels de même famille regroupés : un autre label (`loc_org` → `organization`) ou un nom libre (`loc_org` → `1`, `organization` → `1`). Un label non déclaré rejoint la famille du label le plus court qui termine son nom. |
+| `person_family` | `person` | Famille des noms de personne : ses labels forment un seul groupe, et la règle du nom partiel s'y applique. Un label d'un autre nom la rejoint par `label_families` (`PER` → `person`). |
 | `honorifics` | `M.`, `Mme`, `Dr`, `Mr`… | Civilités ignorées en tête d'un nom de personne. Paramètre avancé. |
 
 ## Development

{pyprocessors_coreference-1.6.18 → pyprocessors_coreference-1.6.22}/README.md

@@ -28,8 +28,8 @@ Pour chaque document, entre mentions de même famille de labels :
 - **un label dont le nom finit par un autre label regroupé est de sa famille** : le
   `location` du NER et l'`afplocation` des lexiques AFP annotent le même span, et vont
   dans le même groupe (de même `organization` et `afporganization`) ;
-- **tous les labels de personne forment une seule famille** (`person`, `afpperson`, ou
-  ceux de `person_labels`) ;
+- **tous les labels de personne forment une seule famille** : ceux de la famille
+  `person_family` (`person`, `afpperson`, ou `PER` déclaré dans `label_families`) ;
 - **un nom partiel de personne rejoint le nom complet dont il est la fin**, que le
   nom complet soit avant ou après lui dans le document : « Macron » et « M. Macron »
   rejoignent « Emmanuel Macron » ;
@@ -88,8 +88,8 @@ document = Document(
 | Paramètre | Défaut | Description |
 |-----------|--------|-------------|
 | `labels` | vide | Labels des mentions à regrouper. Vide : tous les labels. |
-| `person_labels` | vide | Labels de personne : ils forment une seule famille, et la règle du nom partiel s'y applique. Vide : tout label dont le nom contient « person » (`person`, `afpperson`…). |
-| `label_families` | vide | Familles de labels regroupés comme un seul, une famille par ligne, ses labels séparés par des virgules (`organization,afporganization,loc_org`). Un label non déclaré rejoint la famille du label le plus court qui termine son nom. |
+| `label_families` | vide | Familles de labels regroupés comme un seul, chaque label associé à sa famille, les labels de même famille regroupés : un autre label (`loc_org` → `organization`) ou un nom libre (`loc_org` → `1`, `organization` → `1`). Un label non déclaré rejoint la famille du label le plus court qui termine son nom. |
+| `person_family` | `person` | Famille des noms de personne : ses labels forment un seul groupe, et la règle du nom partiel s'y applique. Un label d'un autre nom la rejoint par `label_families` (`PER` → `person`). |
 | `honorifics` | `M.`, `Mme`, `Dr`, `Mr`… | Civilités ignorées en tête d'un nom de personne. Paramètre avancé. |
 
 ## Development

{pyprocessors_coreference-1.6.18 → pyprocessors_coreference-1.6.22}/docs/sherpa/coreference.en.md

@@ -47,8 +47,8 @@ Properties the annotation already carried are kept. Processing the same document
 | Parameter | Default | Effect |
 |---|---|---|
 | **Labels** (`labels`) | — (all labels) | Labels of the mentions to group. Annotations of other labels get no property. Empty, all annotations are grouped. |
-| **Person Labels** (`person_labels`) | — (labels containing "person") | Labels of person names. They form a single family, and only these names benefit from the partial-name rule ("Macron" joins "Emmanuel Macron"). Empty, these are the labels whose name contains "person": `person`, `afpperson`… A `PER` label must therefore be declared here. |
-| **Label Families** (`label_families`) | — | Families of labels grouped as one, one family per line, its labels separated by commas (organization,afporganization,loc_org).<br/> A label not declared here belongs to the family of the shortest label that ends its name (afplocation with location). |
+| **Label Families** (`label_families`) | — | Families of labels grouped as one, each label mapped to its family, the labels mapped to the same family grouped together: another label (`loc_org` → `organization`) or any name (`loc_org` → `1`, `organization` → `1`).<br/> A label not declared here belongs to the family of the shortest label that ends its name (afplocation with location). |
+| **Person Family** (`person_family`) *(advanced)* | `person` | Family of person names: its labels form a single group (`person` and `afpperson`), and only these names benefit from the partial-name rule ("Macron" joins "Emmanuel Macron"). A label of another name joins it through **Label Families** (`PER` → `person`). |
 | **Honorifics** (`honorifics`) *(advanced)* | `["M.", "MM.", "Mme", "Mmes", "Mlle", "Mlles", "Me", "Dr", "Dr.", "Pr", "Pr.", "Mr", "Mr.", "Mrs", …` | Titles ignored in front of a person name, regardless of case. They are not part of the canonical form either. |
 
 <!-- /generated:parameters -->
@@ -166,7 +166,7 @@ Output annotations:
 
 ### 4. Declaring a label family
 
-`loc_org` ends with no other label: undeclared, it stays alone. With **Label Families** = `organization,loc_org`, the "PSG" annotated `loc_org` joins the one annotated `organization`:
+`loc_org` ends with no other label: undeclared, it stays alone. With **Label Families** = `loc_org` → `organization`, the "PSG" annotated `loc_org` joins the one annotated `organization`:
 
 <!-- generated:example:label-families -->
 
@@ -182,7 +182,7 @@ Input annotations:
 | Parc des Princes | `location` | 1.00 |
 | PSG *(#2)* | `organization` | 1.00 |
 
-Parameters: **Label Families** = `["organization,loc_org"]`.
+Parameters: **Label Families** = `{"loc_org": "organization"}`.
 
 Output annotations:
 
@@ -224,9 +224,9 @@ Output annotations:
 
 ## Known limitations
 
-- **A `PER` label is not recognized as a person by default.** Only the labels whose name contains "person" are. With `PER` annotations, "Macron" does not join "Emmanuel Macron" as long as `PER` is not declared in **Person Labels**. Once declared, it groups them:
+- **A `PER` label is not recognized as a person by default.** Only the labels whose name ends with "person" are. With `PER` annotations, "Macron" does not join "Emmanuel Macron" as long as **Label Families** does not map `PER` to `person`. Once declared, it groups them:
 
-<!-- generated:example:person-labels -->
+<!-- generated:example:person-family -->
 
 Text (French):
 
@@ -239,7 +239,7 @@ Input annotations:
 | Emmanuel Macron | `PER` | 1.00 |
 | Macron | `PER` | 1.00 |
 
-Parameters: **Person Labels** = `["PER"]`.
+Parameters: **Label Families** = `{"PER": "person"}`.
 
 Output annotations:
 
@@ -248,7 +248,7 @@ Output annotations:
 | Emmanuel Macron | `PER` | 1.00 | `canonical_form`: Emmanuel Macron<br>`entity_group`: g1<br>`mention_type`: name |
 | Macron | `PER` | 1.00 | `canonical_form`: Emmanuel Macron<br>`entity_group`: g1<br>`mention_type`: name |
 
-<!-- /generated:example:person-labels -->
+<!-- /generated:example:person-family -->
 
 - **The partial-name rule only looks at the end of the name.** Two different people sharing a last name are grouped if only one appears in full: in a document that only cites "Brigitte Macron", a "Macron" designating her husband joins her.
 - **A title missing from the list is part of the name.** "Général Martin" is not reduced to "Martin"; it is grouped with "Martin" by the partial-name rule, but the canonical form of the group then becomes "Général Martin".

{pyprocessors_coreference-1.6.18 → pyprocessors_coreference-1.6.22}/docs/sherpa/coreference.fr.md

@@ -47,8 +47,8 @@ Les propriétés que l'annotation portait déjà sont conservées. Traiter deux
 | Paramètre | Valeur par défaut | Effet |
 |---|---|---|
 | **Labels** (`labels`) | — (tous les labels) | Labels des mentions à regrouper. Les annotations des autres labels ne reçoivent aucune propriété. Vide, toutes les annotations sont regroupées. |
-| **Person Labels** (`person_labels`) | — (les labels contenant « person ») | Labels des noms de personnes. Ils forment une seule famille, et seuls ces noms bénéficient de la règle du nom partiel (« Macron » rejoint « Emmanuel Macron »). Vide, ce sont les labels dont le nom contient « person » : `person`, `afpperson`… Un label `PER` doit donc être déclaré ici. |
-| **Label Families** (`label_families`) | — | Familles de labels regroupés comme un seul, une famille par ligne, ses labels séparés par des virgules (`organization,afporganization,loc_org`). Un label non déclaré ici rejoint la famille du label le plus court qui termine son nom (`afplocation` avec `location`). |
+| **Label Families** (`label_families`) | — | Familles de labels regroupés comme un seul, chaque label associé à sa famille, les labels de même famille regroupés : un autre label (`loc_org` → `organization`) ou un nom libre (`loc_org` → `1`, `organization` → `1`). Un label non déclaré ici rejoint la famille du label le plus court qui termine son nom (`afplocation` avec `location`). |
+| **Person Family** (`person_family`) *(avancé)* | `person` | Famille des noms de personne : ses labels forment un seul groupe (`person` et `afpperson`), et seuls ces noms bénéficient de la règle du nom partiel (« Macron » rejoint « Emmanuel Macron »). Un label d'un autre nom la rejoint par **Label Families** (`PER` → `person`). |
 | **Honorifics** (`honorifics`) *(avancé)* | `["M.", "MM.", "Mme", "Mmes", "Mlle", "Mlles", "Me", "Dr", "Dr.", "Pr", "Pr.", "Mr", "Mr.", "Mrs", …` | Civilités ignorées devant un nom de personne, sans tenir compte des majuscules. Elles ne figurent pas non plus dans la forme canonique. |
 
 <!-- /generated:parameters -->
@@ -166,7 +166,7 @@ Annotations en sortie :
 
 ### 4. Déclarer une famille de labels
 
-`loc_org` ne finit par aucun autre label : sans déclaration, il reste seul. Avec **Label Families** = `organization,loc_org`, le « PSG » annoté `loc_org` rejoint celui annoté `organization` :
+`loc_org` ne finit par aucun autre label : sans déclaration, il reste seul. Avec **Label Families** = `loc_org` → `organization`, le « PSG » annoté `loc_org` rejoint celui annoté `organization` :
 
 <!-- generated:example:label-families -->
 
@@ -182,7 +182,7 @@ Annotations en entrée :
 | Parc des Princes | `location` | 1,00 |
 | PSG *(n°2)* | `organization` | 1,00 |
 
-Paramètres : **Label Families** = `["organization,loc_org"]`.
+Paramètres : **Label Families** = `{"loc_org": "organization"}`.
 
 Annotations en sortie :
 
@@ -224,9 +224,9 @@ Annotations en sortie :
 
 ## Limites à connaître
 
-- **Un label `PER` n'est pas reconnu comme personne par défaut.** Seuls les labels dont le nom contient « person » le sont. Avec des annotations `PER`, « Macron » ne rejoint pas « Emmanuel Macron » tant que `PER` n'est pas déclaré dans **Person Labels**. Déclaré, il les regroupe :
+- **Un label `PER` n'est pas reconnu comme personne par défaut.** Seuls les labels dont le nom finit par « person » le sont. Avec des annotations `PER`, « Macron » ne rejoint pas « Emmanuel Macron » tant que **Label Families** n'associe pas `PER` à `person`. Déclaré, il les regroupe :
 
-<!-- generated:example:person-labels -->
+<!-- generated:example:person-family -->
 
 Texte (français) :
 
@@ -239,7 +239,7 @@ Annotations en entrée :
 | Emmanuel Macron | `PER` | 1,00 |
 | Macron | `PER` | 1,00 |
 
-Paramètres : **Person Labels** = `["PER"]`.
+Paramètres : **Label Families** = `{"PER": "person"}`.
 
 Annotations en sortie :
 
@@ -248,7 +248,7 @@ Annotations en sortie :
 | Emmanuel Macron | `PER` | 1,00 | `canonical_form` : Emmanuel Macron<br>`entity_group` : g1<br>`mention_type` : name |
 | Macron | `PER` | 1,00 | `canonical_form` : Emmanuel Macron<br>`entity_group` : g1<br>`mention_type` : name |
 
-<!-- /generated:example:person-labels -->
+<!-- /generated:example:person-family -->
 
 - **La règle du nom partiel ne regarde que la fin du nom.** Deux personnes différentes qui partagent un nom de famille sont regroupées si une seule apparaît en entier : dans un document qui ne cite que « Brigitte Macron », un « Macron » qui désigne son mari la rejoint.
 - **Une civilité absente de la liste fait partie du nom.** « Général Martin » ne se réduit pas à « Martin » ; il est regroupé avec « Martin » par la règle du nom partiel, mais la forme canonique du groupe devient alors « Général Martin ».

{pyprocessors_coreference-1.6.18 → pyprocessors_coreference-1.6.22}/src/pyprocessors_coreference/__init__.py

@@ -1,3 +1,3 @@
 """Processor grouping the mentions of the same entity"""
 
-__version__ = "1.6.18"
+__version__ = "1.6.22"

{pyprocessors_coreference-1.6.18 → pyprocessors_coreference-1.6.22}/src/pyprocessors_coreference/coreference.py

@@ -36,18 +36,19 @@ class CoreferenceParameters(ProcessorParameters):
         belongs to its family (afplocation with location, afporganization with organization), and all person labels form one family.""",
         json_schema_extra={"extra": "label"},
     )
-    person_labels: list[str] | None = Field(
+    label_families: dict[str, str] | None = Field(
         None,
-        description="""Labels of person names. They form one family (person and afpperson mentions are grouped together),
-        and a partial name ("Macron") joins the full name it ends ("Emmanuel Macron").<br/>
-        If empty, every label whose name contains "person" (person, afpperson...).""",
-        json_schema_extra={"extra": "label"},
-    )
-    label_families: list[str] | None = Field(
-        None,
-        description="""Families of labels grouped as one, one family per line, its labels separated by commas
-        (organization,afporganization,loc_org).<br/>
+        description="""Families of labels grouped as one: each label is mapped to its family, and the labels mapped to the same family
+        are grouped together. The family is another label (loc_org → organization) or any name (loc_org → 1, organization → 1).<br/>
         A label not declared here belongs to the family of the shortest label that ends its name (afplocation with location).""",
+        json_schema_extra={"extra": "key:label"},
+    )
+    person_family: str = Field(
+        "person",
+        description="""Family of person names: its labels are grouped together (person and afpperson mentions),
+        and a partial name ("Macron") joins the full name it ends ("Emmanuel Macron").<br/>
+        A label of another name joins it through Label Families (PER → person).""",
+        json_schema_extra={"extra": "advanced"},
     )
     honorifics: list[str] = Field(
         DEFAULT_HONORIFICS,
@@ -149,33 +150,28 @@ def group_document(document: Document, params: CoreferenceParameters, honorifics
 
 
 def label_families(labels: set[str], params: CoreferenceParameters) -> dict[str, str]:
-    """Label → family, ignoring case: PERSON_FAMILY for a person label, the first label
-    of its line for a label declared in `label_families`, otherwise the family of the
-    shortest known label that ends its name ("afplocation" → "location")."""
-    declared: dict[str, str] = {}
-    for line in params.label_families or []:
-        members = [m.strip().casefold() for m in line.split(",") if m.strip()]
-        declared.update((m, members[0]) for m in members)
-    known = {label.casefold() for label in labels} | declared.keys()
+    """Label → family, ignoring case: its value for a label declared in `label_families`
+    (a value is its own family, so that "organization" joins the labels mapped to it),
+    otherwise the family of the shortest known label that ends its name ("afplocation" →
+    "location"). The family `person_family` is PERSON_FAMILY."""
+    declared = {k.strip().casefold(): v.strip().casefold() for k, v in (params.label_families or {}).items() if k.strip() and v.strip()}
+    for value in list(declared.values()):
+        declared.setdefault(value, value)
+    person = params.person_family.strip().casefold()
+    known = {label.casefold() for label in labels} | declared.keys() | ({person} - {""})
 
     def family(label: str) -> str:
-        if is_person_label(label, params):
-            return PERSON_FAMILY
         folded = label.casefold()
         if folded in declared:
-            return declared[folded]
-        base = min((k for k in known if folded.endswith(k)), key=len)
-        return declared.get(base, base)
+            found = declared[folded]
+        else:
+            base = min((k for k in known if folded.endswith(k)), key=len)
+            found = declared.get(base, base)
+        return PERSON_FAMILY if found == person else found
 
     return {label: family(label) for label in labels}
 
 
-def is_person_label(label: str, params: CoreferenceParameters) -> bool:
-    if params.person_labels:
-        return label in params.person_labels
-    return "person" in label.casefold()
-
-
 def surface_of(a: Annotation, text: str) -> str:
     return a.text if a.text is not None else text[a.start : a.end]