wordsmith-engine 0.3.0

Composable, deterministic-friendly text-generation components for Python.

The Wordsmith Engine

The Wordsmith Engine is a composable, deterministic-friendly text-generation toolkit for Python. It started as a port of the Swift package Wordsmith (by the same author) and focuses on building rich, varied text with small, reusable components.

What it is for

• Generating names for people, towns, ships, gangs, literary works, movies, albums, and fictional materials.
• Building simple language generators from reusable parts.
• Producing repeatable output with a seeded RNG.

Installation

Install the package from PyPI:

pip install wordsmith-engine

Use PDM to install dependencies for development:

pdm install --group dev

Quickstart

from wordsmith import LiteraryTitle

print(LiteraryTitle()())

Core concepts

The Wordsmith Engine is centered around the Component type. Each component can render text with a provided random number generator.

Operator DSL (preferred):

• left | right: Join components with a space.
• left + right: Join components with no separator (useful for punctuation).

Key combinators:

• text(*parts, sep=""): Join components with a custom separator.
• one_of(*options): Pick a random option.
• weighted_one_of((weight, option), ...): Weighted choice across many options.
• either(a, b, first_probability=0.5): Weighted choice between two options.
• maybe(*parts, probability=0.5): Optionally include text.

Common decorators on components:

• .title_case() for title casing (with small-word rules).
• .capitalized() to capitalize all words.
• .first_upper() for first-letter capitalization.
• .prefixed_by_article() / .prefixed_by_determiner() for grammar helpers.
• .possessive_form() for possessives.

Usage examples

import random

from wordsmith import Adjective, AlbumTitle, LiteraryTitle, Noun, one_of, maybe

rng = random.Random(42)

title = (
    "The"
    | maybe(Adjective())
    | one_of("Journey", "Voyage", "Chronicles")
    | "of"
    | Noun().prefixed_by_article()
).title_case()

line = ("Once" | maybe("upon a time", probability=0.5)) + "."

print(title(rng))
print(line(rng))
print(LiteraryTitle()(rng))
print(AlbumTitle()(rng))

Generators included

The Wordsmith Engine ships with a growing set of generators:

• Names: GivenName, Surname, PersonName, AlienName, AncientGivenName, FantasyName
  • GivenName supports gender and cultural grouping with BinaryGender and GivenNameCulture.
• Locations: TownName
• Groups: CriminalGangName, BandName
• Vessels: NauticalShipName
• Literary titles: SimpleLiteraryTitle, UnusualLiteraryTitle, LiteraryTitle
• Movie titles: SimpleMovieTitle, HighConceptMovieTitle, MovieTitle
• Album titles: AlbumTitle
• Materials: FictionalElementName, FictionalMineralName, ChemicalCompoundName
  • ChemicalCompoundName samples real compound names; the element and mineral generators produce fictional names.
• Specials: ReadableUniqueIdentifier, ExoticCharacter

Deterministic output

All components accept a random.Random instance. If you want repeatable results, pass a seeded RNG.

import random
from wordsmith import LiteraryTitle

rng = random.Random(1234)
print(LiteraryTitle()(rng))
print(LiteraryTitle()(rng))

Examples

Run any script under examples/ with PDM, for example:

pdm run python examples/character_names.py
pdm run python examples/fictional_materials.py
pdm run python examples/literary_titles.py
pdm run python examples/movie_titles.py
pdm run python examples/album_titles.py

Project docs

Repo-local architecture, asset, and quality notes live in docs/.

Development

• Install: pdm install --group dev
• Run tests: pdm run pytest
• Run lint: pdm run lint
• Build: pdm build