pycityagent 2.0.0a65__cp311-cp311-macosx_11_0_arm64.whl → 2.0.0a67__cp311-cp311-macosx_11_0_arm64.whl

pycityagent/agent/agent_base.py

@@ -20,19 +20,23 @@ from ..environment.sim.person_service import PersonService
 from ..llm import LLM
 from ..memory import Memory
 from ..message import MessageInterceptor, Messager
-from ..metrics import MlflowClient
 from ..utils import DIALOG_SCHEMA, SURVEY_SCHEMA, process_survey_for_llm
 from ..workflow import Block
 
 logger = logging.getLogger("pycityagent")
 
+__all__ = [
+    "Agent",
+    "AgentType",
+]
+
 
 class AgentType(Enum):
     """
-    Agent类型
+    Agent Type
 
     - Citizen, Citizen type agent
-    - Institution, Orgnization or institution type agent
+    - Institution, Organization or institution type agent
     """
 
     Unspecified = "Unspecified"
@@ -63,18 +67,19 @@ class Agent(ABC):
         copy_writer: Optional[ray.ObjectRef] = None,
     ) -> None:
         """
-        Initialize the Agent.
-
-        Args:
-            name (str): The name of the agent.
-            type (AgentType): The type of the agent. Defaults to `AgentType.Unspecified`
-            llm_client (LLM): The language model client. Defaults to None.
-            economy_client (EconomyClient): The `EconomySim` client. Defaults to None.
-            messager (Messager, optional): The messager object. Defaults to None.
-            simulator (Simulator, optional): The simulator object. Defaults to None.
-            memory (Memory, optional): The memory of the agent. Defaults to None.
-            avro_file (dict[str, str], optional): The avro file of the agent. Defaults to None.
-            copy_writer (ray.ObjectRef): The copy_writer of the agent. Defaults to None.
+        Initialize the `Agent`.
+
+        - **Args**:
+            - `name` (`str`): The name of the agent.
+            - `type` (`AgentType`): The type of the agent. Defaults to `AgentType.Unspecified`.
+            - `llm_client` (`Optional[LLM]`): The language model client used by the agent. Defaults to `None`.
+            - `economy_client` (`Optional[EconomyClient]`): The client for interacting with the economy simulation. Defaults to `None`.
+            - `messager` (`Optional[ray.ObjectRef]`): The object used for messaging between agents. Defaults to `None`.
+            - `message_interceptor` (`Optional[ray.ObjectRef]`): The object used for intercepting messages. Defaults to `None`.
+            - `simulator` (`Optional[Simulator]`): The simulation environment in which the agent operates. Defaults to `None`.
+            - `memory` (`Optional[Memory]`): The memory storage for the agent. Defaults to `None`.
+            - `avro_file` (`Optional[dict[str, str]]`): A dictionary representing an Avro file associated with the agent. Defaults to `None`.
+            - `copy_writer` (`Optional[ray.ObjectRef]`): The object responsible for writing copies. Defaults to `None`.
         """
         self._name = name
         self._type = type
@@ -104,6 +109,28 @@ class Agent(ABC):
 
     @classmethod
     def export_class_config(cls) -> dict[str, dict]:
+        """
+        Export the class configuration as a dictionary.
+
+        - **Args**:
+            - None. This method relies on class attributes and type hints.
+
+        - **Returns**:
+            - `dict[str, dict]`: A dictionary containing the class configuration information, including:
+                - `agent_name`: The name of the class.
+                - `config`: A mapping of configurable fields to their default values.
+                - `description`: A mapping of descriptions for each configurable field.
+                - `blocks`: A list of dictionaries with configuration information for fields that are of type `Block`, each containing:
+                    - `name`: The name of the field.
+                    - `config`: Configuration information for the Block.
+                    - `description`: Description information for the Block.
+                    - `children`: Configuration information for any child Blocks (if applicable).
+
+        - **Description**:
+            - This method parses the annotations within the class to identify and process all fields that inherit from the `Block` class.
+            - For each `Block`-typed field, it calls the corresponding `export_class_config` method to retrieve its configuration and adds it to the result.
+            - If there are child `Block`s, it recursively exports their configurations using the `_export_subblocks` method.
+        """
         result = {
             "agent_name": cls.__name__,
             "config": {},
@@ -153,12 +180,38 @@ class Agent(ABC):
 
     @classmethod
     def export_to_file(cls, filepath: str) -> None:
+        """
+        Export the class configuration to a JSON file.
+
+        - **Args**:
+            - `filepath` (`str`): The path where the JSON file will be saved.
+
+        - **Returns**:
+            - `None`
+
+        - **Description**:
+            - This method calls `export_class_config` to get the configuration dictionary and writes it to the specified file in JSON format with indentation for readability.
+        """
         config = cls.export_class_config()
         with open(filepath, "w") as f:
             json.dump(config, f, indent=4)
 
     @classmethod
-    def import_block_config(cls, config: dict[str, Union[list[dict], str]]) -> Agent:
+    def import_block_config(cls, config: dict[str, Union[list[dict], str]]) -> "Agent":
+        """
+        Import an agent's configuration from a dictionary and initialize the Agent instance along with its Blocks.
+
+        - **Args**:
+            - `config` (`dict[str, Union[list[dict], str]]`): A dictionary containing the configuration of the agent and its blocks.
+
+        - **Returns**:
+            - `Agent`: An initialized Agent instance configured according to the provided configuration.
+
+        - **Description**:
+            - Initializes a new agent using the name found in the configuration.
+            - Dynamically creates Block instances based on the configuration data and assigns them to the agent.
+            - If a block is not found in the global namespace or cannot be created, this method may raise errors.
+        """
         agent = cls(name=config["agent_name"])  # type:ignore
 
         def build_block(block_data: dict[str, Any]) -> Block:
@@ -175,15 +228,40 @@ class Agent(ABC):
         return agent
 
     @classmethod
-    def import_from_file(cls, filepath: str) -> Agent:
+    def import_from_file(cls, filepath: str) -> "Agent":
+        """
+        Load an agent's configuration from a JSON file and initialize the Agent instance.
+
+        - **Args**:
+            - `filepath` (`str`): The path to the JSON file containing the agent's configuration.
+
+        - **Returns**:
+            - `Agent`: An initialized Agent instance configured according to the loaded configuration.
+
+        - **Description**:
+            - Reads the JSON configuration from the given file path.
+            - Delegates the creation of the agent and its blocks to `import_block_config`.
+        """
         with open(filepath, "r") as f:
             config = json.load(f)
             return cls.import_block_config(config)
 
     def load_from_config(self, config: dict[str, list[dict]]) -> None:
         """
-        使用配置更新当前Agent实例的Block层次结构。
+        Update the current Agent instance's Block hierarchy using the provided configuration.
+
+        - **Args**:
+            - `config` (`dict[str, list[dict]]`): A dictionary containing the configuration for updating the agent and its blocks.
+
+        - **Returns**:
+            - `None`
+
+        - **Description**:
+            - Updates the base parameters of the current agent instance according to the provided configuration.
+            - Recursively updates or creates top-level Blocks as specified in the configuration.
+            - Raises a `KeyError` if a required Block is not found in the agent.
         """
+        # 使用配置更新当前Agent实例的Block层次结构。
         # 更新当前Agent的基础参数
         for field in self.configurable_fields:
             if field in config["config"]:
@@ -204,6 +282,20 @@ class Agent(ABC):
                 )
 
     def load_from_file(self, filepath: str) -> None:
+        """
+        Load configuration from a JSON file and update the current Agent instance.
+
+        - **Args**:
+            - `filepath` (`str`): The path to the JSON file containing the agent's configuration.
+
+        - **Returns**:
+            - `None`
+
+        - **Description**:
+            - Reads the configuration from the specified JSON file.
+            - Uses the `load_from_config` method to apply the loaded configuration to the current Agent instance.
+            - This method is useful for restoring an Agent's state from a saved configuration file.
+        """
         with open(filepath, "r") as f:
             config = json.load(f)
             self.load_from_config(config)
@@ -289,7 +381,7 @@ class Agent(ABC):
                 f"EconomyClient access before assignment, please `set_economy_client` first!"
             )
         return self._economy_client
-    
+
     @property
     def memory(self):
         """The Agent's Memory"""
@@ -334,7 +426,7 @@ class Agent(ABC):
                 f"Copy Writer access before assignment, please `set_pgsql_writer` first!"
             )
         return self._pgsql_writer
-    
+
     @property
     def messager(self):
         if self._messager is None:
@@ -342,17 +434,39 @@ class Agent(ABC):
         return self._messager
 
     async def messager_ping(self):
+        """
+        Send a ping request to the connected Messager.
+
+        - **Raises**:
+            - `RuntimeError`: If the Messager is not set.
+
+        - **Returns**:
+            - The result of the remote ping call from the Messager.
+
+        - **Description**:
+            - This method checks if the `_messager` attribute is set. If it is, it sends a ping request asynchronously to the Messager and returns the response.
+            - If the Messager is not set, it raises a RuntimeError.
+        """
         if self._messager is None:
             raise RuntimeError("Messager is not set")
         return await self._messager.ping.remote()  # type:ignore
 
     async def generate_user_survey_response(self, survey: dict) -> str:
-        """生成回答 —— 可重写
-        基于智能体的记忆和当前状态，生成对问卷调查的回答。
-        Args:
-            survey: 需要回答的问卷 dict
-        Returns:
-            str: 智能体的回答
+        """
+        Generate a response to a user survey based on the agent's memory and current state.
+
+        - **Args**:
+            - `survey` (`dict`): The survey that needs to be answered.
+
+        - **Returns**:
+            - `str`: The generated response from the agent.
+
+        - **Description**:
+            - Prepares a prompt for the Language Model (LLM) based on the provided survey.
+            - Constructs a dialog including system prompts, relevant memory context, and the survey question itself.
+            - Uses the LLM client to generate a response asynchronously.
+            - If the LLM client is not available, it returns a default message indicating unavailability.
+            - This method can be overridden by subclasses to customize survey response generation.
         """
         survey_prompt = process_survey_for_llm(survey)
         dialog = []
@@ -385,6 +499,19 @@ class Agent(ABC):
         return response  # type:ignore
 
     async def _process_survey(self, survey: dict):
+        """
+        Process a survey by generating a response and recording it in Avro format and PostgreSQL.
+
+        - **Args**:
+            - `survey` (`dict`): The survey data that includes an ID and other relevant information.
+
+        - **Description**:
+            - Generates a survey response using `generate_user_survey_response`.
+            - Records the response with metadata (such as timestamp, survey ID, etc.) in Avro format and appends it to an Avro file if `_avro_file` is set.
+            - Writes the response and metadata into a PostgreSQL database asynchronously through `_pgsql_writer`, ensuring any previous write operation has completed.
+            - Sends a message through the Messager indicating user feedback has been processed.
+            - Handles asynchronous tasks and ensures thread-safe operations when writing to PostgreSQL.
+        """
         survey_response = await self.generate_user_survey_response(survey)
         _date_time = datetime.now(timezone.utc)
         # Avro
@@ -430,16 +557,26 @@ class Agent(ABC):
                     _data_tuples
                 )
             )
-        await self.messager.send_message.remote(f"exps/{self._exp_id}/user_payback", {"count": 1})# type:ignore
+        await self.messager.send_message.remote(  # type:ignore
+            f"exps/{self._exp_id}/user_payback", {"count": 1}
+        )
 
     async def generate_user_chat_response(self, question: str) -> str:
-        """生成回答 —— 可重写
-        基于智能体的记忆和当前状态，生成对问题的回答。
-        Args:
-            question: 需要回答的问题
+        """
+        Generate a response to a user's chat question based on the agent's memory and current state.
 
-        Returns:
-            str: 智能体的回答
+        - **Args**:
+            - `question` (`str`): The question that needs to be answered.
+
+        - **Returns**:
+            - `str`: The generated response from the agent.
+
+        - **Description**:
+            - Prepares a prompt for the Language Model (LLM) with a system prompt to guide the response style.
+            - Constructs a dialog including relevant memory context and the user's question.
+            - Uses the LLM client to generate a concise and clear response asynchronously.
+            - If the LLM client is not available, it returns a default message indicating unavailability.
+            - This method can be overridden by subclasses to customize chat response generation.
         """
         dialog = []
 
@@ -471,6 +608,20 @@ class Agent(ABC):
         return response  # type:ignore
 
     async def _process_interview(self, payload: dict):
+        """
+        Process an interview interaction by generating a response and recording it in Avro format and PostgreSQL.
+
+        - **Args**:
+            - `payload` (`dict`): The interview data containing the content of the user's message.
+
+        - **Description**:
+            - Logs the user's message as part of the interview process.
+            - Generates a response to the user's question using `generate_user_chat_response`.
+            - Records both the user's message and the generated response with metadata (such as timestamp, speaker, etc.) in Avro format and appends it to an Avro file if `_avro_file` is set.
+            - Writes the messages and metadata into a PostgreSQL database asynchronously through `_pgsql_writer`, ensuring any previous write operation has completed.
+            - Sends a message through the Messager indicating that user feedback has been processed.
+            - Handles asynchronous tasks and ensures thread-safe operations when writing to PostgreSQL.
+        """
         pg_list: list[tuple[dict, datetime]] = []
         auros: list[dict] = []
         _date_time = datetime.now(timezone.utc)
@@ -517,15 +668,43 @@ class Agent(ABC):
                     _data
                 )
             )
-        await self.messager.send_message.remote(f"exps/{self._exp_id}/user_payback", {"count": 1})# type:ignore
+        await self.messager.send_message.remote(  # type:ignore
+            f"exps/{self._exp_id}/user_payback", {"count": 1}
+        )
         print(f"Sent payback message to {self._exp_id}")
 
     async def process_agent_chat_response(self, payload: dict) -> str:
+        """
+        Log the reception of an agent chat response.
+
+        - **Args**:
+            - `payload` (`dict`): The chat response data received from another agent.
+
+        - **Returns**:
+            - `str`: A log message indicating the reception of the chat response.
+
+        - **Description**:
+            - Logs the receipt of a chat response from another agent.
+            - Returns a formatted string for logging purposes.
+        """
         resp = f"Agent {self._uuid} received agent chat response: {payload}"
         logger.info(resp)
         return resp
 
     async def _process_agent_chat(self, payload: dict):
+        """
+        Process a chat message received from another agent and record it.
+
+        - **Args**:
+            - `payload` (`dict`): The chat message data received from another agent.
+
+        - **Description**:
+            - Logs the incoming chat message from another agent.
+            - Prepares the chat message for storage in Avro format and PostgreSQL.
+            - Asynchronously logs the processing of the chat response using `process_agent_chat_response`.
+            - Writes the chat message and metadata into an Avro file if `_avro_file` is set.
+            - Ensures thread-safe operations when writing to PostgreSQL by waiting for any previous write task to complete before starting a new one.
+        """
         pg_list: list[tuple[dict, datetime]] = []
         auros: list[dict] = []
         _date_time = datetime.now(timezone.utc)
@@ -562,29 +741,90 @@ class Agent(ABC):
 
     # Callback functions for MQTT message
     async def handle_agent_chat_message(self, payload: dict):
-        """处理收到的消息，识别发送者"""
+        """
+        Handle an incoming chat message from another agent.
+
+        - **Args**:
+            - `payload` (`dict`): The received message payload containing the chat data.
+
+        - **Description**:
+            - Logs receipt of a chat message from another agent.
+            - Delegates the processing of the chat message to `_process_agent_chat`.
+            - This method is typically used as a callback function for MQTT messages.
+        """
+        # 处理收到的消息，识别发送者
         # 从消息中解析发送者 ID 和消息内容
         logger.info(f"Agent {self._uuid} received agent chat message: {payload}")
         asyncio.create_task(self._process_agent_chat(payload))
 
     async def handle_user_chat_message(self, payload: dict):
-        """处理收到的消息，识别发送者"""
+        """
+        Handle an incoming chat message from a user.
+
+        - **Args**:
+            - `payload` (`dict`): The received message payload containing the chat data.
+
+        - **Description**:
+            - Logs receipt of a chat message from a user.
+            - Delegates the processing of the interview (which includes generating a response) to `_process_interview`.
+            - This method is typically used as a callback function for MQTT messages.
+        """
+        # 处理收到的消息，识别发送者
         # 从消息中解析发送者 ID 和消息内容
         logger.info(f"Agent {self._uuid} received user chat message: {payload}")
         asyncio.create_task(self._process_interview(payload))
 
     async def handle_user_survey_message(self, payload: dict):
-        """处理收到的消息，识别发送者"""
+        """
+        Handle an incoming survey message from a user.
+
+        - **Args**:
+            - `payload` (`dict`): The received message payload containing the survey data.
+
+        - **Description**:
+            - Logs receipt of a survey message from a user.
+            - Extracts the survey data from the payload and delegates its processing to `_process_survey`.
+            - This method is typically used as a callback function for MQTT messages.
+        """
+        # 处理收到的消息，识别发送者
         # 从消息中解析发送者 ID 和消息内容
         logger.info(f"Agent {self._uuid} received user survey message: {payload}")
         asyncio.create_task(self._process_survey(payload["data"]))
 
     async def handle_gather_message(self, payload: Any):
+        """
+        Placeholder for handling gather messages.
+
+        - **Args**:
+            - `payload` (`Any`): The received message payload.
+
+        - **Raises**:
+            - `NotImplementedError`: As this method is not implemented.
+
+        - **Description**:
+            - This method is intended to handle specific types of gather messages but has not been implemented yet.
+        """
         raise NotImplementedError
 
     # MQTT send message
     async def _send_message(self, to_agent_uuid: str, payload: dict, sub_topic: str):
-        """通过 Messager 发送消息"""
+        """
+        Send a message to another agent through the Messager.
+
+        - **Args**:
+            - `to_agent_uuid` (`str`): The UUID of the recipient agent.
+            - `payload` (`dict`): The content of the message to send.
+            - `sub_topic` (`str`): The sub-topic for the MQTT topic structure.
+
+        - **Raises**:
+            - `RuntimeError`: If the Messager is not set.
+
+        - **Description**:
+            - Constructs the full MQTT topic based on the experiment ID, recipient UUID, and sub-topic.
+            - Sends the message asynchronously through the Messager.
+            - Used internally by other methods like `send_message_to_agent`.
+        """
+        # 通过 Messager 发送消息
         if self._messager is None:
             raise RuntimeError("Messager is not set")
         topic = f"exps/{self._exp_id}/agents/{to_agent_uuid}/{sub_topic}"
@@ -598,7 +838,25 @@ class Agent(ABC):
     async def send_message_to_agent(
         self, to_agent_uuid: str, content: str, type: str = "social"
     ):
-        """通过 Messager 发送消息"""
+        """
+        Send a social or economy message to another agent.
+
+        - **Args**:
+            - `to_agent_uuid` (`str`): The UUID of the recipient agent.
+            - `content` (`str`): The content of the message to send.
+            - `type` (`str`, optional): The type of the message ("social" or "economy"). Defaults to "social".
+
+        - **Raises**:
+            - `RuntimeError`: If the Messager is not set.
+
+        - **Description**:
+            - Validates the message type and logs a warning if it's invalid.
+            - Prepares the message payload with necessary metadata such as sender ID, timestamp, etc.
+            - Sends the message asynchronously using `_send_message`.
+            - Optionally records the message in Avro format and PostgreSQL if it's a "social" type message.
+            - Ensures thread-safe operations when writing to PostgreSQL by waiting for any previous write task to complete before starting a new one.
+        """
+        # 通过 Messager 发送消息
         if self._messager is None:
             raise RuntimeError("Messager is not set")
         if type not in ["social", "economy"]:
@@ -648,15 +906,30 @@ class Agent(ABC):
     # Agent logic
     @abstractmethod
     async def forward(self) -> None:
-        """智能体行为逻辑"""
+        """
+        Define the behavior logic of the agent.
+
+        - **Raises**:
+            - `NotImplementedError`: As this method must be implemented by subclasses.
+
+        - **Description**:
+            - This abstract method should contain the core logic for what the agent does at each step of its operation.
+            - It is intended to be overridden by subclasses to define specific behaviors.
+        """
+        # 智能体行为逻辑
         raise NotImplementedError
 
     async def run(self) -> None:
         """
-        统一的Agent执行入口
-        当_blocked为True时，不执行forward方法
+        Unified entry point for executing the agent's logic.
+
+        - **Description**:
+            - Checks if the `_messager` is set and sends a ping request to ensure communication is established.
+            - If the agent is not blocked (`_blocked` is False), it calls the `forward` method to execute the agent's behavior logic.
+            - Acts as the main control flow for the agent, coordinating when and how the agent performs its actions.
         """
         if self._messager is not None:
             await self._messager.ping.remote()  # type:ignore
         if not self._blocked:
-            await self.forward()
+            async with self.llm.semaphore:
+                await self.forward()

pycityagent/cityagent/bankagent.py

@@ -8,11 +8,39 @@ from pycityagent.economy import EconomyClient
 from pycityagent.message import Messager
 from pycityagent.memory import Memory
 import logging
+import pycityproto.city.economy.v2.economy_pb2 as economyv2
 
 logger = logging.getLogger("pycityagent")
 
+def calculate_inflation(prices):
+    # Make sure the length of price data is a multiple of 12
+    length = len(prices)
+    months_in_year = 12
+    full_years = length // months_in_year  # Calculate number of complete years
+    
+    # Remaining data not used in calculation
+    prices = prices[:full_years * months_in_year]
+    
+    # Group by year, calculate average price for each year
+    annual_avg_prices = np.mean(np.reshape(prices, (-1, months_in_year)), axis=1)
+    
+    # Calculate annual inflation rates
+    inflation_rates = []
+    for i in range(1, full_years):
+        inflation_rate = ((annual_avg_prices[i] - annual_avg_prices[i - 1]) / annual_avg_prices[i - 1]) * 100
+        inflation_rates.append(inflation_rate)
+    
+    return inflation_rates
 
 class BankAgent(InstitutionAgent):
+    configurable_fields = ["time_diff"]
+    default_values = {
+        "time_diff": 30 * 24 * 60 * 60,
+    }
+    fields_description = {
+        "time_diff": "Time difference between each forward, day * hour * minute * second",
+    }
+    
     def __init__(
         self,
         name: str,
@@ -53,12 +81,24 @@ class BankAgent(InstitutionAgent):
 
     async def forward(self):
         if await self.month_trigger():
-            citizens = await self.memory.status.get("citizens")
-            agents_forward = []
-            if not np.all(np.array(agents_forward) > self.forward_times):
-                return
-            self.forward_times += 1
-            for uuid in citizens:
-                await self.send_message_to_agent(
-                    uuid, f"bank_forward@{self.forward_times}", "economy"
-                )
+            interest_rate = await self.economy_client.get(self._agent_id, 'interest_rate')
+            citizens = await self.economy_client.get(self._agent_id, 'citizens')
+            for citizen in citizens:
+                wealth = self.economy_client.get(citizen, 'currency')
+                await self.economy_client.add_delta_value(citizen, 'currency', interest_rate*wealth)
+                
+            nbs_id = await self.economy_client.get_org_entity_ids(economyv2.ORG_TYPE_NBS)
+            nbs_id = nbs_id[0]
+            prices = await self.economy_client.get(nbs_id, 'prices')
+            inflations = calculate_inflation(prices)
+            natural_interest_rate = 0.01
+            target_inflation = 0.02
+            if len(inflations) > 0:
+                # natural_unemployment_rate = 0.04
+                inflation_coeff, unemployment_coeff = 0.5, 0.5
+                tao = 1
+                avg_inflation = np.mean(inflations[-tao:])
+                interest_rate = natural_interest_rate + target_inflation + inflation_coeff * (avg_inflation - target_inflation)
+            else:
+                interest_rate = natural_interest_rate + target_inflation
+            await self.economy_client.update(self._agent_id, 'interest_rate', interest_rate)

pycityagent/cityagent/blocks/__init__.py

@@ -14,5 +14,4 @@ __all__ = [
     "SocialBlock",
     "EconomyBlock",
     "OtherBlock",
-    "LongTermDecisionBlock",    
-]
+]