build_tools.syllable_analysis.random_sampler
============================================

.. py:module:: build_tools.syllable_analysis.random_sampler

.. autoapi-nested-parse::

   Random sampling utility for annotated syllables.

   This module provides functionality to randomly sample annotated syllables for inspection
   and quality assurance. It reads the output of the syllable feature annotator and generates
   a random sample in JSON format.

   This module has been refactored (Phase 2) to use common utilities from the
   analysis.common package, eliminating code duplication.

   Usage::

       # Sample 100 syllables (default)
       python -m build_tools.syllable_analysis.random_sampler

       # Sample specific number of syllables
       python -m build_tools.syllable_analysis.random_sampler --samples 50

       # Specify custom input/output paths
       python -m build_tools.syllable_analysis.random_sampler         --input data/annotated/syllables_annotated.json         --output _working/samples.json         --samples 200

       # Use a specific random seed for reproducibility
       python -m build_tools.syllable_analysis.random_sampler --samples 50 --seed 42



Functions
---------

.. autoapisummary::

   build_tools.syllable_analysis.random_sampler.sample_syllables
   build_tools.syllable_analysis.random_sampler.create_argument_parser
   build_tools.syllable_analysis.random_sampler.parse_arguments
   build_tools.syllable_analysis.random_sampler.main


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

.. py:function:: sample_syllables(records, sample_count, seed = None)

   Randomly sample syllables from the full corpus.

   :param records: List of annotated syllable records.
   :param sample_count: Number of samples to draw.
   :param seed: Optional random seed for reproducibility.

   :returns: List of sampled syllable records.

   :raises ValueError: If sample_count is larger than available records.


.. py:function:: create_argument_parser()

   Create and return the argument parser for random sampler.

   This function creates the ArgumentParser with all CLI options but does not
   parse arguments. This separation allows Sphinx documentation tools to
   introspect the parser and auto-generate CLI documentation.

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


.. py:function:: parse_arguments()

   Parse command-line arguments.

   :returns: Parsed argument namespace.


.. py:function:: main()

   Main entry point for random sampling.

   :returns: Exit code (0 for success, 1 for error).