mud_server.translation.validator
================================

.. py:module:: mud_server.translation.validator

.. autoapi-nested-parse::

   Output validator for the OOC→IC translation layer.

   ``OutputValidator`` takes raw LLM text from the renderer and decides
   whether it is suitable for storage as in-character dialogue.  Unsuitable
   output is rejected (returning ``None``) so the caller can fall back to
   the original OOC message.

   Validation pipeline (applied in order)
   ---------------------------------------
   1. **Empty check** — blank string → ``None``.
   2. **PASSTHROUGH sentinel** — the model signals that the OOC input has
      no meaningful IC equivalent (e.g. it was a command or meta-question).
      → ``None``.
   3. **Multi-line check** — strict mode rejects immediately; non-strict
      mode takes only the first non-empty line.
   4. **Quote stripping** — some models (e.g. gemma2) consistently wrap
      output in ``"..."`` or ``'...'``; these are stripped before the
      forbidden-pattern check so that legitimate dialogue is not rejected
      purely because of quoting style.
   5. **Forbidden pattern check** — strict mode only.  Rejects outputs that
      look like emotes, stage directions, or parenthetical narration.  These
      indicate the model has not followed the "one line of raw dialogue"
      constraint.
   6. **Max-length enforcement** — strict mode rejects; non-strict truncates.
   7. **Final empty check** — returns ``None`` if cleaning left an empty
      string.

   Strict vs non-strict
   ---------------------
   ``strict_mode=True`` (the default) treats any constraint violation as a
   hard rejection and returns ``None``.  This is the recommended setting for
   production worlds because it guarantees that only well-formed IC dialogue
   is ever stored — at the cost of occasionally falling back to OOC when
   the model produces slightly imperfect output.

   ``strict_mode=False`` makes a best-effort cleanup attempt for minor
   violations (multi-line → first line; over-length → truncate).  Useful
   for low-stakes worlds or during prompt development.



Attributes
----------

.. autoapisummary::

   mud_server.translation.validator.logger
   mud_server.translation.validator.PASSTHROUGH_SENTINEL


Classes
-------

.. autoapisummary::

   mud_server.translation.validator.OutputValidator


Module Contents
---------------

.. py:data:: logger

.. py:data:: PASSTHROUGH_SENTINEL
   :value: 'PASSTHROUGH'


.. py:class:: OutputValidator(*, strict_mode, max_output_chars)

   Validates and cleans raw LLM output before storage.

   .. attribute:: _strict_mode

      When ``True``, any constraint violation → ``None``.

   .. attribute:: _max_output_chars

      Hard ceiling on IC output character count.

   Initialise the validator.

   :param strict_mode: Reject on first violation vs. best-effort cleanup.
   :param max_output_chars: Maximum allowed character count in the IC output.


   .. py:method:: validate(ic_raw)

      Validate and clean a raw LLM response string.

      Runs the full validation pipeline and returns either a clean IC
      string or ``None``.  A ``None`` return is always accompanied by a
      WARNING log entry so that rejection reasons are traceable.

      :param ic_raw: Raw text returned by the renderer.

      :returns: Cleaned IC string on success, ``None`` if validation fails.