AI Categorization
=================

The *AI Categorization* feature classifies every newly created ticket and moves it
into the queue suggested by the AI model. The classification happens
asynchronously.

The set of candidate queues is built from the list of valid queues defined in
Rexpondo, minus the ones listed in the
``Frontend::Margot::TicketCategorization::ExcludedQueues`` setting. The
service then posts to the AI endpoint the ticket content together with
the candidate queues and receives back the chosen queue name; on success the
ticket is moved and a history entry of the form
``AI categorization: moved to queue '<QueueName>'`` is added.


Enable the Feature
------------------
1. Contact E-Time to purchase and activate the AI integration for your
   subscription.
2. Set ``Frontend::Margot::Categorization::Enable`` to *enabled*.
3. Deploy the System Configuration.

.. important::

   To improve classification performance and avoid misrouting, make sure that
   every queue has an **exhaustive name and description** (``NAME`` and
   ``COMMENT`` fields). Vague or non-descriptive queue names and descriptions
   may confuse the AI model and cause tickets to be moved to the wrong queue.


Settings Reference
------------------

.. list-table::
   :header-rows: 1
   :widths: 35 25 40

   * - SysConfig key
     - Default
     - Description
   * - ``Frontend::Margot::Categorization::Enable``
     - 0
     - Master switch for the AI categorization on ticket creation.
   * - ``Frontend::Margot::TicketCategorization::ExcludedQueues``
     - *(empty)*
     - Comma-separated list of queue names to **exclude** when building the
       candidate list. Sub-queues must use the double-colon notation
       (e.g. ``ParentQueue::SubQueue``). Leave empty to include all valid
       queues.
   * - ``Ticket::EventModulePost###5000-MargotCategorization``
     - ``Module=Kernel::System::Ticket::Event::MargotCategorization``,
       ``Event=TicketCreate``, ``Transaction=1``
     - Event module registration. Set to *invalid* to disable the automatic
       categorization without changing the feature switch.


.. warning::

   If the queue suggested by AI does not exist, is invalid, or is
   present in ``Frontend::Margot::TicketCategorization::ExcludedQueues``,
   the ticket stays in the queue it was
   originally created in and an entry is written to the system log. The
   categorization is best-effort and never blocks ticket creation.