Extraire des dates d’un texte libre

"""
Lire les dates qu'un motif ne peut pas lire : un analyseur de dates éprouvé.

Niveau N1. Le niveau N0 énumère les formes qu'il connaît, et une échéance
relative n'a pas de forme à énumérer : « dans 15 jours » se compte depuis une
date. C'est ce comptage, dans une trentaine de langues, que fait une
bibliothèque d'analyse de dates. `dateparser` ici, `chrono-node` en
JavaScript : locale, gratuite, déterministe, et installée plutôt qu'écrite.

Il faut lui dire deux choses dont un motif n'avait pas besoin. Quelles langues
le texte peut employer — un analyseur à qui l'on donne toutes celles qu'il
connaît lit davantage, et lit davantage de travers. Et depuis quelle date
compter : `reference` n'a pas de valeur par défaut ici, à dessein, parce que
la date depuis laquelle compter est celle du document, pas celle de
l'exécution. « jeudi prochain » dans un courriel reçu il y a trois semaines
n'est pas jeudi prochain.

Un extrait qui confie le travail à une bibliothèque hérite de la
bibliothèque, pas d'une spécification : les deux langages de cette page n'ont
pas le même analyseur, et ils ne lisent pas les mêmes choses. Sur
« 3 janv. 2024 », `dateparser` répond le 3 janvier 2025 et `chrono-node` ne
répond rien, là où le niveau N0 répond le 3 janvier 2024 — c'est pourquoi N0
reste dessous, et non à côté. Sur « jeudi prochain » ils divergent aussi : le
14 mars pour l'un, le 21 pour l'autre.
"""

from datetime import date, datetime

from dateparser.search import search_dates

LANGUAGES = ("fr", "en")


def extract_dates(text: str, reference: date, languages=LANGUAGES) -> list[tuple[str, date]]:
    """
    Return every date found in `text`, as (what was written, what it means).

    `reference` is the date the relative expressions count from: the date of
    the document. It is required, because a default would silently be the day
    of the run, and a backlog reprocessed on Monday would move every deadline.

    "PREFER_DATES_FROM: future" is the reading of a deadline: "le 3 janvier" in
    a March document is the next one, not the one gone by.
    """
    if not isinstance(reference, date):
        raise TypeError("reference must be a date: the date of the document, not of the run")
    if not languages:
        # An empty list means "every language it knows" to the library. Asked
        # for nothing, this returns nothing, as the JavaScript version does.
        raise ValueError("at least one language is needed")
    settings = {
        "RELATIVE_BASE": datetime(reference.year, reference.month, reference.day),
        "PREFER_DATES_FROM": "future",
    }
    found = search_dates(text, languages=list(languages), settings=settings)
    return [(written, value.date()) for written, value in found or []]

/**
 * Lire les dates qu'un motif ne peut pas lire : un analyseur de dates éprouvé.
 *
 * Niveau N1. Le niveau N0 énumère les formes qu'il connaît, et une échéance
 * relative n'a pas de forme à énumérer : « dans 15 jours » se compte depuis une
 * date. C'est ce comptage, dans plusieurs langues, que fait une bibliothèque
 * d'analyse de dates. `chrono-node` ici, `dateparser` en Python : locale,
 * gratuite, déterministe, et installée plutôt qu'écrite.
 *
 * Il faut lui dire deux choses dont un motif n'avait pas besoin. Quelles langues
 * le texte peut employer — `chrono` a un analyseur par langue, et le français ne
 * lit rien d'anglais. Et depuis quelle date compter : `reference` n'a pas de
 * valeur par défaut ici, à dessein, parce que la date depuis laquelle compter
 * est celle du document, pas celle de l'exécution. « jeudi prochain » dans un
 * courriel reçu il y a trois semaines n'est pas jeudi prochain.
 *
 * Un extrait qui confie le travail à une bibliothèque hérite de la
 * bibliothèque, pas d'une spécification : les deux langages de cette page n'ont
 * pas le même analyseur, et ils ne lisent pas les mêmes choses. Sur
 * « 3 janv. 2024 », `dateparser` répond le 3 janvier 2025 et `chrono-node` ne
 * répond rien, là où le niveau N0 répond le 3 janvier 2024 — c'est pourquoi N0
 * reste dessous, et non à côté. Sur « jeudi prochain » ils divergent aussi : le
 * 14 mars pour l'un, le 21 pour l'autre.
 */

import * as chrono from 'chrono-node';

export const LANGUAGES = ['fr', 'en'];

/**
 * Return every date found in `text`, as { text: what was written, date }.
 *
 * `reference` is the date the relative expressions count from: the date of the
 * document. It is required, because a default would silently be the day of the
 * run, and a backlog reprocessed on Monday would move every deadline.
 *
 * `forwardDate` is the reading of a deadline: "le 3 janvier" in a March
 * document is the next one, not the one gone by.
 */
export function extractDates(text, reference, languages = LANGUAGES) {
  if (!(reference instanceof Date) || Number.isNaN(reference.getTime())) {
    throw new TypeError('reference must be a Date: the date of the document, not of the run');
  }
  // Asked for no language, this returns nothing, and says so rather than
  // quietly reading none — the Python library would read every language it knows.
  if (languages.length === 0) throw new RangeError('at least one language is needed');
  const found = [];
  for (const language of languages) {
    const parser = chrono[language];
    if (!parser) throw new RangeError(`chrono has no parser for ${language}`);
    for (const result of parser.parse(text, reference, { forwardDate: true })) {
      // One parser per language means the same words can be read twice: the
      // first language asked for wins, as in the Python version.
      const end = result.index + result.text.length;
      if (found.some((seen) => seen.index < end && result.index < seen.index + seen.text.length)) continue;
      found.push({ index: result.index, text: result.text, date: result.start.date() });
    }
  }
  found.sort((a, b) => a.index - b.index);
  return found.map(({ text: written, date }) => ({ text: written, date }));
}

"""
Extraire les dates en interrogeant un modèle généraliste.

Niveau N3. Sa requête demande de résoudre les dates relatives, « jeudi
prochain » : elle envoie une date de référence avec le texte, et demande
chaque date sous forme de jour du calendrier. Le niveau N1 résout les mêmes
tournures sur place et pour rien ; ce niveau ne vaut son prix que sur celles
qu'un analyseur manque.

La référence est la date du document, pas le jour de l'exécution : « jeudi
prochain » dans un courriel reçu il y a trois semaines n'est pas jeudi
prochain. Elle n'a pas de valeur par défaut ici, à dessein, parce qu'une
valeur par défaut serait discrètement aujourd'hui, et qu'un arriéré retraité
un lundi déplacerait toutes les échéances.

Le plafond sur l'entrée lève au lieu de tronquer : un contrat coupé en deux
reviendrait avec une liste d'échéances qui a l'air complète. Ce que fait un
appelant au-dessus du plafond, c'est découper le document en morceaux qui se
recouvrent et fusionner les réponses ; cet extrait ne le fait pas, à dessein,
parce qu'il montre un appel.

Voyez ce que le code doit faire et que N0 ne faisait pas : passer une date de
référence, parce que rien d'autre n'indique au modèle le jour qu'il est ;
brider la taille de l'entrée ; réessayer en cas d'échec ; analyser une réponse
qui n'est que probablement du JSON valide ; et vérifier le calendrier
lui-même, parce que rien dans la requête n'empêche la réponse de contenir
2024-02-31. Cette plomberie est le vrai coût du niveau, et c'est la part que
les tests doivent couvrir, puisque le modèle lui-même n'est pas testable.
"""

import json
import re
from datetime import date

PROMPT = (
    "Find every date mentioned in the text below. Answer with JSON only: a list\n"
    "of objects with keys `text` and `date`, where `text` is the words as written\n"
    "and `date` is the day in ISO format, YYYY-MM-DD. Resolve relative dates such\n"
    "as 'next Thursday' against the date of the document, which is {reference}.\n"
    "If there is no date, answer with an empty list.\n\nText:\n{text}"
)
ISO_DAY = re.compile(r"[0-9]{4}-[0-9]{2}-[0-9]{2}")

MAX_CHARACTERS = 8000

# The provider named here is an example, not a recommendation: the reasoning
# holds for any general-purpose model API, and the client is swappable. Pass
# any object with a `complete(prompt=..., temperature=...)` method.
MODEL = "gpt-4.1-mini"  # an example id: check the parameters your model accepts


class ExtractionUnavailable(Exception):
    """The provider could not be reached, or answered something unusable."""


class ProviderClient:
    """The one call this snippet makes, on top of the provider's SDK."""

    def __init__(self, sdk=None, model: str = MODEL):
        if sdk is None:  # pragma: no cover - needs a key and a network
            from openai import OpenAI

            sdk = OpenAI()
        self.sdk, self.model = sdk, model

    def complete(self, *, prompt: str, temperature: float) -> str:
        response = self.sdk.chat.completions.create(
            model=self.model,
            messages=[{"role": "user", "content": prompt}],
            temperature=temperature,
        )
        return response.choices[0].message.content


def extract_dates(text: str, client=None, *, reference: date, attempts: int = 3):
    """
    Return every date the model reports, as (what was written, what it means).

    `reference` is the date the relative expressions are resolved against: the
    date of the document. It has no default: it is a keyword argument the
    caller has to pass, because a default would quietly be today.

    `client` is injected so this function can be tested without a network call.
    In production it defaults to a real provider client.
    """
    if not isinstance(reference, date):
        raise TypeError("reference must be a date: the date of the document, not of the run")
    # The provider bills every token of the prompt. Refusing oversized input
    # before the call is a cost control; the cap counts characters, not tokens.
    if len(text) > MAX_CHARACTERS:
        raise ValueError(f"text longer than {MAX_CHARACTERS} characters")
    if not text.strip():
        return []  # nothing to read, so nothing to pay for
    client = client or ProviderClient()

    found = []
    for item in _ask(client, text, reference, attempts):
        try:
            # The same calendar check as N0, on the model's answer this time.
            value = date.fromisoformat(item["date"])
        except ValueError:
            continue  # a day that does not exist is not a date, however fluent
        written = item.get("text")
        found.append((written if isinstance(written, str) else "", value))
    return found


def _unfenced(answer: str) -> str:
    """
    Strip a code fence that wraps the whole answer, and nothing else.

    Models often hand back a JSON answer inside one fenced block, and refusing
    that form would pay for a second call for nothing. Any other departure —
    text before or after, two blocks, a fence never closed — is left alone, and
    fails to parse, which is the point.
    """
    stripped = answer.strip()
    if stripped.startswith("```") and stripped.endswith("```") and stripped.count("```") == 2:
        return stripped[3:-3].removeprefix("json")
    return stripped


def _is_usable(parsed) -> bool:
    """A list of objects, each with a `date` written YYYY-MM-DD, as the prompt asked."""
    return isinstance(parsed, list) and all(
        isinstance(item, dict) and isinstance(item.get("date"), str) and ISO_DAY.fullmatch(item["date"])
        for item in parsed
    )


def _ask(client, text: str, reference: date, attempts: int) -> list[dict]:
    last_error: Exception | None = None
    for _ in range(attempts):
        try:
            answer = client.complete(
                prompt=PROMPT.format(text=text, reference=reference.isoformat()),
                # Temperature zero: a date that changes between two identical
                # calls cannot be reviewed.
                temperature=0,
            )
            if answer is None:  # a refusal carries no content: unusable, not empty
                last_error = ValueError("the model returned no content")
                continue
            parsed = json.loads(_unfenced(answer))
            if _is_usable(parsed):
                return parsed
            # A list of anything else would read as "no date found", which it is not.
            last_error = ValueError("the model answered something other than a list of ISO days")
        except Exception as error:  # noqa: BLE001 - any provider failure is retried
            last_error = error
    raise ExtractionUnavailable(str(last_error))

/**
 * Extraire les dates en interrogeant un modèle généraliste.
 *
 * Niveau N3. Sa requête demande de résoudre les dates relatives, « jeudi
 * prochain » : elle envoie une date de référence avec le texte, et demande
 * chaque date sous forme de jour du calendrier. Le niveau N1 résout les mêmes
 * tournures sur place et pour rien ; ce niveau ne vaut son prix que sur celles
 * qu'un analyseur manque.
 *
 * La référence est la date du document, pas le jour de l'exécution : « jeudi
 * prochain » dans un courriel reçu il y a trois semaines n'est pas jeudi
 * prochain. Elle n'a pas de valeur par défaut ici, à dessein, parce qu'une
 * valeur par défaut serait discrètement aujourd'hui, et qu'un arriéré retraité
 * un lundi déplacerait toutes les échéances.
 *
 * Le plafond sur l'entrée lève au lieu de tronquer : un contrat coupé en deux
 * reviendrait avec une liste d'échéances qui a l'air complète. Ce que fait un
 * appelant au-dessus du plafond, c'est découper le document en morceaux qui se
 * recouvrent et fusionner les réponses ; cet extrait ne le fait pas, à dessein,
 * parce qu'il montre un appel.
 *
 * Voyez ce que le code doit faire et que N0 ne faisait pas : passer une date de
 * référence, parce que rien d'autre n'indique au modèle le jour qu'il est ;
 * brider la taille de l'entrée ; réessayer en cas d'échec ; analyser une réponse
 * qui n'est que probablement du JSON valide ; et vérifier le calendrier
 * lui-même, parce que rien dans la requête n'empêche la réponse de contenir
 * 2024-02-31. Cette plomberie est le vrai coût du niveau, et c'est la part que
 * les tests doivent couvrir, puisque le modèle lui-même n'est pas testable.
 */

const PROMPT = [
  'Find every date mentioned in the text below. Answer with JSON only: a list',
  'of objects with keys `text` and `date`, where `text` is the words as written',
  'and `date` is the day in ISO format, YYYY-MM-DD. Resolve relative dates such',
  'as "next Thursday" against the date of the document, which is {reference}.',
  'If there is no date, answer with an empty list.', '', 'Text:',
].join('\n');
const ISO_DAY = /^([0-9]{4})-([0-9]{2})-([0-9]{2})$/;

export const MAX_CHARACTERS = 8000;

// The provider named here is an example, not a recommendation: the reasoning
// holds for any general-purpose model API, and the client is swappable. Pass
// any object with a `complete({ prompt, temperature })` method.
export const MODEL = 'gpt-4.1-mini'; // an example id: check the parameters your model accepts

export async function providerClient(sdk, model = MODEL) {
  if (!sdk) {
    const { OpenAI } = await import('openai');
    sdk = new OpenAI();
  }
  return {
    async complete({ prompt, temperature }) {
      const response = await sdk.chat.completions.create({
        model,
        messages: [{ role: 'user', content: prompt }],
        temperature,
      });
      return response.choices[0].message.content;
    },
  };
}

export class ExtractionUnavailable extends Error {}

/** The calendar check of N0, applied to the model's answer this time. */
function parseIsoDay(value) {
  const [year, month, day] = ISO_DAY.exec(value).slice(1).map(Number);
  const date = new Date(0);
  date.setUTCFullYear(year, month - 1, day); // unlike Date.UTC, keeps year 24 as 24
  const real = year >= 1 && date.getUTCMonth() === month - 1 && date.getUTCDate() === day;
  return real ? date : null;
}

/** The caller's own calendar day, not the UTC one: past midnight in Paris, UTC is still yesterday. */
function localDay(date) {
  const pad = (n) => String(n).padStart(2, '0');
  return `${String(date.getFullYear()).padStart(4, '0')}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
}

/**
 * Return every date the model reports, as { text: what was written, date }.
 *
 * @param {string} text
 * @param {object} options
 * @param {{complete: Function}} [options.client] injected so this can be
 *   tested without a network call; defaults to a real provider client
 * @param {Date} options.reference the date of the document, which relative
 *   dates are resolved against, read in the local time zone. Required.
 * @param {number} [options.attempts]
 */
export async function extractDates(text, { client, reference, attempts = 3 } = {}) {
  if (!(reference instanceof Date) || Number.isNaN(reference.getTime())) {
    throw new TypeError('reference must be a Date: the date of the document, not of the run');
  }
  // The provider bills every token of the prompt. Refusing oversized input
  // before the call is a cost control; the cap counts characters, not tokens,
  // and code points, as Python does, not UTF-16 units.
  if (text.length > MAX_CHARACTERS && [...text].length > MAX_CHARACTERS) throw new RangeError(`text longer than ${MAX_CHARACTERS} characters`);
  if (!text.trim()) return []; // nothing to read, so nothing to pay for
  client ??= await providerClient();

  const items = await ask(client, text, localDay(reference), attempts);
  // A day that does not exist is not a date, however fluent the answer.
  return items.map((item) => ({ text: typeof item.text === 'string' ? item.text : '', date: parseIsoDay(item.date) }))
    .filter((item) => item.date);
}

/** A list of objects, each with a `date` written YYYY-MM-DD, as the prompt asked. */
function isUsable(parsed) {
  return Array.isArray(parsed) && parsed.every((item) =>
    item !== null && typeof item === 'object' && typeof item.date === 'string' && ISO_DAY.test(item.date));
}

/**
 * Strip a code fence that wraps the whole answer, and nothing else.
 *
 * Models often hand back a JSON answer inside one fenced block, and refusing
 * that form would pay for a second call for nothing. Any other departure — text
 * before or after, two blocks, a fence never closed — is left alone, and fails
 * to parse, which is the point.
 */
function unfenced(answer) {
  const stripped = answer.trim();
  const fences = stripped.match(/```/g)?.length ?? 0;
  if (stripped.startsWith('```') && stripped.endsWith('```') && fences === 2) {
    return stripped.slice(3, -3).replace(/^json/, '');
  }
  return stripped;
}

async function ask(client, text, reference, attempts) {
  let lastError;
  for (let i = 0; i < attempts; i += 1) {
    try {
      // Temperature zero: a date that changes between two identical calls
      // cannot be reviewed.
      const prompt = `${PROMPT.replace('{reference}', reference)}\n${text}`;
      const answer = await client.complete({ prompt, temperature: 0 });
      if (answer === null || answer === undefined) { // a refusal carries no content: unusable, not empty
        lastError = new Error('the model returned no content');
        continue;
      }
      const parsed = JSON.parse(unfenced(answer));
      if (isUsable(parsed)) return parsed;
      // A list of anything else would read as "no date found", which it is not.
      lastError = new Error('the model answered something other than a list of ISO days');
    } catch (error) {
      lastError = error;
    }
  }
  throw new ExtractionUnavailable(String(lastError));
}