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

.. py:module:: build_tools.syllable_walk.db

.. autoapi-nested-parse::

   SQLite database access layer for the syllable walker web interface.

   This module provides functions to query the corpus.db SQLite database
   for syllable data, avoiding the need to load large JSON files into memory.

   The database schema stores syllables with their 12 phonetic features and
   frequency counts, with indexes optimized for common query patterns.

   Functions:
       load_syllables_from_sqlite: Load all syllables with features
       get_syllable_count: Get total syllable count
       syllable_exists: Check if a syllable exists
       get_random_syllable: Get a random syllable



Attributes
----------

.. autoapisummary::

   build_tools.syllable_walk.db.FEATURE_COLUMNS


Functions
---------

.. autoapisummary::

   build_tools.syllable_walk.db.load_syllables_from_sqlite
   build_tools.syllable_walk.db.get_syllable_count
   build_tools.syllable_walk.db.syllable_exists
   build_tools.syllable_walk.db.get_syllable_data
   build_tools.syllable_walk.db.get_random_syllable
   build_tools.syllable_walk.db.load_syllables_from_json
   build_tools.syllable_walk.db.load_syllables


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

.. py:data:: FEATURE_COLUMNS
   :value: ['starts_with_vowel', 'starts_with_cluster', 'starts_with_heavy_cluster', 'contains_plosive',...


.. py:function:: load_syllables_from_sqlite(db_path)

   Load all syllables with features from the database.

   This is the primary data loading function for the web interface.
   Returns data in the same format as the annotated JSON files.

   :param db_path: Path to corpus.db

   :returns: List of dicts with 'syllable', 'frequency', and 'features' keys

   .. admonition:: Example

      >>> syllables = load_syllables_from_sqlite(Path("corpus.db"))
      >>> syllables[0]
      {'syllable': 'ab', 'frequency': 1, 'features': {'starts_with_vowel': True, ...}}


.. py:function:: get_syllable_count(db_path)

   Get the total number of syllables in the database.

   :param db_path: Path to corpus.db

   :returns: Total syllable count


.. py:function:: syllable_exists(db_path, syllable)

   Check if a syllable exists in the database.

   :param db_path: Path to corpus.db
   :param syllable: Syllable to check

   :returns: True if syllable exists, False otherwise


.. py:function:: get_syllable_data(db_path, syllable)

   Get data for a specific syllable.

   :param db_path: Path to corpus.db
   :param syllable: Syllable to look up

   :returns: Dict with syllable data, or None if not found


.. py:function:: get_random_syllable(db_path, seed = None)

   Get a random syllable from the database.

   Uses frequency-weighted random selection if seed is provided for
   reproducibility.

   :param db_path: Path to corpus.db
   :param seed: Optional random seed for reproducibility

   :returns: Random syllable string


.. py:function:: load_syllables_from_json(json_path)

   Load syllables from annotated JSON file (fallback when no DB).

   :param json_path: Path to *_syllables_annotated.json

   :returns: List of dicts with syllable data


.. py:function:: load_syllables(db_path = None, json_path = None)

   Load syllables from database or JSON, with automatic fallback.

   Prefers SQLite database for performance, falls back to JSON if
   database is not available.

   :param db_path: Path to corpus.db (optional)
   :param json_path: Path to annotated JSON (optional)

   :returns: Tuple of (syllables list, source description)

   :raises ValueError: If neither db_path nor json_path is valid