build_tools.syllable_walk_tui.services.combiner_runner
======================================================

.. py:module:: build_tools.syllable_walk_tui.services.combiner_runner

.. autoapi-nested-parse::

   Name combiner execution service.

   Mirrors the CLI behavior of build_tools.name_combiner.



Classes
-------

.. autoapisummary::

   build_tools.syllable_walk_tui.services.combiner_runner.CombinerResult


Functions
---------

.. autoapisummary::

   build_tools.syllable_walk_tui.services.combiner_runner.run_combiner


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

.. py:class:: CombinerResult

   Result from combiner execution.


   .. py:attribute:: candidates
      :type:  list[dict]


   .. py:attribute:: output_path
      :type:  pathlib.Path


   .. py:attribute:: meta_output
      :type:  dict


   .. py:attribute:: error
      :type:  str | None
      :value: None



.. py:function:: run_combiner(patch, combiner_state)

   Run name_combiner for a patch (mirrors CLI behavior exactly).

   This function mirrors the CLI:
       python -m build_tools.name_combiner \
           --run-dir <patch.corpus_dir> \
           --syllables <syllables> \
           --count <count> \
           --seed <seed> \
           --frequency-weight <frequency_weight>

   Output is written to: <run-dir>/candidates/{prefix}_candidates_{N}syl.json

   TUI Extension:
       When combiner_state.syllable_mode == "all", this function also:
       - Generates candidates for 2, 3, and 4 syllables
       - Writes per-length files: {prefix}_candidates_2syl.json, etc.
       - Writes a combined file: {prefix}_candidates_all.json
       - Returns combined candidates in the result

   :param patch: PatchState with corpus data
   :param combiner_state: CombinerState with generation parameters

   :returns: CombinerResult with generated candidates and metadata

   .. note:: Caller is responsible for validating patch state before calling.