agent_namer.py

import random
from typing import ClassVar, List


class AgentNameGenerator:
    """Generate random, friendly names for persistent agents."""

    _FIRST_PARTS: ClassVar[List[str]] = [
        # Popular SSA & UK top names
        "Liam", "Noah", "Oliver", "Theodore", "James", "Henry", "Mateo",
        "Elijah", "Lucas", "William", "Benjamin", "Michael", "Daniel",
        "Logan", "Jackson", "Sebastian", "Aiden", "Alexander", "Jacob",
        "Ryan", "Nathan", "Samuel", "David", "Joseph", "John", "Isaiah",
        "Julian", "Anthony", "Wyatt", "Hudson", "Jack", "Grayson", "Levi",
        "Dylan", "Mohammad", "Frankie", "Otis", "Caleb", "Felix", "Kai",
        "Archie", "Teddy", "Leo", "Harley", "Arthur", "Oscar", "Finn",
        "Freddie", "Hugo", "Albie", "Olivia", "Amelia", "Isla", "Ava",
        "Charlotte", "Sophia", "Mia", "Evelyn", "Harper", "Luna", "Camila",
        "Isabella", "Aria", "Scarlett", "Penelope", "Chloe", "Layla",
        "Eleanor", "Hannah", "Lillian", "Zoe", "Stella", "Hazel", "Aurora",
        "Violet", "Nora", "Grace", "Lily", "Mila", "Poppy", "Freya", "Ruby",

        # Additional common names
        "Aaron", "Adam", "Adrian", "Alan", "Albert", "Alex", "Alfred",
        "Andrew", "Arthur", "Austin", "Barry", "Bernard", "Billy",
        "Bradley", "Brandon", "Brian", "Bruce", "Carl", "Carlos", "Charles",
        "Christian", "Christopher", "Clarence", "Clifford", "Cody", "Craig",
        "Dale", "Danny", "Darren", "Dennis", "Derek", "Donald", "Douglas",
        "Duane", "Dustin", "Dwayne", "Dwight", "Earl", "Edgar", "Edmund",
        "Edward", "Edwin", "Elias", "Eric", "Ernest", "Eugene", "Evan",
        "Floyd", "Francis", "Frederick", "Gabriel", "Gary", "Gene", "George",
        "Gerald", "Gilbert", "Glen", "Gordon", "Gregory", "Harold",
        "Harry", "Harvey", "Hector", "Howard", "Ian", "Isaac", "Ivan",
        "Jared", "Jason", "Javier", "Jay", "Jeffery", "Jeffrey", "Jeremy",
        "Jerome", "Jerry", "Jesse", "Jesus", "Jim", "Jimmy", "Joe", "Joel",
        "Joey", "Jonathan", "Jordan", "Jose", "Joshua", "Juan", "Justin",
        "Keith", "Kelly", "Kenneth", "Kent", "Kevin", "Kurt", "Kyle",
        "Lance", "Larry", "Lawrence", "Lee", "Leo", "Leon", "Leonard",
        "Leroy", "Leslie", "Lester", "Lloyd", "Louis", "Luis", "Manuel",
        "Marc", "Marcus", "Mario", "Marion", "Mark", "Marshall", "Martin",
        "Marvin", "Mason", "Mathew", "Matthew", "Maurice", "Max", "Melvin",
        "Miguel", "Mike", "Milton", "Mitchell", "Morris", "Nathaniel",
        "Neil", "Nicholas", "Norman", "Patrick", "Paul", "Pedro", "Peter",
        "Philip", "Phillip", "Rafael", "Ralph", "Ramon", "Randall",
        "Randy", "Raul", "Ray", "Raymond", "Reginald", "Ricardo", "Richard",
        "Rick", "Ricky", "Robert", "Roberto", "Rodney", "Roger", "Roland",
        "Ron", "Ronald", "Ronnie", "Ross", "Roy", "Ruben", "Russell", "Sam",
        "Scott", "Sean", "Sergio", "Seth", "Shane", "Shaun", "Shawn",
        "Sidney", "Stanley", "Stephen", "Steve", "Steven", "Stuart", "Terrence",
        "Terry", "Thomas", "Timothy", "Todd", "Tom", "Tommy", "Tony", "Travis",
        "Troy", "Tyler", "Tyrone", "Vernon", "Victor", "Vincent", "Virgil",
        "Wade", "Wallace", "Walter", "Warren", "Wayne", "Wesley", "Willard",
        "Willie", "Zachary",
        "Abigail", "Adriana", "Aisha", "Alexandra", "Alice", "Alicia",
        "Allison", "Alyssa", "Amanda", "Amber", "Amy", "Ana", "Andrea",
        "Angela", "Anita", "Ann", "Anna", "Anne", "Annette", "Annie", "April",
        "Ariana", "Ashley", "Audrey", "Barbara", "Beatrice", "Becky", "Belinda",
        "Bernice", "Bertha", "Bessie", "Beth", "Betty", "Beverly", "Billie",
        "Bobbie", "Bonnie", "Brenda", "Bridget", "Brittany", "Brooke",
        "Candace", "Candice", "Carla", "Carmen", "Carol", "Carole", "Caroline",
        "Carolyn", "Carrie", "Casey", "Cassandra", "Catherine", "Cathy",
        "Cecelia", "Cecilia", "Charlene", "Chelsea", "Cheryl", "Christina",
        "Christine", "Christy", "Cindy", "Claire", "Clara", "Claudia",
        "Colleen", "Connie", "Constance", "Courtney", "Crystal", "Cynthia",
        "Daisy", "Dana", "Danielle", "Darlene", "Dawn", "Deanna", "Debbie",
        "Deborah", "Debra", "Delores", "Denise", "Diana", "Diane", "Dianne",
        "Dolores", "Donna", "Dora", "Doris", "Dorothy", "Edith", "Edna",
        "Eileen", "Elaine", "Elena", "Eliza", "Elizabeth", "Ella", "Ellen",
        "Elsie", "Emily", "Emma", "Erica", "Erika", "Erin", "Esther", "Ethel",
        "Eva", "Faith", "Fannie", "Felicia", "Florence", "Frances", "Freda",
        "Frieda", "Gail", "Gayle", "Georgia", "Geraldine", "Gertrude", "Gina",
        "Gladys", "Glenda", "Gloria", "Gwendolyn", "Hailey", "Harriet",
        "Hattie", "Hazel", "Heather", "Heidi", "Helen", "Hilda", "Holly",
        "Ida", "Irene", "Irma", "Jackie", "Jacqueline", "Jamie", "Jane",
        "Janet", "Janice", "Janie", "Jean", "Jeanette", "Jeanne", "Jeannette",
        "Jennie", "Jennifer", "Jenny", "Jessica", "Jessie", "Jill", "Joan",
        "Joann", "Joanna", "Joanne", "Jodi", "Jody", "Johanna", "Jordan",
        "Josefa", "Josefina", "Josephine", "Joy", "Joyce", "Juana", "Juanita",
        "Judith", "Judy", "Julia", "Julie", "June", "Karen", "Karla", "Kate",
        "Katherine", "Kathleen", "Kathryn", "Kathy", "Katie", "Katrina", "Kay",
        "Kayla", "Kelley", "Kelli", "Kellie", "Kelly", "Kelsey", "Kendra",
        "Kenya", "Keri", "Kerri", "Kerry", "Kim", "Kimberly", "Kirsten",
        "Krista", "Kristen", "Kristi", "Kristie", "Kristin", "Kristina",
        "Kristy", "Krystal", "Lacey", "Lakesha", "Lana", "Latasha", "Latoya",
        "Laura", "Lauren", "Laurie", "Laverne", "Leah", "Leigh", "Leila",
        "Lena", "Leona", "Leonor", "Lesa", "Lesley", "Leslie", "Leticia",
        "Lila", "Lilia", "Lillian", "Lillie", "Linda", "Lindsay", "Lindsey",
        "Lisa", "Lois", "Lola", "Lora", "Loraine", "Lorena", "Lorene",
        "Loretta", "Lori", "Lorie", "Lorraine", "Louise", "Lucia", "Lucile",
        "Lucille", "Lucy", "Lula", "Luz", "Lydia", "Lynn", "Lynne", "Mabel",
        "Mable", "Madeline", "Mae", "Magdalena", "Maggie", "Mamie", "Mandy",
        "Marcia", "Margaret", "Margarita", "Margie", "Marguerite", "Maria",
        "Marian", "Marianne", "Marie", "Marilyn", "Marina", "Marion", "Marisa",
        "Marisol", "Maritza", "Marjorie", "Marlene", "Marsha", "Marta",
        "Martha", "Mary", "Maryann", "Mattie", "Maureen", "Maxine", "May",
        "Meagan", "Megan", "Meghan", "Melanie", "Melinda", "Melissa", "Melody",
        "Mercedes", "Meredith", "Michele", "Michelle", "Mildred", "Mindy",
        "Minnie", "Miranda", "Miriam", "Misty", "Mollie", "Molly", "Mona",
        "Monica", "Monique", "Myra", "Myrtle", "Nadia", "Nadine", "Nancy",
        "Naomi", "Natalie", "Natasha", "Nellie", "Nichole", "Nicole", "Nina",
        "Nora", "Norma", "Olga", "Olive", "Paige", "Pam", "Pamela", "Pat",
        "Patricia", "Patsy", "Patti", "Patty", "Paula", "Paulette", "Pauline",
        "Pearl", "Peggy", "Penny", "Phyllis", "Priscilla", "Rachel", "Ramona",
        "Rebecca", "Regina", "Renee", "Rhonda", "Rita", "Robbie", "Roberta",
        "Robin", "Robyn", "Rochelle", "Rosa", "Rosalie", "Rose", "Rosemarie",
        "Rosemary", "Rosie", "Roxanne", "Roxie", "Ruby", "Ruth", "Sabrina",
        "Sadie", "Sallie", "Sally", "Samantha", "Sandra", "Sandy", "Sara",
        "Sarah", "Sasha", "Savannah", "Shannon", "Shari", "Sharon", "Shauna",
        "Shawn", "Shawna", "Sheena", "Sheila", "Shelby", "Shelia", "Shelley",
        "Sheri", "Sherri", "Sherry", "Sheryl", "Shirley", "Silvia", "Simone",
        "Sonia", "Sonja", "Sonya", "Sophia", "Sophie", "Stacey", "Staci",
        "Stacie", "Stacy", "Stella", "Stephanie", "Sue", "Susan", "Susanne",
        "Susie", "Suzanne", "Sylvia", "Tabatha", "Tabitha", "Tamara", "Tameka",
        "Tami", "Tamika", "Tammi", "Tammie", "Tammy", "Tamra", "Tania", "Tanya",
        "Tara", "Tasha", "Teresa", "Teri", "Terri", "Terry", "Thelma", "Theresa",
        "Therese", "Tia", "Tiffany", "Tina", "Toni", "Tonia", "Tonya", "Tracey",
        "Traci", "Tracie", "Tracy", "Tricia", "Trisha", "Valerie", "Vanessa",
        "Velma", "Vera", "Verna", "Veronica", "Vicki", "Vickie", "Vicky",
        "Victoria", "Viola", "Violet", "Virginia", "Vivian", "Wanda", "Wendy",
        "Whitney", "Willie", "Wilma", "Yolanda", "Yvette", "Yvonne",

        # Trending Nameberry uniques
        "Royal", "Hadleigh", "Casper", "Zyla", "Rosalyn", "Tinsley",
        "Eloise", "Maeve", "Aurelia", "Olin", "Silas", "August",
        "Lou", "Rafferty", "Phineas",
        "Saffron", "Cosmo", "Atticus", "Cassius",
        "Zadie", "Ophelia", "Ezekiel", "Dashiell", "Indira", "Arlo",
        "Elara", "Ren", "Soren", "Lysander", "Octavia", "Zelda", "Ambrose",
        "Tallulah", "Winslow",
        "Hale", "Noam", "Reeve", "Torin", "Bellamy",

        # Mythology & folklore
        "Athena", "Apollo", "Orion", "Artemis", "Hermes",
        "Eros", "Persephone",
        "Loki", "Odin", "Thor",
        "Isis", "Osiris", "Horus",
        "Juno",

        # Sci-fi icons
        "Leia", "Rey", "Luke", "Han", "Lando",
        "Ripley", "Sarah", "Kyle", "Neo",
        "Trinity", "Ender", "Petra", "Valentine",
        "Picard", "Spock", "Kirk", "Uhura",
        "Mal", "Kaylee", "Inara", "River", "Shepherd",
        "Jayne", "Zoe", "Deckard", "Roy", "Hal", "Solo",
        "Cassian", "Bodhi", "Iden",
        "John",
        "Paul", "Jessica", "Duncan", "Gurney", "Chani",
        "Alia", "Vladimir",

        # High-fantasy legends
        "Aragorn", "Legolas",
        "Galadriel", "Elrond", "Arwen", "Eowyn", "Faramir",
        "Pippin", "Merry",
        "Crowley",
        "Rand", "Perrin", "Mat", "Egwene", "Nynaeve", "Moiraine",
        "Kvothe", "Denna", "Bast", "Ged",
        "Locke", "Jean", "Sabetha", "Patience", "Fitz",

        # STEM heroes & pioneers
        "Ada", "Alan", "Grace", "Charles", "Rosalind", "Nikola", "Albert",
        "Isaac", "Katherine", "Dorothy", "Hedy", "Claude", "Murray", "Edith",
        "Linus", "Margaret", "Tim", "Guido", "Elon", "Sergey", "Larry",
        "Vint", "Bob", "Jocelyn", "Vera", "Annie", "Mae",
        "Radia", "Sophie", "Mary", "Henrietta", "Lise",
        "Barbara", "Esther", "Karen", "Geoffrey",
        "Andrew", "Sebastian", "Alex",

        # Nature, celestial & modern word-names
        "Nova", "Atlas", "Seraphina", "Xander", "Juniper", "Ember",
        "Evander", "Cassian", "Calista", "Phoenix", "Asher", "Zara", "Milo",
        "Lyra", "Vesper", "Sage", "Rowan", "Indigo", "Valencia",
        "Lumina", "Zenith", "Cobalt", "Titan", "Sapphire",
        "Onyx", "Saffron", "Cedar", "Iris", "Jade", "Coral", "River", "Skye",
        "Storm", "Wilder", "Raven", "Fox",
        "Blaze", "Emberly", "Briar", "Opal", "Peridot", "Kairo",
        "Selene", "Thalia", "Sirius", "Pollux", "Castor", "Nyx",
        "Isolde", "Balthazar", "Gideon",
        "Magnus", "Oberon", "Tiana", "Morgan", "Rhysand",
        "Willow", "Aspen", "Birch", "Meadow", "Ocean", "Skylar",
        "Astra", "Solace", "Nimbus", "Echo",
        "Draco", "Hydra",
        "Lyric", "Arrow",
    ]

    _LAST_PARTS: ClassVar[List[str]] = [
        # Common U.S. & UK surnames
        "Smith", "Johnson", "Williams", "Brown", "Jones", "Garcia", "Miller",
        "Davis", "Rodriguez", "Martinez", "Hernandez", "Lopez", "Gonzalez",
        "Wilson", "Anderson", "Thomas", "Taylor", "Moore", "Jackson", "Martin",
        "Lee", "Perez", "Thompson", "White", "Harris", "Sanchez", "Clark",
        "Ramirez", "Lewis", "Robinson", "Walker", "Young", "Allen", "King",
        "Wright", "Scott", "Torres", "Nguyen", "Hill", "Flores", "Green",
        "Adams", "Nelson", "Baker", "Hall", "Rivera", "Campbell", "Mitchell",
        "Carter", "Roberts", "Gomez", "Phillips", "Evans", "Turner", "Diaz",
        "Parker", "Cruz", "Edwards", "Collins", "Reyes", "Stewart", "Morris",
        "Jenkins", "Perry", "Powell", "Long", "Patterson", "Hughes", "Price",
        "Butler", "Barnes", "Ross", "Henderson", "Coleman", "Jenkins",
        "Foster", "Graham", "Bryant", "Stone", "Hunter", "Dunn", "Murphy",
        "Kelly", "O'Brien", "Byrne", "Ryan", "O'Connor", "Walsh", "Patel",
        "Sutton", "Hayes", "Myers", "Ford", "Hamilton", "Wallace", "Woods",
        "Cole", "West", "Jordan", "Owens", "Reynolds", "Fisher", "Ellis",
        "Harrison", "Gibson", "Mcdonald", "Cruz", "Marshall", "Ortiz",
        "Gomez", "Murray", "Freeman", "Wells", "Webb", "Simpson", "Stevens",
        "Tucker", "Porter", "Hunter", "Hicks", "Crawford", "Henry", "Boyd",
        "Mason", "Morales", "Kennedy", "Warren", "Dixon", "Ramos", "Reyes",
        "Burns", "Gordon", "Shaw", "Holmes", "Rice", "Robertson", "Hunt",
        "Black", "Daniels", "Palmer", "Mills", "Nichols", "Grant", "Knight",
        "Ferguson", "Rose", "Stone", "Hawkins", "Dunn", "Perkins", "Hudson",
        "Spencer", "Gardner", "Stephens", "Payne", "Pierce", "Berry",
        "Matthews", "Arnold", "Wagner", "Willis", "Ray", "Watkins", "Olson",
        "Carroll", "Duncan", "Snyder", "Hart", "Cunningham", "Bradley",
        "Lane", "Andrews", "Ruiz", "Harper", "Fox", "Riley", "Armstrong",
        "Chavez", "Richards", "Day", "Johnston", "Fuller", "Little",
        "Burton", "George", "Willis", "Graham", "Lawrence", "Gray",

        # Scientist / inventor surnames
        "Edison", "Tesla", "Lovelace", "Curie", "Babbage", "Turing", "Hopper",
        "Feynman", "Mandelbrot", "Euler", "Gauss", "Kepler", "Newton",
        "Darwin", "Hawking", "Faraday", "Dirac", "Bohr", "Heisenberg", "Fermi",
        "Galilei", "Pascal", "Leibniz", "Noether", "Franklin", "Hodgkin",
        "Payne-Gaposchkin", "Burnell", "Meitner", "Wu", "Johnson", "Vaughan",
        "Hamilton", "Torvalds", "Berners-Lee", "Cerf", "Kahn", "Hinton",
        "LeCun", "Bengio", "Hassabis", "Silver", "Sutton", "Goodfellow",

        # Stylish & “cool” picks
        "Elsher", "Solace", "Levine", "Thatcher", "Raven", "Bardot", "Lockhart",
        "Kingsley", "Voss", "Sullivan", "Archer", "Steel", "Sterling",
        "Storm", "Wilder", "Fox", "Knight", "Ridge", "Holliday", "Vale",
        "Ashford", "Blackwood", "Brighton", "Carver", "Colt",
        "Devereaux", "Eastwood", "Frost", "Galloway", "Huxley", "Ironwood",
        "Jett", "Kensington", "Langley", "Maddox", "North", "Oakwood", "Pryor",
        "Quincy", "Ryder", "Sawyer", "Tamlin", "Underwood", "Venture",
        "Weston", "York", "Zenith", "Azure",
        "Beacon", "Sentinel", "Guardian",
        "Kernel", "Orbit", "Compass", "Grid", "Spark",
        "Shift", "Module", "Lambda", "Insight", "Veridian", "Hawthorne",
        "Sinclair", "Monroe", "Prescott", "Wilde", "Blaze", "Crestwood",

        # Rare U.S. surnames
        "Afify", "Allaband", "Amspoker", "Ardolf", "Atonal", "Banasiewicz",
        "Beischel", "Bidelspach", "Bombardo", "Bressett", "Bylykbashi",
        "Cipponeri", "Catlow", "Chobot", "Candies", "Dierksheide",
        "Echegoyen", "Falabella", "Fortenberry", "Guillebeaux", "Hansotia",
        "Iacovacci", "Jangula", "Krekeler", "Luttermoser", "Mcquaid",
        "Nisko", "Oeschger", "Pancotti", "Quesenberry", "Reinaas", "Satterthwaite",
        "Tzavaras", "Utech", "Viglianco", "Wenskunas", "Xiongcha", "Ybanez",
        "Zukowski", "Fenstermacher", "Goldschmidt", "Haverbrook", "Krumwiede",
        "Pfeffenberger", "Rauschenbach", "Vonnegut", "Weatherwax", "Zumbrunnen",

        # Fictional & pop-culture
        "Solo", "Organa", "Kenobi", "Potter", "Weasley", "Granger",
        "Lovegood",
        "Picard", "Riker", "Crusher", "LaForge", "Yar", "Troi",
        "Janeway", "Chakotay", "Tuvok", "Paris", "Kim",
        "Harkness", "Song", "Tyler", "Pond", "Oswin",
        "Moriarty", "Watson", "Holmes", "Hudson", "Ripley", "Deckard",
        "Kerrigan", "Raynor", "Mengsk", "Zeratul",
        "Moonshadow", "Nightshade",
        "Silverwind", "Ironstride", "Goldborne", "Stormbringer", "Winterborne",
        "Summerfield", "Thornheart", "Duskwhisper", "Emberfall", "Brightspear",
        "Atreides", "Harkonnen", "Corrino", "Idaho", "Halleck", "Yueh",
        "Wellington", "Finch", "Attano", "Kaldwin", "Pendleton", "Boyle",
    ]

    @classmethod
    def generate(cls, *, seed: int | None = None) -> str:
        """Return a randomly generated agent name."""
        rnd = random.Random(seed)
        return f"{rnd.choice(cls._FIRST_PARTS)} {rnd.choice(cls._LAST_PARTS)}"


# Simple CLI usage for manual testing:
if __name__ == "__main__":
    for _ in range(20):
        print(AgentNameGenerator.generate())