Router un ticket de support vers la bonne équipe

"""
Router un ticket de support avec des règles par mots-clés : ordonnées, avec
une équipe par défaut.

Niveau N0. Déterministe, bibliothèque standard seule, et chaque décision peut
être expliquée à celui qui demande pourquoi son ticket a atterri là.

Deux choses font d'une liste de mots-clés une règle qu'un service de support
peut vraiment appliquer.

D'abord, une priorité explicite. Un ticket parle de plusieurs sujets ; que
deux équipes soient déclenchées par le même ticket est donc le cas normal, pas
l'exception. L'ordre de RULES y répond une fois pour toutes et par écrit, au
lieu de laisser trancher la branche qui s'exécute la première.

Ensuite, une équipe par défaut. Tout ticket doit atterrir quelque part ; celui
qui ne déclenche rien doit partir dans une file qu'un humain surveille, et non
tomber par terre.
"""

import re
import unicodedata

# The queue that gets everything the rules cannot place. Naming it here, next
# to the rules, is what stops a ticket from silently going nowhere.
DEFAULT_TEAM = "general"

# Business knowledge, kept next to the code that applies it.
#
# The order is the priority, and it is a business decision, not a detail of
# implementation: a billing problem has a legal clock on it, an outage blocks
# the customer's work, a parcel is the one that can wait a day. Whoever
# disagrees can reorder this tuple and nothing else.
RULES = (
    ("billing", ("facture", "facturation", "remboursement", "prélèvement", "iban", "devis", "paiement")),
    ("technical", ("bug", "erreur", "panne", "connexion", "mot de passe", "identifiant")),
    ("shipping", ("livraison", "colis", "transporteur", "expédition", "suivi", "retard")),
)


def _fold(text: str) -> str:
    """Lowercase and drop accents, so "Prélèvement" matches "prelevement"."""
    decomposed = unicodedata.normalize("NFD", text.lower())
    return "".join(c for c in decomposed if not unicodedata.combining(c))


# A word boundary on the left only. "facture" then also matches "factures"
# and "facturé"; "facturation" does not start with it, and has its own entry.
# The price is that a keyword matches a longer word starting the same way:
# "panne" catches "panneau", "retard" catches "retardataire", "devis" catches
# "devise". The test names them.
_COMPILED = tuple(
    (team, tuple((word, re.compile(rf"\b{re.escape(_fold(word))}")) for word in words))
    for team, words in RULES
)


def matches(ticket: str) -> dict[str, list[str]]:
    """
    Every team the ticket triggers, with the words that triggered it.

    The routing decision needs only the first team, but the reviewer of a
    misrouted ticket needs this: it shows what the rules saw, and what they
    had to drop.
    """
    folded = _fold(ticket)
    found = {}
    for team, patterns in _COMPILED:
        hits = [word for word, pattern in patterns if pattern.search(folded)]
        if hits:
            found[team] = hits
    return found


def route(ticket: str, default_team: str = DEFAULT_TEAM) -> str:
    """The team that gets the ticket. Always one, and always a real queue."""
    found = matches(ticket)
    for team, _ in RULES:
        if team in found:
            return team
    return default_team

/**
 * Router un ticket de support avec des règles par mots-clés : ordonnées, avec
 * une équipe par défaut.
 *
 * Niveau N0. Déterministe, bibliothèque standard seule, et chaque décision peut
 * être expliquée à celui qui demande pourquoi son ticket a atterri là.
 *
 * Deux choses font d'une liste de mots-clés une règle qu'un service de support
 * peut vraiment appliquer.
 *
 * D'abord, une priorité explicite. Un ticket parle de plusieurs sujets ; que
 * deux équipes soient déclenchées par le même ticket est donc le cas normal, pas
 * l'exception. L'ordre de RULES y répond une fois pour toutes et par écrit, au
 * lieu de laisser trancher la branche qui s'exécute la première.
 *
 * Ensuite, une équipe par défaut. Tout ticket doit atterrir quelque part ; celui
 * qui ne déclenche rien doit partir dans une file qu'un humain surveille, et non
 * tomber par terre.
 */

// The queue that gets everything the rules cannot place. Naming it here, next
// to the rules, is what stops a ticket from silently going nowhere.
export const DEFAULT_TEAM = 'general';

/**
 * Business knowledge, kept next to the code that applies it.
 *
 * The order is the priority, and it is a business decision, not a detail of
 * implementation: a billing problem has a legal clock on it, an outage blocks
 * the customer's work, a parcel is the one that can wait a day. Whoever
 * disagrees can reorder this list and nothing else.
 */
export const RULES = [
  ['billing', ['facture', 'facturation', 'remboursement', 'prélèvement', 'iban', 'devis', 'paiement']],
  ['technical', ['bug', 'erreur', 'panne', 'connexion', 'mot de passe', 'identifiant']],
  ['shipping', ['livraison', 'colis', 'transporteur', 'expédition', 'suivi', 'retard']],
];

/** Lowercase and drop accents, so "Prélèvement" matches "prelevement". */
function fold(text) {
  return text.toLowerCase().normalize('NFD').replace(/\p{M}/gu, '');
}

// A word boundary on the left only, with Python's idea of a word character, so
// both languages cut "我的colis" the same way. "facture" then also matches
// "factures" and "facturé"; "facturation" does not start with it, and has its
// own entry. The price is that a keyword matches a longer word starting the
// same way: "panne" catches "panneau", "retard" catches "retardataire",
// "devis" catches "devise". The test names them.
const COMPILED = RULES.map(([team, words]) => [
  team,
  words.map((word) => [word, new RegExp(`(?<![\\p{L}\\p{N}_])${fold(word).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`, 'u')]),
]);

/**
 * Every team the ticket triggers, with the words that triggered it.
 *
 * The routing decision needs only the first team, but the reviewer of a
 * misrouted ticket needs this: it shows what the rules saw, and what they had
 * to drop.
 */
export function matches(ticket) {
  const folded = fold(ticket);
  const found = {};
  for (const [team, patterns] of COMPILED) {
    const hits = patterns.filter(([, pattern]) => pattern.test(folded)).map(([word]) => word);
    if (hits.length) found[team] = hits;
  }
  return found;
}

/** The team that gets the ticket. Always one, and always a real queue. */
export function route(ticket, defaultTeam = DEFAULT_TEAM) {
  const found = matches(ticket);
  for (const [team] of RULES) {
    if (team in found) return team;
  }
  return defaultTeam;
}

"""
Router un ticket d'après les tickets résolus les plus proches, avec un
encodeur auto-hébergé.

Niveau N2. Le niveau N1 apprend les mots de l'archive ; celui-ci compare des
vecteurs. L'encodeur est un modèle entraîné pour la recherche sémantique et le
repérage de paraphrases : il associe un vecteur à chaque ticket, et un ticket
est routé d'après les tickets résolus dont les vecteurs sont les plus proches,
qu'ils partagent ses mots ou non.

Il n'y a pas d'étape d'entraînement ici, et c'est tout l'intérêt du niveau :
l'index est l'archive elle-même. Une équipe dont le périmètre change est un
ré-encodage, pas un réentraînement.

Ce qu'il coûte : un fichier de modèle à livrer et à tenir à jour, un processus
chaud pour le garder en mémoire, et un routage dont les réponses changent le
jour où vous changez de version de modèle. L'archive doit alors être
ré-encodée, et les anciens scores ne sont pas comparables aux nouveaux.
"""

from __future__ import annotations

MODEL_NAME = "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"

DEFAULT_TEAM = "general"


def load_encoder(name: str = MODEL_NAME):
    """The real encoder: fetched once, then held in memory and run locally."""
    from sentence_transformers import SentenceTransformer  # pragma: no cover

    return SentenceTransformer(name)


def build_index(tickets: list[str], teams: list[str], encoder=None) -> dict:
    """
    Encode the resolved archive once, and keep the encoder for the queries.

    `encoder` is injected so this can be tested without loading a model. Left
    alone, it is the real one above.
    """
    encoder = load_encoder() if encoder is None else encoder
    tickets = list(tickets)
    return {"tickets": tickets, "teams": list(teams), "encoder": encoder,
            "vectors": [_unit(v) for v in encoder.encode(tickets)]}


def neighbours(index: dict, ticket: str, k: int = 3) -> list[tuple[float, str]]:
    """The k nearest resolved tickets, best first, with their cosine score."""
    vector = _unit(index["encoder"].encode([ticket])[0])
    # Vectors from another model do not compare. A different length gives it
    # away, where a dot product would still return a plausible number; a model
    # of the same width goes unnoticed.
    if index["vectors"] and len(vector) != len(index["vectors"][0]):
        raise ValueError("the index was encoded by another model: re-encode the archive")
    scored = [(_dot(known, vector), team)
              for known, team in zip(index["vectors"], index["teams"])]
    # A stable sort, so two equally close tickets always come back in archive
    # order. A routing run has to be replayable.
    scored.sort(key=lambda pair: -pair[0])
    return scored[:k]


def route(index: dict, ticket: str, k: int = 3, min_similarity: float = 0.25,
          default_team: str = DEFAULT_TEAM) -> str:
    """
    The team of the nearest resolved tickets, each voting with its similarity.

    A vote rather than the single best neighbour: one archived ticket that
    happens to be phrased like this one is an accident, three of them are a
    pattern.

    The floor is what keeps the default queue of N0 alive. Below it, nothing
    in the archive resembles this ticket, and the honest answer is that this
    rung has never seen the problem.
    """
    votes: dict[str, float] = {}
    for similarity, team in neighbours(index, ticket, k):
        if similarity >= min_similarity:
            votes[team] = votes.get(team, 0.0) + similarity
    if not votes:
        return default_team
    # Ties go to the team of the closest neighbour, which is the first key
    # inserted above.
    return max(votes, key=lambda team: votes[team])


def _unit(vector) -> list[float]:
    """Cosine similarity is a dot product once both sides have length one."""
    values = [float(v) for v in vector]
    norm = sum(v * v for v in values) ** 0.5
    return [v / norm for v in values] if norm else values


def _dot(a: list[float], b: list[float]) -> float:
    return sum(x * y for x, y in zip(a, b))

/**
 * Router un ticket d'après les tickets résolus les plus proches, avec un
 * encodeur auto-hébergé.
 *
 * Niveau N2. Le niveau N1 apprend les mots de l'archive ; celui-ci compare des
 * vecteurs. L'encodeur est un modèle entraîné pour la recherche sémantique et le
 * repérage de paraphrases : il associe un vecteur à chaque ticket, et un ticket
 * est routé d'après les tickets résolus dont les vecteurs sont les plus proches,
 * qu'ils partagent ses mots ou non.
 *
 * Il n'y a pas d'étape d'entraînement ici, et c'est tout l'intérêt du niveau :
 * l'index est l'archive elle-même. Une équipe dont le périmètre change est un
 * ré-encodage, pas un réentraînement.
 *
 * Ce qu'il coûte : un fichier de modèle à livrer et à tenir à jour, un processus
 * chaud pour le garder en mémoire, et un routage dont les réponses changent le
 * jour où vous changez de version de modèle. L'archive doit alors être
 * ré-encodée, et les anciens scores ne sont pas comparables aux nouveaux.
 */

export const MODEL_NAME = 'Xenova/paraphrase-multilingual-MiniLM-L12-v2';

export const DEFAULT_TEAM = 'general';

/** The real encoder: fetched once, then held in memory and run locally. */
export async function loadEncoder(name = MODEL_NAME) {
  const { pipeline } = await import('@huggingface/transformers');
  // Full precision, as the Python encoder: the transformers.js README gives a
  // quantised model (q8) as the default on WASM.
  const extract = await pipeline('feature-extraction', name, { dtype: 'fp32' });
  return { encode: async (texts) => (await extract(texts, { pooling: 'mean' })).tolist() };
}

/**
 * Encode the resolved archive once, and keep the encoder for the queries.
 *
 * `encoder` is injected so this can be tested without loading a model. Left
 * alone, it is the real one above.
 */
export async function buildIndex(tickets, teams, encoder) {
  const model = encoder ?? (await loadEncoder());
  const kept = [...tickets];
  return {
    tickets: kept,
    teams: [...teams],
    encoder: model,
    vectors: (await model.encode(kept)).map(unit),
  };
}

/** The k nearest resolved tickets, best first, with their cosine score. */
export async function neighbours(index, ticket, k = 3) {
  const vector = unit((await index.encoder.encode([ticket]))[0]);
  // Vectors from another model do not compare. A different length gives it
  // away, where a dot product would still return a plausible number; a model
  // of the same width goes unnoticed.
  if (index.vectors.length && vector.length !== index.vectors[0].length) {
    throw new RangeError('the index was encoded by another model: re-encode the archive');
  }
  const scored = index.vectors.map((known, i) => [dot(known, vector), index.teams[i]]);
  // A stable sort, so two equally close tickets always come back in archive
  // order. A routing run has to be replayable.
  return scored.sort((a, b) => b[0] - a[0]).slice(0, k);
}

/**
 * The team of the nearest resolved tickets, each voting with its similarity.
 *
 * A vote rather than the single best neighbour: one archived ticket that
 * happens to be phrased like this one is an accident, three of them are a
 * pattern.
 *
 * The floor is what keeps the default queue of N0 alive. Below it, nothing in
 * the archive resembles this ticket, and the honest answer is that this rung
 * has never seen the problem.
 */
export async function route(index, ticket, { k = 3, minSimilarity = 0.25, defaultTeam = DEFAULT_TEAM } = {}) {
  const votes = new Map();
  for (const [similarity, team] of await neighbours(index, ticket, k)) {
    if (similarity >= minSimilarity) votes.set(team, (votes.get(team) ?? 0) + similarity);
  }
  if (votes.size === 0) return defaultTeam;
  // Ties go to the team of the closest neighbour, which is the first key
  // inserted above.
  let best = defaultTeam;
  let bestVote = -Infinity;
  for (const [team, vote] of votes) {
    if (vote > bestVote) [best, bestVote] = [team, vote];
  }
  return best;
}

/** Cosine similarity is a dot product once both sides have length one. */
function unit(vector) {
  let sum = 0;
  for (const v of vector) sum += v * v;
  const norm = Math.sqrt(sum);
  return norm ? vector.map((v) => v / norm) : [...vector];
}

function dot(a, b) {
  let total = 0;
  for (let i = 0; i < a.length; i += 1) total += a[i] * b[i];
  return total;
}

"""
Router un ticket en interrogeant un modèle généraliste.

Niveau N3. Aucune règle à maintenir, aucune archive à étiqueter : les noms des
équipes vont dans l'invite, et le modèle répond par l'un d'eux.

Voyez ce que le code doit faire et que le niveau N0 n'avait pas à faire :
borner la taille de ce qui part — en tronquant, jamais en levant, parce qu'un
routeur qui lève laisse le ticket nulle part et que l'équipe se décide le plus
souvent au premier paragraphe —, réessayer quand le fournisseur échoue, analyser
une réponse qui n'est que probablement du JSON, et refuser une équipe que le
modèle a inventée. Cette plomberie est le vrai coût de ce niveau, et c'est la
part que vos tests doivent couvrir, puisque le modèle lui-même n'est pas
testable.

Lisez la fin de `route` de près. Un modèle répond des mots, et les mots ne
sont pas des files. La liste fermée est la seule chose qui sépare une réponse
assurée d'un ticket posé dans une file que personne ne surveille.
"""

from __future__ import annotations

import json

# The queues that exist. Business knowledge, and here also a safety rail.
TEAMS = ("billing", "technical", "shipping")
DEFAULT_TEAM = "general"

MAX_CHARACTERS = 4000

PROMPT = (
    "You are routing a customer support ticket to one team.\n"
    "Answer with JSON only: {{\"team\": \"...\"}} where team is one of: {teams}.\n"
    "If the ticket does not clearly belong to one of them, answer {default!r}.\n\n"
    "Ticket:\n{ticket}"
)


# 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 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 RoutingUnavailable(Exception):
    """The provider could not be reached, or answered something unparseable."""


def route(ticket: str, client=None, *, attempts: int = 3) -> str:
    """
    The team that gets the ticket.

    `client` is injected so this function can be tested without a network
    call. In production it defaults to a real provider client.
    """
    client = client or ProviderClient()

    # The provider bills every token of the prompt, and a ticket with a
    # forwarded thread or a pasted log under it is long. The cap counts
    # characters, not tokens, and it truncates rather than raising: a router
    # that throws leaves the ticket nowhere, and the team is usually decided by
    # the first paragraph anyway. What is cut is said to nobody, which is why
    # the caller gets the ticket back only through its queue.
    answer = _ask(client, ticket[:MAX_CHARACTERS], attempts)
    team = answer.get("team") if isinstance(answer, dict) else None
    team = str(team).strip().lower() if team is not None else ""
    # Two failures, two treatments. A provider that cannot answer is an
    # incident, and `_ask` above raises. A model that answers a team nobody
    # created is a normal Tuesday, and the ticket goes to the default queue.
    return team if team in TEAMS else DEFAULT_TEAM


def _ask(client, ticket: str, attempts: int) -> dict:
    prompt = PROMPT.format(teams=", ".join(TEAMS), default=DEFAULT_TEAM, ticket=ticket)
    last_error: Exception | None = None
    for _ in range(attempts):
        try:
            # The lowest temperature: the SDK documents lower values as more
            # focused and deterministic.
            answer = client.complete(prompt=prompt, temperature=0)
            if not isinstance(answer, str):  # a refusal comes back as no content
                last_error = ValueError("the model answered no text")
                continue
            return json.loads(answer)
        except Exception as error:  # noqa: BLE001 - any provider failure is retried
            last_error = error
    raise RoutingUnavailable(str(last_error))

/**
 * Router un ticket en interrogeant un modèle généraliste.
 *
 * Niveau N3. Aucune règle à maintenir, aucune archive à étiqueter : les noms des
 * équipes vont dans l'invite, et le modèle répond par l'un d'eux.
 *
 * Voyez ce que le code doit faire et que le niveau N0 n'avait pas à faire :
 * borner la taille de ce qui part — en tronquant, jamais en levant, parce qu'un
 * routeur qui lève laisse le ticket nulle part et que l'équipe se décide le plus
 * souvent au premier paragraphe —, réessayer quand le fournisseur échoue, analyser
 * une réponse qui n'est que probablement du JSON, et refuser une équipe que le
 * modèle a inventée. Cette plomberie est le vrai coût de ce niveau, et c'est la
 * part que vos tests doivent couvrir, puisque le modèle lui-même n'est pas
 * testable.
 *
 * Lisez la fin de `route` de près. Un modèle répond des mots, et les mots ne
 * sont pas des files. La liste fermée est la seule chose qui sépare une réponse
 * assurée d'un ticket posé dans une file que personne ne surveille.
 */

// The queues that exist. Business knowledge, and here also a safety rail.
export const TEAMS = ['billing', 'technical', 'shipping'];
export const DEFAULT_TEAM = 'general';

export const MAX_CHARACTERS = 4000;

const PROMPT = [
  'You are routing a customer support ticket to one team.',
  `Answer with JSON only: {"team": "..."} where team is one of: ${TEAMS.join(', ')}.`,
  `If the ticket does not clearly belong to one of them, answer '${DEFAULT_TEAM}'.`,
  '',
  'Ticket:',
].join('\n');

// 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 RoutingUnavailable extends Error {}

/**
 * The team that gets the ticket.
 *
 * @param {string} ticket
 * @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 route(ticket, { client, attempts = 3 } = {}) {
  client ??= await providerClient();

  // The provider bills every token of the prompt, and a ticket with a
  // forwarded thread or a pasted log under it is long. The cap counts
  // characters, not tokens — code points, as in Python — and it truncates
  // rather than throwing: a router that throws leaves the ticket nowhere, and
  // the team is usually decided by the first paragraph anyway.
  const sent = [...ticket].slice(0, MAX_CHARACTERS).join('');

  const answer = await ask(client, sent, attempts);
  const named = answer && typeof answer.team === 'string' ? answer.team.trim().toLowerCase() : '';
  // Two failures, two treatments. A provider that cannot answer is an
  // incident, and `ask` above throws. A model that answers a team nobody
  // created is a normal Tuesday, and the ticket goes to the default queue.
  return TEAMS.includes(named) ? named : DEFAULT_TEAM;
}

async function ask(client, ticket, attempts) {
  let lastError;
  for (let i = 0; i < attempts; i += 1) {
    try {
      // The lowest temperature: the SDK documents lower values as more focused
      // and deterministic.
      const answer = await client.complete({ prompt: `${PROMPT}\n${ticket}`, temperature: 0 });
      if (typeof answer !== 'string') {
        lastError = new Error('the model answered no text'); // a refusal comes back as no content
        continue;
      }
      return JSON.parse(answer);
    } catch (error) {
      lastError = error;
    }
  }
  throw new RoutingUnavailable(String(lastError));
}