# shuhui-zhu/align architecture

> Architecture diagram of the GitHub repository shuhui-zhu/align, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shuhui-zhu/align
- Repository: https://github.com/shuhui-zhu/align

## Overview

ALIGN runs configurable repeated-game simulations in four domains: donation, Prisoner’s Dilemma, trust, and product-choice markets. The user selects a game and model/API in Hydra configuration; main.py constructs a provider client and dispatches to that game’s runner. Runners coordinate game environments and agents, which use game-specific prompts to obtain decisions from an LLM; gossip-enabled play adds public reputation messages to later decisions. Simulation results are written to JSON logs, with README-documented Weights & Biases logging. Some runner and environment excerpts were unavailable, so uncertain internal wiring is omitted.

Main entry points: [`main.py`](https://github.com/shuhui-zhu/align/blob/main/main.py) (Simulation entry), [`scenarios/donor/runner.py`](https://github.com/shuhui-zhu/align/blob/main/scenarios/donor/runner.py) (Donation runner), [`scenarios/pd/runner.py`](https://github.com/shuhui-zhu/align/blob/main/scenarios/pd/runner.py) (PD runner), [`scenarios/trust/runner.py`](https://github.com/shuhui-zhu/align/blob/main/scenarios/trust/runner.py) (Trust runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Configuration & dispatch"]
  node_config["Experiment config<br/>[config.yaml]"]
  node_gameconfigs["Game settings"]
  node_entry["Simulation entry<br/>[main.py]"]
end

subgraph group_games["Game simulation"]
  node_donor_run["Donation runner<br/>[runner.py]"]
  node_donor_env["Donation environment<br/>[env.py]"]
  node_pd_run["PD runner<br/>[runner.py]"]
  node_pd_env["PD environment<br/>[env.py]"]
  node_trust_run["Trust runner<br/>[runner.py]"]
  node_trust_env["Trust environment<br/>[env.py]"]
  node_market_run["Market runner<br/>[runner.py]"]
  node_market_env["Market environment<br/>[env.py]"]
end

subgraph group_decision["Agent decisions"]
  node_donor_agent["Donation agents<br/>[agent.py]"]
  node_donor_prompt["Donation prompts<br/>[prompt.py]"]
  node_pd_agent["PD agents<br/>[agent.py]"]
  node_pd_prompt["PD prompts<br/>[prompt.py]"]
  node_trust_agent["Trust agents<br/>[agent.py]"]
  node_trust_prompt["Trust prompts<br/>[prompt.py]"]
  node_market_agent["Market agents<br/>[agent.py]"]
  node_market_prompt["Market prompts<br/>[prompt.py]"]
end

subgraph group_results["Results &amp; services"]
  node_llm{{"LLM providers"}}
  node_jsonlog[("Simulation JSON")]
  node_wandb{{"Weights &amp; Biases"}}
end

node_user(("Experiment user"))

node_user -->|"sets parameters"| node_config
node_config -->|"loads settings"| node_entry
node_gameconfigs -->|"supplies game settings"| node_entry
node_entry -->|"creates client"| node_llm
node_entry -->|"dispatches"| node_donor_run
node_entry -->|"dispatches"| node_pd_run
node_entry -->|"dispatches"| node_trust_run
node_entry -->|"dispatches"| node_market_run
node_donor_run -->|"uses game state"| node_donor_env
node_donor_run -->|"initializes agents"| node_donor_agent
node_donor_run -->|"builds rules"| node_donor_prompt
node_donor_agent -->|"uses prompts"| node_donor_prompt
node_donor_agent -->|"requests decisions"| node_llm
node_pd_run -->|"uses game state"| node_pd_env
node_pd_run -->|"initializes agents"| node_pd_agent
node_pd_run -->|"builds rules"| node_pd_prompt
node_pd_agent -->|"uses prompts"| node_pd_prompt
node_pd_agent -->|"requests decisions"| node_llm
node_trust_run -->|"uses game state"| node_trust_env
node_trust_run -->|"initializes agents"| node_trust_agent
node_trust_run -->|"builds prompts"| node_trust_prompt
node_trust_agent -->|"uses prompts"| node_trust_prompt
node_trust_agent -->|"requests decisions"| node_llm
node_market_run -->|"uses game state"| node_market_env
node_market_run -->|"initializes agents"| node_market_agent
node_market_run -->|"builds prompts"| node_market_prompt
node_market_agent -->|"uses prompts"| node_market_prompt
node_market_agent -->|"requests decisions"| node_llm
node_donor_run -->|"writes results"| node_jsonlog
node_pd_run -->|"writes results"| node_jsonlog
node_trust_run -->|"writes results"| node_jsonlog
node_market_run -->|"writes results"| node_jsonlog
node_donor_run -.->|"logs metrics"| node_wandb
node_pd_run -.->|"logs metrics"| node_wandb
node_trust_run -.->|"logs metrics"| node_wandb
node_market_run -.->|"logs metrics"| node_wandb

click node_config "https://github.com/shuhui-zhu/align/blob/main/conf/config.yaml"
click node_gameconfigs "https://github.com/shuhui-zhu/align/tree/main/conf/experiment"
click node_entry "https://github.com/shuhui-zhu/align/blob/main/main.py"
click node_donor_run "https://github.com/shuhui-zhu/align/blob/main/scenarios/donor/runner.py"
click node_donor_env "https://github.com/shuhui-zhu/align/blob/main/scenarios/donor/env.py"
click node_pd_run "https://github.com/shuhui-zhu/align/blob/main/scenarios/pd/runner.py"
click node_pd_env "https://github.com/shuhui-zhu/align/blob/main/scenarios/pd/env.py"
click node_trust_run "https://github.com/shuhui-zhu/align/blob/main/scenarios/trust/runner.py"
click node_trust_env "https://github.com/shuhui-zhu/align/blob/main/scenarios/trust/env.py"
click node_market_run "https://github.com/shuhui-zhu/align/blob/main/scenarios/market/runner.py"
click node_market_env "https://github.com/shuhui-zhu/align/blob/main/scenarios/market/env.py"
click node_donor_agent "https://github.com/shuhui-zhu/align/blob/main/scenarios/donor/agent.py"
click node_donor_prompt "https://github.com/shuhui-zhu/align/blob/main/scenarios/donor/prompt.py"
click node_pd_agent "https://github.com/shuhui-zhu/align/blob/main/scenarios/pd/agent.py"
click node_pd_prompt "https://github.com/shuhui-zhu/align/blob/main/scenarios/pd/prompt.py"
click node_trust_agent "https://github.com/shuhui-zhu/align/blob/main/scenarios/trust/agent.py"
click node_trust_prompt "https://github.com/shuhui-zhu/align/blob/main/scenarios/trust/prompt.py"
click node_market_agent "https://github.com/shuhui-zhu/align/blob/main/scenarios/market/agent.py"
click node_market_prompt "https://github.com/shuhui-zhu/align/blob/main/scenarios/market/prompt.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_config,node_gameconfigs,node_entry,node_user toneBlue
class node_donor_run,node_donor_env,node_pd_run,node_pd_env,node_trust_run,node_trust_env,node_market_run,node_market_env toneAmber
class node_donor_agent,node_donor_prompt,node_pd_agent,node_pd_prompt,node_trust_agent,node_trust_prompt,node_market_agent,node_market_prompt toneMint
class node_llm,node_jsonlog,node_wandb toneRose
```

## Components

### Configuration & dispatch

- [Experiment config](https://github.com/shuhui-zhu/align/blob/main/conf/config.yaml): `conf/config.yaml`
- [Game settings](https://github.com/shuhui-zhu/align/tree/main/conf/experiment): `conf/experiment`
- [Simulation entry](https://github.com/shuhui-zhu/align/blob/main/main.py): `main.py`

### Game simulation

- [Donation runner](https://github.com/shuhui-zhu/align/blob/main/scenarios/donor/runner.py): `scenarios/donor/runner.py`
- [Donation environment](https://github.com/shuhui-zhu/align/blob/main/scenarios/donor/env.py): `scenarios/donor/env.py`
- [PD runner](https://github.com/shuhui-zhu/align/blob/main/scenarios/pd/runner.py): `scenarios/pd/runner.py`
- [PD environment](https://github.com/shuhui-zhu/align/blob/main/scenarios/pd/env.py): `scenarios/pd/env.py`
- [Trust runner](https://github.com/shuhui-zhu/align/blob/main/scenarios/trust/runner.py): `scenarios/trust/runner.py`
- [Trust environment](https://github.com/shuhui-zhu/align/blob/main/scenarios/trust/env.py): `scenarios/trust/env.py`
- [Market runner](https://github.com/shuhui-zhu/align/blob/main/scenarios/market/runner.py): `scenarios/market/runner.py`
- [Market environment](https://github.com/shuhui-zhu/align/blob/main/scenarios/market/env.py): `scenarios/market/env.py`

### Agent decisions

- [Donation agents](https://github.com/shuhui-zhu/align/blob/main/scenarios/donor/agent.py): `scenarios/donor/agent.py`
- [Donation prompts](https://github.com/shuhui-zhu/align/blob/main/scenarios/donor/prompt.py): `scenarios/donor/prompt.py`
- [PD agents](https://github.com/shuhui-zhu/align/blob/main/scenarios/pd/agent.py): `scenarios/pd/agent.py`
- [PD prompts](https://github.com/shuhui-zhu/align/blob/main/scenarios/pd/prompt.py): `scenarios/pd/prompt.py`
- [Trust agents](https://github.com/shuhui-zhu/align/blob/main/scenarios/trust/agent.py): `scenarios/trust/agent.py`
- [Trust prompts](https://github.com/shuhui-zhu/align/blob/main/scenarios/trust/prompt.py): `scenarios/trust/prompt.py`
- [Market agents](https://github.com/shuhui-zhu/align/blob/main/scenarios/market/agent.py): `scenarios/market/agent.py`
- [Market prompts](https://github.com/shuhui-zhu/align/blob/main/scenarios/market/prompt.py): `scenarios/market/prompt.py`

### Results & services

- **LLM providers**
- **Simulation JSON**
- **Weights & Biases**

### Other components

- **Experiment user**

## Connections

- Experiment user → Experiment config: sets parameters
- Experiment config → Simulation entry: loads settings
- Game settings → Simulation entry: supplies game settings
- Simulation entry → LLM providers: creates client
- Simulation entry → Donation runner: dispatches
- Simulation entry → PD runner: dispatches
- Simulation entry → Trust runner: dispatches
- Simulation entry → Market runner: dispatches
- Donation runner → Donation environment: uses game state
- Donation runner → Donation agents: initializes agents
- Donation runner → Donation prompts: builds rules
- Donation agents → Donation prompts: uses prompts
- Donation agents → LLM providers: requests decisions
- PD runner → PD environment: uses game state
- PD runner → PD agents: initializes agents
- PD runner → PD prompts: builds rules
- PD agents → PD prompts: uses prompts
- PD agents → LLM providers: requests decisions
- Trust runner → Trust environment: uses game state
- Trust runner → Trust agents: initializes agents
- Trust runner → Trust prompts: builds prompts
- Trust agents → Trust prompts: uses prompts
- Trust agents → LLM providers: requests decisions
- Market runner → Market environment: uses game state
- Market runner → Market agents: initializes agents
- Market runner → Market prompts: builds prompts
- Market agents → Market prompts: uses prompts
- Market agents → LLM providers: requests decisions
- Donation runner → Simulation JSON: writes results
- PD runner → Simulation JSON: writes results
- Trust runner → Simulation JSON: writes results
- Market runner → Simulation JSON: writes results
- Donation runner → Weights & Biases: logs metrics
- PD runner → Weights & Biases: logs metrics
- Trust runner → Weights & Biases: logs metrics
- Market runner → Weights & Biases: logs metrics