econsimulacra 0.1.1__tar.gz

econsimulacra-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SimulacraBusiness
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

econsimulacra-0.1.1/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.1
+Name: econsimulacra
+Version: 0.1.1
+Summary: EconSimulacra: A Digital Twin Platform of Consumer Economy Powered by LLM Agents
+Home-page: https://github.com/SimulacraBusiness/econsimulacra
+License: MIT
+Author: Ryuji Hashimoto
+Author-email: r_hashimoto@simulacra.co.jp
+Requires-Python: >=3.10,<3.13
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Dist: accelerate (>=1.12.0,<2.0.0)
+Requires-Dist: datasets (>=4.5.0,<5.0.0)
+Requires-Dist: numpy (>=1.26.1,<2.0.0)
+Requires-Dist: openai (>=2.21.0,<3.0.0)
+Requires-Dist: outlines (==0.1.11)
+Requires-Dist: protobuf (>=7.34.0,<8.0.0)
+Requires-Dist: rich (>=14.2.0,<15.0.0)
+Requires-Dist: sentencepiece (>=0.2.1,<0.3.0)
+Requires-Dist: statsmodels (>=0.14.6,<0.15.0)
+Requires-Dist: torch (==2.2.1)
+Requires-Dist: transformers (>=4.49.0,<5.0.0)
+Requires-Dist: types-tqdm (>=4.67.3.20260205,<5.0.0.0)
+Requires-Dist: typing-extensions (>=4.15.0,<5.0.0)
+Project-URL: Repository, https://github.com/SimulacraBusiness/econsimulacra
+Description-Content-Type: text/markdown
+
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+<p align="center">
+  <img src="imgs/SimpleGridAnimator.gif" width="48%" />
+  <img src="imgs/SimpleSocialAnimator.gif" width="48%" />
+</p>
+
+
+EconSimulacra is a simulation platform for studying complex socio-economic systems with large language model (LLM) agents. The framework enables researchers and practitioners to simulate:
+
+- household consumption
+- firm pricing strategies
+- narrative diffusion through social networks
+- spatial mobility of agents
+
+By combining agent-based modeling with LLM reasoning, EconSimulacra allows researchers to study emergent macroeconomic phenomena from micro-level behavioral rules.
+
+# Key Features
+
+- 🧠 LLM-driven agents with internal states and reasoning
+- 🏙 Spatial grid environments with agent mobility
+- 🛒 Market interactions (consumption, pricing)
+- 🌐 Social network dynamics (follow, unfollow, narrative diffusion)
+- 📊 Structured simulation logs for analysis
+- ⚡ Parallel simulation execution
+- 🧩 Modular architecture for extensibility
+
+# Conceptual Architecture
+
+EconSimulacra consists of the following main components:
+
+<p align="center">
+  <img src="imgs/framework_structure.png" width="100%" />
+</p>
+
+## [**Simulator**](https://github.com/SimulacraBusiness/econsimulacra/blob/main/src/econsimulacra/simulator.py) 
+
+The **Simulator** executes the simulation, manages temporal progression, and supports parallel execution. At each simulation step, the simulator collects actions from all agents based on their observations and applies them to the environment. The core logic of the simulator is conceptually as follows.
+
+```python
+num_steps: int
+for _ in range(num_steps):
+    all_actions_dic = {}
+    for agent_id in env.agent_ids:
+        agent = self.env.agent_id2agent[agent_id]
+        obs = self.env.get_observations(agent_id=agent_id)
+        action_dic = agent.act(obs)
+        all_actions_dic[agent_id] = action_dic
+    self.env.step(all_actions_dic)
+```
+
+In each step:
+1. The environment provides observations to each agent ```env.get_observations(agent_id=agent_id)```
+2. Agents decide their actions based on these observations ```action_dic = agent.act(obs)```
+3. The environment updates the global state according to the agents' actions. ```env.step(all_actions_dic)```
+
+The Simulator requires ```config``` to apply your simulation settings. See [examples/openai/config.json](https://github.com/SimulacraBusiness/econsimulacra/blob/main/examples/openai/config.json) for an example.
+
+```Python
+simulator = Simulator(
+    config=config_dic_path,
+    env_class=Environment,
+    logger=logger,
+    summarizer_class=SimulationSummarizer,
+)
+```
+
+You can introduce your custom classes in your simulation by specifying ```"type": "MyClass"``` in the config and register them to the Simulator. [examples/openai/main.py](https://github.com/SimulacraBusiness/econsimulacra/blob/main/examples/openai/main.py) provides an example to introduce the custom event ```SubsidyEvent```.
+
+```python
+simulator.register_classes([MyClass1, MyClass2])
+```
+
+
+## [**Environment**](https://github.com/SimulacraBusiness/econsimulacra/blob/main/src/econsimulacra/envs/base.py)
+
+The **Environment** manages the global state of the simulated world, including the internal states of all agents. It is responsible for:
+
+- providing observations to agents (```.get_observations```)
+- applying agents’ actions and updating the world state (```.step```)
+
+The environment includes multiple submodules, such as:
+
+- [**GridSpace**](https://github.com/SimulacraBusiness/econsimulacra/blob/main/src/econsimulacra/envs/space.py): A spatial environment in which agents reside and move. This allows the simulation of spatial interactions, mobility, and location-dependent behaviors.
+- [**SocialNetwork**](https://github.com/SimulacraBusiness/econsimulacra/blob/main/src/econsimulacra/envs/social_networks/base.py): A communication layer where agents can exchange messages and interact socially, enabling the study of information diffusion and social influence. The social network also includes a customizable [**RecommenderSystem**](https://github.com/SimulacraBusiness/econsimulacra/blob/main/src/econsimulacra/envs/social_networks/recsys.py) that can suggest other agents to follow.
+
+## [**Agent**](https://github.com/SimulacraBusiness/econsimulacra/blob/main/src/econsimulacra/agents/base.py)
+
+An **Agent** represents an autonomous decision-maker in the simulation Agents receive structured observations from the environment and determine their actions (```.act```). 
+
+The information available to each agent, both as observations received from the environment and as information disclosed to other agents, is fully configurable via the agent configuration. For example, ```requestObs``` field defines what an agent can perceive from the environment, while ```provideInfo*``` fields define what an agent reveals to others.
+
+EconSimulacra provides a built-in [**LLMAgent**](https://github.com/SimulacraBusiness/econsimulacra/blob/main/src/econsimulacra/agents/llm_agent.py) implementation that leverages LLMs to generate agent behaviors. To ensure reliable and stable simulations, agent actions are generated as structured outputs using [Outlines](https://pypi.org/project/outlines/0.1.11/), which enforces predefined schemas for the generated actions.
+
+The LLM-based agent system is modular and consists of several customizable submodules:
+
+- [**LLMClient**](https://github.com/SimulacraBusiness/econsimulacra/blob/main/src/econsimulacra/llm_services/clients/base.py) – manages the underlying language model and inference settings
+- [**PersonaBuilder**](https://github.com/SimulacraBusiness/econsimulacra/blob/main/src/econsimulacra/llm_services/personas/base.py) – assigns role-playing personas to agents
+- [**PromptBuilder**](https://github.com/SimulacraBusiness/econsimulacra/blob/main/src/econsimulacra/llm_services/prompts/base.py) – constructs prompts used for agent reasoning
+- [**MemoryHandler**](https://github.com/SimulacraBusiness/econsimulacra/blob/main/src/econsimulacra/envs/memory.py) - stores and provides each agent the sequence of their experience in the past time steps as memory
+
+By customizing these components, users can easily modify LLM configurations and experiment with different prompting strategies, personas, and model backends without changing the core simulation logic.
+
+## [**Event**](https://github.com/SimulacraBusiness/econsimulacra/blob/main/src/econsimulacra/envss/event.py)
+
+An **EventManager** is responsible for managing events and triggering them at appropriate times during the simulation. Events can be scheduled based on:
+
+- specific timestamps, (```at```)
+- time intervals or durations, (```between```)
+- periodic execution (e.g., every k steps), (```every```)
+- or the occurrence of specific logs (e.g., when a transaction is generated). (```with```)
+
+You can also adapt probabilistic triggering via ```probability```. By registering custom events, users can introduce exogenous dynamics into the simulation, such as policy interventions or regime shifts, in a flexible and extensible manner.
+
+# Basic Usage
+
+## OpenAI API
+
+This section explains how to run EconSimulacra using the [OpenAI API](https://openai.com/index/openai-api/), based on the example in ```examples/openai```.
+
+### 1. Set OpenAI API Key
+
+You need to provide your OpenAI API key in one of the following ways:
+
+**Option A: Environment Variable (recommended)**
+
+```bash
+export OPENAI_API_KEY="your_api_key"
+```
+
+**Option B: ```config.json```**
+
+```json
+{
+    "llmClient": {
+        "type": "OpenAIClient",
+        "modelName": "gpt-4o-mini",
+        "apiKey": "your_api_key",
+        ...
+    },
+}
+```
+
+### 2. Configure Simulation
+
+An example configuration is provided at: ```config.json```. This file defines simulation parameters (e.g., number of steps), environment settings (e.g., agents, items, space) and LLM-related services (e.g., llm client, prompt settings). You can modify this file to design your own simulation scenario.
+
+### 3. Set Log Output Path
+
+To save simulation logs, set the following environment variable:
+
+```bash
+export LOG_TXT_PATH="path/to/output_log.txt"
+```
+
+### 4. Run Simulation
+
+Move to the example directory and execute:
+
+```python
+cd examples/openai
+python main.py
+```
+
+In this script, custom ```Event``` class: ```SubsidyEvent``` is implemented. The script will 1) load ```config.json```, 2) generate simulator and register the ```SubsidyEvent``` to the simulator, 3) reset the environment and run the simulation loop, and 4) output logs to the specified path.
+

econsimulacra-0.1.1/README.md

@@ -0,0 +1,165 @@
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+<p align="center">
+  <img src="imgs/SimpleGridAnimator.gif" width="48%" />
+  <img src="imgs/SimpleSocialAnimator.gif" width="48%" />
+</p>
+
+
+EconSimulacra is a simulation platform for studying complex socio-economic systems with large language model (LLM) agents. The framework enables researchers and practitioners to simulate:
+
+- household consumption
+- firm pricing strategies
+- narrative diffusion through social networks
+- spatial mobility of agents
+
+By combining agent-based modeling with LLM reasoning, EconSimulacra allows researchers to study emergent macroeconomic phenomena from micro-level behavioral rules.
+
+# Key Features
+
+- 🧠 LLM-driven agents with internal states and reasoning
+- 🏙 Spatial grid environments with agent mobility
+- 🛒 Market interactions (consumption, pricing)
+- 🌐 Social network dynamics (follow, unfollow, narrative diffusion)
+- 📊 Structured simulation logs for analysis
+- ⚡ Parallel simulation execution
+- 🧩 Modular architecture for extensibility
+
+# Conceptual Architecture
+
+EconSimulacra consists of the following main components:
+
+<p align="center">
+  <img src="imgs/framework_structure.png" width="100%" />
+</p>
+
+## [**Simulator**](https://github.com/SimulacraBusiness/econsimulacra/blob/main/src/econsimulacra/simulator.py) 
+
+The **Simulator** executes the simulation, manages temporal progression, and supports parallel execution. At each simulation step, the simulator collects actions from all agents based on their observations and applies them to the environment. The core logic of the simulator is conceptually as follows.
+
+```python
+num_steps: int
+for _ in range(num_steps):
+    all_actions_dic = {}
+    for agent_id in env.agent_ids:
+        agent = self.env.agent_id2agent[agent_id]
+        obs = self.env.get_observations(agent_id=agent_id)
+        action_dic = agent.act(obs)
+        all_actions_dic[agent_id] = action_dic
+    self.env.step(all_actions_dic)
+```
+
+In each step:
+1. The environment provides observations to each agent ```env.get_observations(agent_id=agent_id)```
+2. Agents decide their actions based on these observations ```action_dic = agent.act(obs)```
+3. The environment updates the global state according to the agents' actions. ```env.step(all_actions_dic)```
+
+The Simulator requires ```config``` to apply your simulation settings. See [examples/openai/config.json](https://github.com/SimulacraBusiness/econsimulacra/blob/main/examples/openai/config.json) for an example.
+
+```Python
+simulator = Simulator(
+    config=config_dic_path,
+    env_class=Environment,
+    logger=logger,
+    summarizer_class=SimulationSummarizer,
+)
+```
+
+You can introduce your custom classes in your simulation by specifying ```"type": "MyClass"``` in the config and register them to the Simulator. [examples/openai/main.py](https://github.com/SimulacraBusiness/econsimulacra/blob/main/examples/openai/main.py) provides an example to introduce the custom event ```SubsidyEvent```.
+
+```python
+simulator.register_classes([MyClass1, MyClass2])
+```
+
+
+## [**Environment**](https://github.com/SimulacraBusiness/econsimulacra/blob/main/src/econsimulacra/envs/base.py)
+
+The **Environment** manages the global state of the simulated world, including the internal states of all agents. It is responsible for:
+
+- providing observations to agents (```.get_observations```)
+- applying agents’ actions and updating the world state (```.step```)
+
+The environment includes multiple submodules, such as:
+
+- [**GridSpace**](https://github.com/SimulacraBusiness/econsimulacra/blob/main/src/econsimulacra/envs/space.py): A spatial environment in which agents reside and move. This allows the simulation of spatial interactions, mobility, and location-dependent behaviors.
+- [**SocialNetwork**](https://github.com/SimulacraBusiness/econsimulacra/blob/main/src/econsimulacra/envs/social_networks/base.py): A communication layer where agents can exchange messages and interact socially, enabling the study of information diffusion and social influence. The social network also includes a customizable [**RecommenderSystem**](https://github.com/SimulacraBusiness/econsimulacra/blob/main/src/econsimulacra/envs/social_networks/recsys.py) that can suggest other agents to follow.
+
+## [**Agent**](https://github.com/SimulacraBusiness/econsimulacra/blob/main/src/econsimulacra/agents/base.py)
+
+An **Agent** represents an autonomous decision-maker in the simulation Agents receive structured observations from the environment and determine their actions (```.act```). 
+
+The information available to each agent, both as observations received from the environment and as information disclosed to other agents, is fully configurable via the agent configuration. For example, ```requestObs``` field defines what an agent can perceive from the environment, while ```provideInfo*``` fields define what an agent reveals to others.
+
+EconSimulacra provides a built-in [**LLMAgent**](https://github.com/SimulacraBusiness/econsimulacra/blob/main/src/econsimulacra/agents/llm_agent.py) implementation that leverages LLMs to generate agent behaviors. To ensure reliable and stable simulations, agent actions are generated as structured outputs using [Outlines](https://pypi.org/project/outlines/0.1.11/), which enforces predefined schemas for the generated actions.
+
+The LLM-based agent system is modular and consists of several customizable submodules:
+
+- [**LLMClient**](https://github.com/SimulacraBusiness/econsimulacra/blob/main/src/econsimulacra/llm_services/clients/base.py) – manages the underlying language model and inference settings
+- [**PersonaBuilder**](https://github.com/SimulacraBusiness/econsimulacra/blob/main/src/econsimulacra/llm_services/personas/base.py) – assigns role-playing personas to agents
+- [**PromptBuilder**](https://github.com/SimulacraBusiness/econsimulacra/blob/main/src/econsimulacra/llm_services/prompts/base.py) – constructs prompts used for agent reasoning
+- [**MemoryHandler**](https://github.com/SimulacraBusiness/econsimulacra/blob/main/src/econsimulacra/envs/memory.py) - stores and provides each agent the sequence of their experience in the past time steps as memory
+
+By customizing these components, users can easily modify LLM configurations and experiment with different prompting strategies, personas, and model backends without changing the core simulation logic.
+
+## [**Event**](https://github.com/SimulacraBusiness/econsimulacra/blob/main/src/econsimulacra/envss/event.py)
+
+An **EventManager** is responsible for managing events and triggering them at appropriate times during the simulation. Events can be scheduled based on:
+
+- specific timestamps, (```at```)
+- time intervals or durations, (```between```)
+- periodic execution (e.g., every k steps), (```every```)
+- or the occurrence of specific logs (e.g., when a transaction is generated). (```with```)
+
+You can also adapt probabilistic triggering via ```probability```. By registering custom events, users can introduce exogenous dynamics into the simulation, such as policy interventions or regime shifts, in a flexible and extensible manner.
+
+# Basic Usage
+
+## OpenAI API
+
+This section explains how to run EconSimulacra using the [OpenAI API](https://openai.com/index/openai-api/), based on the example in ```examples/openai```.
+
+### 1. Set OpenAI API Key
+
+You need to provide your OpenAI API key in one of the following ways:
+
+**Option A: Environment Variable (recommended)**
+
+```bash
+export OPENAI_API_KEY="your_api_key"
+```
+
+**Option B: ```config.json```**
+
+```json
+{
+    "llmClient": {
+        "type": "OpenAIClient",
+        "modelName": "gpt-4o-mini",
+        "apiKey": "your_api_key",
+        ...
+    },
+}
+```
+
+### 2. Configure Simulation
+
+An example configuration is provided at: ```config.json```. This file defines simulation parameters (e.g., number of steps), environment settings (e.g., agents, items, space) and LLM-related services (e.g., llm client, prompt settings). You can modify this file to design your own simulation scenario.
+
+### 3. Set Log Output Path
+
+To save simulation logs, set the following environment variable:
+
+```bash
+export LOG_TXT_PATH="path/to/output_log.txt"
+```
+
+### 4. Run Simulation
+
+Move to the example directory and execute:
+
+```python
+cd examples/openai
+python main.py
+```
+
+In this script, custom ```Event``` class: ```SubsidyEvent``` is implemented. The script will 1) load ```config.json```, 2) generate simulator and register the ```SubsidyEvent``` to the simulator, 3) reset the environment and run the simulation loop, and 4) output logs to the specified path.

econsimulacra-0.1.1/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+name = "econsimulacra"
+version = "0.1.1"
+description = "EconSimulacra: A Digital Twin Platform of Consumer Economy Powered by LLM Agents"
+authors = ["Ryuji Hashimoto <r_hashimoto@simulacra.co.jp>"]
+license = "MIT"
+readme = "README.md"
+packages = [{ include = "econsimulacra", from = "src" }]
+include = ["src/econsimulacra/py.typed"]
+repository = "https://github.com/SimulacraBusiness/econsimulacra"
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Typing :: Typed",
+]
+
+# ---------------------------------------------------------
+# Core dependencies (always installed)
+# ---------------------------------------------------------
+[tool.poetry.dependencies]
+python = ">=3.10,<3.13"
+typing-extensions = "^4.15.0"
+torch = "2.2.1"
+numpy = "^1.26.1"
+openai = "^2.21.0"
+outlines = "0.1.11"
+rich = "^14.2.0"
+accelerate = "^1.12.0"
+datasets = "^4.5.0"
+transformers = "^4.49.0"
+statsmodels = "^0.14.6"
+sentencepiece = "^0.2.1"
+protobuf = "^7.34.0"
+types-tqdm = "^4.67.3.20260205"
+
+# ---------------------------------------------------------
+# Development tools
+# Install with:
+#   poetry install --with dev
+# Used in CI (ruff, mypy, pytest)
+# ---------------------------------------------------------
+[tool.poetry.group.dev.dependencies]
+pytest = "^9.0.2"
+pytest-cov = "^7.0.0"
+mypy = "^1.19.1"
+ruff = "^0.14.13"
+
+# ---------------------------------------------------------
+# Mypy configuration
+# Animations layer is excluded because manim lacks full type hints
+# ---------------------------------------------------------
+[tool.mypy]
+python_version = "3.11"
+exclude = ["src/econsimulacra/animations/"]
+
+[[tool.mypy.overrides]]
+module = ["manim", "manim.*"]
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = ["econsimulacra.animations", "econsimulacra.animations.*"]
+ignore_missing_imports = true

econsimulacra-0.1.1/src/econsimulacra/__init__.py

@@ -0,0 +1,19 @@
+from econsimulacra import agents as agents
+from econsimulacra import envs as envs
+from econsimulacra import items as items
+from econsimulacra import logs as logs
+from econsimulacra.simulator import Simulator as Simulator
+from econsimulacra.simulator import SimulationSummarizer as SimulationSummarizer
+from econsimulacra.sim_utils import find_class as find_class
+from econsimulacra.sim_utils import JsonRandom as JsonRandom
+
+__all__ = [
+    "agents",
+    "envs",
+    "items",
+    "logs",
+    "Simulator",
+    "find_class",
+    "JsonRandom",
+    "SimulationSummarizer",
+]

econsimulacra-0.1.1/src/econsimulacra/agents/__init__.py

@@ -0,0 +1,4 @@
+from .base import Agent as Agent
+from .llm_agent import LLMAgent as LLMAgent
+
+__all__ = ["Agent"]