Namegiver: AI-based Character Name Generator

A lightweight, OpenAI-powered Python library for generating unique fictional character names based on user-provided prompts. Designed for writers, game developers, and world-builders.

Features

AI-Generated Names – Distinctive names based on user descriptions.
Ensures Name Distinctiveness – Avoids generating names too similar to previous ones.
Supports CLI & API – Use from the terminal or integrate into Python projects.
Economy Mode – Uses GPT-3.5 by default; switch to GPT-4 if needed.
Token Usage Tracking – Monitor OpenAI API token consumption.

Installation

1. Install via pip

pip install namegiver

This will install the package and all its dependencies.

2. Set Up API Key

Create a .env file in your project directory:

OPENAI_API_KEY=your-api-key-here
ECONOMY_MODE=True

Alternatively, set it in your shell:

export OPENAI_API_KEY="your-api-key-here"
export ECONOMY_MODE="True"

Usage

1. Using the Python API

from namegiver import generate_unique_name, get_token_usage

past_names = ["Elwin", "Alvin", "Elvin"]

# Generate a unique name while avoiding past names
print(generate_unique_name("sci-fi bounty hunter", past_names))

# Show token usage
print("Token Usage Report:", get_token_usage())

2. Using the CLI

Generate a Name

namegen "medieval knight"

Example Output:

Sir Aldrin of Westmere

Specify Maximum Token Length

namegen "steampunk engineer" --max-tokens 5

Example Output:

Brasswick

Avoid Similar Names

namegen "elf warrior" --past-names Legolas Thranduil Elrond

Example Output:

Faerion

Check Token Usage

namegen --report

Example Output:

Token Usage Report: {'total_tokens_used': 50}

Configuration

Environment Variables

Variable	Default	Description
OPENAI_API_KEY	(Required)	Your OpenAI API key
ECONOMY_MODE	True	If True, uses gpt-3.5-turbo. Set to False for GPT-4

How It Works

• The library queries OpenAI's LLM to generate a name.
• If past_names is provided, it asks OpenAI to avoid those names.
• After generation, the name is checked using Levenshtein distance to prevent near-duplicates.
• If the generated name is too similar, the system regenerates up to 5 times.

Development

Run Locally

Clone the repo and install dependencies:

git clone https://github.com/yourusername/namegiver.git
cd namegiver
pip install -e .

Run Tests

Run the test suite with:

pytest tests/

Contributing

Contributions are welcome! Submit issues or pull requests.

License

This project is licensed under the MIT License.