# Technical Document Extraction: LLM-PySC2 Framework Architecture
This document provides a comprehensive technical breakdown of the provided architectural diagram, which illustrates a system named **LLM-PySC2**. This system integrates Large Language Models (LLMs) with the StarCraft II game environment via a structured memory and processing pipeline.
## 1. System Overview
The architecture is divided into four primary functional regions:
1. **LLM-PySC2 (Environment Interface):** The bridge to the StarCraft II game engine.
2. **Memory:** A persistent storage layer for strategy and state history.
3. **LLM Input/Output Processing:** The formatting and parsing layer for model communication.
4. **LLMs:** The external reasoning engines (represented by OpenAI, Meta/Llama, and DeepSeek logos).
---
## 2. Component Analysis
### Region 1: LLM-PySC2 (Left Column)
This region handles the conversion between game-state data and textual information.
* **StarCraft II Game:** The core engine, represented by a screenshot of gameplay showing Protoss units (Stalkers and Pylons).
* **Obs-Text converter:** An oval-shaped processing node that transforms raw game observations into text.
* **Observation Extractor:** Receives data from the converter and sends it to the LLM input stage.
* **Text-Action converter:** An oval-shaped node that translates textual commands back into game-executable actions.
* **Action Extractor:** Receives commands from the LLM output stage and feeds them into the converter.
### Region 2: Memory (Center Column)
A centralized database system to maintain context over time.
* **memory.db:** A structured database containing step-by-step logs.
* *Data Content:* `{step1:[Tactic]:...}`, `{step2:[Tactic]:...}`.
* **get_latest Strategy:** A retrieval component that pulls the most recent tactical state from the database to inform the next LLM prompt.
* **Strategy Extractor:** A component that parses the LLM's output to update the memory database with new tactical decisions.
### Region 3: LLM Input (Top Right)
This block aggregates various data sources into a single prompt for the LLM.
* **Textual Observation:** Real-time data from the Observation Extractor.
* **State Machine Prompt:** A visual/logical template (represented by a diagram with red and blue state boxes and green oval transitions).
* **Last Strategy States:** Historical context retrieved from Memory.
* *Specific Data:* `[Tactic]:<defensive>`, `[PriorityUnit]:<Voidray>`.
### Region 4: LLM Output (Bottom Right)
This block represents the structured response from the LLM, which is then decomposed.
* **Textual Reasoning:** The model's internal "thought process."
* **New Strategy States:** Updated tactical goals.
* *Specific Data:* `[Tactic]:<aggressive>`, `[PriorityUnit]:<Carrier>`.
* **Textual Analysis:** Further breakdown of the current situation.
* **Executable Actions:** Concrete game commands.
* *Specific Data:* `<Train_Carrier()>`, `<All_Units_Attack()>`.
* **Other Textual Content:** Miscellaneous model output.
---
## 3. Data Flow and Logic
The system operates in a closed-loop cycle:
1. **Observation Phase:** The **StarCraft II Game** state is processed by the **Obs-Text converter** into a **Textual Observation**.
2. **Contextualization Phase:** The **Memory** system provides the **Last Strategy States** (e.g., "defensive" with "Voidray").
3. **Inference Phase:** The **LLM Input** (Observation + State Machine + Memory) is sent to the **LLMs** (OpenAI, Meta, or DeepSeek).
4. **Decision Phase:** The LLM returns an **LLM output**.
* The **Strategy Extractor** identifies a shift in strategy (e.g., changing from "defensive" to "aggressive" and prioritizing "Carrier") and updates **memory.db**.
* The **Action Extractor** identifies specific commands (e.g., `Train_Carrier()`) and sends them to the **Text-Action converter**.
5. **Execution Phase:** The converted actions are executed within the **StarCraft II Game**, completing the loop.
## 4. Textual Transcriptions
| Category | Transcribed Text |
| :--- | :--- |
| **Headers** | LLM-PySC2, Memory, LLM input, LLM output, LLMs |
| **Process Nodes** | Observation Extractor, Obs-Text converter, StarCraft II Game, Text-Action converter, Action Extractor, Strategy Extractor, get_latest Strategy |
| **Data Fields (Input)** | Textual Observation, State Machine Prompt, Last Strategy States: [Tactic]:<defensive>, [PriorityUnit]:<Voidray> |
| **Data Fields (Output)** | Textual Reasoning, New Strategy States: [Tactic]:<aggressive>, [PriorityUnit]:<Carrier>, Textual Analysis, Executable Actions: <Train_Carrier()>, <All_Units_Attack()>, Other Textual Content |
| **Database Content** | memory.db, {step1:[Tactic]:...}, {step2:[Tactic]:...} |
