pipeworks_name_generation.generator

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

NameGenerator

Generate phonetically-plausible names deterministically.

Module Contents

class pipeworks_name_generation.generator.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.

Parameters:

pattern (str) – Pattern set name (currently only “simple” is supported)

Raises:

ValueError – If pattern is not recognized

Example

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

Initialize generator with a pattern set.

Parameters:

pattern (str) – Pattern set name (only “simple” supported in POC)

Raises:

ValueError – If pattern is not recognized

pattern

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.

Parameters:

• seed (int) – Random seed for deterministic generation. Same seed = same name, always.

• syllables (int | None) – 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

Return type:

str

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

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).

Parameters:

• count (int) – Number of names to generate

• base_seed (int) – Starting seed (incremented for each name)

• unique (bool) – If True, ensure all names are different

Returns:

List of generated names

Raises:

ValueError – If unable to generate enough unique names

Return type:

list[str]

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!