# nickwalton/ai-dungeonmaster architecture

> Architecture diagram of the GitHub repository nickwalton/ai-dungeonmaster, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nickwalton/ai-dungeonmaster
- Repository: https://github.com/nickwalton/ai-dungeonmaster

## Overview

##### Project Type and Purpose
- This is a standalone, full-stack (monolithic) Python application that runs entirely on the command line.
- Purpose: Provide an interactive, AI-driven text adventure (“Dungeon Master”) using a locally-hosted GPT-2 model (117M parameters).

##### File Structure Analysis
- Top-level entry points:
- dungeon_master.py – the CLI/game loop.
- generator.py – orchestrates calls to the GPT-2 sampling code.
- download_model.py – helper to fetch the GPT-2 checkpoint.
- story_tracker.py – maintains game state and history.
- utils.py – shared utilities (e.g., text cleaning, I/O).
- story_prompts.yaml – seed data for the adventure.
- gpt2/ package:
- download_model.py – duplicates model fetch logic under the package.
- models/117M – stores the downloaded model files (encoder.json, vocab.bpe, checkpoints).
- src/ – GPT-2 implementation modules (encoder.py, model.py, sample.py).
- Configuration: requirements.txt lists external dependencies (tensorflow, numpy, tqdm, regex).

##### README Insights
- Installation steps show pip-based dependencies and GPU alternative.
- Usage: first download the GPT-2 model, then run dungeon_master.py to start the game.
- No network calls at runtime—everything is local.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    User["User"]:::external
    User -->|"input command"| CLI["dungeon_master.py"]:::pythonModule

    %% CLI Layer
    subgraph "CLI Layer"
        CLI
        CLI_DL["download_model.py"]:::pythonModule
    end

    %% Application Logic Layer
    subgraph "Application Logic Layer"
        GEN["generator.py"]:::pythonModule
        TRACKER["story_tracker.py"]:::pythonModule
        UTILS["utils.py"]:::pythonModule
        PROMPTS["story_prompts.yaml"]:::pythonModule
    end

    %% AI Model Layer
    subgraph "AI Model Layer"
        subgraph "GPT-2 Implementation"
            ENCODER["encoder.py"]:::pythonModule
            MODEL_DEF["model.py"]:::pythonModule
            SAMPLE["sample.py"]:::pythonModule
        end
        subgraph "Model Storage"
            MS_DIR["117M Model Files"]:::modelStorage
        end
    end

    %% External Dependencies
    EXTERNAL["requirements.txt"]:::external

    %% Data Flow
    CLI -->|"initialize game"| TRACKER
    TRACKER -->|"assemble prompt"| GEN
    GEN -->|"sample_sequence"| SAMPLE
    SAMPLE -->|"load encoder & checkpoint"| ENCODER
    SAMPLE -->|"read model files"| MS_DIR
    SAMPLE -->|"generate text"| GEN
    GEN -->|"update story"| TRACKER
    TRACKER -->|"return text"| CLI
    CLI -->|"display output"| User

    %% Model Download Flow
    CLI_DL -->|"fetch model"| GDLP["gpt2/download_model.py"]:::pythonModule
    GDLP -->|"save files"| MS_DIR
    CLI_DL -->|"show progress"| EXTERNAL

    %% Click Events
    click CLI "https://github.com/nickwalton/ai-dungeonmaster/blob/master/dungeon_master.py"
    click CLI_DL "https://github.com/nickwalton/ai-dungeonmaster/blob/master/download_model.py"
    click GEN "https://github.com/nickwalton/ai-dungeonmaster/blob/master/generator.py"
    click TRACKER "https://github.com/nickwalton/ai-dungeonmaster/blob/master/story_tracker.py"
    click UTILS "https://github.com/nickwalton/ai-dungeonmaster/blob/master/utils.py"
    click PROMPTS "https://github.com/nickwalton/ai-dungeonmaster/blob/master/story_prompts.yaml"
    click GDLP "https://github.com/nickwalton/ai-dungeonmaster/blob/master/gpt2/download_model.py"
    click ENCODER "https://github.com/nickwalton/ai-dungeonmaster/blob/master/gpt2/src/encoder.py"
    click MODEL_DEF "https://github.com/nickwalton/ai-dungeonmaster/blob/master/gpt2/src/model.py"
    click SAMPLE "https://github.com/nickwalton/ai-dungeonmaster/blob/master/gpt2/src/sample.py"
    click MS_DIR "https://github.com/nickwalton/ai-dungeonmaster/tree/master/gpt2/models/117M"
    click EXTERNAL "https://github.com/nickwalton/ai-dungeonmaster/blob/master/requirements.txt"

    %% Styles
    classDef pythonModule fill:#bbdefb,stroke:#333,stroke-width:1px
    classDef modelStorage fill:#c8e6c9,stroke:#333,stroke-width:1px
    classDef external fill:#fff59d,stroke:#333,stroke-width:1px
```
