#Documentation utilisateur

L'écosystème d'agents aide à répondre à un appel à propositions (AAP) à partir d'une collection Zotero annotée. Il analyse les attendus de l'appel, extrait les concepts de la collection, mesure l'accord entre annotateurs, puis rédige une proposition d'article avec références, citations et mots-clés. Tout est archivé dans Omeka S.

flowchart LR
    subgraph Préparer["1. Préparer (Zotero)"]
        Z1[Collection de documents] --> Z2[Surlignages en couleur,<br/>notes, marqueurs]
    end
    subgraph Paramétrer["2. Paramétrer (interface)"]
        P1[Collection Zotero] --> P2[Lien ou fichier de l'appel]
        P2 --> P3[Plan de la proposition]
    end
    subgraph Lancer["3. Lancer"]
        L1[Enregistrer et lancer] --> L2[Suivre le journal]
    end
    subgraph Exploiter["4. Exploiter"]
        E1[AttenduAPP] --> E2[PropAPP]
        E2 --> E3[Relecture, rapport,<br/>graphe, kappa]
    end
    Préparer --> Paramétrer --> Lancer --> Exploiter

#1. Préparer le corpus dans Zotero

#La collection

Rassembler dans une collection Zotero les documents à mobiliser : articles, chapitres, pages web enregistrées, PDF, DOCX, ODT, EPUB, textes. Chaque notice Zotero fournit la référence bibliographique (BibTeX) de la proposition ; ses pièces jointes fournissent le texte analysé.

#Surligner avec une couleur qui indique votre positionnement

La couleur d'un surlignage indique votre position par rapport au passage. Elle oriente l'extraction des concepts et apparaît dans les citations de la proposition. La table par défaut reprend la palette de Zotero ; elle est modifiable dans Paramètres › Positionnement par couleur.

Les annotations faites dans le lecteur Zotero et celles déjà présentes dans un PDF sont toutes les deux prises en compte.

#Notes et marqueurs

• Une note rattachée à une notice est traitée comme une annotation : c'est typiquement une citation (« … » § 15) accompagnée de votre commentaire. Le repère (§ 15, p. 12) est repris dans la citation.
• Un marqueur (tag) sur une notice, une pièce jointe, une note ou une annotation devient un concept : il apparaît dans le graphe, dans les mots-clés de la proposition et dans Omeka S. Les marqueurs listés dans Marqueurs exclus des mots-clés (par défaut citation) ne deviennent pas des mots-clés.

#Coder les phrases pour l'accord inter-juges

Pour mesurer l'accord entre plusieurs annotateurs (juges), chaque juge ajoute comme marqueur le code de la grille d'annotation (grille_annotation.md) sur la phrase annotée :

Les juges doivent travailler dans une bibliothèque de groupe Zotero : c'est ce qui permet de savoir qui a codé quoi. Les codes ne deviennent pas des concepts.

#2. Utiliser l'interface

L'interface s'ouvre sur http://127.0.0.1:7272. Elle comporte quatre onglets : Paramètres, Exécution, Résultats et Appels traités.

#Paramètres

Enregistrer écrit les modifications dans .env et workflow.config.json ; Rétablir la configuration par défaut revient aux valeurs de config.ts.

#Le plan de la proposition

Le plan est un texte markdown : chaque titre devient une section de la proposition, les lignes Consigne : guident le rédacteur et ne figurent pas dans le texte final.

# Titre de la proposition
Consigne : titre court et explicite, en lien direct avec l'appel.

## Résumé
Consigne : 250 mots maximum ; problématique, démarche, apports attendus.

## Cadre théorique
Consigne : mobiliser les concepts du graphe et les références de la collection, avec citations.

#Quand le site de l'appel bloque le téléchargement

Certains sites (par exemple ceux protégés par Cloudflare) refusent les accès automatiques. Ouvrir la page dans le navigateur, l'enregistrer en PDF (Imprimer › Enregistrer au format PDF) ou en HTML, puis l'importer avec Fichier de l'appel. Le lien reste la source de l'appel dans Omeka S.

#Exécution

Enregistrer et lancer enregistre les paramètres et démarre le traitement. Le journal s'affiche en direct ; un traitement peut être arrêté. On peut fermer la page : le journal reprend à la réouverture.

stateDiagram-v2
    [*] --> Paramétré : Enregistrer
    Paramétré --> EnCours : Enregistrer et lancer
    EnCours --> Terminé : succès
    EnCours --> Échec : erreur d'une étape
    EnCours --> Arrêté : Arrêter
    Terminé --> EnCours : relancer
    Échec --> EnCours : corriger puis relancer
    Arrêté --> EnCours : relancer

Le traitement enchaîne les étapes suivantes (durée indicative : quelques minutes par document, selon la taille des textes) :

flowchart TD
    A[Appel à propositions<br/>→ AttenduAPP] --> C
    B[Documents Zotero<br/>texte, annotations, notes] --> C{ }
    C --> D[Graphe de concepts]
    C --> E[Accord inter-juges]
    D --> F[Export des concepts<br/>dans Omeka S]
    E --> F
    F --> G[Proposition d'article<br/>PropAPP]
    G --> H[Relecture épistémologique]
    H --> I[Rapport de traitement]

Un document dont l'extraction sémantique est déjà faite (date curation:access renseignée dans Omeka S) n'est pas retraité : ses concepts sont relus dans Omeka S. Relancer est donc rapide quand seuls quelques documents ont changé.

#Résultats

L'onglet Résultats affiche les documents produits : markdown mis en forme, tableaux CSV, graphe interactif.

#Le graphe de concepts

La taille d'un concept dépend de son nombre de relations, sa couleur de sa catégorie. Survoler un concept met en évidence ses voisins ; cliquer ouvre sa fiche (relations, documents sources, lien vers l'item Omeka S). La recherche, la légende (pour masquer une catégorie) et le zoom sont dans le panneau.

#Les auteurs de la proposition

Les annotateurs Zotero sont auteurs de la proposition (par nombre d'annotations décroissant), suivis des auteurs supplémentaires saisis dans les paramètres.

#Lire l'accord inter-juges

Le kappa de Fleiss est calculé pour trois juges ou plus, et le kappa de Cohen s'y ajoute avec deux juges. Le rapport liste les codes les plus souvent confondus et un bilan rédigé par l'agent analyste ; le CSV détaille chaque phrase pour un recalibrage ciblé.

#La consommation de tokens

Le rapport de traitement indique le nombre de tokens consommés par les modèles : total, entrée, sortie (et raisonnement), détaillé par traitement (attendus de l'appel, extraction, nettoyage du graphe, rédaction, relecture, bilan kappa) et par modèle. Le total est aussi enregistré dans l'item de configuration de l'exécution (curation:data) et affiché dans l'onglet Appels traités.

#Appels traités

L'onglet Appels traités liste les appels à propositions déjà analysés, avec l'historique de leurs exécutions (date, collection, statut, durée, tokens, titre de la proposition, lien vers la configuration dans Omeka S). Il réunit l'historique local (workflow.history.json) et les configurations enregistrées dans Omeka S : les exécutions faites depuis une autre machine ou avant une réinstallation y figurent aussi.

Pour chaque appel :

• Rejouer relance l'analyse avec la collection choisie (par défaut, la dernière utilisée), avec les paramètres et les connexions actuels : c'est l'usage prévu après une modification de la collection Zotero (nouveaux documents, annotations, notes), un changement de modèle ou de connexion ;
• Charger dans les paramètres reprend l'appel et la collection dans l'onglet Paramètres, pour les ajuster avant de lancer.

Seuls les documents nouveaux ou modifiés sont retraités : ceux dont l'extraction est déjà faite sont relus dans Omeka S. Un appel importé depuis un fichier local ne peut être rejoué que si le fichier est toujours présent dans aap/.

#3. Ce qui est enregistré dans Omeka S

flowchart TD
    COL[Collection Zotero<br/>bibo:Collection] --- CFG[Configuration d'exécution<br/>dcterms:MethodOfInstruction]
    AAP[Appel à propositions<br/>bibo:CallForPapers] -- dcterms:relation --> COL
    DOC[Document Zotero<br/>bibo:AcademicArticle, bibo:BookSection…] -- dcterms:isPartOf --> COL
    ANN[Annotation<br/>oa:Annotation] -- oa:hasTarget --> DOC
    DOC -- dcterms:subject --> CON[Concept<br/>skos:Concept]
    ANN -- curation:tag --> CON
    CON -- dcterms:relation --> CON
    AAP -. médias .-> M1[AttenduAPP, PropAPP, BibTeX]
    COL -. médias .-> M2[relecture, graphe, rapport, CSV]

• Chaque document porte les métadonnées de sa notice Zotero (auteurs, date, revue, DOI…), son texte, ses fichiers et images, et la date de sa dernière extraction (curation:access).
• Chaque annotation porte le passage, votre commentaire, la couleur et le positionnement, les marqueurs (liés aux concepts), le code de la grille et son auteur.
• Un concept n'est jamais créé en double : avant de le créer, le workflow cherche un concept de même identifiant ou de même titre.
• Chaque exécution enregistre sa configuration (sans les clés d'API), son statut et les tokens consommés.

#4. Questions fréquentes

Puis-je modifier le plan de la proposition ? Oui, dans Paramètres › Proposition d'article › Plan de la proposition. Les titres et leur ordre sont respectés par le rédacteur.

Pourquoi un document n'est-il pas retraité ? Son extraction est déjà faite (curation:access). Pour la relancer, vider cette propriété sur l'item du document dans Omeka S.

Une nouvelle note Zotero est-elle prise en compte ? Oui : elle est ajoutée aux annotations du document dans Omeka S, et ses marqueurs deviennent des concepts, sans relancer l'extraction du document.

Le rédacteur peut-il inventer des références ? Il ne reçoit que les clés BibTeX de la collection et doit citer uniquement celles-ci (syntaxe Pandoc [@clé, p. 12]) ; la relecture épistémologique vérifie l'usage des références.