# cicero225/llm_pokemon_scaffold architecture

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

- Interactive diagram: https://gitdiagram.com/cicero225/llm_pokemon_scaffold
- Repository: https://github.com/cicero225/llm_pokemon_scaffold

## Overview

##### Project type and purpose
- This is a specialized “agent harness” that lets large language models (LLMs) play Pokémon Red via a local Game Boy emulator (PyBoy).
- It wraps emulator control, memory‐reading, prompt construction, tool definitions, logging, and a multi‐stage LLM reasoning/navigation pipeline into one Python application.

##### File structure
- Top‐level:
- main.py – CLI entrypoint & orchestrator
- config.py – model & feature flags
- requirements.txt, LICENSE, README.md
- secret_api_keys.py (user‐supplied at runtime)
- ROM file (pokemon.gb) + save files (save.state, locations.pkl)
- agent/ directory (core modules):
- emulator.py – PyBoy wrapper, threads the emulator
- memory_reader.py – reads game state from emulator memory
- simple_agent.py – orchestrates the LLM loop: capture, prompt, call, parse, execute
- prompts.py – system & function‐calling templates (incl. meta-critique stage)
- tool_definitions.py – registers tools (map builder, pathfinder, checkpoint logger, navigator)
- utils.py – helper code (collision map management, token streams for Gemini, etc.)

##### Key README insights
- Multi‐stage reasoning: meta‐critique LLM, checkpoint logs
- Navigation aids: ASCII collision maps, automated pathfinder tool
- Separate emulator thread for continuous game ticking
- LLM interactions via openAI/Gemini/o3 endpoints – function calling paradigm

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Orchestrator"
        CLI["CLI / Orchestrator"]:::local
        Config["Configuration Loader"]:::local
    end

    subgraph "Emulator Thread"
        Emu["Emulator (PyBoy)"]:::io
    end

    subgraph "Agent Thread"
        MR["Memory Reader"]:::local
        Core["Agent Core"]:::local
        Prompt["Prompt Manager"]:::local
        Tools["Tool Registry & Executors"]:::local
        Utils["Utilities"]:::local
    end

    LLM["LLM Service\n(OpenAI / Gemini)"]:::external

    ROM["ROM File\n(pokemon.gb)"]:::storage
    Save["Save State &\nLocation History"]:::storage

    CLI -->|loads config| Config
    CLI -->|starts emulator| Emu
    Emu -->|provides raw memory & screenshot| MR
    MR -->|structured game state| Core
    Core -->|packages state| Prompt
    Prompt -->|sends prompt| LLM
    LLM -->|returns JSON response| Core
    Core -->|invokes tools| Tools
    Tools -->|executes commands| Emu
    Tools -->|utilizes helpers| Utils
    Core -->|saves checkpoint| Save
    ROM -->|loaded by| Emu
    Save -->|loaded/saved by| Emu

    click CLI "https://github.com/cicero225/llm_pokemon_scaffold/blob/master/main.py"
    click Config "https://github.com/cicero225/llm_pokemon_scaffold/blob/master/config.py"
    click Emu "https://github.com/cicero225/llm_pokemon_scaffold/blob/master/agent/emulator.py"
    click MR "https://github.com/cicero225/llm_pokemon_scaffold/blob/master/agent/memory_reader.py"
    click Core "https://github.com/cicero225/llm_pokemon_scaffold/blob/master/agent/simple_agent.py"
    click Prompt "https://github.com/cicero225/llm_pokemon_scaffold/blob/master/agent/prompts.py"
    click Tools "https://github.com/cicero225/llm_pokemon_scaffold/blob/master/agent/tool_definitions.py"
    click Utils "https://github.com/cicero225/llm_pokemon_scaffold/blob/master/agent/utils.py"

    classDef local fill:#bbdefb,stroke:#1e88e5,color:#0d47a1;
    classDef io fill:#c8e6c9,stroke:#2e7d32,color:#1b5e20;
    classDef external fill:#fff59d,stroke:#f9a825,color:#f57f17;
    classDef storage fill:#ffe0b2,stroke:#ef6c00,color:#e65100;
```
