Name generation system

A flexible name generation toolkit creates human-readable identifiers for agents, remotes, hives, and passphrases.

Overview

The name generation system is implemented in libid/name/ using the libname namespace. It provides:

• WordSource interface - Abstraction for word providers
• NamePattern class - Combines words using different joining styles
• NameGenerator toolkit - Main API for building name generators
• Domain-specific generators - Pre-built generators for agents and remotes

Architecture

libid/name/
├── WordSource.hpp          # Interface for word providers
├── ResourceWordSource.hpp  # Loads words from Qt resources
├── CustomWordSource.hpp    # User-provided word lists
├── NamePattern.hpp         # Pattern building and generation
├── NameGenerator.hpp       # Main toolkit API
├── SyllableNameGenerator.hpp  # Base syllabic name generator
├── AgentNameGenerator.hpp  # Agent-specific names (e.g., "Lunara")
└── RemoteNameGenerator.hpp # Remote-specific names (e.g., "Azure Fox")

Design Principles

Toolkit, Not Repository

libname is a toolkit that provides building blocks. Domain-specific naming logic belongs to the consuming code, not to libname. This ensures:

1. Naming stability - Agent names won't change if wordlists are updated
2. Consumer ownership - Each domain controls its naming patterns
3. Flexibility - Consumers can use built-in or custom word sources

Ownership Rules

Pattern Types

The NamePattern::Type enum defines how words are joined:

Built-in Wordlists

The following wordlists are available as Qt resources:

Usage Examples

Using Built-in Generators

#include "name/AgentNameGenerator.hpp"
#include "name/RemoteNameGenerator.hpp"

// Generate agent name (syllabic pattern)
libname::AgentNameGenerator agentGen;
QString agentName = agentGen.generate();  // e.g., "Lunara"

// Generate remote name (adjective + noun pattern)
libname::RemoteNameGenerator remoteGen;
QString remoteName = remoteGen.generate();  // e.g., "Azure Fox"

Using the Toolkit Directly

#include "name/NameGenerator.hpp"

libname::NameGenerator gen;

// Create custom pattern for hive names
auto pattern = gen.pattern(libname::NamePattern::Type::Spaced)
    .addSource(gen.wordSource("adjectives"))
    .addSource(gen.wordSource("habitats"))
    .capitalize(true, false);

QString hiveName = pattern.generate();  // e.g., "Cozy Burrow"

Custom Word Sources

libname::NameGenerator gen;

// Use custom words instead of built-in lists
QStringList techWords = {"quantum", "neural", "cyber"};
auto techSource = libname::NameGenerator::fromList(techWords, "tech");

auto pattern = gen.pattern(libname::NamePattern::Type::Hyphenated)
    .addSource(techSource)
    .addSource(gen.wordSource("animals"))
    .capitalize(false);

QString name = pattern.generate();  // e.g., "quantum-fox"

Passphrase Generation

libname::NameGenerator gen;

// Generate 4-word passphrase with spaces
QString pass = gen.passphrase(4);  // e.g., "correct horse battery staple"

// Generate 3-word passphrase with hyphens
QString pass2 = gen.passphrase(3, "-");  // e.g., "apple-banana-cherry"

Syllabic Word Generation

libname::NameGenerator gen;

// Generate syllabic word with custom syllable sources
QString word = gen.syllabicWord(
    gen.wordSource("syllable_prefix"),
    gen.wordSource("syllable_stem"),
    gen.wordSource("syllable_suffix"),
    true  // capitalize
);  // e.g., "Lunara"

Test Coverage

Related Documentation

• Hive System: See hive-encryption documentation
• Identity Management: See libid documentation
• Delivery System: See libpair/delivery documentation