agentsociety.cityagent.blocks.needs_block

Module Contents

Classes

NeedsBlock

Manages agent’s dynamic needs system including:

Data

INITIAL_NEEDS_PROMPT

EVALUATION_PROMPT

REFLECTION_PROMPT

API

agentsociety.cityagent.blocks.needs_block.INITIAL_NEEDS_PROMPT = <Multiline-String>
agentsociety.cityagent.blocks.needs_block.EVALUATION_PROMPT = <Multiline-String>
agentsociety.cityagent.blocks.needs_block.REFLECTION_PROMPT = <Multiline-String>
class agentsociety.cityagent.blocks.needs_block.NeedsBlock(toolbox: agentsociety.agent.AgentToolbox, agent_memory: agentsociety.memory.Memory, agent_context: agentsociety.agent.DotDict, evaluation_prompt: str = EVALUATION_PROMPT, reflection_prompt: str = REFLECTION_PROMPT, initial_prompt: str = INITIAL_NEEDS_PROMPT)

Bases: agentsociety.agent.Block

Manages agent’s dynamic needs system including:

  • Initializing satisfaction levels

  • Time-based decay of satisfaction values

  • Need prioritization based on thresholds

  • Plan execution evaluation and satisfaction adjustments

Initialization

Initialize needs management system.

Args: llm: Language model instance for processing prompts environment: Simulation environment controller agent_memory: Agent’s memory storage interface

Configuration Parameters: alpha_H: Hunger satisfaction decay rate per hour (default: 0.15) alpha_D: Energy satisfaction decay rate per hour (default: 0.08) alpha_P: Safety satisfaction decay rate per hour (default: 0.05) alpha_C: Social satisfaction decay rate per hour (default: 0.1) T_H: Hunger threshold for triggering need (default: 0.2) T_D: Energy threshold for triggering need (default: 0.2) T_P: Safety threshold for triggering need (default: 0.2) T_C: Social threshold for triggering need (default: 0.3)

async reset()

Reset the needs block.

async initialize()

Initialize agent’s satisfaction levels using profile data.

  • Runs once per simulation day

  • Collects demographic data from memory

  • Generates initial satisfaction values via LLM

  • Handles JSON parsing and validation

async reflect_to_intervention(intervention: str)
async time_decay()

Apply time-based decay to satisfaction values.

  • Calculates hours since last update

  • Applies exponential decay to each satisfaction dimension

  • Ensures values stay within [0,1] range

async update_when_plan_completed()
async determine_current_need()

Determine agent’s current dominant need based on:

  • Satisfaction thresholds

  • Need priority hierarchy (hungry > tired > safe > social)

  • Workday requirements

  • Ongoing plan interruptions

async evaluate_and_adjust_needs(completed_plan)

Evaluate plan execution results and adjust satisfaction values.

  • Extracts step evaluations from completed plan

  • Constructs evaluation prompt for LLM

  • Processes LLM response and updates satisfaction values

  • Implements retry logic for invalid responses

async forward()

Main execution flow for needs management:

  1. Initialize satisfaction values (if needed)

  2. Apply time-based decay

  3. Handle completed plans

  4. Determine current dominant need