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

.. py:module:: build_tools.syllable_walk

.. autoapi-nested-parse::

   Syllable Walker - Phonetic Feature Space Exploration

   The syllable walker is a phonetic exploration tool that generates sequences of syllables by "walking" through
   phonetic feature space using cost-based random selection. It enables corpus analysis, pattern discovery, and
   exploration of phonetic relationships. This is a **build-time analysis tool only** - not used during runtime
   name generation.

   The walker explores syllable datasets by moving probabilistically from one syllable to phonetically
   similar syllables. Each step considers:

   - **Phonetic distance** - How many features change (Hamming distance)
   - **Frequency bias** - Preference for common vs rare syllables
   - **Temperature** - Amount of randomness in selection
   - **Inertia** - Tendency to stay at current syllable

   Key Features:

   - Four pre-configured profiles (clerical, dialect, goblin, ritual)
   - Custom parameter control for fine-tuned exploration
   - Deterministic walks (same seed = same walk, reproducible)
   - Interactive web interface for browser-based exploration
   - Batch processing to generate thousands of walks for analysis
   - Fast operation (<10ms per walk after initialization)
   - Large corpus support (efficiently handles 500k+ syllables)

   Main Components:

   - SyllableWalker: Core walking algorithm with efficient neighbor graph
   - WalkProfile: Configuration preset for different walking behaviors
   - WALK_PROFILES: Predefined profiles (clerical, dialect, goblin, ritual)

   Usage:
       >>> from build_tools.syllable_walk import SyllableWalker
       >>>
       >>> # Load annotated syllables
       >>> walker = SyllableWalker("data/annotated/syllables_annotated.json")
       >>>
       >>> # Walk using a profile
       >>> walk = walker.walk_from_profile(
       ...     start="ka",
       ...     profile="dialect",
       ...     steps=5,
       ...     seed=42
       ... )
       >>>
       >>> # Display walk sequence
       >>> print(" → ".join(s["syllable"] for s in walk))
       ka → ki → ti → ta → da → de

   CLI Usage:

       .. code-block:: bash

          # Walk with a profile
          python -m build_tools.syllable_walk data.json --start ka --profile dialect --steps 5

          # Launch interactive web interface
          python -m build_tools.syllable_walk data.json --web --port 8080

          # Batch walks for analysis
          python -m build_tools.syllable_walk data.json --batch 100 --profile ritual



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/build_tools/syllable_walk/cli/index
   /autoapi/build_tools/syllable_walk/profiles/index
   /autoapi/build_tools/syllable_walk/server/index
   /autoapi/build_tools/syllable_walk/walker/index
   /autoapi/build_tools/syllable_walk/web_assets/index