Lore NPC

Interactive chat with any NPC characters based on your world's lore.

Overview

NPC Lore Generator is a command-line tool that allows you to create rich, lore-consistent non-player characters (NPCs) for your fantasy or sci-fi worlds. Using advanced AI models, it generates detailed character profiles that are fully consistent with your world's lore and history.

The tool also provides an interactive chat interface where you can ask questions about your world's lore and get accurate, consistent answers based on the context you provide.

Features

• Lore-Consistent NPC Generation: Create NPCs with detailed backstories, personalities, skills, and equipment that fit perfectly within your world's lore.
• Interactive Lore Guide: Ask questions about your world and get accurate, consistent answers based on the lore context you provide.
• Multiple Factions Support: Generate characters from different factions, cultures, and species within your world.
• Rich CLI Interface: Beautiful terminal interface with syntax highlighting and markdown support.
• Flexible World Context: Use any text document as your world context - from simple descriptions to complex lore documents.

Installation

Prerequisites

• Python 3.12 or higher
• An OpenAI API key (for the GPT models)

Installation Steps

1. Clone the repository:

   git clone https://github.com/i.bahlai/lore-npc.git
   cd lore-npc
   

2. Install the package using uv:

   uv sync
   

3. Set up your environment variables by copying the example file:

   cp .env.example .env
   

4. Edit the .env file and add your OpenAI API key:

   PYDANTIC_AI_OPENAI_KEY=your_openai_api_key_here
   

Usage

The tool provides two main commands:

Generate NPCs

Create a new NPC based on your world's lore:

uv run lore-npc npc generate-npc /path/to/your/world/context.md

Example:

uv run lore-npc npc generate-npc docs/fantasy.md

This will generate a JSON-formatted NPC with all the details like name, personality traits, skills, background, etc.

Here's an example of what the output looks like:

Interactive Lore Chat

Chat with a lore guide about your world:

uv run lore-npc chat run-cli /path/to/your/world/context.md

Example:

uv run lore-npc chat run-cli docs/fantasy.md

Once in the chat, you can ask questions like:

• "Tell me about the Ironhold Clans"
• "What happened during the Sundering?"
• "Create a character from the Ethereal Schism"

Type 'exit' to quit the chat.

Here's an example of what the chat interface looks like in action:

World Context

The tool requires a world context file to generate consistent content. This can be any text document describing your world's lore, history, factions, cultures, etc.

An example fantasy world context is provided in docs/fantasy.md.

Configuration

The tool can be configured through environment variables. See .env.example for all available options:

• PYDANTIC_AI_OPENAI_KEY: Your OpenAI API key (required)
• PYDANTIC_AI_NANO_MODEL: The model used for NPC generation (default: gpt-5-nano)
• PYDANTIC_AI_MINI_MODEL: The model used for smaller tasks (default: gpt-5-mini)
• PYDANTIC_AI_BIG_MODEL: The model used for complex tasks (default: gpt-5)
• PYDANTIC_AI_RETRIES: Number of retries for API calls (default: 3)

Code Quality

The project uses several tools to ensure code quality:

• Ruff: For linting and formatting
• MyPy: For type checking
• Pre-commit: For running checks before commits

Run these tools with:

# Linting and formatting
ruff check .
ruff format .

# Type checking
mypy src/

# Run all pre-commit checks
pre-commit run --all-files

Project Structure

src/lore_npc/
├── cli/              # Command-line interface commands
├── core/             # Core settings and models
├── schemas/          # Data schemas and validation
├── services/         # Business logic services
└── utils/            # Utility functions and AI agents

Evaluation Criteria

• Correctness of implementation: The tool correctly generates NPCs and answers lore questions based on the provided context.
• Quality and variety of generated content: NPCs have rich, varied characteristics that fit within the world's lore.
• Code design and architecture: Clean, modular code with clear separation of concerns.
• How well the system handles various user requests: The tool handles different types of questions and requests appropriately.
• Documentation and code clarity: Clear documentation and well-commented code.

Deliverables

• GitHub repository with source code
• README with setup and usage instructions
• Working interactive system ready for demonstration

License

This project is licensed under the Apache License - see the LICENSE file for details.