pyannotators-entityfishing 1.6.73__tar.gz → 1.6.77__tar.gz

{pyannotators_entityfishing-1.6.73 → pyannotators_entityfishing-1.6.77}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pyannotators-entityfishing
-Version: 1.6.73
+Version: 1.6.77
 Summary: Annotator based on entity-fishing
 Project-URL: Homepage, https://github.com/oterrier/pyannotators_entityfishing/
 Author-email: Olivier Terrier <olivier.terrier@kairntech.com>

{pyannotators_entityfishing-1.6.73 → pyannotators_entityfishing-1.6.77}/src/pyannotators_entityfishing/__init__.py

@@ -1,3 +1,3 @@
 """Annotator based on entity-fishing"""
 
-__version__ = "1.6.73"
+__version__ = "1.6.77"

{pyannotators_entityfishing-1.6.73 → pyannotators_entityfishing-1.6.77}/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.0.0",
+  "version": "1.1.0",
   "description": "Cree et entretient les depots Python de Kairntech qui consomment python-archetype : creation d'un plugin a partir de sa graine, et mesure de la derive d'un depot par rapport a elle.",
   "author": {
     "name": "Kairntech",

pyannotators_entityfishing-1.6.77/submodules/python-archetype/skills/new-plugin/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: new-plugin
+description: Créer un plugin Sherpa — importeur (pyimporters), processeur ou annotateur (pymultirole), et plus tard convertisseur, formateur ou segmenteur — à partir d'un format ou d'un besoin : clone la graine du contrat, écrit la classe et ses paramètres, les tests et leurs fixtures, la table du README, et câble le plugin dans le paquet de flavor du serveur. À utiliser quand on demande un nouvel importeur, un nouveau format de thésaurus, un nouveau processeur ou un nouvel annotateur, ou un nouveau plugin pyimporters / pymultirole.
+---
+
+# Créer un plugin Sherpa
+
+Tu fais **deux choses de nature différente**, et il ne faut pas les confondre :
+
+- **l'enveloppe** (`pyproject.toml`, `Taskfile.yml`, `Jenkinsfile`, `.gitignore`…)
+  est produite par la graine et sa task `init`. **Tu ne l'écris pas, tu la lances.**
+  Elle doit rester identique aux dépôts frères à l'identifiant près ; la réécrire
+  de mémoire, c'est fabriquer un dépôt de plus subtilement différent.
+- **le contenu** (la classe, ses paramètres, les tests, les fixtures, le README, le
+  câblage inter-dépôts) demande du jugement. C'est ton travail.
+
+La méthode, ce qu'elle remplace et pourquoi : `md/PLUGIN_TEMPLATE.md` du poste,
+ou le `README.md` de la graine.
+
+## 1. Rassembler l'essentiel (demander, ne pas supposer)
+
+- **le type** — voir [`references/types.md`](references/types.md) : la table type →
+  graine, groupe d'entry-points, classe de base, paquet de flavor, layout, patron de
+  description. Si le type demandé n'a pas encore de graine, **le dire et
+  s'arrêter** : ne pas improviser une enveloppe.
+- **le nom** — en minuscules, sans préfixe : `foo` donne `pyprocessors_foo`,
+  `pyprocessors-foo`, et l'entry-point `foo`.
+- **le préfixe de classe** — la casse est libre et suit le sujet, pas le nom :
+  `CSV`, `MeSH`, `Jev`, `EntityFishing`. Il donne les classes de la table des types
+  (`<CLASS>KnowledgeParser`, `<CLASS>Processor`, `<CLASS>Annotator`, et leurs
+  options ou paramètres).
+- **la description** — une ligne, sur le patron des dépôts frères donné par la
+  table des types.
+- **ce que demande le type** — chaque `references/<type>.md` liste ses propres
+  questions : un fichier d'exemple pour un importeur, un document réaliste pour un
+  processeur, un texte et ses annotations attendues pour un annotateur.
+
+## 2. L'enveloppe : lancer la graine, ne rien inventer
+
+```bash
+git clone git@bitbucket.org:kairntech/<prefixe>_seed.git <prefixe>_<nom>
+cd <prefixe>_<nom>
+# Le submodule d'ABORD : le Taskfile l'INCLUT, donc Task refuse de charger le
+# fichier — et 'task init' n'existe pas — tant qu'il n'est pas initialisé.
+git submodule update --init
+task init NAME=<nom> CLASS=<CLASS> DESC="<description>"
+```
+
+`init` renomme le paquet, le module et le test, substitue l'identifiant, écrit la
+description à ses trois emplacements, remet la version à `1.6.0`, retire le
+`publish: false` du Jenkinsfile, coupe la section « graine » du README, se
+supprime du Taskfile, et repointe `origin` en gardant `seed` en lecture seule.
+
+Vérifier tout de suite, avant d'écrire une ligne de code :
+
+```bash
+task            # doit sortir en 0 sur le squelette
+```
+
+## 3 à 5. Le contenu : la classe, les tests, le README
+
+Lire **`references/<type>.md`** et le suivre : c'est la seule partie qui change
+d'un type à l'autre.
+
+- [`references/importer.md`](references/importer.md)
+- [`references/processor.md`](references/processor.md)
+- [`references/annotator.md`](references/annotator.md)
+
+Deux règles valent pour tous les types :
+
+- remplacer le corps de la classe de la graine, **garder sa forme** : la classe de
+  paramètres, la méthode du contrat, `get_model()` ;
+- **garder le test de découverte par entry-point** que la graine fournit. Un plugin
+  dont l'entry-point est faux s'importe très bien, passe tous ses autres tests, et
+  n'est jamais appelé par le serveur.
+
+## 6. Le câblage inter-dépôts — sans lui, le plugin n'existe pas
+
+Le serveur découvre les plugins par entry-point, mais **seulement parmi les
+paquets installés**, et ce qui est installé est la liste de dépendances d'un
+paquet de flavor. Un plugin non câblé ne remonte jamais dans l'API.
+
+- ajouter `"<distribution>>=1.6.0,<1.7.0"` aux `dependencies` du paquet de flavor
+  (`references/<type>.md` dit lequel) ;
+- aligner la borne de `pyimporters_plugins` ou `pymultirole-plugins` sur celle des
+  dépôts frères, ne pas l'élargir ;
+- le dépôt Bitbucket `kairntech/<prefixe>_<nom>` (**underscore** : seul le nom de
+  distribution prend le tiret) est créé par une personne, avec le script de
+  création de dépôt, qui crée aussi le webhook et le job Jenkins. Il demande des
+  identifiants : **ne pas le lancer soi-même**, le demander. Puis pousser, et
+  vérifier le premier build.
+
+## 7. Vérifier, et ne rendre la main que vert
+
+```bash
+task                 # lint, tests, SBOM, CVE, build
+```
+
+Corriger jusqu'au 0 — ruff compris, y compris le formatage des blocs ```python des
+fichiers Markdown, que `ruff format` vérifie aussi. Ne pas déclarer terminé sur un
+`task` rouge, et ne pas désactiver une règle pour faire passer le lint.
+
+## Ce qu'il ne faut pas faire
+
+- réécrire l'enveloppe à la main, ou « améliorer » le `pyproject.toml` : l'écart
+  avec les dépôts frères est le défaut, pas la variété ;
+- toucher à `submodules/` : code épinglé, hors de notre autorité ;
+- réciter l'ordre du pipeline de mémoire. Il vit dans `STAGES` et l'archétype
+  peut avoir bougé depuis l'installation de ce plugin : l'interroger
+  (`task stages`, `task --list`) ;
+- versionner `uv.lock` (`LOCK_VERSIONED: "false"` ici : `py:sync` résout à neuf) ;
+- écrire la version à la main : c'est la CI qui la pose.

pyannotators_entityfishing-1.6.77/submodules/python-archetype/skills/new-plugin/references/annotator.md

@@ -0,0 +1,51 @@
+# Annotator — le contenu à écrire
+
+Graine `kairntech/pyannotators_seed`, layout `src/pyannotators_<nom>/`, fichier
+`src/pyannotators_<nom>/<nom>.py`. Modèle vivant : `pyannotators_entityfishing`
+(enveloppe identique, service externe, mappings de labels).
+
+## À demander en plus
+
+- **les labels produits**, et d'où ils viennent : fixes, configurables, ou
+  calculés (les `mapped_labels` d'entityfishing) ;
+- **un texte d'exemple** et les annotations qu'on en attend, offsets compris : c'est
+  la fixture des tests ;
+- **un service externe ?** Son URL par défaut, la variable d'environnement qui la
+  surcharge, la clé et l'endroit où elle vit (`tests/.env`, jamais versionné).
+
+## L'annotateur
+
+Remplacer le corps de `src/pyannotators_<nom>/<nom>.py`, **garder la forme** :
+
+- les paramètres dérivent de `AnnotatorParameters` et se déclarent en
+  `Field(défaut, description=...)` ; `json_schema_extra={"extra": ...}` comme pour
+  un processeur (`advanced`, `label`, `internal`…) ;
+- `annotate(documents, parameters)` reçoit et rend **tout le lot**. Comme les
+  annotateurs frères, il écrit ses propres annotations dans `document.annotations` ;
+- une `Annotation` a `start` et `end` en **offsets de caractères dans
+  `document.text`, fin exclue**, `labelName`, `text`, `score`, et ses liens vers une
+  base de connaissances dans `terms` (des `Term` : `identifier`, `lexicon`,
+  `preferredForm`, `properties`) ;
+- `AnnotatorBase` a pour métaclasse `ABCSingleton` : même règle que pour un
+  processeur, rien dans `self` qui dépende d'un appel ;
+- `get_model()` renvoie la classe de paramètres.
+
+## Les tests
+
+- le test du modèle et le test de découverte par entry-point de la graine, gardés ;
+- un test d'annotation qui vérifie les **offsets exacts** et
+  `text[a.start:a.end] == a.text` pour chaque annotation : c'est ce qui attrape
+  un décalage d'un caractère ou une confusion octets/caractères ;
+- un document sans occurrence, qui doit revenir avec une liste vide ;
+- si l'annotateur appelle un service : pas de réseau par défaut (fixtures
+  enregistrées), tests live derrière un marqueur `integration`.
+
+## Le README
+
+Compléter la table des paramètres, et dire quels labels l'annotateur produit.
+
+## Le câblage
+
+`"pyannotators-<nom>>=1.6.0,<1.7.0"` dans les `dependencies` du paquet de flavor de
+`pymultirole_server/packages/` : `pymultirole-builtins` pour un annotateur
+générique, la flavor du client sinon (`references/types.md`).

pyannotators_entityfishing-1.6.77/submodules/python-archetype/skills/new-plugin/references/importer.md

@@ -0,0 +1,50 @@
+# Importer — le contenu à écrire
+
+Graine `kairntech/pyimporters_seed`, paquet à plat `pyimporters_<nom>/`, fichier
+`pyimporters_<nom>/<nom>.py`.
+
+## À demander en plus
+
+- **le format source** — un fichier d'exemple si possible, sinon la spec. Sans
+  échantillon, les options et le compte attendu des tests sont des devinettes :
+  demander.
+
+## Le parser
+
+Remplacer le corps de `pyimporters_<nom>/<nom>.py`, **garder la forme** :
+
+- les options dérivent de `KnowledgeParserOptions` et se déclarent en
+  `Query(défaut, description=...)` — le schéma remonte dans l'API du serveur,
+  donc chaque `description` est de la documentation utilisateur, pas un commentaire ;
+- `parse()` est un **générateur** qui `yield` des `Term` ; ne pas construire de liste ;
+- `maybe_archive(source, encoding=...)` déplie `zip`/`gzip` de façon
+  transparente : s'en servir plutôt que d'ouvrir le fichier, et ajouter `"zip"`
+  aux extensions ;
+- renseigner `bar.max` puis `bar.start()` quand le nombre de termes est
+  connaissable d'avance (une première passe de comptage est acceptable), sinon se
+  contenter de `bar.next()` ;
+- `get_extensions()` liste les extensions **sans le point** : `["csv", "tsv", "zip"]`.
+
+Un `Term` a `identifier` (obligatoire), `preferredForm`, `lexicon`, `properties`
+(dict libre — c'est là que vont les formes alternatives, sous `altForms`).
+
+## Les tests et leurs fixtures
+
+- un test de parsing avec un **vrai fichier** dans `tests/data/`, et un
+  `check_expected()` qui vérifie un compte de concepts et un `Term` précis à un
+  index donné. Un compte exact vaut mieux qu'un `assert len(...) > 0` : c'est ce
+  qui attrape une régression de séparateur ou d'encodage.
+- si le format se distribue en archive, un test sur le `.zip` — comme
+  `test_zipped_text` dans `pyimporters_csv`.
+
+## Le README
+
+Compléter la table des options : une ligne par option, avec son défaut et sa
+description, **plus le comportement de repli** quand il n'est pas évident (dans
+`pyimporters_csv`, un nom de colonne inconnu retombe sur la colonne 0 et
+journalise un avertissement — ça se documente).
+
+## Le câblage
+
+`"pyimporters-<nom>>=1.6.0,<1.7.0"` dans les `dependencies` de
+`pyimporters_server/packages/pyimporters-builtins/pyproject.toml`.

pyannotators_entityfishing-1.6.77/submodules/python-archetype/skills/new-plugin/references/processor.md

@@ -0,0 +1,55 @@
+# Processor — le contenu à écrire
+
+Graine `kairntech/pyprocessors_seed`, layout `src/pyprocessors_<nom>/`, fichier
+`src/pyprocessors_<nom>/<nom>.py`. Modèles vivants : `pyprocessors_jev` (enveloppe
+identique, appel HTTP, tests avec un `recorder`).
+
+## À demander en plus
+
+- **ce que le processeur lit et ce qu'il écrit** sur le `Document` : `text`,
+  `annotations` (et leurs `terms`), `categories`, `metadata`, `altTexts`,
+  `sentences`. Un processeur agit presque toujours sur ce qu'un plugin précédent
+  a produit : il faut un **document d'exemple réaliste**, annotations comprises,
+  sinon les tests vérifient un cas qui n'arrive jamais.
+- **un service externe ?** Son URL par défaut, la variable d'environnement qui la
+  surcharge, la clé et l'endroit où elle vit (`tests/.env`, jamais versionné).
+
+## Le processeur
+
+Remplacer le corps de `src/pyprocessors_<nom>/<nom>.py`, **garder la forme** :
+
+- les paramètres dérivent de `ProcessorParameters` et se déclarent en
+  `Field(défaut, description=...)` — le schéma remonte dans l'API de
+  `pymultirole_server`, donc chaque `description` est de la documentation
+  utilisateur. `json_schema_extra={"extra": ...}` pilote l'affichage dans Sherpa :
+  `advanced` (replié par défaut), `label` (sélecteur de label du projet),
+  `internal` (masqué), `multiline`… — reprendre les valeurs des dépôts frères ;
+- `process(documents, parameters)` reçoit et rend **tout le lot** : modifier les
+  documents en place et les renvoyer, sans en perdre ni en réordonner. Un document
+  qui échoue ne doit pas faire perdre le lot (voir `process_one` dans
+  `pyprocessors_jev`) ;
+- `ProcessorBase` a pour métaclasse `ABCSingleton` : une instance par classe. Ne
+  rien garder dans `self` qui dépende d'un appel ; un client HTTP se met en cache
+  par paramètres (`functools.cache`), pas en attribut ;
+- `get_model()` renvoie la classe de paramètres.
+
+## Les tests
+
+- le test du modèle et le test de découverte par entry-point de la graine, gardés ;
+- un test de traitement sur des `Document` construits dans le test, qui vérifie
+  **ce qui a été écrit** (labels, scores, offsets) et **ce qui n'a pas bougé** ;
+- si le processeur appelle un service : aucun appel réseau par défaut. Remplacer
+  l'appel par un enregistreur (fixture `recorder`, comme `pyprocessors_jev`), et
+  mettre les tests live derrière un marqueur `integration`, exclu de `addopts`.
+
+## Le README
+
+Compléter la table des paramètres : une ligne par paramètre, avec son défaut et sa
+description, plus le comportement de repli (un service injoignable, un document
+sans annotation…).
+
+## Le câblage
+
+`"pyprocessors-<nom>>=1.6.0,<1.7.0"` dans les `dependencies` du paquet de flavor de
+`pymultirole_server/packages/` : `pymultirole-builtins` pour un processeur
+générique, la flavor du client sinon (`references/types.md`).

pyannotators_entityfishing-1.6.77/submodules/python-archetype/skills/new-plugin/references/types.md

@@ -0,0 +1,61 @@
+# Table des types de plugins
+
+Ce qui distingue un type d'un autre est **de la donnée** — quelques colonnes. C'est
+la raison pour laquelle il y a *un* skill `new-plugin` et non un par famille :
+six skills à 90 % identiques dériveraient les uns des autres, et rien ne lint un
+skill.
+
+| type | graine | groupe d'entry-points | classe de base | paquet de flavor | graine prête ? |
+|------|--------|-----------------------|----------------|------------------|----------------|
+| `importer` | `kairntech/pyimporters_seed` | `pyimporters.plugins` | `KnowledgeParserBase` (`pyimporters_plugins.base`) | `pyimporters_server/packages/pyimporters-builtins` | **oui** |
+| `converter` | `kairntech/pyconverters_seed` | `pyconverters.plugins` | `ConverterBase` (`pymultirole_plugins.v1.converter`) | `pymultirole_server/packages/pymultirole-builtins` | non |
+| `processor` | `kairntech/pyprocessors_seed` | `pyprocessors.plugins` | `ProcessorBase` (`pymultirole_plugins.v1.processor`) | `pymultirole-builtins` ou une flavor dédiée | **oui** |
+| `annotator` | `kairntech/pyannotators_seed` | `pyannotators.plugins` | `AnnotatorBase` (`pymultirole_plugins.v1.annotator`) | `pymultirole-builtins` ou une flavor dédiée | **oui** |
+| `formatter` | `kairntech/pyformatters_seed` | `pyformatters.plugins` | `FormatterBase` (`pymultirole_plugins.v1.formatter`) | `pymultirole-builtins` | non |
+| `segmenter` | `kairntech/pysegmenters_seed` | `pysegmenters.plugins` | `SegmenterBase` (`pymultirole_plugins.v1.segmenter`) | `pymultirole-builtins` | non |
+
+## Ce que chaque graine prête produit
+
+| type | layout | `MODULE` du Taskfile | `CLASS` (exemple) → classes produites | patron de `DESC` | contenu à écrire |
+|------|--------|----------------------|----------------------------------------|------------------|------------------|
+| `importer` | à plat : `pyimporters_<nom>/` | `pyimporters_<nom>` | `CSV` → `CSVKnowledgeParser`, `CSVOptions` | « Sherpa FOO knowledge import plugin » | [`importer.md`](importer.md) |
+| `processor` | `src/pyprocessors_<nom>/` | `src/pyprocessors_<nom>` | `Foo` → `FooProcessor`, `FooParameters` | « Processor based on foo » | [`processor.md`](processor.md) |
+| `annotator` | `src/pyannotators_<nom>/` | `src/pyannotators_<nom>` | `Foo` → `FooAnnotator`, `FooParameters` | « Annotator based on foo » | [`annotator.md`](annotator.md) |
+
+Le layout suit la famille, pas une préférence : les dépôts `pyimporters_*` ont leur
+paquet à plat, les dépôts `pymultirole` sont en `src/` — dont `pyprocessors_jev` et
+`pyannotators_entityfishing`, déjà passés sous `python-archetype`, sur lesquels les
+graines `pymultirole` sont calquées (ruff à 256 colonnes compris). Après `task init`,
+le Taskfile d'un processeur est identique octet pour octet à celui de
+`pyprocessors_jev`, celui d'un annotateur à celui de `pyannotators_entityfishing`.
+
+Les paquets de flavor de `pymultirole_server/packages/` : `pymultirole-builtins`,
+`pymultirole-afp`, `pymultirole-cairn`, `pymultirole-escrim`, `pymultirole-grouperf`,
+`pymultirole-ner`, `pymultirole-scai`, `pymultirole-xcago` (`pymultirole-app` est le
+serveur, pas une flavor). Un plugin propre à un client va dans la flavor de ce
+client ; demander, ne pas deviner.
+
+## Trois graines existent aujourd'hui
+
+`pyimporters_seed`, `pyprocessors_seed` et `pyannotators_seed` sont poussées, et ne
+publient rien (`publish: false`). **Les trois autres n'existent pas encore.** La
+famille `pymultirole` passe progressivement sous `python-archetype` : quelques dépôts
+sont migrés, la plupart portent encore la sortie de `cookiecutter-pymultirole`
+(`bumpversion.py`, `AUTHORS.md`, `CHANGELOG.md`, `RELEASE.md`, `mypy.ini`, `docs/`).
+
+Si on demande un type dont la graine n'existe pas : **le dire et s'arrêter.**
+Improviser l'enveloppe reviendrait à recréer à la main ce que la graine garantit,
+sans la garantie — et le dépôt produit devrait être migré comme les autres. La
+bonne réponse est de créer d'abord la graine du type, sur le modèle des trois
+existantes.
+
+## Pourquoi une graine par contrat, et un seul skill
+
+Une graine doit **builder** : un `ConverterBase` et un `ProcessorBase` n'ont pas
+la même signature, donc un dépôt ne peut pas builder les deux. Une graine
+paramétrée qui supprimerait quatre contrats sur cinq à l'`init` redeviendrait un
+template — du code non exécutable, hors CI, exactement le défaut qu'on corrige.
+
+Un skill, lui, n'a rien à builder : le dupliquer ne coûte pas un job Jenkins, ça
+coûte une divergence que personne ne mesure. D'où un corps unique (`SKILL.md`) et
+une référence par type pour ce qui change vraiment : le contenu à écrire.

pyannotators_entityfishing-1.6.77/tools/eval_linking.py

@@ -0,0 +1,451 @@
+#!/usr/bin/env python3
+"""Evaluate entity linking on gold corpora: entity-fishing /disambiguate vs term lookup + Jev.
+
+SHERPA-3037, the evaluation step of ADR-0001 (docs/adr/0001-linking-candidats-entityfishing-decision-jev.md).
+
+The gold corpora are MSNBC and AQUAINT from the entity-fishing repository
+(data/corpus/corpus-long): news texts where every mention carries its offset and the
+expected Wikipedia title (empty = NIL, an entity with no page). They are downloaded
+into .cache/linking/ and never copied into this repository. Gold titles are resolved to
+Wikidata QIDs through the Wikipedia API, redirects included.
+
+The gold mention spans stand in for the NER: every system is scored on the same
+mentions. The corpora carry no NER type, so the Jev chain runs WITHOUT the type
+filter of the mappings.
+
+Systems
+-------
+disambiguate  entity-fishing /disambiguate on the whole text, as the annotator calls it
+prior         the most common sense: the best prob_c of the term lookup
+jev           term lookup (top K) + one Jev Choice per distinct surface, one call per document
+
+    .venv/bin/python tools/eval_linking.py --corpus msnbc --limit 3     # smoke run
+    .venv/bin/python tools/eval_linking.py                              # both corpora
+    .venv/bin/python tools/eval_linking.py --bench 8                    # latency and throughput, real calls
+
+Jev answers are cached per (model, document) in .cache/linking/jev.json, so a re-run
+costs nothing; --refresh-jev forces new calls. The key is read from JEV_API_KEY or
+TYPESAFE_API_KEY (tests/.env is loaded if present).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+import time
+import xml.etree.ElementTree as ET
+from collections import Counter
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import requests
+
+ROOT = Path(__file__).resolve().parent.parent
+CACHE = ROOT / ".cache" / "linking"
+RAW = "https://raw.githubusercontent.com/kermitt2/entity-fishing/master/data/corpus/corpus-long"
+EF_DEFAULT = "https://entityfishing.kairntech.com"
+JEV_URL = "https://api.typesafe.ai/v1/systemone"
+WIKIPEDIA_API = "https://en.wikipedia.org/w/api.php"
+USER_AGENT = "kairntech-eval-linking/0.1 (olivier.terrier@kairntech.com)"
+NONE = "NONE"
+THRESHOLDS = [0.0, 0.5, 0.7, 0.9]
+
+session = requests.Session()
+session.headers["User-Agent"] = USER_AGENT
+
+
+# --------------------------------------------------------------------------- cache
+
+
+def cached(name: str) -> dict:
+    path = CACHE / name
+    return json.loads(path.read_text()) if path.exists() else {}
+
+
+def save(name: str, data: dict) -> None:
+    CACHE.mkdir(parents=True, exist_ok=True)
+    (CACHE / name).write_text(json.dumps(data, ensure_ascii=False))
+
+
+# --------------------------------------------------------------------------- corpus
+
+
+@dataclass
+class Mention:
+    start: int
+    end: int
+    surface: str
+    title: str  # expected Wikipedia title, "" for NIL
+    qid: str | None = None  # resolved gold QID, None for NIL or unresolved
+
+
+@dataclass
+class Doc:
+    corpus: str
+    name: str
+    text: str
+    mentions: list[Mention] = field(default_factory=list)
+
+
+def fetch_text(url: str, path: Path) -> str:
+    if not path.exists():
+        resp = session.get(url, timeout=60)
+        resp.raise_for_status()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_bytes(resp.content)
+    return path.read_text(encoding="utf-8")
+
+
+def load_corpus(corpus: str) -> list[Doc]:
+    xml = fetch_text(f"{RAW}/{corpus}/{corpus}.xml", CACHE / corpus / f"{corpus}.xml")
+    docs = []
+    for d in ET.fromstring(xml).findall("document"):
+        name = d.get("docName")
+        text = fetch_text(f"{RAW}/{corpus}/RawText/{name}", CACHE / corpus / "RawText" / name)
+        doc = Doc(corpus, name, text)
+        for a in d.findall("annotation"):
+            start, length = int(a.findtext("offset")), int(a.findtext("length"))
+            surface = a.findtext("mention") or ""
+            if text[start : start + length] != surface:
+                continue  # one misaligned gold offset in MSNBC: skipped, not guessed
+            doc.mentions.append(Mention(start, start + length, surface, (a.findtext("wikiName") or "").strip()))
+        docs.append(doc)
+    return docs
+
+
+def resolve_titles(docs: list[Doc]) -> None:
+    """Gold Wikipedia titles → Wikidata QIDs, following redirects (the corpora date from 2007-2010)."""
+    cache = cached("titles.json")
+    titles = sorted({m.title for d in docs for m in d.mentions if m.title and m.title not in cache})
+    for i in range(0, len(titles), 50):
+        batch = titles[i : i + 50]
+        resp = session.get(
+            WIKIPEDIA_API,
+            params={"action": "query", "titles": "|".join(batch), "redirects": 1, "prop": "pageprops", "ppprop": "wikibase_item", "format": "json", "formatversion": 2},
+            timeout=60,
+        )
+        query = resp.json()["query"]
+        rename = {n["from"]: n["to"] for n in query.get("normalized", [])}
+        rename.update({r["from"]: r["to"] for r in query.get("redirects", [])})
+        qid_of = {p["title"]: p.get("pageprops", {}).get("wikibase_item") for p in query["pages"]}
+        for title in batch:
+            final = title
+            for _ in range(3):  # normalized, then redirected
+                final = rename.get(final, final)
+            cache[title] = qid_of.get(final)
+    save("titles.json", cache)
+    for d in docs:
+        for m in d.mentions:
+            m.qid = cache.get(m.title) if m.title else None
+
+
+# --------------------------------------------------------------------------- entity-fishing
+
+
+def disambiguate(doc: Doc, ef: str, min_selector: float) -> dict[tuple[int, int], str]:
+    cache = cached("disambiguate.json")
+    key = f"{doc.corpus}/{doc.name}/{min_selector}"
+    if key not in cache:
+        query = {"text": doc.text, "language": {"lang": "en"}, "minSelectorScore": min_selector}
+        resp = session.post(f"{ef}/service/disambiguate", files={"query": (None, json.dumps(query))}, timeout=300)
+        entities = resp.json().get("entities", []) if resp.ok else []
+        cache[key] = [[e["offsetStart"], e["offsetEnd"], e["wikidataId"]] for e in entities if e.get("wikidataId")]
+        save("disambiguate.json", cache)
+    return {(s, e): q for s, e, q in cache[key]}
+
+
+def fetch_term(s: str, ef: str) -> tuple[str, list[dict]]:
+    resp = session.get(f"{ef}/service/kb/term/{requests.utils.quote(s, safe='')}", params={"lang": "en"}, timeout=60)
+    return s, (resp.json().get("senses", []) if resp.ok else [])
+
+
+def term_lookup(surfaces: list[str], ef: str) -> dict[str, list[dict]]:
+    cache = cached("terms.json")
+    missing = [s for s in surfaces if s not in cache]
+    with ThreadPoolExecutor(8) as pool:
+        cache.update(dict(pool.map(lambda s: fetch_term(s, ef), missing)))
+    if missing:
+        save("terms.json", cache)
+    return {s: cache[s] for s in surfaces}
+
+
+def fetch_concept(p: str, ef: str) -> tuple[str, dict]:
+    resp = session.get(f"{ef}/service/kb/concept/{p}", params={"lang": "en"}, timeout=60)
+    c = resp.json() if resp.ok else {}
+    facts = {}
+    for st in c.get("statements", []):
+        if st.get("propertyId") in ("P31", "P106", "P27", "P17", "P641", "P159") and st.get("valueName"):
+            facts.setdefault(st["propertyName"], []).append(st["valueName"])
+    defs = c.get("definitions") or [{}]
+    return p, {"qid": c.get("wikidataId"), "definition": first_sentence(defs[0].get("definition", "")), "facts": {k: v[:3] for k, v in facts.items()}}
+
+
+def concepts(pageids: list[int], ef: str) -> dict[str, dict]:
+    cache = cached("concepts.json")
+    missing = sorted({str(p) for p in pageids} - set(cache))
+    with ThreadPoolExecutor(8) as pool:
+        cache.update(dict(pool.map(lambda p: fetch_concept(p, ef), missing)))
+    if missing:
+        save("concepts.json", cache)
+    return {str(p): cache[str(p)] for p in pageids}
+
+
+def first_sentence(wikitext: str) -> str:
+    t = re.sub(r"\[\[(?:[^|\]]*\|)?([^\]]*)\]\]", r"\1", wikitext)
+    t = re.sub(r"'''?|\{\{[^}]*\}\}|\([^)]*\)", "", t)
+    return re.split(r"(?<=\.)\s", re.sub(r"\s+", " ", t).strip())[0][:300]
+
+
+# --------------------------------------------------------------------------- Jev
+
+
+def candidates_of(doc: Doc, k: int, ef: str) -> dict[str, list[dict]]:
+    """Distinct surface → its top-K candidates (qid, title, prior, description)."""
+    surfaces = sorted({m.surface for m in doc.mentions})
+    senses = term_lookup(surfaces, ef)
+    kept = {s: senses[s][:k] for s in surfaces}
+    return assemble(kept, concepts([sense["pageid"] for ss in kept.values() for sense in ss], ef))
+
+
+def fresh_candidates(doc: Doc, k: int, ef: str) -> dict[str, list[dict]]:
+    """Same as candidates_of, with no cache: what the production chain pays per document."""
+    surfaces = sorted({m.surface for m in doc.mentions})
+    with ThreadPoolExecutor(8) as pool:
+        kept = {s: ss[:k] for s, ss in pool.map(lambda s: fetch_term(s, ef), surfaces)}
+        pageids = sorted({str(sense["pageid"]) for ss in kept.values() for sense in ss})
+        info = dict(pool.map(lambda p: fetch_concept(p, ef), pageids))
+    return assemble(kept, info)
+
+
+def assemble(kept: dict[str, list[dict]], info: dict[str, dict]) -> dict[str, list[dict]]:
+    out = {}
+    for s, ss in kept.items():
+        cands, seen = [], set()
+        for sense in ss:
+            c = info[str(sense["pageid"])]
+            if c["qid"] and c["qid"] not in seen:
+                seen.add(c["qid"])
+                cands.append({"qid": c["qid"], "title": sense["preferred"], "prior": sense["prob_c"], "definition": c["definition"], "facts": c["facts"]})
+        out[s] = cands
+    return out
+
+
+def build_questions(cands: dict[str, list[dict]]) -> tuple[list[str], dict]:
+    surfaces = [s for s in sorted(cands) if cands[s]]
+    questions = {}
+    for i, s in enumerate(surfaces):
+        criteria = {c["qid"]: {"name": c["title"], "description": c["definition"], "facts": c["facts"]} for c in cands[s]}
+        criteria[NONE] = "None of the listed entities is the one meant by the mention"
+        questions[f"m{i}"] = {
+            "type": "choice",
+            "instructions": {"mention": s, "question": "In `text`, which knowledge-base entity does `mention` refer to?"},
+            "criteria": criteria,
+        }
+    return surfaces, questions
+
+
+def call_jev(text: str, questions: dict, model: str, key: str) -> dict:
+    resp = session.post(JEV_URL, json={"model": model, "state": {"text": text}, "questions": questions}, headers={"Authorization": f"Bearer {key}"}, timeout=300)
+    resp.raise_for_status()
+    return resp.json()
+
+
+def jev(doc: Doc, cands: dict[str, list[dict]], model: str, key: str, refresh: bool) -> tuple[dict, dict]:
+    cache = cached("jev.json")
+    ck = f"{model}/{doc.corpus}/{doc.name}"
+    if ck in cache and not refresh:
+        return cache[ck]["answers"], cache[ck]["usage"]
+    surfaces, questions = build_questions(cands)
+    if not questions:
+        return {}, {}
+    result = call_jev(doc.text, questions, model, key)
+    answers = {surfaces[int(q[1:])]: a for q, a in result["answers"].items()}
+    cache[ck] = {"answers": answers, "usage": result.get("usage", {})}
+    save("jev.json", cache)
+    return answers, result.get("usage", {})
+
+
+# --------------------------------------------------------------------------- scoring
+
+
+@dataclass
+class Score:
+    linked: int = 0  # non-NIL gold mentions that got a link
+    correct: int = 0
+    gold: int = 0  # non-NIL gold mentions with a resolved QID
+    nil: int = 0
+    nil_abstained: int = 0
+
+    def add(self, m: Mention, predicted: str | None) -> None:
+        if m.title == "":
+            self.nil += 1
+            self.nil_abstained += predicted is None
+            return
+        self.gold += 1
+        if predicted is not None:
+            self.linked += 1
+            self.correct += predicted == m.qid
+
+    def row(self) -> str:
+        p = self.correct / self.linked if self.linked else 0.0
+        r = self.correct / self.gold if self.gold else 0.0
+        f = 2 * p * r / (p + r) if p + r else 0.0
+        nil = f"{self.nil_abstained}/{self.nil}" if self.nil else "-"
+        return f"P {p:6.1%}  R {r:6.1%}  F1 {f:6.1%}   (correct {self.correct}/{self.gold}, linked {self.linked})   NIL abstained {nil}"
+
+
+# --------------------------------------------------------------------------- bench
+
+
+def stats(values: list[float]) -> str:
+    v = sorted(values)
+    p95 = v[min(len(v) - 1, round(0.95 * (len(v) - 1)))]
+    return f"mean {sum(v) / len(v):6.2f} s   median {v[len(v) // 2]:6.2f} s   p95 {p95:6.2f} s"
+
+
+def bench(docs: list[Doc], args, key: str) -> int:
+    """Time the real calls, no cache: per-stage latency, then Jev throughput at several concurrencies."""
+    per_corpus = max(1, args.bench // 2)
+    sample = [d for c in ("msnbc", "aquaint") for d in [x for x in docs if x.corpus == c][:per_corpus]]
+    timings: dict[str, list[float]] = {"disambiguate": [], "kb concepts": [], "candidates": [], "jev": []}
+    n_qids = []
+    usage, prepared = Counter(), []
+    for n, doc in enumerate(sample, 1):
+        print(f"# latency {n}/{len(sample)} {doc.corpus}/{doc.name}", file=sys.stderr)
+        t = time.perf_counter()
+        query = {"text": doc.text, "language": {"lang": "en"}, "minSelectorScore": args.min_selector}
+        resp = session.post(f"{args.ef}/service/disambiguate", files={"query": (None, json.dumps(query))}, timeout=300)
+        timings["disambiguate"].append(time.perf_counter() - t)
+        # What pyannotators_entityfishing does next (get_kb_concepts): one /kb/concept per
+        # distinct QID, on a pool of 8 connections, to apply the mappings and build the terms.
+        qids = sorted({e["wikidataId"] for e in resp.json().get("entities", []) if e.get("wikidataId")})
+        n_qids.append(len(qids))
+        t = time.perf_counter()
+        with ThreadPoolExecutor(8) as pool:
+            list(pool.map(lambda q: session.get(f"{args.ef}/service/kb/concept/{q}", timeout=60), qids))
+        timings["kb concepts"].append(time.perf_counter() - t)
+        t = time.perf_counter()
+        cands = fresh_candidates(doc, args.k, args.ef)
+        timings["candidates"].append(time.perf_counter() - t)
+        _, questions = build_questions(cands)
+        prepared.append((doc, questions))
+        if args.no_jev:
+            continue
+        t = time.perf_counter()
+        result = call_jev(doc.text, questions, args.model, key)
+        timings["jev"].append(time.perf_counter() - t)
+        usage.update(result.get("usage", {}))
+
+    words = [len(d.text.split()) for d in sample]
+    questions = [len(q) for _, q in prepared]
+    print(f"\n{len(sample)} documents: {sum(words) / len(words):.0f} words, {sum(n_qids) / len(n_qids):.0f} distinct QIDs from /disambiguate and {sum(questions) / len(questions):.0f} Jev questions per document on average")
+    if not args.no_jev:
+        print(f"Jev tokens: {usage['input_tokens'] / len(sample):.0f} input, {usage['output_tokens'] / len(sample):.0f} output per document")
+    print("\nLatency per document, calls in sequence:")
+    for stage, values in timings.items():
+        if values:
+            print(f"  {stage:13} {stats(values)}")
+    current = [d + k for d, k in zip(timings["disambiguate"], timings["kb concepts"], strict=True)]
+    print(f"  {'CURRENT':13} {stats(current)}   (disambiguate + kb concepts, as pyannotators_entityfishing)")
+    if args.no_jev:
+        print(f"  {'candidates':13} (the new chain adds its Jev call to this; skipped by --no-jev)")
+        return 0
+    chain = [c + j for c, j in zip(timings["candidates"], timings["jev"], strict=True)]
+    print(f"  {'NEW':13} {stats(chain)}   (candidates + jev)")
+
+    print("\nJev throughput (same documents):")
+    print(f"  concurrency  1: {len(sample) / sum(timings['jev']):.2f} documents/s, {usage['input_tokens'] / sum(timings['jev']):.0f} input tokens/s")
+    for c in args.concurrency:
+        if c == 1:
+            continue
+        t = time.perf_counter()
+        with ThreadPoolExecutor(c) as pool:
+            results = list(pool.map(lambda dq: call_jev(dq[0].text, dq[1], args.model, key), prepared))
+        wall = time.perf_counter() - t
+        tokens = sum(r.get("usage", {}).get("input_tokens", 0) for r in results)
+        print(f"  concurrency {c:2}: {len(sample) / wall:.2f} documents/s, {tokens / wall:.0f} input tokens/s   (wall {wall:.1f} s)")
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--corpus", action="append", choices=["msnbc", "aquaint"], help="default: both")
+    parser.add_argument("--limit", type=int, default=0, help="first N documents of each corpus (smoke run)")
+    parser.add_argument("--ef", default=EF_DEFAULT)
+    parser.add_argument("--min-selector", type=float, default=0.3, help="minSelectorScore of /disambiguate (annotator default: 0.3)")
+    parser.add_argument("--k", type=int, default=8, help="candidates kept per mention")
+    parser.add_argument("--model", default="jev-latest")
+    parser.add_argument("--refresh-jev", action="store_true")
+    parser.add_argument("--no-jev", action="store_true", help="skip the Jev calls (candidates and baselines only; with --bench, time entity-fishing only)")
+    parser.add_argument("--bench", type=int, default=0, metavar="N", help="time real calls (no cache) on N documents, half from each corpus")
+    parser.add_argument("--concurrency", type=int, nargs="+", default=[1, 8], help="Jev concurrencies measured by --bench")
+    args = parser.parse_args()
+
+    env = ROOT / "tests" / ".env"
+    if env.exists():
+        for line in env.read_text().splitlines():
+            if "=" in line and not line.lstrip().startswith("#"):
+                k, v = line.split("=", 1)
+                os.environ.setdefault(k.strip(), v.strip().strip("'\""))
+    key = os.getenv("JEV_API_KEY") or os.getenv("TYPESAFE_API_KEY")
+    if not key and not args.no_jev:
+        print("No JEV_API_KEY: use --no-jev", file=sys.stderr)
+        return 1
+
+    docs = []
+    for corpus in args.corpus or ["msnbc", "aquaint"]:
+        docs += load_corpus(corpus)[: args.limit or None]
+    if args.bench:
+        return bench(docs, args, key)
+    resolve_titles(docs)
+    unresolved = sum(1 for d in docs for m in d.mentions if m.title and not m.qid)
+    for d in docs:  # a gold title with no QID cannot be scored either way
+        d.mentions = [m for m in d.mentions if not m.title or m.qid]
+
+    scores: dict[str, Score] = {"disambiguate": Score(), "prior": Score()}
+    for t in THRESHOLDS:
+        scores[f"jev conf>={t}"] = Score()
+    cand_recall, usage = Counter(), Counter()
+
+    for n, doc in enumerate(docs, 1):
+        print(f"# {n}/{len(docs)} {doc.corpus}/{doc.name} ({len(doc.mentions)} mentions)", file=sys.stderr)
+        ef_links = disambiguate(doc, args.ef, args.min_selector)
+        cands = candidates_of(doc, args.k, args.ef)
+        answers, u = ({}, {}) if args.no_jev else jev(doc, cands, args.model, key, args.refresh_jev)
+        usage.update(u)
+        for m in doc.mentions:
+            scores["disambiguate"].add(m, ef_links.get((m.start, m.end)))
+            cs = cands.get(m.surface, [])
+            scores["prior"].add(m, max(cs, key=lambda c: c["prior"])["qid"] if cs else None)
+            if m.qid:
+                cand_recall["gold"] += 1
+                cand_recall["in_candidates"] += any(c["qid"] == m.qid for c in cs)
+            a = answers.get(m.surface)
+            for t in THRESHOLDS:
+                pred = None
+                if a and a["choice"] != NONE and a["confidence"] >= t:
+                    pred = a["choice"]
+                scores[f"jev conf>={t}"].add(m, pred)
+            if a and m.qid:  # keep_ambiguity: the gold QID among the 2 most probable non-NONE options
+                best2 = [q for q, _ in sorted(a["probabilities"].items(), key=lambda kv: -kv[1]) if q != NONE][:2]
+                cand_recall["top2"] += m.qid in best2
+
+    mentions = sum(len(d.mentions) for d in docs)
+    print(f"\n{len(docs)} documents, {mentions} mentions scored ({unresolved} gold titles with no QID dropped)")
+    print(f"candidate recall @K={args.k}: {cand_recall['in_candidates']}/{cand_recall['gold']} = {cand_recall['in_candidates'] / max(cand_recall['gold'], 1):.1%}  (ceiling of the term-lookup chain)\n")
+    for name, s in scores.items():
+        if name.startswith("jev") and args.no_jev:
+            continue
+        print(f"{name:16} {s.row()}")
+    if not args.no_jev:
+        print(f"{'jev top-2':16} gold QID among the 2 most probable options: {cand_recall['top2']}/{cand_recall['gold']} = {cand_recall['top2'] / max(cand_recall['gold'], 1):.1%}")
+        print(f"\nJev usage: {usage['input_tokens']} input tokens, {usage['output_tokens']} output tokens, {usage['input_tokens'] / max(len(docs), 1):.0f} input tokens per document")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pyannotators_entityfishing-1.6.73/submodules/python-archetype/skills/new-plugin/SKILL.md

@@ -1,132 +0,0 @@
----
-name: new-plugin
-description: Créer un plugin Sherpa — importeur (pyimporters), et plus tard convertisseur, processeur, annotateur, formateur ou segmenteur (pymultirole) — à partir d'un format ou d'un besoin : clone la graine du contrat, écrit la classe et ses options, les tests et leurs fixtures, la table d'options du README, et câble le plugin dans le paquet de flavor du serveur. À utiliser quand on demande un nouvel importeur, un nouveau format de thésaurus, ou un nouveau plugin pyimporters / pymultirole.
----
-
-# Créer un plugin Sherpa
-
-Tu fais **deux choses de nature différente**, et il ne faut pas les confondre :
-
-- **l'enveloppe** (`pyproject.toml`, `Taskfile.yml`, `Jenkinsfile`, `.gitignore`…)
-  est produite par la graine et sa task `init`. **Tu ne l'écris pas, tu la lances.**
-  Elle doit rester identique aux dépôts frères à l'identifiant près ; la réécrire
-  de mémoire, c'est fabriquer un neuvième dépôt subtilement différent.
-- **le contenu** (le parser, ses options, les tests, les fixtures, le README, le
-  câblage inter-dépôts) demande du jugement. C'est ton travail.
-
-La méthode, ce qu'elle remplace et pourquoi : `md/PLUGIN_TEMPLATE.md` du poste,
-ou le `README.md` de la graine.
-
-## 1. Rassembler l'essentiel (demander, ne pas supposer)
-
-- **le type** — `importer` aujourd'hui ; voir `references/types.md` pour la table
-  type → graine, groupe d'entry-points, classe de base, paquet de flavor. Si le
-  type demandé n'a pas encore de graine, **le dire et s'arrêter** : ne pas
-  improviser une enveloppe.
-- **le nom** — en minuscules, sans préfixe : `foo` donne `pyimporters_foo`,
-  `pyimporters-foo`, et l'entry-point `foo`.
-- **le préfixe de classe** — la casse est libre et suit le format, pas le nom :
-  `CSV`, `MeSH`, `SKOSRF`. Il donne `<CLASS>KnowledgeParser` et `<CLASS>Options`.
-- **la description** — une ligne, sur le patron des dépôts frères :
-  « Sherpa FOO knowledge import plugin ».
-- **le format source** — un fichier d'exemple si possible, sinon la spec. Sans
-  échantillon, les options et le compte attendu des tests sont des devinettes :
-  demander.
-
-## 2. L'enveloppe : lancer la graine, ne rien inventer
-
-```bash
-git clone git@bitbucket.org:kairntech/pyimporters_seed.git pyimporters_<nom>
-cd pyimporters_<nom>
-# Le submodule d'ABORD : le Taskfile l'INCLUT, donc Task refuse de charger le
-# fichier — et 'task init' n'existe pas — tant qu'il n'est pas initialisé.
-git submodule update --init
-task init NAME=<nom> CLASS=<CLASS> DESC="<description>"
-```
-
-`init` renomme le paquet, le module, le test et sa fixture, substitue
-l'identifiant, écrit la description à ses trois emplacements, remet la version à
-`1.6.0`, retire le `publish: false` du Jenkinsfile, coupe la section « graine »
-du README, se supprime du Taskfile, et repointe `origin` en gardant `seed` en
-lecture seule.
-
-Vérifier tout de suite, avant d'écrire une ligne de code :
-
-```bash
-task            # doit sortir en 0 sur le squelette
-```
-
-## 3. Le parser
-
-Remplacer le corps de `pyimporters_<nom>/<nom>.py`, **garder la forme** :
-
-- les options dérivent de `KnowledgeParserOptions` et se déclarent en
-  `Query(défaut, description=...)` — le schéma remonte dans l'API du serveur,
-  donc chaque `description` est de la documentation utilisateur, pas un commentaire ;
-- `parse()` est un **générateur** qui `yield` des `Term` ; ne pas construire de liste ;
-- `maybe_archive(source, encoding=...)` déplie `zip`/`gzip` de façon
-  transparente : s'en servir plutôt que d'ouvrir le fichier, et ajouter `"zip"`
-  aux extensions ;
-- renseigner `bar.max` puis `bar.start()` quand le nombre de termes est
-  connaissable d'avance (une première passe de comptage est acceptable), sinon se
-  contenter de `bar.next()` ;
-- `get_extensions()` liste les extensions **sans le point** : `["csv", "tsv", "zip"]`.
-
-Un `Term` a `identifier` (obligatoire), `preferredForm`, `lexicon`, `properties`
-(dict libre — c'est là que vont les formes alternatives, sous `altForms`).
-
-## 4. Les tests et leurs fixtures
-
-Deux tests au minimum, dans la forme des dépôts frères :
-
-- un test de parsing avec un **vrai fichier** dans `tests/data/`, et un
-  `check_expected()` qui vérifie un compte de concepts et un `Term` précis à un
-  index donné. Un compte exact vaut mieux qu'un `assert len(...) > 0` : c'est ce
-  qui attrape une régression de séparateur ou d'encodage.
-- **garder le test de découverte par entry-point** que la graine fournit, en
-  ajustant le nom. Un plugin dont l'entry-point est faux s'importe très bien,
-  passe tous ses tests de parsing, et n'est jamais appelé par le serveur.
-
-Si le format se distribue en archive, ajouter un test sur le `.zip` — comme
-`test_zipped_text` dans `pyimporters_csv`.
-
-## 5. Le README
-
-Compléter la table des options laissée par la graine : une ligne par option,
-avec son défaut et sa description, **plus le comportement de repli** quand il
-n'est pas évident (dans `pyimporters_csv`, un nom de colonne inconnu retombe sur
-la colonne 0 et journalise un avertissement — ça se documente).
-
-## 6. Le câblage inter-dépôts — sans lui, le plugin n'existe pas
-
-Le serveur découvre les parsers par entry-point, mais **seulement parmi les
-paquets installés**, et ce qui est installé est la liste de dépendances d'un
-paquet de flavor. Un plugin non câblé ne remonte jamais dans l'API.
-
-- ajouter `"pyimporters-<nom>>=1.6.0,<1.7.0"` aux `dependencies` du paquet de
-  flavor (`references/types.md` dit lequel ; pour un importeur,
-  `pyimporters_server/packages/pyimporters-builtins/pyproject.toml`) ;
-- aligner la borne de `pyimporters_plugins` sur celle des dépôts frères, ne pas
-  l'élargir ;
-- créer le dépôt Bitbucket `kairntech/pyimporters_<nom>` (**underscore** : seul le
-  nom de distribution prend le tiret), pousser, vérifier le premier build.
-
-## 7. Vérifier, et ne rendre la main que vert
-
-```bash
-task                 # lint, tests, SBOM, CVE, build
-```
-
-Corriger jusqu'au 0 — ruff compris. Ne pas déclarer terminé sur un `task` rouge,
-et ne pas désactiver une règle pour faire passer le lint.
-
-## Ce qu'il ne faut pas faire
-
-- réécrire l'enveloppe à la main, ou « améliorer » le `pyproject.toml` : l'écart
-  avec les dépôts frères est le défaut, pas la variété ;
-- toucher à `submodules/` : code épinglé, hors de notre autorité ;
-- réciter l'ordre du pipeline de mémoire. Il vit dans `STAGES` et l'archétype
-  peut avoir bougé depuis l'installation de ce plugin : l'interroger
-  (`task stages`, `task --list`) ;
-- versionner `uv.lock` (`LOCK_VERSIONED: "false"` ici : `py:sync` résout à neuf) ;
-- écrire la version à la main : c'est la CI qui la pose.

pyannotators_entityfishing-1.6.73/submodules/python-archetype/skills/new-plugin/references/types.md

@@ -1,37 +0,0 @@
-# Table des types de plugins
-
-Ce qui distingue un type d'un autre est **de la donnée** — quatre colonnes. C'est
-la raison pour laquelle il y a *un* skill `new-plugin` et non un par famille :
-six skills à 90 % identiques dériveraient les uns des autres, et rien ne lint un
-skill.
-
-| type | graine | groupe d'entry-points | classe de base | paquet de flavor | graine prête ? |
-|------|--------|-----------------------|----------------|------------------|----------------|
-| `importer` | `kairntech/pyimporters_seed` | `pyimporters.plugins` | `KnowledgeParserBase` (`pyimporters_plugins.base`) | `pyimporters_server/packages/pyimporters-builtins` | **oui** |
-| `converter` | `kairntech/pyconverters_seed` | `pyconverters.plugins` | `ConverterBase` (`pymultirole_plugins.v1.converter`) | `pymultirole_server/packages/pymultirole-builtins` | non |
-| `processor` | `kairntech/pyprocessors_seed` | `pyprocessors.plugins` | `ProcessorBase` (`pymultirole_plugins.v1.processor`) | `pymultirole-builtins` ou une flavor dédiée | non |
-| `annotator` | `kairntech/pyannotators_seed` | `pyannotators.plugins` | `AnnotatorBase` (`pymultirole_plugins.v1.annotator`) | `pymultirole-builtins` | non |
-| `formatter` | `kairntech/pyformatters_seed` | `pyformatters.plugins` | `FormatterBase` (`pymultirole_plugins.v1.formatter`) | `pymultirole-builtins` | non |
-| `segmenter` | `kairntech/pysegmenters_seed` | `pysegmenters.plugins` | `SegmenterBase` (`pymultirole_plugins.v1.segmenter`) | `pymultirole-builtins` | non |
-
-## Une seule graine existe aujourd'hui
-
-`pyimporters_seed` est poussée, son build est vert, et elle ne publie rien
-(`publish: false`). **Les cinq autres n'existent pas** : la famille
-`pymultirole` n'est pas encore passée sous `python-archetype`, et ses 63 dépôts
-portent encore la sortie de `cookiecutter-pymultirole` (`bumpversion.py`,
-`AUTHORS.md`, `CHANGELOG.md`, `RELEASE.md`, `mypy.ini`, `docs/`, layout `src/`).
-
-Si on demande un type dont la graine n'existe pas : **le dire et s'arrêter.**
-Improviser l'enveloppe reviendrait à recréer à la main ce que la graine garantit,
-sans la garantie — et le dépôt produit devrait être migré comme les 63 autres.
-
-## Pourquoi une graine par contrat, et un seul skill
-
-Une graine doit **builder** : un `ConverterBase` et un `ProcessorBase` n'ont pas
-la même signature, donc un dépôt ne peut pas builder les deux. Une graine
-paramétrée qui supprimerait quatre contrats sur cinq à l'`init` redeviendrait un
-template — du code non exécutable, hors CI, exactement le défaut qu'on corrige.
-
-Un skill, lui, n'a rien à builder : le dupliquer ne coûte pas un job Jenkins, ça
-coûte une divergence que personne ne mesure.