ClientAI Tutorial: Building an AI Dungeon Master¶

In this tutorial, we'll walk through the process of creating an AI-powered Dungeon Master using the ClientAI package. We'll explain each concept in detail and build our game step-by-step, providing context for every decision we make, both technical and gameplay-related.

Table of Contents¶

Introduction
Setting Up the Project
2.5 Creating the Project Structure
Creating the Game Structure
Integrating Multiple AI Providers
Developing the Enhanced AI Dungeon Master
Main Script that Runs the Game
Running the Game
Conclusion and Further Improvements

1. Introduction¶

ClientAI is a Python package that provides a unified interface for interacting with multiple AI providers. In this tutorial, we'll use ClientAI to create an AI Dungeon Master that can generate story elements, NPC dialogues, and dynamic environments using different AI models.

Our AI Dungeon Master will be a text-based role-playing game (RPG) where the game's content is dynamically generated by AI. This approach allows for infinite replayability and unique experiences for each player.

We'll focus on explaining both technical decisions (such as class structures and AI interactions) and gameplay decisions (like character creation and game mechanics).

The final result is available in this github repo.

2. Setting Up the Project¶

First, let's set up our project and install the necessary dependencies.

Create a new directory for your project:

mkdir ai_dungeon_master
cd ai_dungeon_master

Install ClientAI and its dependencies:

If you want to use poetry, you may skip this part.

pip install clientai[all]

This command installs ClientAI with support for all providers. If you only need specific providers, you can install them individually (e.g., pip install clientai[openai] for just OpenAI support).

Install additional dependencies:

If you want to use poetry, you may also skip this part.

We'll need some additional packages for our project.

pip install requests

requests: For making HTTP requests to check if the local AI servers are running.
Install Ollama:

Ollama is a local AI model server that we'll use to run the Llama 3 model. Follow these steps to install Ollama:

For macOS or Linux:

curl -fsSL https://ollama.com/install.sh | sh

For Windows: Download the installer from the Ollama GitHub releases page and follow the installation instructions.
Pull the Llama 3 model from Ollama:

After installing Ollama, you need to download the Llama 3 model. Run the following command:

ollama pull llama3

This command will download and set up the Llama 3 model for use with Ollama. The download might take some time depending on your internet connection.

These imports will be used throughout our project:

random: For generating random numbers and making random choices.
subprocess: For starting and managing subprocesses like local AI servers.
time: For adding delays and managing timeouts.
requests: For making HTTP requests to check server availability.
logging: For logging information and errors.
ClientAI: The main class from the ClientAI package that we'll use to interact with AI providers.

2.5 Creating the Project Structure¶

Before we dive into the code, let's set up a proper project structure. This will help us organize our code and make it easier to maintain and expand in the future.

Create the following directory structure:

clientai_dungeon_master/
├── pyproject.toml
├── README.md
├── .gitignore
├── .env
└── ai_dungeon_master/
    ├── __init__.py
    ├── main.py
    ├── game/
    │   ├── __init__.py
    │   ├── character.py
    │   ├── game_state.py
    │   └── dungeon_master.py
    ├── ai/
    │   ├── __init__.py
    │   ├── ai_providers.py
    │   └── ollama_server.py
    └── utils/
        ├── __init__.py
        └── text_utils.py

Create a pyproject.toml file in the root directory with the following content:

If you're using pip directly, you may skip this part

[tool.poetry]
name = "clientai-dungeon-master"
version = "0.1.0"
description = "An AI-powered dungeon master for text-based RPG adventures"
authors = ["Your Name <your.email@example.com>"]
readme = "README.md"
packages = [{include = "clientai_dungeon_master"}]

[tool.poetry.dependencies]
python = "^3.11"
clientai = "^0.1.2"
requests = "^2.32.3"
python-decouple = "^3.8"


[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

and run

poetry install

Create a .gitignore file in the root directory with the following content:

# Python
__pycache__/
*.py[cod]
*.pyo
*.pyd
.Python
env/
venv/
ENV/

# Poetry
.venv/
dist/

# Environment variables
.env

# IDEs
.vscode/
.idea/

# Logs
*.log

# OS generated files
.DS_Store
.DS_Store?
._*
.Spotlight-V100
.Trashes
ehthumbs.db
Thumbs.db

Create a .env file in the root directory to store your API keys:

OPENAI_API_KEY=your_openai_api_key_here
REPLICATE_API_KEY=your_replicate_api_key_here

Remember to replace your_openai_api_key_here and your_replicate_api_key_here with your actual API keys.

Move the relevant code into the appropriate files based on the new structure.

This structure separates concerns, making the code more modular and easier to maintain. It also sets up the project for potential future expansion, such as adding more game features or integrating additional AI providers.

3. Creating the Game Structure¶

Before integrating AI, we'll create the basic structure of our game. This includes classes to represent the character, game state, and AI providers.

Character Class¶

The Character class represents the player's character in the game. It stores essential character information like name, race, class, background story, and stats.

ai_dungeon_master/game/character.py

class Character:
    def __init__(self, name: str, race: str, class_type: str, background: str, stats: dict):
        self.name = name
        self.race = race
        self.class_type = class_type
        self.background = background
        self.stats = stats

    def __str__(self):
        return f"Name: {self.name}, Race: {self.race}, Class: {self.class_type}, Background: {self.background}, Stats: {self.stats}"

Here we define a character with attributes like a name, race, class, background and stats (like Strength, Intelligence, Wisdom). This is really simple, but will be enough to customize what happens in the story.

We'll also define the __str__ method to be able to print the character's details easily.

GameState Class¶

The GameState class keeps track of the game's current state, including the character's status, location, inventory, health, experience, and quests.

ai_dungeon_master/game/game_state.py

from typing import Optional

from .character import Character

class GameState:
    def __init__(self, character: Character):
        self.character = character
        self.location = "entrance"
        self.inventory = []
        self.health = 100
        self.experience = 0
        self.quests = []

    def update(self, location: Optional[str] = None, item: Optional[str] = None, health_change: int = 0, exp_gain: int = 0, quest: Optional[str] = None):
        if location:
            self.location = location
        if item:
            self.inventory.append(item)
        self.health = max(0, min(100, self.health + health_change))
        self.experience += exp_gain
        if quest:
            self.quests.append(quest)

    def __str__(self):
        return f"{str(self.character)}\nLocation: {self.location}, Health: {self.health}, XP: {self.experience}, Inventory: {', '.join(self.inventory)}, Quests: {', '.join(self.quests)}"

We keep track of the state to keep a more consistent experience, we can't expect this to be always generated by the llm. We need to pass the game state as a guide to generate the content.

The update method allows easy updates to the game state, we'll keep health within 0 to 100, and add an inventory and quests to add more depth to the game.

4. Integrating Multiple AI Providers¶

We'll use ClientAI to create a class that manages interactions with different AI providers. This abstraction allows us to switch between providers seamlessly.

AIProviders Class¶

ai_dungeon_master/ai/ai_providers.py

from typing import List

from clientai import ClientAI

class AIProviders:
    def __init__(self):
        self.openai = ClientAI('openai', api_key=openai_token)
        self.replicate = ClientAI('replicate', api_key=replicate_token)
        self.ollama = ClientAI('ollama', host="http://localhost:11434")

    def chat(
        self,
        messages: List[dict],
        provider: str = 'openai',
        openai_model="gpt-4o-mini",
        replicate_model="meta/meta-llama-3-8b-instruct",
        ollama_model="llama3",
    ):
        if provider == 'openai':
            return self.openai.chat(messages, model=openai_model, stream=True)
        elif provider == 'replicate':
            return self.replicate.chat(messages, model=replicate_model, stream=True)
        elif provider == 'ollama':
            return self.ollama.chat(messages, model=ollama_model, stream=True)
        else:
            raise ValueError(f"Unknown provider: {provider}")

We create instances of ClientAI for each provider with the necessary API keys or host information, then abstract the chat method to allow for easy switching between AI providers.

We are going to use ClientAI to use multiple AI models from different providers, since we want to find what is the best model for each task balancing performance and costs.

Managing API Keys with python-decouple and a .env File¶

To securely handle your API keys without exposing them in your codebase, you can use the python-decouple package and store your keys in a .env file. This approach keeps sensitive information out of your code and version control.

Install python-decouple: You may skip this if you used poetry

pip install python-decouple

Create a .env File: In your project's root directory, make sure the .env has your API keys:

OPENAI_API_KEY=your_openai_api_key_here
REPLICATE_API_KEY=your_replicate_api_key_here

Replace your_openai_api_key_here and your_replicate_api_key_here with your actual API keys.

Ensure .env is added to .gitignore: To prevent the .env file from being tracked by version control, ensure it is in your .gitignore file:

# .gitignore
.env

This ensures your API keys remain private and aren't pushed to repositories like GitHub.

Access the API Keys in Your Code: Import config from decouple and retrieve the API keys:

ai_dungeon_master/ai/ai_providers.py

from decouple import config

openai_token = config('OPENAI_API_KEY')
replicate_token = config('REPLICATE_API_KEY')

Now, you can use these variables when initializing your AI providers.

Update the AIProviders Class:

ai_dungeon_master/ai/ai_providers.py

from typing import List

from clientai import ClientAI
from decouple import config

openai_token = config('OPENAI_API_KEY')
replicate_token = config('REPLICATE_API_KEY')he ol

class AIProviders:
    def __init__(self):
        self.openai = ClientAI('openai', api_key=openai_token)
        self.replicate = ClientAI('replicate', api_key=replicate_token)
        self.ollama = ClientAI('ollama', host="http://localhost:11434")

 ...

Managing AI Servers¶

We need to ensure that local AI servers (like Ollama) are running before the game starts, so let's define a function to start ollama.

ai_dungeon_master/ai/ollama_server.py

import subprocess
import time
import requests
import logging

logging.basicConfig(level=logging.INFO)

def start_ollama_server(timeout: int = 30, check_interval: float = 1.0):
    """
    Start the Ollama server and wait for it to be ready.
    """
    logging.info("Starting Ollama server...")

    try:
        process = subprocess.Popen(
            ['ollama', 'serve'],
            stdout=subprocess.PIPE,
            stderr=subprocess.PIPE,
            text=True
        )
    except subprocess.SubprocessError as e:
        logging.error(f"Failed to start Ollama process: {e}")
        raise

    start_time = time.time()
    while time.time() - start_time < timeout:
        try:
            response = requests.get('http://localhost:11434', timeout=5)
            if response.status_code == 200:
                logging.info("Ollama server is ready.")
                return process
        except requests.ConnectionError:
            pass
        except requests.RequestException as e:
            logging.error(f"Unexpected error when checking Ollama server: {e}")
            process.terminate()
            raise

        if process.poll() is not None:
            stdout, stderr = process.communicate()
            logging.error(f"Ollama process terminated unexpectedly. stdout: {stdout}, stderr: {stderr}")
            raise subprocess.SubprocessError("Ollama process terminated unexpectedly")

        time.sleep(check_interval)

    process.terminate()
    raise TimeoutError(f"Ollama server did not start within {timeout} seconds")

By managing the server startup within the code, we reduce the setup burden on the player.