build_tools.name_selector.name_class

Name class policy data models and YAML loading.

This module defines the dataclasses for representing name class policies and provides functions to load them from YAML configuration files.

The Name Class Matrix is externalized to data/name_classes.yml, separating policy configuration from code. This enables: - Non-programmers to tune name classes - Version control tracking of policy evolution - Multiple projects sharing the codebase with different policies

Policy Structure

Each name class defines: - description: Human-readable purpose - syllable_range: [min, max] syllables (inclusive) - features: Dict mapping feature names to policy values

Policy values: - “preferred”: Actively sought (+1 score) - “tolerated”: Neutral (0 score) - “discouraged”: Rejected or penalized

Usage

>>> from build_tools.name_selector.name_class import load_name_classes
>>> policies = load_name_classes("data/name_classes.yml")
>>> first_name_policy = policies["first_name"]
>>> first_name_policy.description
'Direct social address. Optimized for addressability and mouth-feel.'
>>> first_name_policy.features["ends_with_vowel"]
'preferred'

Attributes

`PolicyValue`
`FEATURE_NAMES`

Classes

NameClassPolicy

Policy configuration for a single name class.

Functions

`load_name_classes`(yaml_path)	Load name class policies from a YAML file.
`get_default_policy_path`()	Get the default path to name_classes.yml.

Module Contents

build_tools.name_selector.name_class.PolicyValue

build_tools.name_selector.name_class.FEATURE_NAMES

class build_tools.name_selector.name_class.NameClassPolicy[source]

Policy configuration for a single name class.

Defines feature preferences for evaluating name candidates. Policies are loaded from YAML and remain immutable during evaluation.

Attributes

namestr: Identifier for this name class (e.g., “first_name”, “place_name”).
descriptionstr: Human-readable description of the name class purpose.
syllable_rangetuple[int, int]: Allowed syllable count range [min, max], inclusive.
featuresdict[str, PolicyValue]: Mapping of feature name to policy value (“preferred”, “tolerated”, “discouraged”).

Examples

>>> policy = NameClassPolicy(
...     name="first_name",
...     description="Direct social address.",
...     syllable_range=(2, 3),
...     features={"ends_with_vowel": "preferred", "ends_with_stop": "discouraged"},
... )
>>> policy.features["ends_with_vowel"]
'preferred'

name: str

description: str

syllable_range: tuple[int, int]

features: dict[str, PolicyValue]

build_tools.name_selector.name_class.load_name_classes(yaml_path)[source]

Load name class policies from a YAML file.

Parameters

yaml_pathstr | Path: Path to the name_classes.yml file.

Returns

dict[str, NameClassPolicy]: Dictionary mapping name class identifiers to their policies.

Raises

FileNotFoundError: If the YAML file does not exist.
ValueError: If the YAML structure is invalid or policies fail validation.

Examples

>>> policies = load_name_classes("data/name_classes.yml")
>>> "first_name" in policies
True
>>> policies["first_name"].syllable_range
(2, 3)

build_tools.name_selector.name_class.get_default_policy_path()[source]

Get the default path to name_classes.yml.

Returns

Path: Path to data/name_classes.yml relative to project root.

Notes

This assumes the project structure has data/name_classes.yml at the root.