Route a support ticket to the right team

"""
Route a support ticket with keyword rules: ordered, with a default team.

Rung N0. Deterministic, standard library only, and every decision can be
explained to the person who asks why their ticket landed where it did.

Two things turn a keyword list into a rule a support desk can actually run.

First, an explicit priority. Tickets mention several subjects, so two teams
matching the same ticket is the normal case, not the exception. The order of
RULES answers it once and in writing, rather than leaving it to whichever
branch happens to run first.

Second, a default team. Every ticket must land somewhere; a ticket that
matches nothing has to go to a queue a human watches, not to the floor.
"""

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

/**
 * Route a support ticket with keyword rules: ordered, with a default team.
 *
 * Rung N0. Deterministic, no dependency, and every decision can be explained
 * to the person who asks why their ticket landed where it did.
 *
 * Two things turn a keyword list into a rule a support desk can actually run.
 *
 * First, an explicit priority. Tickets mention several subjects, so two teams
 * matching the same ticket is the normal case, not the exception. The order of
 * RULES answers it once and in writing, rather than leaving it to whichever
 * branch happens to run first.
 *
 * Second, a default team. Every ticket must land somewhere; a ticket that
 * matches nothing has to go to a queue a human watches, not to the floor.
 */

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

"""
Route a ticket by its nearest resolved tickets, with a self-hosted encoder.

Rung N2. N1 learns the words of the archive; this compares vectors instead.
The encoder is a model trained for semantic search and paraphrase mining: it
maps each ticket to a vector, and a ticket is routed by the resolved tickets
whose vectors are closest, whether or not they share its words.

There is no training step here, and that is the point of the rung: the index
is the archive itself. A team that changes scope is a re-encoding, not a
retraining.

What it costs: a model file to ship and keep in sync, a warm process to hold
it, and a routing whose answers change the day you upgrade the model. The
archive also has to be re-encoded then, and the old scores are not comparable
to the new.
"""

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

/**
 * Route a ticket by its nearest resolved tickets, with a self-hosted encoder.
 *
 * Rung N2. N1 learns the words of the archive; this compares vectors instead.
 * The encoder is a model trained for semantic search and paraphrase mining: it
 * maps each ticket to a vector, and a ticket is routed by the resolved tickets
 * whose vectors are closest, whether or not they share its words.
 *
 * There is no training step here, and that is the point of the rung: the index
 * is the archive itself. A team that changes scope is a re-encoding, not a
 * retraining.
 *
 * What it costs: a model file to ship and keep in sync, a warm process to hold
 * it, and a routing whose answers change the day you upgrade the model. The
 * archive also has to be re-encoded then, and the old scores are not
 * comparable to the new.
 */

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

"""
Route a ticket by asking a general-purpose model.

Rung N3. No rules to maintain and no archive to label: the team names go in
the prompt, and the model answers with one of them.

Note what the code has to do that N0 did not: cap the input size, retry a
provider that fails, parse an answer that is only probably JSON, and refuse a
team the model made up. That plumbing is the real cost of this rung, and it is
the part your tests have to cover, because the model itself is not testable.

Read the end of `route` closely. A model answers with words, and
words are not queues. The closed list is the only thing standing between a
confident answer and a ticket sitting in a queue nobody watches.
"""

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

/**
 * Route a ticket by asking a general-purpose model.
 *
 * Rung N3. No rules to maintain and no archive to label: the team names go in
 * the prompt, and the model answers with one of them.
 *
 * Note what the code has to do that N0 did not: cap the input size, retry a
 * provider that fails, parse an answer that is only probably JSON, and refuse
 * a team the model made up. That plumbing is the real cost of this rung, and
 * it is the part your tests have to cover, because the model itself is not
 * testable.
 *
 * Read the end of `route` closely. A model answers with words, and words are
 * not queues. The closed list is the only thing standing between a confident
 * answer and a ticket sitting in a queue nobody watches.
 */

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