# cooperative-ia/cooperativegpt architecture

> Architecture diagram of the GitHub repository cooperative-ia/cooperativegpt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cooperative-ia/cooperativegpt
- Repository: https://github.com/cooperative-ia/cooperativegpt

## Overview

CooperativeGPT runs LLM-driven agents in Melting Pot substrate simulations: a user selects a game/scenario and players, the server sets up the environment, agents reason from observations and memory, and their actions advance the simulation. Supporting branches include human-controlled play, cooperative understanding, substrate-specific game rules, and recording/replay. Relationships among many agent modules are based on the SOURCE INDEX; unsampled implementations are not inferred beyond those references.

Main entry points: [`agent/agent.py`](https://github.com/cooperative-ia/cooperativegpt/blob/main/agent/agent.py) (LLM agent), [`main.py`](https://github.com/cooperative-ia/cooperativegpt/blob/main/main.py) (Simulation runner), [`game_environment/server.py`](https://github.com/cooperative-ia/cooperativegpt/blob/main/game_environment/server.py) (Episode server), [`game_environment/playing_utils/level_playing_utils.py`](https://github.com/cooperative-ia/cooperativegpt/blob/main/game_environment/playing_utils/level_playing_utils.py) (Level play loop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Simulation orchestration"]
  node_arguments["Run configuration<br/>[args_handler.py]"]
  node_runner["Simulation runner<br/>[main.py]"]
end

subgraph group_agents["Agent reasoning"]
  node_agent["LLM agent<br/>[agent.py]"]
  node_human["Human agent<br/>[human_agent.py]"]
  node_cognition["Cognitive modules"]
  node_understanding["Cooperative understanding<br/>[understanding.py]"]
  node_spatial["Spatial memory<br/>[spatial_memory.py]"]
  node_shortmemory["Short-term memory"]
  node_retrieval["Memory retrieval<br/>[retrieve.py]"]
end

subgraph group_environment["Game environment"]
  node_server["Episode server<br/>[server.py]"]
  node_playing["Level play loop"]
  node_substrates["Game substrates"]
  node_installer["Substrate installer<br/>[installer.py]"]
  node_bots["Bot policies<br/>[bots.py]"]
  node_observations["Observation generation"]
  node_scene["Scene description"]
  node_recorder["Episode recorder<br/>[recorder.py]"]
  node_replay["Simulation replay"]
end

subgraph group_services["Memory and model services"]
  node_longmemory[("Long-term memory")]
  node_llmutil["LLM utilities<br/>[llm.py]"]
  node_llm["Model adapters<br/>[base_llm.py]"]
  node_gui["Player interface<br/>[player_gui.py]"]
  node_files["Memory persistence<br/>[files.py]"]
end

node_user(("Simulation user"))

node_user -->|"sets options"| node_arguments
node_arguments -->|"configures"| node_runner
node_runner -->|"starts episode"| node_server
node_server -->|"installs substrate"| node_installer
node_server -->|"runs episode"| node_playing
node_server -->|"initializes bots"| node_bots
node_server -->|"selects game"| node_substrates
node_playing -->|"generates observations"| node_observations
node_playing -->|"describes scene"| node_scene
node_playing -->|"records play"| node_recorder
node_recorder -->|"supports replay"| node_replay
node_runner -->|"runs agents"| node_agent
node_agent -->|"uses reasoning"| node_cognition
node_agent -->|"updates memory"| node_shortmemory
node_agent -->|"stores memories"| node_longmemory
node_agent -->|"plans movement"| node_spatial
node_agent -->|"uses cooperation"| node_understanding
node_agent -->|"retrieves memories"| node_retrieval
node_retrieval -->|"queries memories"| node_longmemory
node_cognition -->|"uses prompts"| node_llmutil
node_llmutil -->|"selects model"| node_llm
node_runner -.->|"optional human play"| node_human
node_human -->|"uses interface"| node_gui
node_runner -->|"persists memories"| node_files

click node_arguments "https://github.com/cooperative-ia/cooperativegpt/blob/main/utils/args_handler.py"
click node_runner "https://github.com/cooperative-ia/cooperativegpt/blob/main/main.py"
click node_server "https://github.com/cooperative-ia/cooperativegpt/blob/main/game_environment/server.py"
click node_playing "https://github.com/cooperative-ia/cooperativegpt/blob/main/game_environment/playing_utils/level_playing_utils.py"
click node_substrates "https://github.com/cooperative-ia/cooperativegpt/tree/main/game_environment/substrates/python"
click node_installer "https://github.com/cooperative-ia/cooperativegpt/blob/main/game_environment/substrates/installer.py"
click node_bots "https://github.com/cooperative-ia/cooperativegpt/blob/main/game_environment/bots.py"
click node_observations "https://github.com/cooperative-ia/cooperativegpt/blob/main/game_environment/scene_descriptor/observations_generator.py"
click node_scene "https://github.com/cooperative-ia/cooperativegpt/blob/main/game_environment/scene_descriptor/scene_descriptor.py"
click node_recorder "https://github.com/cooperative-ia/cooperativegpt/blob/main/game_environment/recorder/recorder.py"
click node_replay "https://github.com/cooperative-ia/cooperativegpt/blob/main/game_environment/recorder/recreate_simulation.py"
click node_agent "https://github.com/cooperative-ia/cooperativegpt/blob/main/agent/agent.py"
click node_human "https://github.com/cooperative-ia/cooperativegpt/blob/main/agent/human_agent.py"
click node_cognition "https://github.com/cooperative-ia/cooperativegpt/tree/main/agent/cognitive_modules"
click node_understanding "https://github.com/cooperative-ia/cooperativegpt/blob/main/agent/cooperative_modules/understanding.py"
click node_spatial "https://github.com/cooperative-ia/cooperativegpt/blob/main/agent/memory_structures/spatial_memory.py"
click node_shortmemory "https://github.com/cooperative-ia/cooperativegpt/blob/main/agent/memory_structures/short_term_memory.py"
click node_longmemory "https://github.com/cooperative-ia/cooperativegpt/blob/main/agent/memory_structures/long_term_memory.py"
click node_retrieval "https://github.com/cooperative-ia/cooperativegpt/blob/main/agent/cognitive_modules/retrieve.py"
click node_llmutil "https://github.com/cooperative-ia/cooperativegpt/blob/main/utils/llm.py"
click node_llm "https://github.com/cooperative-ia/cooperativegpt/blob/main/llm/base_llm.py"
click node_gui "https://github.com/cooperative-ia/cooperativegpt/blob/main/utils/player_gui.py"
click node_files "https://github.com/cooperative-ia/cooperativegpt/blob/main/utils/files.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_arguments,node_runner,node_user toneBlue
class node_agent,node_human,node_cognition,node_understanding,node_spatial,node_shortmemory,node_retrieval toneAmber
class node_server,node_playing,node_substrates,node_installer,node_bots,node_observations,node_scene,node_recorder,node_replay toneMint
class node_longmemory,node_llmutil,node_llm,node_gui,node_files toneRose
```

## Components

### Simulation orchestration

- [Run configuration](https://github.com/cooperative-ia/cooperativegpt/blob/main/utils/args_handler.py): `utils/args_handler.py`
- [Simulation runner](https://github.com/cooperative-ia/cooperativegpt/blob/main/main.py): `main.py`

### Agent reasoning

- [LLM agent](https://github.com/cooperative-ia/cooperativegpt/blob/main/agent/agent.py): `agent/agent.py`
- [Human agent](https://github.com/cooperative-ia/cooperativegpt/blob/main/agent/human_agent.py): `agent/human_agent.py`
- [Cognitive modules](https://github.com/cooperative-ia/cooperativegpt/tree/main/agent/cognitive_modules): `agent/cognitive_modules`
- [Cooperative understanding](https://github.com/cooperative-ia/cooperativegpt/blob/main/agent/cooperative_modules/understanding.py): `agent/cooperative_modules/understanding.py`
- [Spatial memory](https://github.com/cooperative-ia/cooperativegpt/blob/main/agent/memory_structures/spatial_memory.py): `agent/memory_structures/spatial_memory.py`
- [Short-term memory](https://github.com/cooperative-ia/cooperativegpt/blob/main/agent/memory_structures/short_term_memory.py): `agent/memory_structures/short_term_memory.py`
- [Memory retrieval](https://github.com/cooperative-ia/cooperativegpt/blob/main/agent/cognitive_modules/retrieve.py): `agent/cognitive_modules/retrieve.py`

### Game environment

- [Episode server](https://github.com/cooperative-ia/cooperativegpt/blob/main/game_environment/server.py): `game_environment/server.py`
- [Level play loop](https://github.com/cooperative-ia/cooperativegpt/blob/main/game_environment/playing_utils/level_playing_utils.py): `game_environment/playing_utils/level_playing_utils.py`
- [Game substrates](https://github.com/cooperative-ia/cooperativegpt/tree/main/game_environment/substrates/python): `game_environment/substrates/python`
- [Substrate installer](https://github.com/cooperative-ia/cooperativegpt/blob/main/game_environment/substrates/installer.py): `game_environment/substrates/installer.py`
- [Bot policies](https://github.com/cooperative-ia/cooperativegpt/blob/main/game_environment/bots.py): `game_environment/bots.py`
- [Observation generation](https://github.com/cooperative-ia/cooperativegpt/blob/main/game_environment/scene_descriptor/observations_generator.py): `game_environment/scene_descriptor/observations_generator.py`
- [Scene description](https://github.com/cooperative-ia/cooperativegpt/blob/main/game_environment/scene_descriptor/scene_descriptor.py): `game_environment/scene_descriptor/scene_descriptor.py`
- [Episode recorder](https://github.com/cooperative-ia/cooperativegpt/blob/main/game_environment/recorder/recorder.py): `game_environment/recorder/recorder.py`
- [Simulation replay](https://github.com/cooperative-ia/cooperativegpt/blob/main/game_environment/recorder/recreate_simulation.py): `game_environment/recorder/recreate_simulation.py`

### Memory and model services

- [Long-term memory](https://github.com/cooperative-ia/cooperativegpt/blob/main/agent/memory_structures/long_term_memory.py): `agent/memory_structures/long_term_memory.py`
- [LLM utilities](https://github.com/cooperative-ia/cooperativegpt/blob/main/utils/llm.py): `utils/llm.py`
- [Model adapters](https://github.com/cooperative-ia/cooperativegpt/blob/main/llm/base_llm.py): `llm/base_llm.py`
- [Player interface](https://github.com/cooperative-ia/cooperativegpt/blob/main/utils/player_gui.py): `utils/player_gui.py`
- [Memory persistence](https://github.com/cooperative-ia/cooperativegpt/blob/main/utils/files.py): `utils/files.py`

### Other components

- **Simulation user**

## Connections

- Simulation user → Run configuration: sets options (evidence: `utils/args_handler.py`)
- Run configuration → Simulation runner: configures (evidence: `main.py`)
- Simulation runner → Episode server: starts episode (evidence: `main.py`)
- Episode server → Substrate installer: installs substrate (evidence: `game_environment/server.py`)
- Episode server → Level play loop: runs episode (evidence: `game_environment/server.py`)
- Episode server → Bot policies: initializes bots (evidence: `game_environment/server.py`)
- Episode server → Game substrates: selects game (evidence: `game_environment/server.py`)
- Level play loop → Observation generation: generates observations (evidence: `game_environment/playing_utils/level_playing_utils.py`)
- Level play loop → Scene description: describes scene (evidence: `game_environment/playing_utils/level_playing_utils.py`)
- Level play loop → Episode recorder: records play (evidence: `game_environment/playing_utils/level_playing_utils.py`)
- Episode recorder → Simulation replay: supports replay (evidence: `game_environment/recorder/recorder.py`)
- Simulation runner → LLM agent: runs agents (evidence: `main.py`)
- LLM agent → Cognitive modules: uses reasoning (evidence: `agent/agent.py`)
- LLM agent → Short-term memory: updates memory (evidence: `agent/agent.py`)
- LLM agent → Long-term memory: stores memories (evidence: `agent/agent.py`)
- LLM agent → Spatial memory: plans movement (evidence: `agent/agent.py`)
- LLM agent → Cooperative understanding: uses cooperation (evidence: `agent/agent.py`)
- LLM agent → Memory retrieval: retrieves memories (evidence: `agent/agent.py`)
- Memory retrieval → Long-term memory: queries memories (evidence: `agent/cognitive_modules/retrieve.py`)
- Cognitive modules → LLM utilities: uses prompts (evidence: `agent/cognitive_modules/act.py`)
- LLM utilities → Model adapters: selects model (evidence: `utils/llm.py`)
- Simulation runner → Human agent: optional human play
- Human agent → Player interface: uses interface (evidence: `agent/human_agent.py`)
- Simulation runner → Memory persistence: persists memories (evidence: `main.py`)