Configuration Reference

All simulation settings are stored in a single JSON (or Python dict) that is passed to Simulator. This page documents every top-level key and their required / optional sub-keys.

Top-Level Structure

{
    "simulation": { ... },
    "environment": { ... },
    "<spaceName>": { ... },
    "<socialNetworkName>": { ... },
    "<agentName>": { ... },
    "<itemName>": { ... },
    "<serviceName>": { ... },
    "<eventName>": { ... }
}

Simulation Configuration

Controls the overall simulation run.

Key	Required	Description
numSteps	✓	Total number of environment steps to execute.
parallelBatchSize		Number of agents that call act() concurrently per step. Defaults to 1 (sequential).
events		List of event configuration keys. Each key must appear as a top-level entry in the config.

Environment Configuration

Declares the components that make up the simulation world.

Key	Required	Description
space	✓	Key of the grid-space configuration block.
socialNetwork	✓	Key of the social-network configuration block.
cashName	✓	Name of the item that acts as the numéraire (e.g., "Yen"). Must appear in items.
agents	✓	List of agent configuration keys.
items	✓	List of item configuration keys. Must include cashName.
service		List of service configuration keys (e.g., "llmClient").

Space Configuration

"gridSpace": {
    "type": "GridSpace",
    "gridSize": [50, 50]
}

Key	Required	Description
type	✓	Class name — use "GridSpace" for the built-in implementation.
gridSize	✓	[width, height] of the 2-D discrete grid.

Social Network Configuration

"socialNetwork": {
    "type": "SocialNetwork",
    "followCap": 3,
    "recSys": {
        "type": "TwoHopRecommenderSystem",
        "maxRecommendations": 2,
        "isRandomized": true,
        "temperature": 0.4
    }
}

Key	Required	Description
type	✓	Class name — use "SocialNetwork" for the built-in implementation.
followCap		Maximum number of agents a single agent may follow. Omit for no limit.
recSys		Recommender-system configuration block (see below).

recSys sub-keys:

Key	Required	Description
type	✓	Recommender-system class name (e.g., "TwoHopRecommenderSystem").
maxRecommendations		Maximum number of follow suggestions per step.
isRandomized		Whether suggestions are sampled probabilistically.
temperature		Softmax temperature \(\tau\) used when isRandomized is true. Higher \(\tau\) → more uniform sampling.

Agent Configuration

Each agent key maps to a block that configures all agents of that type:

"Household": {
    "type": "LLMAgent",
    "isHousehold": true,
    "numAgents": 118,
    "inventory": {
        "Yen": [100000, 200000],
        "Rice": [3, 10]
    }
}

Key	Required	Description
type	✓	Agent class name registered with the simulator.
isHousehold		If true, the agent can move on the grid. If false (firm / retailer), the agent can set item prices. Defaults to false.
numAgents		Number of instances to create. Defaults to 1.
inventory		Initial inventory. Each value is either a fixed number or a [min, max] range drawn uniformly at reset.
requestObs		List of observation keys the agent requests from the environment. Use ["all"] to request everything available.
provideInfo4AllAgents		List of information keys this agent broadcasts to every other agent (e.g., ["self_pos"]).
provideInfo4CoLocatedAgents		List of information keys shared only with co-located agents (e.g., ["inventory"]).
isRichInfoAllowed		If true, the agent receives market-price information. Defaults to false.

Item Configuration

"Rice": {
    "type": "Item",
    "initialPrice": 1000.0
}

Key	Required	Description
type		Item class name. Defaults to the item key name.
initialPrice		Initial market price \(p_0\). Defaults to 0.0.

Event Configuration

"provideSubsidy": {
    "type": "SubsidyEvent",
    "trigger": {
        "every": 30,
        "probability": 1.0
    },
    "subsidyAmount": 50000
}

trigger sub-keys:

Key	Required	Description
at		Tuple of step indices at which to fire the event.
every		Period \(k\); the event fires at steps \(k, 2k, 3k, \ldots\)
between		[start, end] — the event is only eligible within this step range.
with		List of Log class names; the event fires whenever one of these log entries is produced.
probability		Probability \(p \in [0, 1]\) with which the event fires on each eligible step. Defaults to 1.0.