Découper une adresse en champs

"""
Étiqueter chaque jeton d'une adresse par une régression logistique sur des
traits de contexte.

Niveau N1. N0 lit l'adresse qu'il attend ; celui-ci lit l'adresse qu'on lui
donne. Chaque mot est étiqueté pour lui-même — numéro, type de voie, nom de
voie, complément, code postal, ville — d'après ce à quoi il ressemble et
d'après ce qui se trouve de part et d'autre. Les champs sont ensuite
reconstruits à partir des étiquettes.

C'est là tout le gain : un complément au milieu de la ligne n'avale plus la
voie, parce que « Bâtiment » est un mot que le modèle a déjà vu à cette place,
et non un jeton imprévu dans un motif figé.

Le prix est un jeu d'entraînement étiqueté. Le test et l'essai l'entraînent
sur dix-huit adresses étiquetées à la main, et il lit déjà une rue, une
résidence et une ville qu'il n'a jamais vues ; toute convention absente de ce
jeu est une convention que le modèle ne connaît pas.
"""

import re
import unicodedata

from sklearn.feature_extraction import DictVectorizer
from sklearn.linear_model import LogisticRegression
from sklearn.pipeline import make_pipeline

# The labels are the fields, so the mapping back is a grouping and nothing more.
LABELS = ("number", "street_type", "street", "complement", "postcode", "city")

TOKEN = re.compile(r"[^\W_]+")


def tokenise(address: str) -> list[str]:
    """Words and numbers, punctuation dropped."""
    return TOKEN.findall(unicodedata.normalize("NFKC", address))


def fold(word: str) -> str:
    """Lowercase and accent-free, so "Allée" and "allee" share a trait."""
    decomposed = unicodedata.normalize("NFD", word.lower())
    return "".join(c for c in decomposed if not unicodedata.combining(c))


def features(tokens: list[str], i: int) -> dict:
    """
    What the token looks like, and what surrounds it.

    The neighbours carry much of the signal: five digits followed by a
    capitalised word look like a postcode and a town. Position counts as well:
    on "75011 Paris, 8 rue des Lilas" the end of the line wins, and the town
    comes out as "Lilas".
    """
    token = tokens[i]
    return {
        f"token={fold(token)}": 1,
        f"previous={fold(tokens[i - 1]) if i else '<start>'}": 1,
        f"next={fold(tokens[i + 1]) if i + 1 < len(tokens) else '<end>'}": 1,
        "digits": float(token.isdigit()),
        "five_digits": float(token.isdigit() and len(token) == 5),
        "short_number": float(token.isdigit() and len(token) <= 3),
        "capitalised": float(token[:1].isupper()),
        "position": i / len(tokens),
        "last": float(i == len(tokens) - 1),
    }


def train(examples):
    """
    `examples` pairs an address with one label per token, in reading order.

    Tagging is the work of this rung, and mistagging it is the usual way the
    rung is made to fail, so a misaligned example is rejected rather than
    quietly learnt.
    """
    rows, targets = [], []
    for address, labels in examples:
        tokens = tokenise(address)
        if len(tokens) != len(labels):
            raise ValueError(f"{len(tokens)} tokens for {len(labels)} labels: {address!r}")
        rows += [features(tokens, i) for i in range(len(tokens))]
        targets += list(labels)
    model = make_pipeline(
        DictVectorizer(),
        LogisticRegression(max_iter=1000, class_weight="balanced"),
    )
    model.fit(rows, targets)
    return model


def parse(model, address: str) -> dict:
    """Group the labelled tokens back into fields, in reading order."""
    fields = dict.fromkeys(LABELS, "")
    tokens = tokenise(address)
    if not tokens:
        return fields
    predicted = model.predict([features(tokens, i) for i in range(len(tokens))])
    for token, label in zip(tokens, predicted):
        fields[label] = f"{fields[label]} {token}".strip()
    # The street type stays available on its own, and also opens the street, so
    # the output can be compared field by field with the rung below.
    fields["street"] = f"{fields['street_type']} {fields['street']}".strip()
    return fields

/**
 * Étiqueter chaque jeton d'une adresse par une régression logistique sur des
 * traits de contexte.
 *
 * Niveau N1. N0 lit l'adresse qu'il attend ; celui-ci lit l'adresse qu'on lui
 * donne. Chaque mot est étiqueté pour lui-même — numéro, type de voie, nom de
 * voie, complément, code postal, ville — d'après ce à quoi il ressemble et
 * d'après ce qui se trouve de part et d'autre. Les champs sont ensuite
 * reconstruits à partir des étiquettes.
 *
 * C'est là tout le gain : un complément au milieu de la ligne n'avale plus la
 * voie, parce que « Bâtiment » est un mot que le modèle a déjà vu à cette place,
 * et non un jeton imprévu dans un motif figé.
 *
 * Une régression binaire par étiquette, entraînée par simple descente de
 * gradient, et la plus forte l'emporte. Écrite ici plutôt que tirée d'une
 * bibliothèque : aucune dépendance à installer pour un modèle de cette taille.
 */

// The labels are the fields, so the mapping back is a grouping and nothing more.
export const LABELS = ['number', 'street_type', 'street', 'complement', 'postcode', 'city'];

const TOKEN = /[\p{L}\p{N}]+/gu;

/** Words and numbers, punctuation dropped. */
export function tokenise(address) {
  return address.normalize('NFKC').match(TOKEN) ?? [];
}

/** Lowercase and accent-free, so "Allée" and "allee" share a trait. */
export function fold(word) {
  return word.toLowerCase().normalize('NFD').replace(/\p{M}/gu, '');
}

const isDigits = (token) => /^\d+$/.test(token);

/**
 * What the token looks like, and what surrounds it.
 *
 * The neighbours carry much of the signal: five digits followed by a
 * capitalised word look like a postcode and a town. Position counts as well:
 * on "75011 Paris, 8 rue des Lilas" the end of the line wins, and the town
 * comes out as "Lilas".
 */
export function features(tokens, i) {
  const token = tokens[i];
  return {
    [`token=${fold(token)}`]: 1,
    [`previous=${i > 0 ? fold(tokens[i - 1]) : '<start>'}`]: 1,
    [`next=${i + 1 < tokens.length ? fold(tokens[i + 1]) : '<end>'}`]: 1,
    digits: Number(isDigits(token)),
    five_digits: Number(isDigits(token) && token.length === 5),
    short_number: Number(isDigits(token) && token.length <= 3),
    capitalised: Number(token[0] !== token[0].toLowerCase()),
    position: i / tokens.length,
    last: Number(i === tokens.length - 1),
  };
}

/**
 * `examples` pairs an address with one label per token, in reading order.
 *
 * Tagging is the work of this rung, and mistagging it is the usual way the rung
 * is made to fail, so a misaligned example is rejected rather than quietly
 * learnt.
 */
export function train(examples, { epochs = 300, rate = 0.3 } = {}) {
  const rows = [];
  const targets = [];
  for (const [address, labels] of examples) {
    const tokens = tokenise(address);
    if (tokens.length !== labels.length) {
      throw new Error(`${tokens.length} tokens for ${labels.length} labels: ${address}`);
    }
    tokens.forEach((_, i) => {
      rows.push(features(tokens, i));
      targets.push(labels[i]);
    });
  }

  // Two labels at least, as scikit-learn demands: with one, every token would
  // get it, and with none, parsing would have no label to pick.
  if (new Set(targets).size < 2) throw new RangeError('train needs at least two different labels');

  // One column per trait seen in training. A trait absent from this map is a
  // word the model never met, and it simply contributes nothing at prediction.
  const columns = new Map();
  const vectors = rows.map((row) =>
    Object.entries(row).map(([name, value]) => {
      if (!columns.has(name)) columns.set(name, columns.size);
      return [columns.get(name), value];
    }));

  const weights = {};
  for (const label of new Set(targets)) {
    const w = new Float64Array(columns.size + 1); // the last cell is the bias
    for (let epoch = 0; epoch < epochs; epoch += 1) {
      for (let i = 0; i < vectors.length; i += 1) {
        const target = targets[i] === label ? 1 : 0;
        const error = 1 / (1 + Math.exp(-score(w, vectors[i]))) - target;
        for (const [column, value] of vectors[i]) w[column] -= rate * error * value;
        w[columns.size] -= rate * error;
      }
    }
    weights[label] = w;
  }
  return { columns, weights };
}

/** Group the labelled tokens back into fields, in reading order. */
export function parse(model, address) {
  const fields = Object.fromEntries(LABELS.map((name) => [name, '']));
  const tokens = tokenise(address);
  tokens.forEach((token, i) => {
    const vector = vectorise(features(tokens, i), model.columns);
    const label = Object.keys(model.weights).reduce((best, candidate) =>
      score(model.weights[candidate], vector) > score(model.weights[best], vector) ? candidate : best);
    fields[label] = `${fields[label]} ${token}`.trim();
  });
  // The street type stays available on its own, and also opens the street, so
  // the output can be compared field by field with the rung below.
  fields.street = `${fields.street_type} ${fields.street}`.trim();
  return fields;
}

function vectorise(row, columns) {
  return Object.entries(row)
    .filter(([name]) => columns.has(name))
    .map(([name, value]) => [columns.get(name), value]);
}

function score(weights, vector) {
  let total = weights[weights.length - 1];
  for (const [column, value] of vector) total += weights[column] * value;
  return total;
}

"""
Découper une adresse avec un analyseur statistique auto-hébergé.

Niveau N2. libpostal est un analyseur entraîné sur plus d'un milliard
d'adresses de tous les pays habités. Il étiquette un jeton d'après son
contexte, comme au niveau N1, mais là où N1 connaît les dix-huit adresses
françaises qu'on lui a étiquetées, l'entraînement de libpostal couvre aussi
les conventions des autres pays. S'il en lit une correctement, rien ici ne le
mesure. Il tourne sur votre machine, donc aucune adresse n'en sort.

Ce qui vous appartient à ce niveau n'est pas le modèle. C'est le lot, la borne
de taille, la correspondance entre son jeu d'étiquettes et le vôtre, et la
réponse à « que fait le code quand l'analyseur renvoie quelque chose
d'inutilisable ». Le modèle est une boîte noire, avec une liste d'étiquettes
fixe et aucun score de confiance, et la dernière fonction ci-dessous est
l'endroit où cela devient votre problème.
"""

from __future__ import annotations

# A postal address is short: La Poste's rules allow six lines of 38 characters,
# which is 228 characters plus the separators. The cap is set above that, at
# 300, so that a line written with generous punctuation still goes through;
# anything past it is not an address, and is refused before parsing.
MAX_CHARACTERS = 300

FIELDS = ("number", "street", "complement", "postcode", "city")

# libpostal's label set is its own, and wider than ours. Five of its labels
# land in our complement, "house" among them: libpostal's name for a building
# or a venue, where a French residence name goes. Everything unmapped is dropped
# on purpose: an unmapped label that silently became a field would be a
# surprise in a letter.
COMPONENTS = {
    "house_number": "number",
    "road": "street",
    "house": "complement",
    "unit": "complement",
    "level": "complement",
    "staircase": "complement",
    "entrance": "complement",
    "postcode": "postcode",
    "city": "city",
}


class ParsingUnavailable(Exception):
    """The parser failed, or answered something no caller can act on."""


class LibpostalParser:
    """The real parser: a C library and its data files, loaded once per process on import."""

    def __init__(self) -> None:
        from postal.parser import parse_address  # a large local install

        self._parse_address = parse_address

    def predict(self, addresses: list[str]) -> list[dict]:
        """One label-to-value mapping per address, in the order given."""
        return [self._merge(self._parse_address(a)) for a in addresses]

    @staticmethod
    def _merge(components) -> dict:
        """libpostal yields (value, label) pairs, and repeats a label freely."""
        merged: dict[str, str] = {}
        for value, label in components:
            merged[label] = f"{merged.get(label, '')} {value}".strip()
        return merged


def parse_addresses(addresses, parser=None, *, attempts: int = 2) -> list[dict]:
    """
    Parse a batch of addresses into fields.

    `parser` is injected so this can be tested without installing the model. In
    production it defaults to the real one above.

    The whole batch goes to the parser object in one call, but libpostal has no
    batching: `LibpostalParser.predict` parses the addresses one after the other.
    """
    batch = list(addresses)
    for address in batch:
        if len(address) > MAX_CHARACTERS:
            raise ValueError(f"address longer than {MAX_CHARACTERS} characters")
    if not batch:
        return []
    parser = parser or LibpostalParser()

    rows = _predict(parser, batch, attempts)
    if len(rows) != len(batch):
        raise ParsingUnavailable("the parser returned one row per address, and did not")
    return [_to_fields(row) for row in rows]


def _predict(parser, batch: list[str], attempts: int) -> list[dict]:
    """
    Retry a failed parse once. Loading is not retried: a parser that cannot
    load its data files fails before this point, with its own error.
    """
    last_error: Exception | None = None
    for _ in range(attempts):
        try:
            return parser.predict(batch)
        except Exception as error:  # noqa: BLE001 - any model failure is retried
            last_error = error
    raise ParsingUnavailable(str(last_error))


def _to_fields(row) -> dict:
    """Keep the labels we mapped, join those that share a field, drop the rest."""
    if row is None:
        row = {}
    if not isinstance(row, dict):
        raise ParsingUnavailable(f"the parser returned a {type(row).__name__}, not a mapping")
    fields = dict.fromkeys(FIELDS, "")
    for label, value in row.items():
        field = COMPONENTS.get(label)
        if field and isinstance(value, str) and value.strip():
            fields[field] = f"{fields[field]} {value.strip()}".strip()
    return fields

/**
 * Découper une adresse avec un analyseur statistique auto-hébergé.
 *
 * Niveau N2. libpostal est un analyseur entraîné sur plus d'un milliard
 * d'adresses de tous les pays habités. Il étiquette un jeton d'après son
 * contexte, comme au niveau N1, mais là où N1 connaît les dix-huit adresses
 * françaises qu'on lui a étiquetées, l'entraînement de libpostal couvre aussi
 * les conventions des autres pays. S'il en lit une correctement, rien ici ne le
 * mesure. Il tourne sur votre machine, donc aucune adresse n'en sort.
 *
 * Ce qui vous appartient à ce niveau n'est pas le modèle. C'est le lot, la borne
 * de taille, la correspondance entre son jeu d'étiquettes et le vôtre, et la
 * réponse à « que fait le code quand l'analyseur renvoie quelque chose
 * d'inutilisable ». Le modèle est une boîte noire, avec une liste d'étiquettes
 * fixe et aucun score de confiance, et la dernière fonction ci-dessous est
 * l'endroit où cela devient votre problème.
 */

// A postal address is short: La Poste's rules allow six lines of 38 characters,
// which is 228 characters plus the separators. The cap is set above that, at
// 300, so that a line written with generous punctuation still goes through;
// anything past it is not an address, and is refused before parsing.
export const MAX_CHARACTERS = 300;

export const FIELDS = ['number', 'street', 'complement', 'postcode', 'city'];

// libpostal's label set is its own, and wider than ours. Five of its labels
// land in our complement, "house" among them: libpostal's name for a building
// or a venue, where a French residence name goes. Everything unmapped is dropped
// on purpose: an unmapped label that silently became a field would be a
// surprise in a letter.
const COMPONENTS = {
  house_number: 'number',
  road: 'street',
  house: 'complement',
  unit: 'complement',
  level: 'complement',
  staircase: 'complement',
  entrance: 'complement',
  postcode: 'postcode',
  city: 'city',
};

export class ParsingUnavailable extends Error {}

/** The real parser: a native binding and its data files, loaded once per process on import. */
export class LibpostalParser {
  static async load() {
    // node-postal is CommonJS: imported from a module, its exports sit under
    // `default`, and `parser` is not detected as a named export.
    const { parser } = (await import('node-postal')).default;
    return new LibpostalParser((address) => parser.parse_address(address));
  }

  constructor(parseAddress) {
    this.parseAddress = parseAddress;
  }

  /** One label-to-value mapping per address, in the order given. */
  async predict(addresses) {
    return addresses.map((address) => merge(this.parseAddress(address)));
  }
}

/** libpostal yields {component, value} pairs, and repeats a component freely. */
function merge(components) {
  const merged = {};
  for (const { component, value } of components) {
    merged[component] = `${merged[component] ?? ''} ${value}`.trim();
  }
  return merged;
}

/**
 * Parse a batch of addresses into fields.
 *
 * `parser` is injected so this can be tested without installing the model. In
 * production it defaults to the real one above.
 *
 * The whole batch goes to the parser object in one call, but libpostal has no
 * batching: `LibpostalParser.predict` parses the addresses one after the other.
 */
export async function parseAddresses(addresses, parser, { attempts = 2 } = {}) {
  const batch = [...addresses];
  for (const address of batch) {
    // Code points, as Python counts them: an emoji is one character, not two.
    if ([...address].length > MAX_CHARACTERS) {
      throw new RangeError(`address longer than ${MAX_CHARACTERS} characters`);
    }
  }
  if (batch.length === 0) return [];
  const model = parser ?? (await LibpostalParser.load());

  const rows = await predict(model, batch, attempts);
  if (rows.length !== batch.length) {
    throw new ParsingUnavailable('the parser returned one row per address, and did not');
  }
  return rows.map(toFields);
}

/**
 * Retry a failed parse once. Loading is not retried: a parser that cannot load
 * its data files fails before this point, with its own error.
 */
async function predict(parser, batch, attempts) {
  let lastError;
  for (let i = 0; i < attempts; i += 1) {
    try {
      return await parser.predict(batch);
    } catch (error) {
      lastError = error;
    }
  }
  throw new ParsingUnavailable(String(lastError));
}

/** Keep the labels we mapped, join those that share a field, drop the rest. */
function toFields(row) {
  if (row !== null && row !== undefined && (typeof row !== 'object' || Array.isArray(row))) {
    throw new ParsingUnavailable('the parser returned something other than a mapping');
  }
  const fields = Object.fromEntries(FIELDS.map((name) => [name, '']));
  for (const [label, value] of Object.entries(row ?? {})) {
    const field = COMPONENTS[label];
    if (field && typeof value === 'string' && value.trim()) {
      fields[field] = `${fields[field]} ${value.trim()}`.trim();
    }
  }
  return fields;
}

"""
Découper une adresse en appelant un modèle généraliste.

Niveau N3. Il est ici pour qu'on voie ce qu'il coûte, pas parce que cette
fiche le recommande.

Notez ce que le code doit faire et que N0 ne faisait pas : borner la taille de
l'entrée, réessayer après un échec, analyser une réponse qui n'est que
probablement du JSON valide, et vérifier que les champs rendus étaient bien
dans l'adresse. Ce dernier point est propre à l'extraction : une valeur que
l'adresse ne contient pas est écartée, parce qu'un code postal plausible est
pire qu'un champ vide — rien en aval ne le mettra jamais en doute.

Cette plomberie est le vrai coût de ce niveau, et c'est la part que vos tests
doivent couvrir, parce que le modèle lui-même n'est pas testable.
"""

from __future__ import annotations

import json
import re
import unicodedata

# 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

FIELDS = ("number", "street", "complement", "postcode", "city")

PROMPT = (
    "Split the postal address below into fields.\n"
    "Answer with JSON only: an object with the keys `number`, `street`,\n"
    "`complement`, `postcode` and `city`. Copy the text exactly as it is\n"
    "written, and leave a key empty when the address does not carry it.\n\n"
    "Address:\n{address}"
)

# An address is a short line. The cap is a cost control: the provider bills the
# tokens of the prompt as well as those of the answer.
MAX_CHARACTERS = 300


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


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


def parse(address: str, client=None, *, attempts: int = 3) -> dict:
    """
    Split an address into number, street, complement, postcode and town.

    `client` is injected so this function can be tested without a network call.
    In production it defaults to a real provider client.
    """
    if len(address) > MAX_CHARACTERS:
        raise ValueError(f"address longer than {MAX_CHARACTERS} characters")
    client = client or ProviderClient()

    answer = _ask(client, address, attempts)
    source = _words(address)
    taken = [False] * len(source)
    values = {key: _text(answer.get(key)) for key in FIELDS}
    fields = dict.fromkeys(FIELDS, "")
    # Kept only if the model copied it from the address, as whole words not
    # already claimed by another field. Longest first, so a postcode "12" cannot
    # take its digits out of "Appartement 12". What it made up is dropped, and an empty
    # field is a question a human can see.
    for key in sorted(FIELDS, key=lambda k: -len(_words(values[k]))):
        words = _words(values[key])
        for start in range(len(source) - len(words) + 1) if words else ():
            end = start + len(words)
            if source[start:end] == words and not any(taken[start:end]):
                taken[start:end] = [True] * len(words)
                fields[key] = values[key].strip()
                break
    return fields


def _ask(client, address: str, attempts: int) -> dict:
    last_error: Exception | None = None
    for _ in range(attempts):
        try:
            # Temperature zero, because an address that splits differently
            # between two identical calls cannot be reconciled with anything.
            answer = client.complete(prompt=PROMPT.format(address=address), temperature=0)
            # No content (a refusal) is as unusable as prose.
            parsed = json.loads(answer) if isinstance(answer, str) else None
            if isinstance(parsed, dict):
                return parsed
            last_error = ValueError("the model answered something that is not an object")
        except Exception as error:  # noqa: BLE001 - any provider failure is retried
            last_error = error
    raise ParsingUnavailable(str(last_error))


def _text(value) -> str:
    """A string as it came, a whole number as its digits (75011), anything else as nothing."""
    if isinstance(value, (int, float)) and not isinstance(value, bool) and float(value).is_integer():
        return str(int(value))
    return value if isinstance(value, str) else ""


def _words(text: str) -> list[str]:
    """Case, spacing and punctuation are the model's to change; the words are not."""
    return re.findall(r"[^\W_]+", unicodedata.normalize("NFKC", text).lower())

/**
 * Découper une adresse en appelant un modèle généraliste.
 *
 * Niveau N3. Il est ici pour qu'on voie ce qu'il coûte, pas parce que cette
 * fiche le recommande.
 *
 * Notez ce que le code doit faire et que N0 ne faisait pas : borner la taille de
 * l'entrée, réessayer après un échec, analyser une réponse qui n'est que
 * probablement du JSON valide, et vérifier que les champs rendus étaient bien
 * dans l'adresse. Ce dernier point est propre à l'extraction : une valeur que
 * l'adresse ne contient pas est écartée, parce qu'un code postal plausible est
 * pire qu'un champ vide — rien en aval ne le mettra jamais en doute.
 *
 * Cette plomberie est le vrai coût de ce niveau, et c'est la part que vos tests
 * doivent couvrir, parce que le modèle lui-même n'est pas testable.
 */

// 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 const FIELDS = ['number', 'street', 'complement', 'postcode', 'city'];

const PROMPT = [
  'Split the postal address below into fields.',
  'Answer with JSON only: an object with the keys `number`, `street`,',
  '`complement`, `postcode` and `city`. Copy the text exactly as it is',
  'written, and leave a key empty when the address does not carry it.',
  '',
  'Address:',
].join('\n');

// An address is a short line. The cap is a cost control: the provider bills the
// tokens of the prompt as well as those of the answer.
export const MAX_CHARACTERS = 300;

export class ParsingUnavailable extends Error {}

/**
 * Split an address into number, street, complement, postcode and town.
 *
 * @param {string} address
 * @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 {number} [options.attempts]
 */
export async function parse(address, { client, attempts = 3 } = {}) {
  // Code points, as Python counts them: an emoji is one character, not two.
  if ([...address].length > MAX_CHARACTERS) {
    throw new RangeError(`address longer than ${MAX_CHARACTERS} characters`);
  }
  client ??= await providerClient();

  const answer = await ask(client, address, attempts);
  const source = words(address);
  const taken = source.map(() => false);
  const values = Object.fromEntries(FIELDS.map((key) => [key, text(answer[key])]));
  const fields = Object.fromEntries(FIELDS.map((name) => [name, '']));
  // Kept only if the model copied it from the address, as whole words not
  // already claimed by another field. Longest first, so a postcode "12" cannot
  // take its digits out of "Appartement 12". What it made up is dropped, and an empty
  // field is a question a human can see.
  for (const key of [...FIELDS].sort((a, b) => words(values[b]).length - words(values[a]).length)) {
    const wanted = words(values[key]);
    for (let start = 0; wanted.length && start + wanted.length <= source.length; start += 1) {
      const end = start + wanted.length;
      if (wanted.every((w, i) => source[start + i] === w) && !taken.slice(start, end).some(Boolean)) {
        taken.fill(true, start, end);
        fields[key] = values[key].trim();
        break;
      }
    }
  }
  return fields;
}

async function ask(client, address, attempts) {
  let lastError;
  for (let i = 0; i < attempts; i += 1) {
    try {
      const answer = await client.complete({
        prompt: `${PROMPT}\n${address}`,
        // Temperature zero, because an address that splits differently between
        // two identical calls cannot be reconciled with anything.
        temperature: 0,
      });
      // No content (a refusal) is as unusable as prose.
      const parsed = typeof answer === 'string' ? JSON.parse(answer) : null;
      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) return parsed;
      lastError = new Error('the model answered something that is not an object');
    } catch (error) {
      lastError = error;
    }
  }
  throw new ParsingUnavailable(String(lastError));
}

/** A string as it came, a whole number as its digits (75011), anything else as nothing. */
function text(value) {
  if (Number.isInteger(value)) return String(value);
  return typeof value === 'string' ? value : '';
}

/** Case, spacing and punctuation are the model's to change; the words are not. */
function words(value) {
  return value.normalize('NFKC').toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [];
}