build_tools.name_selector.name_class
====================================

.. py:module:: build_tools.name_selector.name_class

.. autoapi-nested-parse::

   Name class policy data models and YAML loading.

   This module defines the dataclasses for representing name class policies
   and provides functions to load them from YAML configuration files.

   The Name Class Matrix is externalized to data/name_classes.yml, separating
   policy configuration from code. This enables:
   - Non-programmers to tune name classes
   - Version control tracking of policy evolution
   - Multiple projects sharing the codebase with different policies

   Policy Structure
   ----------------
   Each name class defines:
   - description: Human-readable purpose
   - syllable_range: [min, max] syllables (inclusive)
   - features: Dict mapping feature names to policy values

   Policy values:
   - "preferred": Actively sought (+1 score)
   - "tolerated": Neutral (0 score)
   - "discouraged": Rejected or penalized

   Usage
   -----
   >>> from build_tools.name_selector.name_class import load_name_classes
   >>> policies = load_name_classes("data/name_classes.yml")
   >>> first_name_policy = policies["first_name"]
   >>> first_name_policy.description
   'Direct social address. Optimized for addressability and mouth-feel.'
   >>> first_name_policy.features["ends_with_vowel"]
   'preferred'



Attributes
----------

.. autoapisummary::

   build_tools.name_selector.name_class.PolicyValue
   build_tools.name_selector.name_class.FEATURE_NAMES


Classes
-------

.. autoapisummary::

   build_tools.name_selector.name_class.NameClassPolicy


Functions
---------

.. autoapisummary::

   build_tools.name_selector.name_class.load_name_classes
   build_tools.name_selector.name_class.get_default_policy_path


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

.. py:data:: PolicyValue

.. py:data:: FEATURE_NAMES

.. py:class:: NameClassPolicy

   Policy configuration for a single name class.

   Defines feature preferences for evaluating name candidates.
   Policies are loaded from YAML and remain immutable during evaluation.

   Attributes
   ----------
   name : str
       Identifier for this name class (e.g., "first_name", "place_name").

   description : str
       Human-readable description of the name class purpose.

   syllable_range : tuple[int, int]
       Allowed syllable count range [min, max], inclusive.

   features : dict[str, PolicyValue]
       Mapping of feature name to policy value ("preferred", "tolerated",
       "discouraged").

   Examples
   --------
   >>> policy = NameClassPolicy(
   ...     name="first_name",
   ...     description="Direct social address.",
   ...     syllable_range=(2, 3),
   ...     features={"ends_with_vowel": "preferred", "ends_with_stop": "discouraged"},
   ... )
   >>> policy.features["ends_with_vowel"]
   'preferred'


   .. py:attribute:: name
      :type:  str


   .. py:attribute:: description
      :type:  str


   .. py:attribute:: syllable_range
      :type:  tuple[int, int]


   .. py:attribute:: features
      :type:  dict[str, PolicyValue]


.. py:function:: load_name_classes(yaml_path)

   Load name class policies from a YAML file.

   Parameters
   ----------
   yaml_path : str | Path
       Path to the name_classes.yml file.

   Returns
   -------
   dict[str, NameClassPolicy]
       Dictionary mapping name class identifiers to their policies.

   Raises
   ------
   FileNotFoundError
       If the YAML file does not exist.
   ValueError
       If the YAML structure is invalid or policies fail validation.

   Examples
   --------
   >>> policies = load_name_classes("data/name_classes.yml")
   >>> "first_name" in policies
   True
   >>> policies["first_name"].syllable_range
   (2, 3)


.. py:function:: get_default_policy_path()

   Get the default path to name_classes.yml.

   Returns
   -------
   Path
       Path to data/name_classes.yml relative to project root.

   Notes
   -----
   This assumes the project structure has data/name_classes.yml at the root.