pipeworks_mud_mapper.services.description_validator
===================================================

.. py:module:: pipeworks_mud_mapper.services.description_validator

.. autoapi-nested-parse::

   Deterministic validator for LLM-generated room descriptions.

   This module implements the hard-rule validator described in
   ``_working/description_validator.md``. It enforces structural constraints
   without rewriting or negotiating prose, in line with the Craft of Constraint
   principle that authority lives outside the model.

   Design goals:
   - Deterministic: same input yields same output.
   - Explainable: every failure is labeled and traceable to a rule.
   - Non-creative: the validator never edits or suggests replacements.



Classes
-------

.. autoapisummary::

   pipeworks_mud_mapper.services.description_validator.ValidationResult


Functions
---------

.. autoapisummary::

   pipeworks_mud_mapper.services.description_validator.load_validator_config
   pipeworks_mud_mapper.services.description_validator.validate_description


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

.. py:class:: ValidationResult

   Result of validating a room description.

   .. attribute:: valid

      True when no hard rule failures were detected.

      :type: :py:class:`bool`

   .. attribute:: hard_failures

      Named hard rule failures (non-negotiable in the validator).

      :type: :py:class:`list[str]`

   .. attribute:: soft_failures

      Advisory failures for future expansion (currently unused).

      :type: :py:class:`list[str]`

   .. attribute:: metrics

      Numeric metrics captured during validation (word counts, bounds).

      :type: :py:class:`dict`

   .. attribute:: rule_hits

      Tokens matched per rule, for UI staging visibility.

      :type: :py:class:`dict[str`, :py:class:`list[str]]`


.. py:function:: load_validator_config()

   Load validator rules from JSON config.

   Returns an empty dict on missing or invalid config to keep validation
   stable and non-failing in the UI path.


.. py:function:: validate_description(text, target_words)

   Validate a description against hard rules.

   :param text: Generated description text to validate.
   :type text: :py:class:`str`
   :param target_words: Target word count from the UI. Used to compute bounds.
   :type target_words: :py:class:`int`

   :returns: Structured results for UI display and persistence.
   :rtype: :py:class:`ValidationResult`