build_tools.name_combiner.cli
=============================

.. py:module:: build_tools.name_combiner.cli

.. autoapi-nested-parse::

   Command-line interface for the name combiner.

   This module provides the CLI for generating name candidates from an
   annotated syllable corpus. It follows the project's CLI documentation
   standards with sphinx-argparse compatible argument parser.

   Usage
   -----
   Generate 2-syllable candidates::

       python -m build_tools.name_combiner \
           --run-dir _working/output/20260110_115453_pyphen/ \
           --syllables 2 \
           --count 10000 \
           --seed 42

   Generate 3-syllable candidates with uniform sampling::

       python -m build_tools.name_combiner \
           --run-dir _working/output/20260110_115453_pyphen/ \
           --syllables 3 \
           --count 5000 \
           --frequency-weight 0.0



Functions
---------

.. autoapisummary::

   build_tools.name_combiner.cli.create_argument_parser
   build_tools.name_combiner.cli.parse_arguments
   build_tools.name_combiner.cli.discover_annotated_json
   build_tools.name_combiner.cli.main


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

.. py:function:: create_argument_parser()

   Create and return the argument parser for the name combiner.

   Returns
   -------
   argparse.ArgumentParser
       Configured ArgumentParser ready to parse command-line arguments.

   Notes
   -----
   This function follows the project's CLI documentation standards,
   enabling sphinx-argparse to auto-generate documentation.


.. py:function:: parse_arguments(args = None)

   Parse command-line arguments.

   Parameters
   ----------
   args : list[str] | None, optional
       Arguments to parse. If None, uses sys.argv.

   Returns
   -------
   argparse.Namespace
       Parsed arguments.


.. py:function:: discover_annotated_json(run_dir)

   Discover the annotated JSON file in a run directory.

   Parameters
   ----------
   run_dir : Path
       Path to extraction run directory.

   Returns
   -------
   tuple[Path, str]
       (path_to_annotated_json, prefix) where prefix is 'pyphen' or 'nltk'.

   Raises
   ------
   FileNotFoundError
       If no annotated JSON is found.
   ValueError
       If run directory structure is unexpected.


.. py:function:: main(args = None)

   Main entry point for the name combiner CLI.

   Parameters
   ----------
   args : list[str] | None, optional
       Command-line arguments. If None, uses sys.argv.

   Returns
   -------
   int
       Exit code (0 for success, non-zero for error).