agent_urban_planning.Agent

class Agent(agent_id, household_size, age_head, has_children, has_elderly, income, savings, job_location, car_owner, weight, preferences=<factory>, home_zone='', education=None, migration_background=None, employment_status=None, tenure=None)[source]

Bases: object

One representative household type (a weighted demographic record).

Each agent represents a slice of the population. Demographic fields drive both the closed-form utility computation (via income and location) and the LLM-elicited persona used by V5 engines (through persona_summary()). The optional richer demographic fields (education, migration, employment, tenure) are populated only when the agent is sampled from the 10D Berlin joint distribution; legacy engines (V1..V4) ignore them.

Variables:

  • agent_id – Stable integer identifier across runs.

  • household_size – Number of persons in the household.

  • age_head – Age of the household head (constrained 21-85 in sampling).

  • has_children – Whether the household has any members aged < 18.

  • has_elderly – Whether the household has any members aged >= 65.

  • income – Monthly household income in scenario-currency units.

  • savings – Liquid savings (default income * 6).

  • job_location – Zone name where the agent works (for Singapore scenarios; ignored when the engine optimizes workplace jointly with residence).

  • car_owner – Whether the household owns a car.

  • weight – Population share assigned to this type. Across the full AgentPopulation these weights must sum to 1.

  • preferences – Optional PreferenceWeights recorded in the JSON output. Most engines ignore this — it is preserved for diagnostic output.

  • home_zone – Planning area where the agent resides (used by engines that need an outside-option reference).

  • education – "low", "mid", "high", or None.

  • migration_background – "none", "EU", "non-EU", or None.

  • employment_status – "employed", "self-employed", "unemployed", "retired_or_student", or None.

  • tenure – "owner", "renter", or None.

Parameters:

Examples

>>> from agent_urban_planning.core.agents import Agent
>>> a = Agent(
...     agent_id=0, household_size=3, age_head=42, has_children=True,
...     has_elderly=False, income=5000.0, savings=30000.0,
...     job_location="CBD", car_owner=False, weight=0.001,
... )
>>> a.income
5000.0
agent_id: int
household_size: int
age_head: int
has_children: bool
has_elderly: bool
income: float
savings: float
job_location: str
car_owner: bool
weight: float
preferences: PreferenceWeights
home_zone: str = ''
education: str | None = None
migration_background: str | None = None
employment_status: str | None = None
tenure: str | None = None