Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/salesforce/ai-economist/llms.txt

Use this file to discover all available pages before exploring further.

The Build component (registry name "Build") allows BasicMobileAgent instances to spend one unit each of Wood and Stone to construct a House landmark on their current tile, receiving a coin payment in return. Building has a configurable labor cost and supports heterogeneous skill levels that modify each agent’s payout.
The agent must be standing on an empty tile — no existing landmark or resource — and must possess the required resources in their inventory before the build action takes effect.

​
Constructor parameters

​
payment
int
default:"10"
Base amount of Coin an agent receives for successfully building a house. Must be >= 0.
​
payment_max_skill_multiplier
int
default:"1"
Upper bound on the skill multiplier applied to payment. Must be >= 1. When set above 1, skilled agents can earn up to payment * payment_max_skill_multiplier per build.
​
skill_dist
string
default:"none"
Distribution used to sample each agent’s build skill at episode reset.
ValueBehavior
"none"All agents use a multiplier of 1 (uniform skill)
"pareto"Multipliers sampled from a Pareto distribution
"lognormal"Multipliers sampled from a log-normal distribution
​
build_labor
float
default:"10.0"
Labor units charged to agent.state["endogenous"]["Labor"] each time a house is successfully built. Must be >= 0.

​
Resource cost

Building a house always consumes exactly:
ResourceAmount
Wood1 unit
Stone1 unit
These costs are fixed and defined in self.resource_cost = {"Wood": 1, "Stone": 1}. Required world entities: Wood, Stone, Coin, House, Labor.

​
Action space

This component adds 1 discrete action for each BasicMobileAgent:
Action indexMeaning
0No-op — do nothing
1Attempt to build a house at the current tile

​
Building sequence

When an agent takes action 1, component_step() calls agent_can_build() to verify all preconditions, then:
  1. Deducts 1 Wood and 1 Stone from the agent’s inventory.
  2. Calls world.create_landmark("House", row, col, agent.idx) to place the landmark.
  3. Adds agent.state["build_payment"] (the skill-adjusted coin amount) to the agent’s inventory.
  4. Charges build_labor to agent.state["endogenous"]["Labor"].

​
Build preconditions

agent_can_build() returns True only when all three conditions hold:
  • The agent has >= 1 Wood in inventory.
  • The agent has >= 1 Stone in inventory.
  • The current tile contains no existing resource or landmark.

​
Agent state fields

This component adds the following state fields to every BasicMobileAgent:
​
build_payment
float
Effective coin payout for the next build action. Initialized to payment and updated each episode reset according to the sampled skill multiplier.
​
build_skill
float
Raw sampled skill value (before clamping). Initialized to 1.

​
Observations

Agents observe their own normalized build skill. The planner receives nothing from this component.
​
build_payment
float
Agent’s current build_payment normalized by the base payment value.
​
build_skill
float
The raw sampled skill value stored in sampled_skills[agent.idx].

​
Action masks

The single build action is masked to 0 whenever agent_can_build() returns False (insufficient resources or tile already occupied). It is unmasked (1) otherwise.

​
Metrics

get_metrics() returns a dict with per-agent build counts and a total:
​
{agent_idx}/n_builds
int
Number of successful builds by this agent over the episode.
​
total_builds
int
Total number of House landmarks currently on the map (world.maps.get("House") > 0).

​
Dense log

get_dense_log() returns a list (one entry per timestep) of build-event lists. Each build event is a dict:
​
builder
int
Agent index that performed the build.
​
loc
ndarray
[row, col] location where the house was placed.
​
income
float
Coin payment received for this build.

​
Skill sampling

At every episode reset additional_reset_steps() re-samples each agent’s skill:
skill sampling
PMSM = payment_max_skill_multiplier

# skill_dist == "pareto"
sampled_skill = np.random.pareto(4)
pay_rate = np.minimum(PMSM, (PMSM - 1) * sampled_skill + 1)

# skill_dist == "lognormal"
sampled_skill = np.random.lognormal(-1, 0.5)
pay_rate = np.minimum(PMSM, (PMSM - 1) * sampled_skill + 1)

agent.state["build_payment"] = float(pay_rate * payment)
agent.state["build_skill"] = float(sampled_skill)

​
Example usage

env_config = {
    "components": [
        {
            "Build": {
                "payment": 10,
                "payment_max_skill_multiplier": 3,
                "skill_dist": "lognormal",
                "build_labor": 10.0,
            }
        }
    ]
}

Build docs developers (and LLMs) love

Get started for freeTalk to us