Extraire les mots-clés d’un document

"""
Les termes qui distinguent ce document des autres du même dossier.

Niveau N1. Le niveau N0 lit un document et ne peut dire que ce qu'il répète.
Tous les contrats d'un dossier de contrats répètent « conditions générales de
vente », et relire ce contrat-là plus attentivement ne révélera jamais que
l'expression ne vaut rien : l'information est dans le dossier, pas dans le
document.

Les candidats sont donc les mêmes qu'au niveau N0 — même découpage, même
liste de mots vides — et seul le classement change. Chaque mot reçoit le
logarithme du nombre de documents divisé par le nombre de ceux qui le
contiennent, et une expression vaut la moyenne de ses mots, multipliée par le
nombre de fois où le document la dit. Un mot présent dans tous les documents
vaut alors exactement zéro, et c'est tout l'objet.

Les égalités sont le cas ordinaire, pas l'exception. Sur un document court,
chaque expression apparaît une fois et dans aucun autre document : elles
valent toutes log(N), et sur un compte rendu de conseil municipal, neuf
termes partagent le même score. Ce qui les départage doit donc vouloir dire
quelque chose — l'expression la plus longue d'abord, parce qu'elle en dit
plus, puis celle qui apparaît le plus tôt, parce qu'un document annonce son
sujet tôt. La chaîne ne vient qu'en dernier, et seulement pour que les deux
langages répondent dans le même ordre : classer par l'alphabet mettait le
sujet du document là où tombe son initiale. Et `tied_at_cut` dit combien de
termes restés dehors partagent le score du dernier retenu, pour qu'un
appelant qui lit « les cinq meilleurs » de douze équivalents le sache.

Deux documents ne sont pas une collection : avec deux, log(2/1) vaut 0,69 et
log(2/2) vaut zéro, si bien que le classement est binaire — présent chez
l'autre, ou non. Le plancher est à deux parce qu'en dessous il n'y a rien à
comparer, pas parce que deux suffisent.

Une différence assumée avec la formule habituelle : `scikit-learn` lisse, et
plancher ce logarithme à un fait qu'un terme présent partout pèse encore
quelque chose. C'est juste quand les poids alimentent une similarité — la
fiche sur les articles voisins emploie la forme lissée pour cette raison.
C'est faux ici : un terme présent dans tous les documents de votre collection
n'est le mot-clé d'aucun d'eux, et l'arrondir à « un peu » le remettrait dans
la liste.

Le modèle, c'est la collection. Il s'ajuste en mémoire, en une passe, à
partir des documents que vous détenez déjà ; il n'y a rien à télécharger et
rien à envoyer.
"""

from __future__ import annotations

import math

from n0 import candidates_of, extract_key_terms

# Kept so the two rungs are told apart in a report that mixes them.
SOURCE = "corpus"


def extract_key_terms_in_corpus(documents, stop_words, *, top: int = 8) -> dict:
    """
    For each document, the phrases the rest of the collection does not share.

    `documents` is the collection itself: the ranking is only as good as what
    you compare against, and two documents are not a collection.
    """
    if not isinstance(documents, (list, tuple)):
        return {"documents": [], "reason": f"expected a list, not {type(documents).__name__}"}
    if len(documents) < 2:
        return {"documents": [], "reason": "a corpus of at least two documents is required"}
    stop = list(stop_words or [])
    if not stop:
        return {"documents": [], "reason": "a stop list is required, one per language"}

    per_document = [candidates_of(text if isinstance(text, str) else "", stop)
                    for text in documents]
    holders = {}
    for phrases in per_document:
        for word in {word for phrase in phrases for word in phrase.split(" ")}:
            holders[word] = holders.get(word, 0) + 1
    total = len(documents)
    idf = {word: math.log(total / count) for word, count in holders.items()}

    ranked = []
    for index, text in enumerate(documents):
        counted = extract_key_terms(text if isinstance(text, str) else "", stop,
                                    top=len(per_document[index]) or 1)["terms"]
        terms = [{"text": term["text"], "key": term["key"], "count": term["count"],
                  "first": term["first"],
                  "score": _rounded(term["count"] * _mean(term["key"], idf))}
                 for term in counted]
        # Equal scores are the ordinary case, not the exception: on a short
        # document every phrase appears once and in no other document, so every
        # one of them scores log(N). What breaks the tie has to mean something
        # — the longer phrase first, because it says more, then the one that
        # appears earliest, because a document states its subject early. The
        # key comes last, and only so that two languages answer in the same
        # order.
        terms.sort(key=lambda t: (-t["score"], -t["count"],
                                  -len(t["key"].split(" ")), t["first"], t["key"]))
        kept = terms[:top]
        # How many terms outside the cut share the score of the last one kept:
        # a caller that reads « the top five » of twelve equals should know.
        tied = 0
        if kept and len(terms) > len(kept):
            tied = sum(1 for term in terms[len(kept):] if term["score"] == kept[-1]["score"])
        ranked.append({"index": index, "terms": kept, "tied_at_cut": tied})
    return {"documents": ranked, "reason": None}


def _mean(key: str, idf: dict) -> float:
    words = key.split(" ")
    return sum(idf.get(word, 0.0) for word in words) / len(words)


def _rounded(value: float) -> float:
    """
    Four decimals, by the same two operations in both languages: Python and
    JavaScript do not round a half the same way, and a ranking must not depend
    on which one ran.
    """
    return math.floor(value * 10000 + 0.5) / 10000

/**
 * Les termes qui distinguent ce document des autres du même dossier.
 *
 * Niveau N1. Le niveau N0 lit un document et ne peut dire que ce qu'il répète.
 * Tous les contrats d'un dossier de contrats répètent « conditions générales de
 * vente », et relire ce contrat-là plus attentivement ne révélera jamais que
 * l'expression ne vaut rien : l'information est dans le dossier, pas dans le
 * document.
 *
 * Les candidats sont donc les mêmes qu'au niveau N0 — même découpage, même
 * liste de mots vides — et seul le classement change. Chaque mot reçoit le
 * logarithme du nombre de documents divisé par le nombre de ceux qui le
 * contiennent, et une expression vaut la moyenne de ses mots, multipliée par le
 * nombre de fois où le document la dit. Un mot présent dans tous les documents
 * vaut alors exactement zéro, et c'est tout l'objet.
 *
 * Les égalités sont le cas ordinaire, pas l'exception. Sur un document court,
 * chaque expression apparaît une fois et dans aucun autre document : elles
 * valent toutes log(N), et sur un compte rendu de conseil municipal, neuf
 * termes partagent le même score. Ce qui les départage doit donc vouloir dire
 * quelque chose — l'expression la plus longue d'abord, parce qu'elle en dit
 * plus, puis celle qui apparaît le plus tôt, parce qu'un document annonce son
 * sujet tôt. La chaîne ne vient qu'en dernier, et seulement pour que les deux
 * langages répondent dans le même ordre : classer par l'alphabet mettait le
 * sujet du document là où tombe son initiale. Et `tied_at_cut` dit combien de
 * termes restés dehors partagent le score du dernier retenu, pour qu'un
 * appelant qui lit « les cinq meilleurs » de douze équivalents le sache.
 *
 * Deux documents ne sont pas une collection : avec deux, log(2/1) vaut 0,69 et
 * log(2/2) vaut zéro, si bien que le classement est binaire — présent chez
 * l'autre, ou non. Le plancher est à deux parce qu'en dessous il n'y a rien à
 * comparer, pas parce que deux suffisent.
 *
 * Une différence assumée avec la formule habituelle : `scikit-learn` lisse, et
 * plancher ce logarithme à un fait qu'un terme présent partout pèse encore
 * quelque chose. C'est juste quand les poids alimentent une similarité — la
 * fiche sur les articles voisins emploie la forme lissée pour cette raison.
 * C'est faux ici : un terme présent dans tous les documents de votre collection
 * n'est le mot-clé d'aucun d'eux, et l'arrondir à « un peu » le remettrait dans
 * la liste.
 *
 * Le modèle, c'est la collection. Il s'ajuste en mémoire, en une passe, à
 * partir des documents que vous détenez déjà ; il n'y a rien à télécharger et
 * rien à envoyer.
 */

import { candidatesOf, extractKeyTerms } from './n0.js';

// Kept so the two rungs are told apart in a report that mixes them.
export const SOURCE = 'corpus';

/**
 * For each document, the phrases the rest of the collection does not share.
 *
 * `documents` is the collection itself: the ranking is only as good as what
 * you compare against, and two documents are not a collection.
 */
export function extractKeyTermsInCorpus(documents, stopWords, { top = 8 } = {}) {
  if (!Array.isArray(documents)) {
    return { documents: [], reason: `expected a list, not ${typeof documents}` };
  }
  if (documents.length < 2) {
    return { documents: [], reason: 'a corpus of at least two documents is required' };
  }
  const stop = [...(stopWords ?? [])];
  if (stop.length === 0) {
    return { documents: [], reason: 'a stop list is required, one per language' };
  }

  const perDocument = documents.map((text) => candidatesOf(typeof text === 'string' ? text : '', stop));
  const holders = new Map();
  for (const phrases of perDocument) {
    const words = new Set(phrases.flatMap((phrase) => phrase.split(' ')));
    for (const word of words) holders.set(word, (holders.get(word) ?? 0) + 1);
  }
  const total = documents.length;
  const idf = new Map([...holders].map(([word, count]) => [word, Math.log(total / count)]));

  const ranked = documents.map((text, index) => {
    const counted = extractKeyTerms(typeof text === 'string' ? text : '', stop,
      { top: perDocument[index].length || 1 }).terms;
    const terms = counted.map((term) => ({
      text: term.text,
      key: term.key,
      count: term.count,
      first: term.first,
      score: rounded(term.count * mean(term.key, idf)),
    }));
    // Equal scores are the ordinary case, not the exception: on a short
    // document every phrase appears once and in no other document, so every
    // one of them scores log(N). What breaks the tie has to mean something —
    // the longer phrase first, because it says more, then the one that appears
    // earliest, because a document states its subject early. The key comes
    // last, and only so that two languages answer in the same order.
    const mots = (term) => term.key.split(' ').length;
    terms.sort((a, b) => b.score - a.score || b.count - a.count
      || mots(b) - mots(a) || a.first - b.first
      || (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
    const kept = terms.slice(0, top);
    // How many terms outside the cut share the score of the last one kept: a
    // caller that reads « the top five » of twelve equals should know.
    const tiedAtCut = kept.length > 0 && terms.length > kept.length
      ? terms.slice(kept.length).filter((term) => term.score === kept.at(-1).score).length
      : 0;
    return { index, terms: kept, tied_at_cut: tiedAtCut };
  });
  return { documents: ranked, reason: null };
}

function mean(key, idf) {
  const words = key.split(' ');
  return words.reduce((sum, word) => sum + (idf.get(word) ?? 0), 0) / words.length;
}

/**
 * Four decimals, by the same two operations in both languages: Python and
 * JavaScript do not round a half the same way, and a ranking must not depend
 * on which one ran.
 */
function rounded(value) {
  return Math.floor(value * 10000 + 0.5) / 10000;
}