Interactive Demo
================

A live interactive demo of EconSimulacra is available at:

   **https://econsimulacra.onrender.com**

No installation or API key is required.  The demo replays a pre-recorded
simulation log in your browser, letting you explore agent behavior, market
dynamics, and social network formation in real time.

Overview
--------

The demo GUI consists of five panels.

**Grid Map**
   Shows agents moving on a 10 × 10 spatial grid.  Each agent is represented
   by an emoji that reflects its current stress level:

   - 😊 calm (avg stress ≤ 25)
   - 😐 normal (avg stress ≤ 50)
   - 😟 stressed (avg stress ≤ 75)
   - 😫 max stress (avg stress > 75)
   - 😴 sleeping

   Stores are shown as 🏪 (retailer) or 🍕 (restaurant).  When a transaction
   is completed, a popup appears above the store showing the item name and
   total quantity sold in that time step (e.g. ``Rice x12``).  Click any agent
   to select it and see its name and details in the Agent Inspector.

**Social Network**
   Displays follow relationships between agents as a force-directed graph.
   Nodes are emoji icons (same stress-based faces as the Grid Map).
   Directed edges show who follows whom; arrowheads point toward the
   followed agent.  Click a node to inspect the agent.

**Macro Dashboard**
   Time-series charts of aggregate statistics:

   - Average household wealth
   - Item prices over time
   - Orders and tweets per step

   The horizontal axis shows calendar time when available, and falls back to
   step number otherwise.

**Agent Inspector** *(right sidebar)*
   Detailed state of the selected agent: name, wealth, inventory, stress
   breakdown by category, last inner thought, and last tweet.

**Event Feed** *(right sidebar)*
   A scrolling stream of recent simulation events (moves, orders, tweets,
   follows, etc.).

Playback Controls
-----------------

The toolbar at the top provides the following controls.

.. list-table::
   :widths: 25 75

   * - Play / Pause
     - Start or pause the replay.
   * - Skip Forward
     - Jump ahead 10 steps.
   * - Speed selector
     - Set the replay speed (0.5× – 20×).
   * - Seek bar
     - Drag to any position.  Dragging backward automatically resumes
       playback from the new position, even after the simulation has ended.
   * - Time display
     - Shows the current calendar time (e.g. ``2025-12-19 11:00``) when
       the log contains timestamps, otherwise shows the step counter.

Using Your Own Log File
-----------------------

You can replay any EconSimulacra log file generated by your own simulation.

1. Run your simulation and save the log:

   .. code-block:: bash

      export LOG_TXT_PATH="my_simulation.txt"
      cd examples/openai
      python main.py

2. Open https://econsimulacra.onrender.com in your browser.
3. Click **Upload log file** and select your ``my_simulation.txt``.
4. The GUI will parse the log and start the replay automatically.

.. note::

   The demo server accepts ``.txt`` log files up to 200 MB.  For large logs,
   consider using the :ref:`local GUI server <running-locally>` instead.

.. _running-locally:

Running the GUI Locally
-----------------------

To run the GUI server on your own machine:

.. code-block:: bash

   cd gui
   bash start.sh

This builds the React frontend and starts a FastAPI server at
``http://localhost:8000``.  The server automatically loads
``gui/demo_log.txt`` as the default log if present.