pipeworks_name_generation.generator
===================================

.. py:module:: pipeworks_name_generation.generator

.. autoapi-nested-parse::

   Core name generation - minimal proof of concept version.

   This is the SIMPLEST possible implementation that passes tests.
   Features to add later:
   - Pattern loading from YAML files
   - Phonotactic constraints
   - Custom pattern sets
   - Performance optimization

   For now: Hardcoded syllables, basic logic.



Classes
-------

.. autoapisummary::

   pipeworks_name_generation.generator.NameGenerator


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

.. py:class:: NameGenerator(pattern)

   Generate phonetically-plausible names deterministically.

   This is a minimal proof-of-concept implementation with hardcoded
   syllables. Pattern loading and advanced features will be added later.

   The key requirement is DETERMINISM: same seed = same name, always.
   This is critical for games where entity IDs must map to consistent names.

   :param pattern: Pattern set name (currently only "simple" is supported)

   :raises ValueError: If pattern is not recognized

   .. admonition:: Example

      >>> gen = NameGenerator(pattern="simple")
      >>> name = gen.generate(seed=42)
      >>> assert gen.generate(seed=42) == name  # Deterministic!

   Initialize generator with a pattern set.

   :param pattern: Pattern set name (only "simple" supported in POC)

   :raises ValueError: If pattern is not recognized


   .. py:attribute:: pattern


   .. py:method:: generate(seed, syllables = None)

      Generate a single name deterministically.

      This is the core method. Given the same seed, it MUST produce
      the same name every time. This determinism is critical for games.

      :param seed: Random seed for deterministic generation.
                   Same seed = same name, always.
      :param syllables: Number of syllables to use (defaults to random 2-3).
                        Must be between 1 and len(available syllables).

      :returns: Generated name string, capitalized (e.g., "Kalathin")

      :raises ValueError: If syllable count is invalid

      .. admonition:: Example

         >>> gen = NameGenerator(pattern="simple")
         >>> gen.generate(seed=1)
         'Marindel'
         >>> gen.generate(seed=1)  # Same seed
         'Marindel'  # Same name!
         >>> gen.generate(seed=2)  # Different seed
         'Soravyn'  # Different name



   .. py:method:: generate_batch(count, base_seed, unique = True)

      Generate multiple names at once.

      This is useful for bulk generation (e.g., populating a town with NPCs).

      :param count: Number of names to generate
      :param base_seed: Starting seed (incremented for each name)
      :param unique: If True, ensure all names are different

      :returns: List of generated names

      :raises ValueError: If unable to generate enough unique names

      .. admonition:: Example

         >>> gen = NameGenerator(pattern="simple")
         >>> names = gen.generate_batch(count=3, base_seed=100)
         >>> len(names)
         3
         >>> names == gen.generate_batch(count=3, base_seed=100)
         True  # Deterministic!