WonderEcon: an interactive LLM-agent economic simulation system

🌍 Overview

WonderEcon is a configurable, LLM-driven yet economic-rule-grounded multi-agent simulation system with two integrated components:

• an economic simulation engine, in which households, firms, commercial banks, a central bank, and a government interact across five markets to form a self-consistent macroeconomic loop;
• a player system that enables human-in-the-loop counterfactuals, allowing users to take over an economic agent, override its decisions, and compare the resulting outcomes with those of the original LLM agent.

LLM Decision Pipeline

Each priced economic action follows a four-step natural-language pipeline:

1. Observation: the agent reads its own state and relevant economic information.
2. Belief: the agent forms a free-text economic belief.
3. Price: the agent commits to a desired price, wage, rate, or ratio.
4. Action: the agent makes a final economic decision.

Live Demo

🎮 Click here to play WonderEcon online

_{No installation required — enter Player Mode and take over a household agent directly in your browser.}

Video Demo

▶️ Click here to watch demo

🔥 News

---

Item	Details
Current Version	v0.0.1
Previous Version	v0.0.0
Major Version	v0.0.1
Release Type	Bug Fix
Last Updated	August 4, 2026

Current Version v0.0.1

• Released on August 4, 2026
• This release focuses on frontend modularization, backend API integration, and bug fixes.
• Major changes
  • Frontend
    • Extracted key interface components(Agent Explorer, View Agent.Tick Result, and View Simulation Summary) and map components (god_view_map,routesandperson) into independent components
  • Backend
    • Added a new API module named results_gen
    • Integrated the results_gen APIs into the configuration workflow of the Observer interface
  • Bug fixes
    • Fixed an issue where the Generate Default World Config button failed to generate and apply the default world configuration
    • Added a confirmation dialog to prevent unsaved generated results from being overwritten (Confirm, Generate World Config, results_gen, and results_default), Users can
      • discard and regenerate
      • or view the existing generated result
      • or cancel and continue editing

Previous Version v0.0.0

• Released on July 11, 2026
• Initial project release
• The demo supported the submission of the related research paper and included:
  • an economic simulation engine connecting major economic agents and markets;
  • a player system for taking control of agents and comparing human decisions with LLM-generated decisions.

🚀 Quick Start

Downloads

All related files are distributed through the Releases page. Download the packages you need from there.

File	Description
WonderEcon-code-v0.0.1.zip	Source code of the underlying algorithm engine.
WonderEcon-v0.0.1.zip	Interactive-platform includes "Observe_mode" and "Player_mode".

Requirements

• OS: Windows only (for Interactive Platform)

• Python: Python 3.11 or later is recommended (Add the Python path to your computer's PATH environment variable)

• Dependencies:

  • Python packages:

    pip install camel-ai matplotlib numpy "mcp<2"

  • Node.js (optional, recommended): used only to refresh the building popover data after a simulation run. Without it the system still runs normally — the step fails with a [Popover] Rebuild failed message and the popover keeps showing data from the previous build. Download any recent LTS version from nodejs.org, then verify with:

    node -v

    The script uses only Node built-in modules, so no npm install is needed.

• Using a Python Virtual Environment: By default start_all.bat invokes whichever python is first on your system PATH. If you would rather run WonderEcon inside a dedicated virtual environment (conda, venv, etc.), you can ask an AI assistant to adapt the launcher for you. Example prompt:

  I want to use the Python virtual environment at <path to your environment> to run the WonderEcon program located at <path to WonderEcon>. Please modify start_all.bat accordingly. Point the launcher at the interpreter file named exactly python.exe inside that environment — do not use python3.exe or any other filename, as WonderEcon checks the interpreter's filename.

  Make sure the path ends with python.exe — not any other filename:

  ✅  "\path\to\your\env\python.exe"         (conda)
  ✅  "\path\to\your\env\Scripts\python.exe" (venv)
  ❌  "\path\to\your\env\python3.exe"
  ❌  "\path\to\your\env\python3.12.exe"

  WonderEcon checks the interpreter's filename to tell a normal Python run apart from a packaged build. If the name is anything other than python.exe or pythonw.exe, it silently reads settings.json from the wrong folder (so your API key and model settings are ignored) and writes results into your environment directory instead of the project folder. No error is shown, so this is easy to miss.

Running the Interactive Platform

1. From the Releases page, download and unzip WonderEcon-v0.0.1.zip.
2. Double-click start_all.bat to launch the system.
3. In the system, you can choose to enter Observe mode / Player mode. If you enter the player mode, you need to choose information including economic month, identity and risk preference. And you can play in the WonderEcon world. Once the system opens in observer mode, the quickest way in is to click "Generate Default World Config" at the bottom-right, then click "Enter Observer Console" to go straight into the world.
4. When you are done, return to the terminal window opened by start_all.bat and press any key to stop all services. Do not close the terminal window directly — doing so will leave background processes running.

Algorithm Engine

If you only want the underlying simulation engine (without the interactive front end), download and unzip WonderEcon-code-v0.0.1.zip from the Releases page.

👁️ God's Eye / Observer Mode(Developing)

Configurable Simulation Interface

WonderEcon provides a web-based wizard for configuring:

• agent populations(planned)

  The default showcase world runs 156 agents (140 households, 12 firms, 2 commercial banks, a central bank, and a government) for 13 monthly ticks.
  

• economic policy

  tax rates 
  a clickable interest-rate timeline
  

• macro environment

  the starting economic-background phase
  editable per-tick news
  brand-effect coefficient
  

• technical settings

  the agent LLM model
  temperature
  concurrency
  

Configuration overview:

World Scale Settings	Economic Policy Settings
Macro Environment Settings	Technical Config
Confirm and Generate	Discard Unsaved Changes and View Default World

This flowchart shows the full user flow from launching Observer Mode to viewing the final world state, covering configuration editing, result generation and storage, and confirmation dialogs:

Interactive Economic Map Replay

Once the scenario is configured, WonderEcon advances the economic world through a fixed monthly tick order.

• Each tick follows a structured 25-step simulation procedure, as detailed below, and the process repeats until the simulation horizon is reached.

   Users can:
  - select different agents at different ticks and inspect their complete decision processes.
  - watch the agent's decision process as an animation (through five markets)
  - inspect the same decision records in JSON format
  - compare agent behavior across different ticks
  - track macro economic indicators

Agent Selection	View 5 Scenes
JSON View	Macro Economic Indicator Diagrams

This replay mechanism allows WonderEcon to connect micro-level agent decisions with macro-level economic dynamics.

🎮 Player View / Participant Mode

The Player View turns a completed simulation into a playable counterfactual economic world.
Instead of only observing the system from a global perspective, a human participant can enter the simulated economy, take over one household agent, and make decisions across five economic stations.

Create Your Economic Character

Before entering the economic world, the player selects an entry tick and a target profile by choosing 5 levels of:

• wealth tier
• employment status
• risk preference

The system then matches the player to one household agent and transfers the agent’s full state to the player.

After confirmation, the player enters the economic city and begins interacting with the simulated economy.

Make Decisions on 5 Economic Markets

After choosing the character, the player takes over this household and overrides its original LLM-generated decisions.

You can click guide and hint to view economic environment, market news and get directed to current task:

Across the five economic stations, the player can make decisions on:

Station	Player Decision	Demo
Loan	Eligibility: Labor-force, employed, wealth level ≤ 2, and not receiving government safety-net subsidies. Set a desired loan rate. Choose whether to borrow. If borrowing, set the loan amount (5%–50% of last-tick wage).
Employment	Eligibility: Labor-force players only. Set a desired wage. Choose whether to quit (if employed). Unemployed or quitting players re-enter the labor market.
Consumption	Set desired prices for necessity and luxury goods. Choose the consumption ratio. Allocate spending between necessity and luxury goods.
Stocks	Set desired prices for a necessity and a luxury stock. Choose the investment ratio. Allocate investments between the two stocks. Stocks are cleared by call auction.
Deposits	All remaining assets are automatically deposited. Set only the desired deposit rate to influence bank matching. Deposits have no cap and always succeed.

All other agents’ decisions remain unchanged.
This design creates a clean counterfactual comparison between the human player and the original LLM agent.

Counterfactual Feedback

After the player completes one economic tick, WonderEcon provides feedback on the player’s performance.

The feedback includes:

• Decision Review
• Performance comparison with original agent and group average:
  • asset change
  • happiness measure
• economic personality profile

---

🌟 Economic Personality Type Indicator (EPTI)

WonderEcon’s Player Mode allows users to take control of a household agent, make decisions across five economic stations, and receive one of 16 Economic Personality Type Indicator (EPTI) classifications based on their economic behaviors.

EPTI characterizes a player's economic personality along four dimensions, each with two opposing poles; one representative letter per dimension forms a personality code such as SRCF or APTU.

The system then generates an Economic Personality Type Indicator (EPTI) profile along four dimensions:

Dimension	Poles
Time Preference	Spend vs. Amass
Risk Attitude	Risk-taking vs. Prudent
Market Stance	Contrarian vs. Trend-following
Consumption Taste	Utilitarian vs. Fine

Dimension 1 · Time preference: Spend (S) ↔ Amass (A)

This dimension reflects how the player allocates disposable funds between “enjoying now” and “accumulating for the future.”

• S (Spend): tends to put a higher share of available funds into current consumption, valuing immediate utility and enjoyment, leaving less for saving and investment — “money is for spending, live in the moment.”
• A (Amass): tends to hold down current consumption and keep more funds as deposits or investment, valuing intertemporal security and wealth accumulation, willing to delay gratification — “money is for saving, drop by drop.”

Dimension 2 · Risk attitude: Risk-taking (R) ↔ Prudent (P)

This dimension reflects the player's tolerance for risk and volatility in borrowing, portfolio holdings, and career choices.

• R (Risk-taking): willing to take on leverage through borrowing, hold heavy stock positions, prefer the more volatile luxury stock, and even quit outright to chase a higher wage; pursues high returns and can bear high risk.
• P (Prudent): low debt, light positions, a preference for stable assets, and a tendency to keep the current job; puts capital safety and stability first.

Dimension 3 · Market stance: Contrarian (C) ↔ Trend-following (T)

This dimension reflects whether, in pricing goods and stocks, the player judges independently or follows the crowd relative to peers.

• C (Contrarian): the direction in which desired prices deviate from the market reference is opposite to that of the peer majority; has independent judgment and dares to move against the trend.
• T (Trend-following): the deviation direction of desired prices aligns with the peer majority; follows the market consensus and moves with the crowd.

Dimension 4 · Consumption taste: Utilitarian (U) ↔ Fine (F)

This dimension reflects how the player splits the consumption budget between necessities and luxuries.

• U (Utilitarian): directs more of the consumption budget to necessities, valuing function and costeffectiveness, practicality first.
• F (Fine): directs more of the consumption budget to luxuries, willing to pay a premium for quality and brand “if you buy, buy the best; life should have quality.”

The combination of the first two EPTI dimensions (Time Preference and Risk Attitude) forms the four Core Types：

Each EPTI type is based on the player's revealed economic preferences and represented by a visual character avatar.

Opportunity Seekers · 机会探索者（SR） Spend + Risk-taking personality types Embrace the present, pursue emerging opportunities, and accept uncertainty in search of greater rewards. 享受当下、主动寻找机会，并愿意承担不确定性以争取更高回报。
SRCU Contrarian Hunter 反骨淘金人 Spend · Risk-taking Contrarian · Utilitarian 别人追热闹，我只捡真正值钱的机会。 I look for real value where others aren't looking.	SRCF Contrarian Connoisseur 小众氪金王 Spend · Risk-taking Contrarian · Fine 爆款不香，小众才上头。 I spend on what stands out—not on what stands out to everyone else.	SRTU Trend Rider 爆款冲锋手 Spend · Risk-taking Trend-following · Utilitarian 风来了先上车，好用才是硬道理。 When the market moves, I move with it—as long as it delivers.	SRTF Trend Lover 潮流氪金手 Spend · Risk-taking Trend-following · Fine 追最热的风，买最闪的自己。 I embrace what's trending and enjoy the best it has to offer.
Thoughtful Consumers · 理性消费者（SP） Spend + Prudent personality types Enjoy present consumption while carefully evaluating value, quality, and financial security. 享受当下消费，同时重视实际价值、产品质量与财务安全。
SPCU Smart Shopper 省心买买侠 Spend · Prudent Contrarian · Utilitarian 爱买，但每一分钱都要花得明明白白。 I enjoy spending, but every purchase has to make sense.	SPCF Quality Seeker 质感慢买家 Spend · Prudent Contrarian · Fine 不急着下单，只等真正心动的质感。 I spend patiently, waiting for quality that's truly worth it.	SPTU Consensus Shopper 口碑种草官 Spend · Prudent Trend-following · Utilitarian 大家都说值，我才安心入手。 I trust the crowd when it's time to spend.	SPTF Careful Trend Follower 精致稳稳党 Spend · Prudent Trend-following · Fine 精致可以有，但风险不能有。 I enjoy quality while staying safely with the crowd.
Strategic Investors · 战略投资者（AR） Amass + Risk-taking personality types Prioritize future wealth while accepting calculated risks and investing in promising opportunities. 重视未来财富积累，并愿意通过承担经过判断的风险把握成长机会。
ARCU Contrarian Investor 冷门抄底王 Amass · Risk-taking Contrarian · Utilitarian 别人看不懂的时刻，我已经悄悄上车。 I invest where others hesitate.	ARCF Patient Collector 小众收藏家 Amass · Risk-taking Contrarian · Fine 平时不乱花，出手只买长期心动。 I save patiently and spend only on lasting value.	ARTU Opportunity Rider 风口上车党 Amass · Risk-taking Trend-following · Utilitarian 日常不乱买，趋势来了必须冲。 I save for the right moment, then ride the trend.	ARTF Future Investor 赛道氪金手 Amass · Risk-taking Trend-following · Fine 看准赛道就加仓，钱要花在未来感上。 I invest where I believe the future is headed.
Steady Planners · 稳健规划者（AP） Amass + Prudent personality types Build wealth gradually, avoid unnecessary risks, and prioritize long-term stability and security. 通过稳步积累财富、减少不必要的风险，追求长期稳定与安全感。
APCU Rational Navigator 理智掌舵人 Amass · Prudent Contrarian · Utilitarian 不被消费主义牵绊的一生。 I'd rather build wealth than chase consumption.	APCF Thoughtful Minimalist 低调质感派 Amass · Prudent Contrarian · Fine 钱要慢慢赚，品味要偷偷长。 I save steadily while quietly appreciating quality.	APTU Steady Saver 人间存钱罐 Amass · Prudent Trend-following · Utilitarian 余额给我安全感，比任何爆款都上头。 Growing my savings is more satisfying than following trends.	APTF Refined Saver 精致存钱家 Amass · Prudent Trend-following · Fine 一边认真存钱，一边认真生活。 I believe saving wisely and living well can go together.

📊 Evaluation Highlights

We evaluate WonderEcon from two complementary perspectives.

• In Macro-Level Validity, we test whether the agents’ emergent responses match the stylized facts of monetary tightening.
• In the User Study, we assess the usability of the player platform and the perceived accuracy of the Economic Personality Type Indicator (EPTI) through a preliminary participant evaluation.

Macro Validity

Across four LLM backends, the system reproduces six well-known economic principles under an interest-rate hiking cycle.

Table . Macro-validity targets. Each row verifies an economic principle under the interest-rate-hiking scenario.

Economic Principle	Indicator(s)	Predicted Response
Dividend-Discount Model (DDM)	Stock price	Stock price declines
Okun's Law	Employment rate; GDP	Employment and GDP both decline
Credit Channel	Loan volume	Loan volume contracts
Intertemporal Substitution (Euler)	Deposit volume	Deposit volume rises
IS Curve	GDP	GDP growth slows or GDP declines
Phillips Curve	Goods prices; employment rate	Inflation slows as employment falls

Table . Principle-verification results across LLM backends.

Economic Principle	Claude-Sonnet-4.6	GPT-4o	Gemini-3.1-Flash-Lite	Grok-4.1-Fast
Dividend-Discount Model (DDM)	10/10	10/10	10/10	10/10
Okun's Law	8/10	10/10	10/10	9/10
Credit Channel	10/10	10/10	10/10	9/10
Intertemporal Substitution (Euler)	10/10	10/10	10/10	10/10
IS Curve	10/10	10/10	10/10	10/10
Phillips Curve	8/10	9/10	10/10	9/10
Overall	56/60	59/60	60/60	57/60

Each cell reports the number of runs, out of ten, in which the emergent trend matches the theoretical prediction defined above.

User Study

we evaluate the player platform with 33 participants who each complete one play session. Each participant completed one full play session.

During the session, participants

• controlled a household agent
• made economic decisions across the available market stations
• reviewed the resulting counterfactual outcomes
• received an EPTI profile.

After completing the session, participants rated the system on a five-point Likert scale including three usability dimensions, three experience dimensions, the perceived accuracy of the four EPTI axes, and overall satisfaction.

🏠 Hall of Supporters：

Developed by：

Jing Qian, Boyu Liu, Wenyuan Gu, Hang Ruan, Cheng Huo, Junjie Yang, Mingyu Deng, Zhen Xu, Feilin Li, Jiale Han, Benyou Wang