wordgen.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_orchestrator/wordgen.py
 
"""
Random word generator for session and plan names.
 
Purpose
-------
Produces readable random-word identifiers (e.g., ``sunny-weaving-honey``)
to replace timestamp-based defaults for sessions and plans.
 
Responsibilities
----------------
- Maintain three curated word lists (adjectives, gerunds, nouns)
- Generate kebab-case n-word identifiers via :func:`random_words`
- Produce unique names with collision avoidance via :func:`random_name`
- Generate numbered plan filenames via :func:`random_plan_filename`
 
Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 — module load lifecycle
    L3 — generation events (name produced, collisions retried)
    L4 — per-call word selection details
 
Contracts
---------
- :func:`random_words` returns ``list[str]`` of lowercase words
- :func:`random_name` returns a unique kebab-case string (no underscores)
- :func:`random_plan_filename` returns ``NNN-word-word-word.md``
- Word lists are module-level tuples; immutable after import
- No external dependencies required
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
"""
from __future__ import annotations
 
import random
from typing import Callable
 
from oc_diagnostics import _dbg
 
_ADJECTIVES: tuple[str, ...] = (
    "amber", "ancient", "azure", "bold", "bright", "broad", "calm", "clear",
    "cold", "cool", "crisp", "crystal", "curious", "dark", "deep", "distant",
    "dreamy", "drifting", "dusky", "electric", "emerald", "eternal", "fading",
    "fierce", "floating", "fluid", "fragrant", "free", "frosted", "frozen",
    "gentle", "gilded", "gleaming", "glowing", "golden", "graceful", "grand",
    "hidden", "hollow", "humble", "hushed", "icy", "idle", "indigo", "inner",
    "jade", "jovial", "keen", "kind", "light", "lonely", "lucid", "luminous",
    "mellow", "misty", "moonlit", "mossy", "muted", "mystic", "narrow",
    "nimble", "noble", "northern", "ocean", "open", "pale", "patient",
    "peaceful", "phantom", "quiet", "radiant", "rapid", "rare", "raw",
    "restless", "rising", "rosy", "rustic", "sacred", "scattered", "serene",
    "shimmering", "silent", "silver", "simple", "sleek", "slender", "slow",
    "smooth", "soft", "solar", "solemn", "solitary", "somber", "sparkling",
    "still", "stoic", "sturdy", "subtle", "summer", "sunlit", "sunny",
    "supple", "swift", "tender", "timeless", "twilight", "vast", "velvet",
    "verdant", "vibrant", "vivid", "wandering", "warm", "weathered", "wild",
    "windy", "wintry", "wise", "wooden", "woven", "young", "zephyr",
    "acorn", "breezy", "burnished", "canopy", "cedar", "cobalt", "coral",
    "crimson", "dawning", "dense", "dappled", "earthy", "enchanted",
    "fern", "floral", "foggy", "granite", "grassy", "harvest", "heather",
    "highland", "hazy", "ivory", "jasper", "lavender", "leafy", "linen",
    "lofty", "lunar", "maple", "marble", "meadow", "midnight", "mineral",
    "morning", "mosaic", "murky", "native", "nebula", "onyx", "opaque",
    "opaline", "orchid", "overcast", "pearlescent", "pebbled", "petal",
    "pine", "plains", "polished", "porous", "primal", "pristine", "quartz",
    "reedy", "regal", "remote", "rippling", "roaming", "rocky", "rugged",
    "sagebrush", "sandy", "sapphire", "saturated", "shadowed", "shallow",
    "shaded", "shifting", "shoreline", "silken", "skeletal", "sleepy",
    "sloped", "smoky", "snowy", "speckled", "spiral", "starlit", "steady",
    "steep", "stony", "stormy", "stranded", "stripped", "sunken", "sunward",
    "tapered", "temperate", "textured", "tidal", "timbered", "tinted",
    "towering", "tranquil", "tropical", "tundra", "turquoise", "twisted",
    "undulant", "uneven", "untamed", "upland", "veiled", "volcanic",
    "watery", "winding", "woolly", "worn", "wrapped", "amber", "ashen",
    "barren", "billowing", "bleached", "brackish", "braided", "breathless",
    "brine", "briny", "broken", "cascading", "ceaseless", "charcoal",
    "chill", "chiseled", "churning", "circling", "coppery", "crested",
    "crossing", "crunchy", "crystalline", "damp", "debris", "decayed",
    "dewed", "dim", "dormant", "dried", "dusty", "fading", "fallen",
    "fallow", "fertile", "filmy", "flinty", "flowing", "foamy", "forested",
    "fractured", "fragile", "glistening", "glittering", "gravel", "gray",
    "green", "grotto", "groundless", "gushing", "halcyon", "hammered",
    "highland", "hollow", "horizoned", "humid", "incandescent", "inky",
    "island", "knotted", "lakeward", "lapping", "latticed", "leaning",
    "limestone", "loamy", "lonesome", "loosened", "lowland", "luminant",
)
 
_GERUNDS: tuple[str, ...] = (
    "blooming", "blossoming", "bouncing", "breathing", "brewing", "bridging",
    "burning", "carving", "cascading", "casting", "chasing", "circling",
    "climbing", "coiling", "cooling", "crossing", "dancing", "drifting",
    "echoing", "falling", "fading", "floating", "flowing", "flying",
    "folding", "forging", "gathering", "gliding", "gleaming", "glowing",
    "growing", "guiding", "healing", "humming", "hunting", "journeying",
    "leaping", "learning", "lifting", "listening", "looping", "mapping",
    "melting", "mending", "merging", "mirroring", "moving", "murmuring",
    "opening", "pacing", "passing", "pausing", "peeling", "reaching",
    "reading", "resting", "returning", "rising", "roaming", "rolling",
    "rooting", "running", "sailing", "searching", "seeking", "shifting",
    "shining", "singing", "sinking", "sleeping", "sliding", "soaring",
    "sorting", "sparkling", "spinning", "spreading", "sprouting", "staying",
    "streaming", "stretching", "sweeping", "swelling", "swirling",
    "threading", "tumbling", "turning", "unfolding", "walking", "wandering",
    "watching", "weaving", "weaving", "whistling", "winding", "wondering",
    "working", "wrapping", "yielding", "arching", "awakening", "bending",
    "binding", "braiding", "branching", "breaking", "calming", "changing",
    "charting", "clearing", "collecting", "combining", "condensing",
    "connecting", "containing", "converging", "cooling", "covering",
    "cresting", "curling", "curving", "cutting", "deepening", "descending",
    "digging", "dimming", "dissolving", "diverging", "diving", "drawing",
    "edging", "emerging", "encircling", "ending", "eroding", "escaping",
    "etching", "expanding", "extending", "filtering", "finding", "finishing",
    "flashing", "flattening", "fleeing", "flickering", "flipping", "flooding",
    "flushing", "focusing", "following", "forming", "fracturing", "gathering",
    "grounding", "hanging", "hiding", "holding", "hovering", "illuminating",
    "intersecting", "intertwining", "isolating", "joining", "keeping",
    "kindling", "knotting", "landing", "launching", "layering", "leaving",
    "lining", "linking", "loosening", "lowering", "making", "marking",
    "meeting", "misting", "narrowing", "navigating", "nearing", "nesting",
    "noting", "nudging", "outlining", "overflowing", "overlapping",
    "parting", "peaking", "pooling", "pouring", "pressing", "pulling",
    "pushing", "radiating", "raising", "raking", "redirecting", "reflecting",
    "releasing", "remaining", "renewing", "repeating", "resolving",
    "retreating", "revealing", "rewinding", "rippling", "routing",
    "scattering", "sealing", "sending", "separating", "setting", "shaping",
    "sharing", "sheltering", "showing", "signaling", "skimming", "skipping",
    "smoothing", "spiraling", "stabilizing", "stacking", "starting",
    "steadying", "stepping", "stitching", "stopping", "submerging",
    "surfacing", "surrounding", "swaying", "tapping", "teaching", "testing",
    "tightening", "tilting", "tracing", "tracking", "trading", "trailing",
    "transforming", "traveling", "traversing", "trimming", "twisting",
    "uncovering", "unfolding", "unwinding", "upwelling", "vanishing",
    "varying", "venturing", "viewing", "waking", "warming", "weathering",
)
 
_NOUNS: tuple[str, ...] = (
    "amber", "anchor", "arc", "ash", "basin", "bay", "beacon", "bloom",
    "blossom", "bone", "branch", "bridge", "brook", "candle", "canyon",
    "cedar", "channel", "clay", "clearing", "cliff", "cloud", "coal",
    "coast", "comet", "compass", "coral", "crest", "current", "dawn",
    "delta", "den", "desert", "dew", "drift", "dune", "dust", "echo",
    "ember", "estuary", "fawn", "feather", "fern", "field", "fjord",
    "flame", "flint", "fog", "forest", "frost", "gale", "garden", "gate",
    "glade", "glacier", "gorge", "grain", "granite", "grove", "harbor",
    "haven", "hawk", "heath", "hill", "hollow", "honey", "horizon",
    "hue", "inlet", "island", "jade", "kelp", "lagoon", "lake", "lantern",
    "lark", "laurel", "leaf", "ledge", "lighthouse", "loch", "log",
    "marsh", "meadow", "mesa", "mist", "moon", "moonbeam", "moss",
    "mountain", "mud", "nest", "night", "oak", "ocean", "orbit", "otter",
    "passage", "path", "peat", "pebble", "peak", "pine", "plain", "pool",
    "prairie", "quartz", "rain", "rapids", "ravine", "reef", "ridge",
    "rift", "ripple", "river", "rock", "root", "rose", "ruin", "salt",
    "sand", "sandbar", "sea", "sedge", "sediment", "shadow", "shale",
    "shelf", "shore", "shrub", "sierra", "signal", "sky", "slate",
    "snow", "soil", "spring", "star", "starlight", "steppe", "stone",
    "storm", "strand", "stream", "summit", "swamp", "swift", "thorn",
    "tide", "timber", "tundra", "vale", "valley", "vapor", "vine",
    "volcano", "wave", "wetland", "willow", "wind", "woodland", "wraith",
    "acorn", "algae", "alder", "alluvium", "anemone", "antler", "aster",
    "aurora", "bark", "bedrock", "birch", "blight", "bluff", "bog",
    "boulder", "bract", "brine", "burrow", "butte", "cairn", "canopy",
    "cape", "carve", "cascade", "cave", "chamomile", "chasm", "cirque",
    "cobble", "copse", "cove", "crater", "crag", "creek", "crevice",
    "crust", "culm", "cyme", "dale", "datum", "debris", "declivity",
    "depths", "dewdrop", "divide", "downdraft", "downpour", "dragonfly",
    "eddy", "elevation", "elm", "erosion", "escarpment", "esteem",
    "expanse", "faultline", "fen", "fernbed", "fissure", "flare",
    "floodplain", "flume", "foliage", "foothill", "ford", "geyser",
    "gust", "habitat", "halo", "hardwood", "headland", "heartwood",
    "helix", "heron", "hillside", "hoarfrost", "hotspring", "humus",
    "hurricane", "hydra", "icefall", "icefield", "ignite", "impasse",
    "inlet", "iris", "ironwood", "isthmus", "jetty", "juniper", "karst",
    "kettle", "kindling", "knoll", "lichen", "lignite", "limb", "linden",
    "lithosphere", "loam", "loess", "lumen", "lupine", "mantle",
    "manzanita", "marl", "massif", "millstone", "moraine", "morass",
    "mudflat", "mulch", "mussel", "narrows", "nocturne", "nodule",
    "nutrient", "obsidian", "olivine", "onyx", "opal", "outcrop",
    "overhang", "oxbow", "oyster", "parcel", "pasture", "penumbra",
    "permafrost", "pillar", "pinnacle", "plateau", "plover", "plume",
    "polarity", "pollen", "pond", "poplar", "pumice", "reedbed",
    "remnant", "resin", "rill", "rivulet", "rockfall", "runoff",
    "rushes", "sandstone", "sapwood", "savanna", "scarp", "schist",
    "scree", "seabed", "seam", "seawall", "sedge", "seep", "shingle",
    "silhouette", "silt", "sinew", "skyline", "slough", "snowdrift",
    "snowfield", "softwood", "solstice", "spillway", "spruce", "spur",
    "starling", "strata", "subsoil", "sundew", "tableland", "talus",
    "tamarack", "tangent", "tendril", "terrace", "thicket", "thornbush",
    "thunderhead", "topsoil", "torrent", "treeline", "tributary",
    "turf", "twilight", "understory", "upland", "uplift", "vestige",
    "vista", "vortex", "watershed", "weathervane", "wetgrass",
    "windbreak", "windfall", "windrow", "winterkill", "wren", "yew",
)
 
 
def random_words(n: int = 3) -> list[str]:
    """Return n random words from the internal word lists.
 
    For n=3 draws one adjective, one gerund, one noun (in order).
    For other n, samples from the combined pool without replacement.
    """
    func = "random_words"
    if n == 3:
        words = [
            random.choice(_ADJECTIVES),
            random.choice(_GERUNDS),
            random.choice(_NOUNS),
        ]
    else:
        pool = list(_ADJECTIVES + _GERUNDS + _NOUNS)
        words = random.sample(pool, min(n, len(pool)))
    _dbg("OC_CHAT.MAIN", func, f"selected {words}", 4)
    return words
 
 
def random_name(
    exists_fn: Callable[[str], bool] | None = None,
    n: int = 3,
    max_attempts: int = 5,
) -> str:
    """Generate a unique kebab-case random name.
 
    Retries on collision (via exists_fn) up to max_attempts times.
    Falls back to appending a 4-digit suffix if all attempts collide.
 
    Args:
        exists_fn: Optional callable; returns True if name already taken.
        n: Number of words in the name.
        max_attempts: Maximum retries before falling back to suffix.
 
    Returns:
        Kebab-case string such as ``sunny-weaving-honey``.
    """
    func = "random_name"
    for attempt in range(max_attempts):
        name = "-".join(random_words(n))
        if exists_fn is None or not exists_fn(name):
            _dbg("OC_CHAT.MAIN", func, f"generated {name!r} (attempt {attempt + 1})", 3)
            return name
        _dbg("OC_CHAT.MAIN", func, f"collision on {name!r}, retrying", 3)
 
    # All attempts collided — append a 4-digit suffix
    name = f"{'-'.join(random_words(n))}-{random.randint(1000, 9999)}"
    _dbg("OC_CHAT.MAIN", func, f"fallback to suffixed {name!r}", 3)
    return name
 
 
def random_plan_filename(prefix_number: int, n: int = 3) -> str:
    """Generate a numbered plan filename with random-word tail.
 
    Format: ``NNN-word-word-word.md`` (zero-padded 3-digit prefix).
    Example: ``007-sunny-weaving-honey.md``
 
    Args:
        prefix_number: Numeric prefix (0–999).
        n: Number of random words in the tail.
 
    Returns:
        Filename string including the ``.md`` extension.
    """
    func = "random_plan_filename"
    tail = "-".join(random_words(n))
    filename = f"{prefix_number:03d}-{tail}.md"
    _dbg("OC_CHAT.MAIN", func, f"generated {filename!r}", 3)
    return filename