Extract dates from free text

"""
Read the dates a pattern cannot: a mature date parser.

Rung N1. Rung N0 enumerates the shapes it knows, and a relative deadline has
no shape to enumerate: "dans 15 jours" has to be counted from a date. That
counting, in thirty-odd languages, is what a date parser library does.
`dateparser` here, `chrono-node` in JavaScript: local, free, deterministic,
and installed rather than written.

Two things have to be told to it that a pattern never needed. Which languages
the text may be in — a parser given every language it knows reads more, and
reads more wrongly. And which date to count from: `reference` has no default
here, on purpose, because the date to count from is the date of the document,
not the date of the run. "jeudi prochain" in an email received three weeks ago
is not next Thursday.

A snippet that hands the job to a library inherits the library, not a
specification: the two languages of this page do not have the same parser, and
they do not read the same things. On "3 janv. 2024" `dateparser` answers
3 January 2025 and `chrono-node` answers nothing, where rung N0 answers
3 January 2024 — which is why N0 stays underneath rather than beside. On
"jeudi prochain" they disagree too: 14 March for one, 21 March for the other.
"""

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 []]

/**
 * Read the dates a pattern cannot: a mature date parser.
 *
 * Rung N1. Rung N0 enumerates the shapes it knows, and a relative deadline has
 * no shape to enumerate: "dans 15 jours" has to be counted from a date. That
 * counting, in several languages, is what a date parser library does.
 * `chrono-node` here, `dateparser` in Python: local, free, deterministic, and
 * installed rather than written.
 *
 * Two things have to be told to it that a pattern never needed. Which languages
 * the text may be in — `chrono` has one parser per language, and the French one
 * reads nothing English. And which date to count from: `reference` has no
 * default here, on purpose, because the date to count from is the date of the
 * document, not the date of the run. "jeudi prochain" in an email received
 * three weeks ago is not next Thursday.
 *
 * A snippet that hands the job to a library inherits the library, not a
 * specification: the two languages of this page do not have the same parser, and
 * they do not read the same things. On "3 janv. 2024" `dateparser` answers
 * 3 January 2025 and `chrono-node` answers nothing, where rung N0 answers
 * 3 January 2024 — which is why N0 stays underneath rather than beside. On
 * "jeudi prochain" they disagree too: 14 March for one, 21 March for the other.
 */

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 }));
}

"""
Extract dates by asking a general-purpose model.

Rung N3. Its request asks for relative dates, "jeudi prochain", to be
resolved: it sends a reference date along with the text, and asks for every
date as a calendar day. Rung N1 resolves the same expressions locally and for
nothing; this rung is worth its price only on the ones a parser misses.

The reference is the date of the document, not the day of the run: "jeudi
prochain" in an email received three weeks ago is not next Thursday. It has no
default here, on purpose, because a default would quietly be today and a
backlog reprocessed on Monday would move every deadline.

The cap on the input raises rather than truncating: a contract cut in half
would come back with a list of deadlines that looks complete. What a caller
does above the cap is split the document into overlapping chunks and merge the
answers; this snippet does not, on purpose, because it shows one call.

Note what the code has to do that N0 did not: pass a reference date, because
the model is not told what day it is otherwise; cap the input size; retry on
failure; parse an answer that is only probably valid JSON; and check the
calendar itself, because nothing in the request stops the answer from holding
2024-02-31. That plumbing is the real cost of the rung, and it is the part the
tests have to cover, because the model itself is not 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))

/**
 * Extract dates by asking a general-purpose model.
 *
 * Rung N3. Its request asks for relative dates, "jeudi prochain", to be
 * resolved: it sends a reference date along with the text, and asks for every
 * date as a calendar day. Rung N1 resolves the same expressions locally and for
 * nothing; this rung is worth its price only on the ones a parser misses.
 *
 * The reference is the date of the document, not the day of the run: "jeudi
 * prochain" in an email received three weeks ago is not next Thursday. It has no
 * default here, on purpose, because a default would quietly be today and a
 * backlog reprocessed on Monday would move every deadline.
 *
 * The cap on the input raises rather than truncating: a contract cut in half
 * would come back with a list of deadlines that looks complete. What a caller
 * does above the cap is split the document into overlapping chunks and merge the
 * answers; this snippet does not, on purpose, because it shows one call.
 *
 * Note what the code has to do that N0 did not: pass a reference date, because
 * the model is not told what day it is otherwise; cap the input size; retry on
 * failure; parse an answer that is only probably valid JSON; and check the
 * calendar itself, because nothing in the request stops the answer from holding
 * 2024-02-31. That plumbing is the real cost of the rung, and it is the part the
 * tests have to cover, because the model itself is not 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));
}