# git-disl/pokellmon architecture

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

- Interactive diagram: https://gitdiagram.com/git-disl/pokellmon
- Repository: https://github.com/git-disl/pokellmon

## Overview

##### Project type and purpose
- From the README and file tree, PokéLLMon is a Python-based AI agent and training platform that integrates with the Pokémon Showdown battle engine. It provides:
- A client to connect to a local Showdown server
- An environment simulator modeling Pokémon battles
- Multiple “player” policies (heuristic, GPT-based, LLM-based)
- Prompt construction modules to query OpenAI’s API
- Training pipelines (self-play, PPO finetuning, reward-model based)
- Data pipelines for static game data and preference datasets

##### File structure
- Top-level:
- src/client – connection code, client/server configuration
- src/environment – battle simulator classes (Battle, Pokémon, Moves, etc.)
- src/player – different agent implementations
- src/prompt – prompt templates and loader
- src/data – data normalization, static JSON assets (pokedex, moves, abilities, etc.)
- Training & orchestration scripts at root (train.py, self_play_llm.py, finetune_ppo.py)
- Config folder with YAMLs for modes (SFT, DPO) and model presets
- External deps: OpenAI API, Node.js/Showdown server

##### README for additional insights
- Architecture isn’t explicitly drawn, but the workflow is:
1. Launch local Showdown engine
2. Start Python “main.py” client
3. Use configured OpenAI key for LLM calls
4. Execute battles, self-play, or training

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Inference Pipeline
    subgraph "Inference Pipeline"
        direction TB
        Server["Showdown Server"]:::external
        Client["Python Client\n(src/client)"]:::core
        Concurrency["Concurrency Utilities\n(src/concurrency.py)"]:::core
        EnvSim["Environment Simulator\n(src/environment)"]:::core
        DataStore["Data Store\n(src/data/static)"]:::data
        DataPipeline["Data Pipelines & Normalization\n(src/data)"]:::data
        Prompt["Prompt Builder\n(src/prompt)"]:::core
        OpenAI["OpenAI API"]:::external
        Policy["Policy Modules\n(src/player)"]:::ai
    end

    %% Training Pipeline
    subgraph "Training Pipeline"
        direction TB
        TrainOrch["Training Orchestrator\n(train.py, self_play_llm.py,\nfinetune_ppo.py, src/trainers.py)"]:::training
        Preference["Preference Dataset Loader\n(src/preference_datasets.py)"]:::data
        Config["Configuration Management\n(src/config)"]:::core
    end

    %% Metrics & Logging
    Metrics["Metrics & Logging\n(gen_statistics.py, src/stats.py)"]:::monitor

    %% Inference Flows
    Server <-->|"WebSocket JSON"| Client
    Client -->|"battle events"| EnvSim
    EnvSim -->|"state"| Prompt
    DataStore -->|"assets JSON"| Prompt
    DataPipeline -->|"normalized data"| EnvSim
    Prompt -->|"prompt text"| OpenAI
    OpenAI -->|"LLM response"| Policy
    Policy -->|"next action"| Client

    %% Training Flows
    TrainOrch -->|"self-play loop"| Client
    TrainOrch -->|"use preferences"| Preference
    TrainOrch -->|"update models"| Policy
    TrainOrch -->|"ingest data"| DataPipeline
    Config -->|"mode & model settings"| TrainOrch

    %% Metrics taps
    Client -->|"events"| Metrics
    EnvSim -->|"state snapshots"| Metrics
    Prompt -->|"prompts"| Metrics
    Policy -->|"actions"| Metrics
    TrainOrch -->|"training stats"| Metrics

    %% Click Events
    click Client "https://github.com/git-disl/pokellmon/blob/main/src/client/client.py"
    click Concurrency "https://github.com/git-disl/pokellmon/blob/main/src/concurrency.py"
    click EnvSim "https://github.com/git-disl/pokellmon/tree/main/src/environment/"
    click DataStore "https://github.com/git-disl/pokellmon/tree/main/src/data/static/"
    click DataPipeline "https://github.com/git-disl/pokellmon/blob/main/src/data/gen_data.py"
    click DataPipeline "https://github.com/git-disl/pokellmon/blob/main/src/data/normalize.py"
    click Prompt "https://github.com/git-disl/pokellmon/blob/main/src/prompt/read_prompt.py"
    click Policy "https://github.com/git-disl/pokellmon/blob/main/src/player/player.py"
    click Preference "https://github.com/git-disl/pokellmon/blob/main/src/preference_datasets.py"
    click Config "https://github.com/git-disl/pokellmon/blob/main/src/config/config.yaml"
    click TrainOrch "https://github.com/git-disl/pokellmon/blob/main/train.py"

    %% Styles
    classDef core fill:#AED6F1,stroke:#3498DB,color:#1B4F72
    classDef data fill:#D6EAF8,stroke:#5DADE2,color:#1B4F72
    classDef ai fill:#ABEBC6,stroke:#58D68D,color:#145A32
    classDef external fill:#F5CBA7,stroke:#EB984E,color:#7E5109
    classDef training fill:#D2B4DE,stroke:#AF7AC5,color:#4A235A
    classDef monitor fill:#F9E79F,stroke:#F4D03F,color:#7D6608
```
