pyprocessors-coreference 1.6.8__tar.gz → 1.6.12__tar.gz

{pyprocessors_coreference-1.6.8 → pyprocessors_coreference-1.6.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pyprocessors-coreference
-Version: 1.6.8
+Version: 1.6.12
 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>

pyprocessors_coreference-1.6.12/docs/sherpa/coreference.en.md

@@ -0,0 +1,224 @@
+# Coreference Processor (`coreference`)
+
+Groups the mentions of the same entity in a document: "Emmanuel Macron", "M. Macron" and "MACRON" get the same group identifier and the same canonical form, "Emmanuel Macron".
+
+## When to use it
+
+- Before linking to a knowledge base (Entity-Fishing, a lexicon): linking then looks for the full form of the name, easier to identify, and applies the same result to all the mentions of the group.
+- To count or follow the entities of a newswire corpus, where a full name is often taken up by the last name alone, with or without title.
+
+## When not to use it
+
+- The processor only groups **names**. It does not link a pronoun ("il", "elle") or a description ("le président") to the name they designate.
+- It finds no entity: it works on the annotations made by an annotator placed before it (a named-entity model, a lexicon).
+- It does not group mentions across documents: groups are specific to each document.
+
+## Prerequisites
+
+| Prerequisite | Required | Why |
+|---|---|---|
+| Entity annotations | **Yes** | The processor only groups existing annotations. A document without annotation is returned as is. |
+
+<!-- generated:languages -->
+
+**Supported languages:** the plugin declares no language restriction.
+
+<!-- /generated:languages -->
+
+Name comparison does not depend on the language, but the default **Honorifics** list only contains French and English titles.
+
+## What it produces
+
+The processor neither creates nor removes annotations. It adds **properties** to each annotation it groups:
+
+| Property | Content | Example |
+|---|---|---|
+| `entity_group` | the group identifier, the same for all the mentions of an entity in the document, numbered in order of appearance | `g1` |
+| `canonical_form` | the longest form of the group, without title: the most words, then the most characters | `Emmanuel Macron` |
+| `mention_type` | the type of mention, always `name` | `name` |
+| `entity_group_candidates` | only for an ambiguous partial name: the groups it could belong to | `["g1", "g2"]` |
+
+Properties the annotation already carried are kept. Processing the same document twice gives the same result.
+
+## Parameters
+
+<!-- generated:parameters -->
+
+| 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. |
+| **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 -->
+
+## How it works
+
+Two mentions go in the same group in the following cases:
+
+1. **Same form and same label.** The comparison ignores case and apostrophe variants: "Airbus" and "AIRBUS" are grouped.
+2. **Same family of persons.** All person labels count as one: a "George Lucas" annotated `person` by a model and `afpperson` by a lexicon forms a single group.
+3. **Partial name, for persons only.** A name that ends a longer name joins this name, whether it appears before or after it in the document: "Macron" and "M. Macron" join "Emmanuel Macron". The **Honorifics** titles are ignored for the comparison.
+
+Are **never** grouped:
+
+- **a first name alone**: "Emmanuel" does not join "Emmanuel Macron", as it does not end the name;
+- **an ambiguous partial name**: with "Emmanuel Macron" and "Brigitte Macron" in the same document, "Macron" forms its own group. Its `entity_group_candidates` property lists the two possible groups, and the linking step decides;
+- **different labels**, persons aside: the person "George Washington" and the place "Washington" stay separate;
+- **a partial name of an organization or a place**: "Airbus" does not join "Airbus Defence and Space".
+
+## Examples
+
+In each example, the output table shows the properties added to each annotation.
+
+### 1. A partial name joins the full name
+
+"M. Macron" joins "Emmanuel Macron": same group `g1`, same canonical form. The first name alone, "Emmanuel", forms its own group:
+
+<!-- generated:example:partial-name -->
+
+Text (French):
+
+> Emmanuel Macron parle. M. Macron sourit. Emmanuel repart.
+
+Input annotations:
+
+| Annotated text | Label | Score |
+|---|---|---|
+| Emmanuel Macron | `person` | 1.00 |
+| M. Macron | `person` | 1.00 |
+| Emmanuel | `person` | 1.00 |
+
+Default parameters.
+
+Output annotations:
+
+| Annotated text | Label | Score | Properties |
+|---|---|---|---|
+| Emmanuel Macron | `person` | 1.00 | `canonical_form`: Emmanuel Macron<br>`entity_group`: g1<br>`mention_type`: name |
+| M. Macron | `person` | 1.00 | `canonical_form`: Emmanuel Macron<br>`entity_group`: g1<br>`mention_type`: name |
+| Emmanuel | `person` | 1.00 | `canonical_form`: Emmanuel<br>`entity_group`: g2<br>`mention_type`: name |
+
+<!-- /generated:example:partial-name -->
+
+### 2. An ambiguous partial name
+
+Two people bear the name "Macron": the mention "Macron" forms its own group, and `entity_group_candidates` lists the two possible groups:
+
+<!-- generated:example:ambiguous -->
+
+Text (French):
+
+> Emmanuel Macron et Brigitte Macron voyagent. Macron sourit.
+
+Input annotations:
+
+| Annotated text | Label | Score |
+|---|---|---|
+| Emmanuel Macron | `person` | 1.00 |
+| Brigitte Macron | `person` | 1.00 |
+| Macron | `person` | 1.00 |
+
+Default parameters.
+
+Output annotations:
+
+| Annotated text | Label | Score | Properties |
+|---|---|---|---|
+| Emmanuel Macron | `person` | 1.00 | `canonical_form`: Emmanuel Macron<br>`entity_group`: g1<br>`mention_type`: name |
+| Brigitte Macron | `person` | 1.00 | `canonical_form`: Brigitte Macron<br>`entity_group`: g2<br>`mention_type`: name |
+| Macron | `person` | 1.00 | `canonical_form`: Macron<br>`entity_group`: g3<br>`entity_group_candidates`: ["g1", "g2"]<br>`mention_type`: name |
+
+<!-- /generated:example:ambiguous -->
+
+### 3. Organizations and places
+
+Persons aside, there is no partial name: "AIRBUS" does not join "Airbus Defence and Space". And different labels stay separate: the person "George Washington" and the place "Washington" each have their own group:
+
+<!-- generated:example:other-labels -->
+
+Text (French):
+
+> Airbus Defence and Space recrute. AIRBUS aussi. George Washington est né loin de Washington.
+
+Input annotations:
+
+| Annotated text | Label | Score |
+|---|---|---|
+| Airbus Defence and Space | `organisation` | 1.00 |
+| AIRBUS | `organisation` | 1.00 |
+| George Washington | `person` | 1.00 |
+| Washington | `lieu` | 1.00 |
+
+Default parameters.
+
+Output annotations:
+
+| Annotated text | Label | Score | Properties |
+|---|---|---|---|
+| Airbus Defence and Space | `organisation` | 1.00 | `canonical_form`: Airbus Defence and Space<br>`entity_group`: g1<br>`mention_type`: name |
+| AIRBUS | `organisation` | 1.00 | `canonical_form`: AIRBUS<br>`entity_group`: g2<br>`mention_type`: name |
+| George Washington | `person` | 1.00 | `canonical_form`: George Washington<br>`entity_group`: g3<br>`mention_type`: name |
+| Washington | `lieu` | 1.00 | `canonical_form`: Washington<br>`entity_group`: g4<br>`mention_type`: name |
+
+<!-- /generated:example:other-labels -->
+
+### 4. Grouping only some labels
+
+With **Labels** = `person`, the place "Washington" gets no property:
+
+<!-- generated:example:labels -->
+
+Text (French):
+
+> Emmanuel Macron à Washington.
+
+Input annotations:
+
+| Annotated text | Label | Score |
+|---|---|---|
+| Emmanuel Macron | `person` | 1.00 |
+| Washington | `lieu` | 1.00 |
+
+Parameters: **Labels** = `["person"]`.
+
+Output annotations:
+
+| Annotated text | Label | Score | Properties |
+|---|---|---|---|
+| Emmanuel Macron | `person` | 1.00 | `canonical_form`: Emmanuel Macron<br>`entity_group`: g1<br>`mention_type`: name |
+| Washington | `lieu` | 1.00 | — |
+
+<!-- /generated:example:labels -->
+
+## 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:
+
+<!-- generated:example:person-labels -->
+
+Text (French):
+
+> Emmanuel Macron parle. Macron sourit.
+
+Input annotations:
+
+| Annotated text | Label | Score |
+|---|---|---|
+| Emmanuel Macron | `PER` | 1.00 |
+| Macron | `PER` | 1.00 |
+
+Parameters: **Person Labels** = `["PER"]`.
+
+Output annotations:
+
+| Annotated text | Label | Score | Properties |
+|---|---|---|---|
+| 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 -->
+
+- **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".
+- **Mentions of labels excluded by Labels receive nothing**, not even a group of their own.

pyprocessors_coreference-1.6.12/docs/sherpa/coreference.fr.md

@@ -0,0 +1,224 @@
+# Processeur Coréférence (`coreference`)
+
+Regroupe les mentions d'une même entité dans un document : « Emmanuel Macron », « M. Macron » et « MACRON » reçoivent le même identifiant de groupe et la même forme canonique, « Emmanuel Macron ».
+
+## Quand l'utiliser
+
+- Avant la liaison à une base de connaissances (Entity-Fishing, un lexique) : la liaison cherche alors la forme complète du nom, plus facile à identifier, et applique le même résultat à toutes les mentions du groupe.
+- Pour compter ou suivre les entités d'un corpus de dépêches, où un nom complet est souvent repris par le seul nom de famille, avec ou sans civilité.
+
+## Quand ne pas l'utiliser
+
+- Le processeur ne regroupe que des **noms**. Il ne relie pas un pronom (« il », « elle ») ni une description (« le président ») au nom qu'ils désignent.
+- Il ne trouve aucune entité : il travaille sur les annotations posées par un annotateur placé avant lui (un modèle d'entités nommées, un lexique).
+- Il ne regroupe pas les mentions entre documents : les groupes sont propres à chaque document.
+
+## Prérequis
+
+| Prérequis | Obligatoire | Pourquoi |
+|---|---|---|
+| Annotations d'entités | **Oui** | Le processeur ne regroupe que des annotations existantes. Un document sans annotation est rendu tel quel. |
+
+<!-- generated:languages -->
+
+**Langues prises en charge :** le plugin ne déclare aucune restriction de langue.
+
+<!-- /generated:languages -->
+
+La comparaison des noms ne dépend pas de la langue, mais la liste par défaut de **Honorifics** ne contient que des civilités françaises et anglaises.
+
+## Ce qu'il produit
+
+Le processeur ne crée ni ne supprime d'annotation. Il ajoute des **propriétés** à chaque annotation qu'il regroupe :
+
+| Propriété | Contenu | Exemple |
+|---|---|---|
+| `entity_group` | l'identifiant du groupe, le même pour toutes les mentions d'une entité dans le document, numéroté dans l'ordre d'apparition | `g1` |
+| `canonical_form` | la forme la plus longue du groupe, sans civilité : le plus de mots, puis le plus de caractères | `Emmanuel Macron` |
+| `mention_type` | le type de mention, toujours `name` | `name` |
+| `entity_group_candidates` | seulement pour un nom partiel ambigu : les groupes auxquels il pourrait appartenir | `["g1", "g2"]` |
+
+Les propriétés que l'annotation portait déjà sont conservées. Traiter deux fois le même document donne le même résultat.
+
+## Paramètres
+
+<!-- generated:parameters -->
+
+| 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. |
+| **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 -->
+
+## Fonctionnement
+
+Deux mentions vont dans le même groupe dans les cas suivants :
+
+1. **Même forme et même label.** La comparaison ignore les majuscules et les variantes d'apostrophe : « Airbus » et « AIRBUS » sont regroupés.
+2. **Même famille de personnes.** Tous les labels de personnes comptent comme un seul : un « George Lucas » annoté `person` par un modèle et `afpperson` par un lexique forme un seul groupe.
+3. **Nom partiel, pour les personnes seulement.** Un nom qui termine un nom plus long rejoint ce nom, qu'il apparaisse avant ou après lui dans le document : « Macron » et « M. Macron » rejoignent « Emmanuel Macron ». Les civilités de **Honorifics** sont ignorées pour comparer.
+
+Ne sont **jamais** regroupés :
+
+- **un prénom seul** : « Emmanuel » ne rejoint pas « Emmanuel Macron », car il ne termine pas le nom ;
+- **un nom partiel ambigu** : avec « Emmanuel Macron » et « Brigitte Macron » dans le même document, « Macron » forme son propre groupe. Sa propriété `entity_group_candidates` liste les deux groupes possibles, et c'est l'étape de liaison qui tranche ;
+- **des labels différents**, hors personnes : la personne « George Washington » et le lieu « Washington » restent séparés ;
+- **un nom partiel d'organisation ou de lieu** : « Airbus » ne rejoint pas « Airbus Defence and Space ».
+
+## Exemples
+
+Dans chaque exemple, le tableau de sortie montre les propriétés ajoutées à chaque annotation.
+
+### 1. Un nom partiel rejoint le nom complet
+
+« M. Macron » rejoint « Emmanuel Macron » : même groupe `g1`, même forme canonique. Le prénom seul, « Emmanuel », forme son propre groupe :
+
+<!-- generated:example:partial-name -->
+
+Texte (français) :
+
+> Emmanuel Macron parle. M. Macron sourit. Emmanuel repart.
+
+Annotations en entrée :
+
+| Texte annoté | Label | Score |
+|---|---|---|
+| Emmanuel Macron | `person` | 1,00 |
+| M. Macron | `person` | 1,00 |
+| Emmanuel | `person` | 1,00 |
+
+Paramètres par défaut.
+
+Annotations en sortie :
+
+| Texte annoté | Label | Score | Propriétés |
+|---|---|---|---|
+| Emmanuel Macron | `person` | 1,00 | `canonical_form` : Emmanuel Macron<br>`entity_group` : g1<br>`mention_type` : name |
+| M. Macron | `person` | 1,00 | `canonical_form` : Emmanuel Macron<br>`entity_group` : g1<br>`mention_type` : name |
+| Emmanuel | `person` | 1,00 | `canonical_form` : Emmanuel<br>`entity_group` : g2<br>`mention_type` : name |
+
+<!-- /generated:example:partial-name -->
+
+### 2. Un nom partiel ambigu
+
+Deux personnes portent le nom « Macron » : la mention « Macron » forme son propre groupe, et `entity_group_candidates` liste les deux groupes possibles :
+
+<!-- generated:example:ambiguous -->
+
+Texte (français) :
+
+> Emmanuel Macron et Brigitte Macron voyagent. Macron sourit.
+
+Annotations en entrée :
+
+| Texte annoté | Label | Score |
+|---|---|---|
+| Emmanuel Macron | `person` | 1,00 |
+| Brigitte Macron | `person` | 1,00 |
+| Macron | `person` | 1,00 |
+
+Paramètres par défaut.
+
+Annotations en sortie :
+
+| Texte annoté | Label | Score | Propriétés |
+|---|---|---|---|
+| Emmanuel Macron | `person` | 1,00 | `canonical_form` : Emmanuel Macron<br>`entity_group` : g1<br>`mention_type` : name |
+| Brigitte Macron | `person` | 1,00 | `canonical_form` : Brigitte Macron<br>`entity_group` : g2<br>`mention_type` : name |
+| Macron | `person` | 1,00 | `canonical_form` : Macron<br>`entity_group` : g3<br>`entity_group_candidates` : ["g1", "g2"]<br>`mention_type` : name |
+
+<!-- /generated:example:ambiguous -->
+
+### 3. Organisations et lieux
+
+Hors personnes, il n'y a pas de nom partiel : « AIRBUS » ne rejoint pas « Airbus Defence and Space ». Et des labels différents restent séparés : la personne « George Washington » et le lieu « Washington » ont chacun leur groupe :
+
+<!-- generated:example:other-labels -->
+
+Texte (français) :
+
+> Airbus Defence and Space recrute. AIRBUS aussi. George Washington est né loin de Washington.
+
+Annotations en entrée :
+
+| Texte annoté | Label | Score |
+|---|---|---|
+| Airbus Defence and Space | `organisation` | 1,00 |
+| AIRBUS | `organisation` | 1,00 |
+| George Washington | `person` | 1,00 |
+| Washington | `lieu` | 1,00 |
+
+Paramètres par défaut.
+
+Annotations en sortie :
+
+| Texte annoté | Label | Score | Propriétés |
+|---|---|---|---|
+| Airbus Defence and Space | `organisation` | 1,00 | `canonical_form` : Airbus Defence and Space<br>`entity_group` : g1<br>`mention_type` : name |
+| AIRBUS | `organisation` | 1,00 | `canonical_form` : AIRBUS<br>`entity_group` : g2<br>`mention_type` : name |
+| George Washington | `person` | 1,00 | `canonical_form` : George Washington<br>`entity_group` : g3<br>`mention_type` : name |
+| Washington | `lieu` | 1,00 | `canonical_form` : Washington<br>`entity_group` : g4<br>`mention_type` : name |
+
+<!-- /generated:example:other-labels -->
+
+### 4. Ne regrouper que certains labels
+
+Avec **Labels** = `person`, le lieu « Washington » ne reçoit aucune propriété :
+
+<!-- generated:example:labels -->
+
+Texte (français) :
+
+> Emmanuel Macron à Washington.
+
+Annotations en entrée :
+
+| Texte annoté | Label | Score |
+|---|---|---|
+| Emmanuel Macron | `person` | 1,00 |
+| Washington | `lieu` | 1,00 |
+
+Paramètres : **Labels** = `["person"]`.
+
+Annotations en sortie :
+
+| Texte annoté | Label | Score | Propriétés |
+|---|---|---|---|
+| Emmanuel Macron | `person` | 1,00 | `canonical_form` : Emmanuel Macron<br>`entity_group` : g1<br>`mention_type` : name |
+| Washington | `lieu` | 1,00 | — |
+
+<!-- /generated:example:labels -->
+
+## 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 :
+
+<!-- generated:example:person-labels -->
+
+Texte (français) :
+
+> Emmanuel Macron parle. Macron sourit.
+
+Annotations en entrée :
+
+| Texte annoté | Label | Score |
+|---|---|---|
+| Emmanuel Macron | `PER` | 1,00 |
+| Macron | `PER` | 1,00 |
+
+Paramètres : **Person Labels** = `["PER"]`.
+
+Annotations en sortie :
+
+| Texte annoté | Label | Score | Propriétés |
+|---|---|---|---|
+| 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 -->
+
+- **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 ».
+- **Les mentions des labels exclus par Labels ne reçoivent rien**, pas même un groupe à elles seules.

{pyprocessors_coreference-1.6.8 → pyprocessors_coreference-1.6.12}/src/pyprocessors_coreference/__init__.py

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

{pyprocessors_coreference-1.6.8 → pyprocessors_coreference-1.6.12}/submodules/python-archetype/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "python-archetype",
   "displayName": "Kairntech python-archetype",
-  "version": "1.3.2",
+  "version": "1.3.6",
   "description": "Cree et entretient les depots Python de Kairntech qui consomment python-archetype : creation d'un plugin a partir de sa graine, page d'aide Sherpa d'un plugin, et mesure de la derive d'un depot par rapport a elle.",
   "author": {
     "name": "Kairntech",

{pyprocessors_coreference-1.6.8 → pyprocessors_coreference-1.6.12}/submodules/python-archetype/resources/help/help_examples.py

@@ -24,7 +24,9 @@ Le dépôt du plugin rend la fixture visible depuis 'tests/conftest.py' :
     from help_examples import help_example  # noqa: E402, F401
 """
 
+import io
 import json
+import zipfile
 from pathlib import Path
 
 import pytest
@@ -36,14 +38,90 @@ EXAMPLES_DIR = Path("build") / "help-examples"
 MAX_CONTENT = 100_000
 
 
-def _content(data: bytes) -> dict:
-    """Le contenu d'un fichier ou d'une réponse : son texte s'il en est un, sa taille sinon."""
-    content = {"size": len(data)}
+# Un classeur se montre par ses feuilles : au-delà, la page n'en citerait qu'un extrait.
+MAX_SHEETS = 5
+MAX_SHEET_ROWS = 50
+# Une archive se montre par la liste de ses fichiers, et le texte des premiers.
+MAX_MEMBERS = 20
+
+
+def _sheets(data: bytes) -> list[dict] | None:
+    """Les feuilles d'un classeur Excel, ou None si ce n'en est pas un (ou sans openpyxl)."""
     try:
-        text = data.decode("utf-8")
+        import openpyxl
+
+        workbook = openpyxl.load_workbook(io.BytesIO(data), read_only=True, data_only=True)
+    except Exception:  # noqa: BLE001 -- une archive zip qui n'est pas un classeur, ou pas d'openpyxl
+        return None
+    sheets = []
+    for sheet in workbook.worksheets[:MAX_SHEETS]:
+        rows = []
+        for row in sheet.iter_rows(values_only=True):
+            if len(rows) == MAX_SHEET_ROWS:
+                break
+            rows.append(["" if value is None else str(value) for value in row])
+        # Sans les colonnes vides de droite, qu'openpyxl rend quand une ligne est plus longue.
+        width = max((max((i + 1 for i, v in enumerate(row) if v), default=0) for row in rows), default=0)
+        sheets.append({"name": sheet.title, "rows": [row[:width] for row in rows]})
+    return sheets
+
+
+def _archive(data: bytes) -> list[dict] | None:
+    """Les fichiers d'une archive zip : nom, taille, et texte quand c'en est un."""
+    try:
+        archive = zipfile.ZipFile(io.BytesIO(data))
+    except zipfile.BadZipFile:
+        return None
+    # Un document Office (docx, pptx) est une archive, mais ses fichiers XML n'apprennent rien au lecteur.
+    if "[Content_Types].xml" in archive.namelist():
+        return None
+    members = []
+    for info in archive.infolist()[:MAX_MEMBERS]:
+        if info.is_dir():
+            continue
+        member = {"name": info.filename, "size": info.file_size}
+        decoded = _text(archive.read(info))
+        if decoded is not None:
+            member["text"] = decoded[0][:MAX_CONTENT]
+        members.append(member)
+    return members
+
+
+def _text(data: bytes) -> tuple[str, str] | None:
+    """Le texte et son encodage : UTF-8, sinon Latin-1 (cp1252) pour un texte sans octet de contrôle."""
+    try:
+        return data.decode("utf-8"), "utf-8"
     except UnicodeDecodeError:
+        pass
+    # Latin-1 décode n'importe quels octets : un octet de contrôle (hors tabulation et fins
+    # de ligne) trahit un contenu binaire.
+    if any(byte < 0x20 and byte not in b"\t\n\r\f" for byte in data):
+        return None
+    try:
+        return data.decode("cp1252"), "cp1252"
+    except UnicodeDecodeError:
+        return None
+
+
+def _content(data: bytes) -> dict:
+    """Le contenu d'un fichier ou d'une réponse : son texte, les feuilles d'un classeur, les fichiers d'une archive, ou sa taille."""
+    content = {"size": len(data)}
+    if data.startswith(b"PK"):
+        sheets = _sheets(data)
+        if sheets is not None:
+            content["sheets"] = sheets
+            return content
+        members = _archive(data)
+        if members is not None:
+            content["archive"] = members
+            return content
+    decoded = _text(data)
+    if decoded is None:
         return content
+    text, encoding = decoded
     content["text"] = text[:MAX_CONTENT]
+    if encoding != "utf-8":
+        content["encoding"] = encoding
     if len(text) > MAX_CONTENT:
         content["truncated"] = True
     return content