build_tools.syllable_walk.profiles
==================================

.. py:module:: build_tools.syllable_walk.profiles

.. autoapi-nested-parse::

   Walk profile definitions for syllable walker.

   This module defines WalkProfile dataclass and predefined profiles that
   encode different walking behaviors (conservative, balanced, chaotic, etc.).

   Profiles provide convenient presets for common use cases:
   - Clerical: Conservative, favors common syllables
   - Dialect: Balanced exploration, neutral frequency
   - Goblin: Chaotic, favors rare syllables
   - Ritual: Maximum exploration, strongly favors rare

   .. admonition:: Example

      >>> from build_tools.syllable_walk.profiles import WALK_PROFILES
      >>> profile = WALK_PROFILES["goblin"]
      >>> profile.temperature
      1.5



Attributes
----------

.. autoapisummary::

   build_tools.syllable_walk.profiles.WALK_PROFILES


Classes
-------

.. autoapisummary::

   build_tools.syllable_walk.profiles.WalkProfile


Functions
---------

.. autoapisummary::

   build_tools.syllable_walk.profiles.get_profile
   build_tools.syllable_walk.profiles.list_profiles


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

.. py:class:: WalkProfile

   Configuration profile for a syllable walk.

   A profile encapsulates all parameters needed for a walk, providing
   named presets for different behaviors.

   .. attribute:: name

      Human-readable profile name (e.g., "Dialect Walk")

   .. attribute:: description

      Brief description of profile behavior

   .. attribute:: max_flips

      Maximum feature flips allowed per step (1-3)

   .. attribute:: temperature

      Exploration temperature (0.1-5.0)

   .. attribute:: frequency_weight

      Frequency bias (-2.0 to 2.0)

   .. admonition:: Example

      >>> profile = WalkProfile(
      ...     name="Custom Walk",
      ...     description="High temperature, neutral frequency",
      ...     max_flips=2,
      ...     temperature=2.0,
      ...     frequency_weight=0.0
      ... )
      >>> print(profile)
      Custom Walk: High temperature, neutral frequency


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


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


   .. py:attribute:: max_flips
      :type:  int


   .. py:attribute:: temperature
      :type:  float


   .. py:attribute:: frequency_weight
      :type:  float


.. py:data:: WALK_PROFILES
   :type:  Dict[str, WalkProfile]

.. py:function:: get_profile(name)

   Get a walk profile by name.

   :param name: Profile name (case-insensitive)

   :returns: WalkProfile object

   :raises ValueError: If profile name not found

   .. admonition:: Example

      >>> profile = get_profile("goblin")
      >>> profile.temperature
      1.5
      >>> profile = get_profile("GOBLIN")  # Case-insensitive
      >>> profile.temperature
      1.5


.. py:function:: list_profiles()

   Get all available walk profiles.

   :returns: Dictionary mapping profile names to WalkProfile objects (copy)

   .. admonition:: Example

      >>> profiles = list_profiles()
      >>> for name, profile in profiles.items():
      ...     print(f"{name}: {profile.description}")
      clerical: Conservative, favors common syllables, minimal phonetic change
      dialect: Moderate exploration, neutral frequency bias
      goblin: Chaotic, favors rare syllables, high phonetic variation
      ritual: Maximum exploration, strongly favors rare syllables