AgentTorch API
- Execute simulations
- Customize agents
- Customize populations
- Engage with results
import pandas as pd
import os
Simulation Input
Simulation Input : Input to our simulation is a dataset consisting of population generated based on the census data of a specific region. We have currently generated population for New York City and New Zealand.
Lets see how the population data looks like for New Zealand
NZ_SYNTHETIC_POPULATION_PATH = os.path.join(os.getcwd(), 'simulator_data/census_populations/NZ/synthetic_populations/population_data.pkl')
nz_population = pd.read_pickle(NZ_SYNTHETIC_POPULATION_PATH)
nz_population.head(5)
| area | age | gender | ethnicity | region | |
|---|---|---|---|---|---|
| 0 | 204200 | U19 | female | Maori | Bay of Plenty |
| 1 | 204200 | U19 | female | Maori | Bay of Plenty |
| 2 | 204200 | U19 | male | European | Bay of Plenty |
| 3 | 204200 | U19 | female | Maori | Bay of Plenty |
| 4 | 204200 | U19 | female | Maori | Bay of Plenty |
The above data shows the population attributes of 5 agents, like ‘age’, ‘gender’, ‘region where the agent resides’, ‘ethnicity’ and ‘area code of residence’. We assign these attributes to each of our simulated agents, to mimic real world population dynamic.
We also provide APIs to generate your own synthetic population, though we will not get into the details here.
Run Simulation
Dataloader is the common interface to load, setup or modify the simulation parameters such as Number of Runs, Population Size, Region for which Population data is to be used. It also does the necessary pipelining to setup the flow of simulation.
It compiles a config file which is used by the Executor to run the simulation.
from AgentTorch.dataloader import DataLoader
# 'populations' is the package where generated population for each region is saved.
# We are picking New Zealand's (NZ) population for this run.
from populations import NZ
# 'models' is the package where the simulation logic for different use cases are defined.
# We are picking the macro_economics model for this simulation. It models the population's economic behavior during covid, by simulating a financial market.
from models import macro_economics
from macro_economics.config import NUM_AGENTS
# Initialize the data loader with the preferred model and the region's population.
data_loader = DataLoader(model = macro_economics, region = NZ, population_size = NUM_AGENTS)
Config saved at: /Users/shashankkumar/Documents/GitHub/MacroEcon/models/macro_economics/yamls/config.yaml
Config saved at: /Users/shashankkumar/Documents/GitHub/MacroEcon/models/macro_economics/yamls/config.yaml
Config saved at: /Users/shashankkumar/Documents/GitHub/MacroEcon/models/macro_economics/yamls/config.yaml
Example 1: Use Executor API to run a simulation
# Executor is the common interface to run simulation
# It takes the model and data loader as input and executes the simulation.
from AgentTorch.execute import Executor
agents_sim = Executor(model = macro_economics,data_loader = data_loader)
agents_sim.execute()
running episode 0...
Substep Action: Earning decision
LLM benchmark expts
Some Example Prompts: ['You are female of age U19, living in the Bay of Plenty region. It is September 2020, number of covid cases is 874.0. The price of Essential Goods is 12.0. With all these factors in play, and considering aspects like your living costs, any future aspirations, and the broader economic trends, how is your willingness to work this month? Furthermore, how would you plan your expenditures? ', 'You are female of age U19, living in the Otago region. It is September 2020, number of covid cases is 874.0. The price of Essential Goods is 12.0. With all these factors in play, and considering aspects like your living costs, any future aspirations, and the broader economic trends, how is your willingness to work this month? Furthermore, how would you plan your expenditures? ', 'You are female of age U19, living in the Tasman region. It is September 2020, number of covid cases is 874.0. The price of Essential Goods is 12.0. With all these factors in play, and considering aspects like your living costs, any future aspirations, and the broader economic trends, how is your willingness to work this month? Furthermore, how would you plan your expenditures? ']
Substep: Agent Earning!
Substep: Agent Consumption
Executing Substep: Labor Market
Executing Substep: Financial Market
Substep Action: Earning decision
LLM benchmark expts
Some Example Prompts: ['You are female of age U19, living in the Bay of Plenty region. It is October 2020, number of covid cases is 701.0. The price of Essential Goods is 12.012574195861816. With all these factors in play, and considering aspects like your living costs, any future aspirations, and the broader economic trends, how is your willingness to work this month? Furthermore, how would you plan your expenditures? ', 'You are female of age U19, living in the Otago region. It is October 2020, number of covid cases is 701.0. The price of Essential Goods is 12.012574195861816. With all these factors in play, and considering aspects like your living costs, any future aspirations, and the broader economic trends, how is your willingness to work this month? Furthermore, how would you plan your expenditures? ', 'You are female of age U19, living in the Tasman region. It is October 2020, number of covid cases is 701.0. The price of Essential Goods is 12.012574195861816. With all these factors in play, and considering aspects like your living costs, any future aspirations, and the broader economic trends, how is your willingness to work this month? Furthermore, how would you plan your expenditures? ']
Substep: Agent Earning!
Substep: Agent Consumption
Executing Substep: Labor Market
Executing Substep: Financial Market
Simulation Ended.
Example 2: Use DataLoader API to customize the agent - Make LLM an Agent
Let’s modify the prompt used by our LLM Agent, and re-run the simulation
Original Prompt is : “You are {gender} of age {age}, living in the {region} region. It is {month} {year}, number of covid cases is {covid_cases}. The price of Essential Goods is {price_of_goods}. With all these factors in play, and considering aspects like your living costs, any future aspirations, and the broader economic trends, how is your willingness to work this month? Furthermore, how would you plan your expenditures? “
We will modify this to remove the information about price of essential goods. This might, help us understand the population/market behaviour when info on inflation is not present.
MODIFIED_EARNING_ACTION_PROMPT = "You are {gender} of age {age}, living in the {region} region. It is {month} {year}, number of covid cases is {covid_cases}. With all these factors in play, and considering aspects like your living costs, any future aspirations, and the broader economic trends, how is your willingness to work this month? Furthermore, how would you plan your expenditures? "
data_loader.set_config_attribute('EARNING_ACTION_PROMPT', MODIFIED_EARNING_ACTION_PROMPT)
agent_sim_modified = Executor(model = macro_economics,data_loader = data_loader)
# With this set, we can now run the simulation again using the executor.
agent_sim_modified.execute()
Config saved at: /Users/shashankkumar/Documents/GitHub/MacroEcon/models/macro_economics/yamls/config.yaml
resolvers already registered..
running episode 0...
Substep Action: Earning decision
LLM benchmark expts
Some Example Prompts: ['You are female of age U19, living in the Bay of Plenty region. It is September 2020, number of covid cases is 874.0. With all these factors in play, and considering aspects like your living costs, any future aspirations, and the broader economic trends, how is your willingness to work this month? Furthermore, how would you plan your expenditures? ', 'You are female of age U19, living in the Otago region. It is September 2020, number of covid cases is 874.0. With all these factors in play, and considering aspects like your living costs, any future aspirations, and the broader economic trends, how is your willingness to work this month? Furthermore, how would you plan your expenditures? ', 'You are female of age U19, living in the Tasman region. It is September 2020, number of covid cases is 874.0. With all these factors in play, and considering aspects like your living costs, any future aspirations, and the broader economic trends, how is your willingness to work this month? Furthermore, how would you plan your expenditures? ']
Substep: Agent Earning!
Substep: Agent Consumption
Executing Substep: Labor Market
Executing Substep: Financial Market
Substep Action: Earning decision
LLM benchmark expts
Some Example Prompts: ['You are female of age U19, living in the Bay of Plenty region. It is October 2020, number of covid cases is 701.0. With all these factors in play, and considering aspects like your living costs, any future aspirations, and the broader economic trends, how is your willingness to work this month? Furthermore, how would you plan your expenditures? ', 'You are female of age U19, living in the Otago region. It is October 2020, number of covid cases is 701.0. With all these factors in play, and considering aspects like your living costs, any future aspirations, and the broader economic trends, how is your willingness to work this month? Furthermore, how would you plan your expenditures? ', 'You are female of age U19, living in the Tasman region. It is October 2020, number of covid cases is 701.0. With all these factors in play, and considering aspects like your living costs, any future aspirations, and the broader economic trends, how is your willingness to work this month? Furthermore, how would you plan your expenditures? ']
Substep: Agent Earning!
Substep: Agent Consumption
Executing Substep: Labor Market
Executing Substep: Financial Market
Simulation Ended.
Visualize Results
Simulations produce a state trace
More info on state trace ….
from macro_economics.config import STATE_TRACE_PATH
from AgentTorch.LLM.llm_qa import load_state_trace
state_trace = load_state_trace(STATE_TRACE_PATH,NZ_NUM_AGENTS)
state_trace[0].columns
Index(['ID', 'age', 'area', 'assets', 'consumption_propensity', 'ethnicity',
'gender', 'household', 'monthly_income', 'post_tax_income', 'region',
'will_work', 'month', 'year'],
dtype='object')
Example 3: Use Visualizer API to engage the simulation trace for retrospective and prospective analysis
# Visualizer is the helper class to visualize the output variables of the simulation
# As we would expect, it takes simulation trace as input
from AgentTorch.visualize import Visualizer
visualizer = Visualizer(state_trace)
# We can plot a few variables of interest like Consumption Propensity and Will to Work.
visualizer.plot('consumption_propensity')
Make this Notebook Trusted to load map: File -> Trust Notebook
# Next lets visualize the Aggregate Willingness to work in each region
visualizer.plot('will_to_work')
Make this Notebook Trusted to load map: File -> Trust Notebook
Talk with Simulation
Q/A : AgentTorch gives you the ability to perform Q/A with the simulation, through its integration of simulation trace and conversation history with th Analysis Agent (LLM Agent).
Configuration
from macro_economics.config import OPENAI_API_KEY
conversations_memory_directory = ROOT_DIR + 'populations/NZ/simulation_memory_output/2020/9'
state_trace_path = ROOT_DIR + 'populations/NZ/state_data_dict.pkl'
Analyze
DocumentRetriever : It sets up a vector db containing all the converations intiated with the LLM Agent, during the runtime of the simulation.
from AgentTorch.LLM.llm_qa import DocumentRetriever
conversation_memory_retriever = DocumentRetriever(directory=conversation_memory_directory)
Batches: 0%| | 0/16 [00:00<?, ?it/s]
SimulationAnalysisAgent abstracts away the logic for analysis module, so you can do what’s more fun, that is analyzing the simulation behaviour.
from AgentTorch.LLM.llm_qa import SimulationAnalysisAgent
analyser = SimulationAnalysisAgent(openai_api_key=OPENAI_API_KEY, document_retriever=memory_retriever, temperature=0, state_trace_path=state_trace_path)
analyser.query("Which age group has lowest median income, how much is it?")
[1m> Entering new AgentExecutor chain...[0m
[32;1m[1;3m
Invoking: `run_analysis_on_simulation_state` with `{'query': 'Which age group has the lowest median income and how much is it?'}`
[0m[36;1m[1;3mThe age group with the lowest median income is 20t29 with a median income of $168.00.[0m[32;1m[1;3mThe age group with the lowest median income is 20-29 years old, with a median income of $168.00.[0m
[1m> Finished chain.[0m
{'input': 'Which age group has lowest median income, how much is it?',
'output': 'The age group with the lowest median income is 20-29 years old, with a median income of $168.00.'}
analyser.query("Which age group has highest consumption")
[1m> Entering new AgentExecutor chain...[0m
[32;1m[1;3m
Invoking: `run_analysis_on_simulation_state` with `{'query': 'Which age group has the highest consumption?'}`
[0m[36;1m[1;3mThe age group with the highest consumption is 65A.[0m[32;1m[1;3mThe age group with the highest consumption is 65 and above.[0m
[1m> Finished chain.[0m
{'input': 'Which age group has highest consumption',
'output': 'The age group with the highest consumption is 65 and above.'}
analyser.query("How is inflation affecting consumption behaviour?")
[1m> Entering new AgentExecutor chain...[0m
[32;1m[1;3m
Invoking: `simulation_memory_retriever` with `{'query': 'inflation and consumption behaviour'}`
[0m
Batches: 0%| | 0/1 [00:00<?, ?it/s]
[33;1m[1;3mReasoning: Let's think step by step in order to[32m produce the answer. We observe a decrease in the number of COVID cases from 874.0 to 701.0, indicating a potential improvement in the pandemic situation in the Wellington region. This improvement might lead to a higher willingness to work due to perceived lower health risks and possibly more job opportunities as the economy might start to recover. The slight increase in the price of Essential Goods from 12.0 to 12.012574195861816 suggests a minimal inflation in the cost of living, which might not significantly impact the overall expenditure strategy but indicates economic activity. Given the age group (30t39), there's likely a strong incentive to maintain or increase income levels to support any current or future financial goals, such as savings, investments,[0m
Reasoning: Let's think step by step in order to[32m produce the answer. Given the decrease in the number of COVID cases from 874.0 to 701.0, there is a slight improvement in the pandemic situation in the Waikato region. This improvement might lead to a more stable economic environment and potentially more job security. As a male in the age group of 40 to 49, you are likely to have significant financial responsibilities, possibly including a family to support, a mortgage, and future savings to consider. The slight increase in the price of Essential Goods from 12.0 to 12.012574195861816 indicates a marginal inflation but doesn't significantly impact the overall cost of living. Considering these factors:
1. **Willingness to Work**: With the decrease in[0m
Reasoning: Let's think step by step in order to produce the answer. We observe a decrease in the number of COVID cases from 874.0 to 701.0, indicating a potential improvement in the pandemic situation in the Wellington region. This improvement might lead to a higher willingness to work due to perceived lower health risks and possibly more job opportunities as the economy might start to recover. The slight increase in the price of Essential Goods from 12.0 to 12.012574195861816 suggests a minimal inflation in the cost of living, which might not significantly impact the overall expenditure strategy but indicates economic activity. Given the age group (30t39), there's likely a strong incentive to maintain or increase income levels to support any current or future financial goals, such as savings, investments,
Answer:[32m [0.75, 0.6][0m
Reasoning: Let's think step by step in order to produce the answer. Given the decrease in the number of COVID cases from 874.0 to 701.0, there is a slight improvement in the pandemic situation in the Waikato region. This improvement might lead to a more stable economic environment and potentially more job security. As a male in the age group of 40 to 49, you are likely to have significant financial responsibilities, possibly including a family to support, a mortgage, and future savings to consider. The slight increase in the price of Essential Goods from 12.0 to 12.012574195861816 indicates a marginal inflation but doesn't significantly impact the overall cost of living. Considering these factors: 1. **Willingness to Work**: With the decrease in
Answer:[32m [0.7, 0.7][0m
Reasoning: Let's think step by step in order to produce the answer. We need to consider several factors: 1. **Age and Health Risk**: At age 65, you are in a higher risk category for COVID-19. This increases the risk associated with working, especially if your job cannot be done remotely. 2. **COVID-19 Cases**: The number of cases in the Otago region has decreased from 874.0 to 701.0. This indicates a positive trend, but the risk of infection is still present. 3. **Price of Essential Goods**: The price has slightly increased from 12.0 to 12.012574195861816. This indicates inflation but not at a significant rate that would drastically change consumption habits. 4. **Economic Trends and
Answer:[32m [0.25, 0.65][0m
You are an individual living during the COVID-19 pandemic. You need to decide your willingness to work each month and portion of your assests you are willing to spend to meet your consumption demands, based on the current situation of NYC.
---[0m[32;1m[1;3m
Invoking: `run_analysis_on_simulation_state` with `{'query': 'impact of inflation on consumption behaviour'}`
[0m[36;1m[1;3m ID age area assets consumption_propensity ethnicity \
0 0 20t29 0.0 0.000000 0.00 hispanic
1 1 20t29 0.0 0.000000 0.00 hispanic
2 2 20t29 0.0 0.000000 0.00 asian
3 3 20t29 0.0 0.000000 0.00 hispanic
4 4 20t29 0.0 0.000000 0.00 hispanic
... ... ... ... ... ... ...
56775 56775 U19 22.0 333.087189 1.05 asian
56776 56776 U19 22.0 221.979263 1.05 asian
56777 56777 U19 22.0 221.979263 1.05 hispanic
56778 56778 U19 22.0 333.087189 1.05 hispanic
56779 56779 U19 22.0 333.087189 1.05 hispanic
gender household monthly_income post_tax_income region \
0 male 0.0 0.000000 0.0 Bay of Plenty
1 male 1.0 0.000000 0.0 Bay of Plenty
2 female 2.0 0.000000 0.0 Bay of Plenty
3 male 3.0 0.000000 0.0 Bay of Plenty
4 male 4.0 0.000000 0.0 Bay of Plenty
... ... ... ... ... ...
56775 female 450.0 196.094788 0.0 Wellington
56776 female 264.0 196.094788 0.0 Wellington
56777 female 234.0 196.094788 0.0 Wellington
56778 male 292.0 196.094788 0.0 Wellington
56779 female 309.0 196.094788 0.0 Wellington
will_work month year adjusted_consumption inflation_impact
0 0.0 0 0 0.0 0.000000
1 0.0 0 0 0.0 0.000000
2 0.0 0 0 0.0 0.000000
3 0.0 0 0 0.0 0.000000
4 0.0 0 0 0.0 0.000000
... ... ... ... ... ...
56775 0.0 4 0 0.0 196.094788
56776 0.0 4 0 0.0 196.094788
56777 0.0 4 0 0.0 196.094788
56778 0.0 4 0 0.0 196.094788
56779 0.0 4 0 0.0 196.094788
[283900 rows x 16 columns][0m[32;1m[1;3mThe analysis of the simulation data shows that inflation has a varying impact on consumption behavior across different demographics. Here are some key observations:
1. For younger age groups (20-29), the impact of inflation on consumption propensity is minimal. This could be due to their relatively lower assets and income levels.
2. For the age group under 19, the impact of inflation is more pronounced. This could be due to their reliance on fixed income sources like allowances or part-time jobs, which do not adjust for inflation.
3. Across different regions, the impact of inflation on consumption behavior also varies. For instance, in the Wellington region, the impact of inflation is more noticeable compared to the Bay of Plenty region.
4. The impact of inflation on consumption behavior also varies by ethnicity and gender. For instance, the Asian and Hispanic communities show a higher impact of inflation on their consumption behavior compared to other ethnicities. Similarly, females show a higher impact of inflation on their consumption behavior compared to males.
These observations suggest that inflation can affect consumption behavior in complex ways, depending on various demographic and economic factors.[0m
[1m> Finished chain.[0m
{'input': 'How is inflation affecting consumption behaviour?',
'output': 'The analysis of the simulation data shows that inflation has a varying impact on consumption behavior across different demographics. Here are some key observations:\n\n1. For younger age groups (20-29), the impact of inflation on consumption propensity is minimal. This could be due to their relatively lower assets and income levels.\n\n2. For the age group under 19, the impact of inflation is more pronounced. This could be due to their reliance on fixed income sources like allowances or part-time jobs, which do not adjust for inflation.\n\n3. Across different regions, the impact of inflation on consumption behavior also varies. For instance, in the Wellington region, the impact of inflation is more noticeable compared to the Bay of Plenty region.\n\n4. The impact of inflation on consumption behavior also varies by ethnicity and gender. For instance, the Asian and Hispanic communities show a higher impact of inflation on their consumption behavior compared to other ethnicities. Similarly, females show a higher impact of inflation on their consumption behavior compared to males.\n\nThese observations suggest that inflation can affect consumption behavior in complex ways, depending on various demographic and economic factors.'}
Bring your own Population
from models import macro_economics
from populations import NYC
from macro_economics.config import NYC_NUM_AGENTS
data_loader_nyc = DataLoader(model = macro_economics, region = NYC, population_size = NYC_NUM_AGENTS)
agents_sim = Executor(macro_economics,data_loader_nyc)
agents_sim.execute()
Config saved at: /Users/shashankkumar/Documents/GitHub/MacroEcon/models/macro_economics/yamls/config.yaml
Config saved at: /Users/shashankkumar/Documents/GitHub/MacroEcon/models/macro_economics/yamls/config.yaml
Config saved at: /Users/shashankkumar/Documents/GitHub/MacroEcon/models/macro_economics/yamls/config.yaml
resolvers already registered..
running episode 0...
Substep Action: Earning decision
LLM benchmark expts
Some Example Prompts: ['You are male of age 20t29, living in the BK region. It is September 2020, number of covid cases is 874.0. With all these factors in play, and considering aspects like your living costs, any future aspirations, and the broader economic trends, how is your willingness to work this month? Furthermore, how would you plan your expenditures? ', 'You are male of age 20t29, living in the BX region. It is September 2020, number of covid cases is 874.0. With all these factors in play, and considering aspects like your living costs, any future aspirations, and the broader economic trends, how is your willingness to work this month? Furthermore, how would you plan your expenditures? ', 'You are male of age 20t29, living in the MN region. It is September 2020, number of covid cases is 874.0. With all these factors in play, and considering aspects like your living costs, any future aspirations, and the broader economic trends, how is your willingness to work this month? Furthermore, how would you plan your expenditures? ']
Substep: Agent Earning!
Substep: Agent Consumption
Executing Substep: Labor Market
Executing Substep: Financial Market
Substep Action: Earning decision
LLM benchmark expts
Some Example Prompts: ['You are male of age 20t29, living in the BK region. It is October 2020, number of covid cases is 701.0. With all these factors in play, and considering aspects like your living costs, any future aspirations, and the broader economic trends, how is your willingness to work this month? Furthermore, how would you plan your expenditures? ', 'You are male of age 20t29, living in the BX region. It is October 2020, number of covid cases is 701.0. With all these factors in play, and considering aspects like your living costs, any future aspirations, and the broader economic trends, how is your willingness to work this month? Furthermore, how would you plan your expenditures? ', 'You are male of age 20t29, living in the MN region. It is October 2020, number of covid cases is 701.0. With all these factors in play, and considering aspects like your living costs, any future aspirations, and the broader economic trends, how is your willingness to work this month? Furthermore, how would you plan your expenditures? ']
Substep: Agent Earning!
Substep: Agent Consumption
Executing Substep: Labor Market
Executing Substep: Financial Market
Simulation Ended.