docs/developer/module-policy.md

Politique de modules contribués

Sprint 97 — B.6 du plan d'évolution 2026.

Ce document décrit le cadre de qualité applicable à tout module qu'un utilisateur tiers veut faire évaluer dans une pipeline composée Picarones (axe B). Picarones étant un banc d'essai, le code des modules reste chez l'utilisateur — la plateforme se contente de les charger, les exécuter, et les évaluer. La politique ci-dessous décrit les garanties d'interface et les métadonnées obligatoires pour qu'un module soit acceptable.

TL;DR

Pour qu'un module soit acceptable :

1. Il hérite de picarones.domain.module_protocol.BaseModule (Sprint 33).
2. Il déclare ses input_types et output_types (parmi ArtifactType.{IMAGE, TEXT, ALTO, PAGE, ENTITIES, READING_ORDER}).
3. Il fournit un ModuleManifest avec 5 champs obligatoires : name, version, author, license, description.
4. Il passe audit_module(MyClass, manifest) (cf. picarones.evaluation.metrics.module_policy).

Un module qui ne passe pas l'audit n'est pas exécutable. Pas exécutable = pas dans la pipeline, pas dans le rapport.

Pourquoi cette politique

Avec l'arrivée de l'axe B (banc d'essai de pipelines composées), Picarones évalue des modules tiers que l'institution amène : LLM correcteurs, reconstructeurs ALTO, classifieurs d'entités, mappeurs divers. Sans cadre, ce mode d'usage est ingérable :

• on ne sait pas qui a écrit quoi ;
• on ne sait pas sous quelle licence le module est distribué ;
• on ne peut pas reproduire un benchmark si la version a changé ;
• on ne peut pas citer le module dans un papier scientifique ;
• l'interface peut casser silencieusement et personne ne s'en aperçoit.

La politique de modules adresse ces 5 points avec un manifest structuré et un audit automatique au chargement.

Manifest — champs obligatoires

from picarones.evaluation.metrics.module_policy import ModuleManifest

manifest = ModuleManifest(
    name="my-llm-correcteur",
    version="1.2.0",
    author="alice@institution.fr",
    license="MIT",
    description="Correcteur LLM pour textes médiévaux français.",
    input_types=["text"],
    output_types=["text"],
    citation=(
        "Alice Dupont, 2025. A Domain-Adapted LLM Corrector for "
        "Medieval French. arXiv:2511.12345."
    ),
    homepage="https://github.com/alice/my-llm-correcteur",
    picarones_min_version="1.2.0",
)

Champ	Obligatoire	Description
name	oui	Identifiant unique (slug).
version	oui	Version sémantique (1.2.0).
author	oui	Auteur ou institution responsable.
license	oui	SPDX recommandé (MIT, Apache-2.0, GPL-3.0-or-later…), non validé techniquement.
description	oui	Description courte (≤ 1 phrase).
input_types	oui	Liste des types d'entrée acceptés.
output_types	oui	Liste des types de sortie produits.
citation	non	Citation académique (BibTeX, DOI, ou texte libre).
homepage	non	URL du dépôt ou de la page projet.
picarones_min_version	non	Version minimale de Picarones requise.
extra	non	Métadonnées libres.

Contrat BaseModule

Tout module exécutable hérite de picarones.domain.module_protocol.BaseModule (Sprint 33). Le contrat minimal est :

from picarones.domain.artifacts import ArtifactType
from picarones.domain.module_protocol import BaseModule

class MyLlmCorrecteur(BaseModule):
    name = "my-llm-correcteur"
    input_types = (ArtifactType.TEXT,)
    output_types = (ArtifactType.TEXT,)
    execution_mode = "io"  # "io" pour API, "cpu" pour local

    def process(self, inputs):
        text = inputs[ArtifactType.TEXT]
        # ... votre logique ...
        return {ArtifactType.TEXT: corrected_text}

Audit automatique

from picarones.evaluation.metrics.module_policy import audit_module

result = audit_module(MyLlmCorrecteur, manifest)
if not result.passed:
    for check in result.checks:
        if not check.passed:
            print(f"FAIL: {check.name} | {check.detail}")
    raise SystemExit("module rejeté par l'audit")

L'audit vérifie :

1. Manifest valide — 5 champs obligatoires non vides + input_types/output_types non vides.
2. Héritage — la classe hérite de BaseModule.
3. Cohérence I/O — module.input_types et module.output_types correspondent (case-insensitive) à ceux du manifest.
4. Méthode process — callable sur la classe.

Stratégie d'ouverture en deux temps

Picarones est aujourd'hui en phase fermée : seuls les modules officiels (ceux dans picarones/adapters/ocr/, picarones/adapters/llm/, picarones/pipeline/) sont garantis stables. Les modules contribués externes sont acceptés via PR sur le repo principal après audit.

La phase ouverte sera déclenchée quand 5–6 modules officiels stables et un guide de contribution éprouvé seront disponibles. L'ouverture passera alors par des plugins PyPI (picarones-module-X) avec mécanisme entry_points. Le manifest et l'audit décrits ici sont la fondation de cette phase ouverte — tout plugin externe devra les fournir.

Vue HTML « Modules audités »

Quand une pipeline composée est exécutée, le rapport HTML expose un bloc « Modules audités » (cf. picarones.reports.html.module_audit_render.build_module_audit_html) qui liste pour chaque module :

• statut d'audit (✓ vert ou ✗ rouge avec compte des checks échoués) ;
• métadonnées (version, auteur, licence) ;
• types d'entrée/sortie ;
• citation académique (si fournie) ;
• page projet (si fournie).

Le module ne juge pas la qualité scientifique du module — il expose les métadonnées que le contributeur a déclarées, pour permettre la reproductibilité et la citation correcte dans les publications dérivées.