pycityagent 2.0.0a65__cp39-cp39-macosx_11_0_arm64.whl → 2.0.0a67__cp39-cp39-macosx_11_0_arm64.whl

pycityagent/simulation/simulation.py

@@ -13,19 +13,30 @@ import yaml
 from langchain_core.embeddings import Embeddings
 
 from ..agent import Agent, InstitutionAgent
-from ..cityagent import (BankAgent, FirmAgent, GovernmentAgent, NBSAgent,
-                         SocietyAgent, memory_config_bank, memory_config_firm,
-                         memory_config_government, memory_config_nbs,
-                         memory_config_societyagent)
+from ..cityagent import BankAgent, FirmAgent, GovernmentAgent, NBSAgent, SocietyAgent
+from ..cityagent.memory_config import (
+    memory_config_bank,
+    memory_config_firm,
+    memory_config_government,
+    memory_config_nbs,
+    memory_config_societyagent,
+    memory_config_init,
+)
 from ..cityagent.initial import bind_agent_info, initialize_social_network
-from ..cityagent.message_intercept import (EdgeMessageBlock,
-                                           MessageBlockListener,
-                                           PointMessageBlock)
+from ..cityagent.message_intercept import (
+    EdgeMessageBlock,
+    MessageBlockListener,
+    PointMessageBlock,
+)
 from ..economy.econ_client import EconomyClient
 from ..environment import Simulator
 from ..llm import SimpleEmbedding
-from ..message import (MessageBlockBase, MessageBlockListenerBase,
-                       MessageInterceptor, Messager)
+from ..message import (
+    MessageBlockBase,
+    MessageBlockListenerBase,
+    MessageInterceptor,
+    Messager,
+)
 from ..metrics import init_mlflow_connection
 from ..metrics.mlflow_client import MlflowClient
 from ..survey import Survey
@@ -36,26 +47,55 @@ from .storage.pg import PgWriter, create_pg_tables
 logger = logging.getLogger("pycityagent")
 
 
+__all__ = ["AgentSimulation"]
+
 class AgentSimulation:
-    """城市智能体模拟器"""
+    """
+    A class to simulate a multi-agent system.
+
+    This simulation framework is designed to facilitate the creation and management of multiple agent types within an experiment.
+    It allows for the configuration of different agents, memory configurations, and metric extractors, as well as enabling institutional settings.
+
+    Attributes:
+        exp_id (str): A unique identifier for the current experiment.
+        agent_class (List[Type[Agent]]): A list of agent classes that will be instantiated in the simulation.
+        agent_config_file (Optional[dict]): Configuration file or dictionary for initializing agents.
+        logging_level (int): The level of logging to be used throughout the simulation.
+        default_memory_config_func (Dict[Type[Agent], Callable]): Dictionary mapping agent classes to their respective memory configuration functions.
+    """
 
     def __init__(
         self,
         config: dict,
         agent_class: Union[None, type[Agent], list[type[Agent]]] = None,
         agent_config_file: Optional[dict] = None,
-        metric_extractor: Optional[list[tuple[int, Callable]]] = None,
+        metric_extractors: Optional[list[tuple[int, Callable]]] = None,
         enable_institution: bool = True,
         agent_prefix: str = "agent_",
         exp_name: str = "default_experiment",
         logging_level: int = logging.WARNING,
     ):
         """
-        Args:
-            agent_class: 智能体类
-            config: 配置
-            agent_prefix: 智能体名称前缀
-            exp_name: 实验名称
+        Initializes the AgentSimulation with the given parameters.
+
+        - **Description**:
+            - Sets up the simulation environment based on the provided configuration. Depending on the `enable_institution` flag,
+              it can include a predefined set of institutional agents. If specific agent classes are provided, those will be used instead.
+
+        - **Args**:
+            - `config` (dict): The main configuration dictionary for the simulation.
+            - `agent_class` (Union[None, Type[Agent], List[Type[Agent]]], optional):
+                Either a single agent class or a list of agent classes to instantiate. Defaults to None, which implies a default set of agents.
+            - `agent_config_file` (Optional[dict], optional): An optional configuration file or dictionary used to initialize agents. Defaults to None.
+            - `metric_extractors` (Optional[List[Tuple[int, Callable]]], optional):
+                A list of tuples containing intervals and callables for extracting metrics from the simulation. Defaults to None.
+            - `enable_institution` (bool, optional): Flag indicating whether institutional agents should be included in the simulation. Defaults to True.
+            - `agent_prefix` (str, optional): Prefix string for naming agents. Defaults to "agent_".
+            - `exp_name` (str, optional): The name of the experiment. Defaults to "default_experiment".
+            - `logging_level` (int, optional): Logging level to set for the simulation's logger. Defaults to logging.WARNING.
+
+        - **Returns**:
+            - None
         """
         self.exp_id = str(uuid.uuid4())
         if isinstance(agent_class, list):
@@ -166,11 +206,11 @@ class AgentSimulation:
                 experiment_name=exp_name,
                 run_id=mlflow_run_id,
             )
-            self.metric_extractor = metric_extractor
+            self.metric_extractors = metric_extractors
         else:
             logger.warning("Mlflow is not enabled, NO MLFLOW STORAGE")
             self.mlflow_client = None
-            self.metric_extractor = None
+            self.metric_extractors = None
 
         # pg
         _pgsql_config: dict[str, Any] = _storage_config.get("pgsql", {})
@@ -216,8 +256,9 @@ class AgentSimulation:
         - enable_institution: bool, default is True
         - agent_config:
             - agent_config_file: Optional[dict[type[Agent], str]]
+            - memory_config_init_func: Optional[Callable]
             - memory_config_func: Optional[dict[type[Agent], Callable]]
-            - metric_extractor: Optional[list[tuple[int, Callable]]]
+            - metric_extractors: Optional[list[tuple[int, Callable]]]
             - init_func: Optional[list[Callable[AgentSimulation, None]]]
             - group_size: Optional[int]
             - embedding_model: Optional[EmbeddingModel]
@@ -258,28 +299,33 @@ class AgentSimulation:
         simulation = cls(
             config=simulation_config,
             agent_config_file=config["agent_config"].get("agent_config_file", None),
-            metric_extractor=config["agent_config"].get("metric_extractor", None),
+            metric_extractors=config["agent_config"].get("metric_extractors", None),
             enable_institution=config.get("enable_institution", True),
             exp_name=config.get("exp_name", "default_experiment"),
             logging_level=config.get("logging_level", logging.WARNING),
         )
         environment = config.get(
-            "environment", 
+            "environment",
             {
-                "weather": "The weather is normal", 
-                "crime": "The crime rate is low", 
-                "pollution": "The pollution level is low", 
-                "temperature": "The temperature is normal"
-            }
+                "weather": "The weather is normal",
+                "crime": "The crime rate is low",
+                "pollution": "The pollution level is low",
+                "temperature": "The temperature is normal",
+                "day": "Workday" 
+            },
         )
         simulation._simulator.set_environment(environment)
         logger.info("Initializing Agents...")
-        agent_count = []
-        agent_count.append(config["agent_config"]["number_of_citizen"])
-        agent_count.append(config["agent_config"]["number_of_firm"])
-        agent_count.append(config["agent_config"]["number_of_government"])
-        agent_count.append(config["agent_config"]["number_of_bank"])
-        agent_count.append(config["agent_config"]["number_of_nbs"])
+        agent_count = {
+            SocietyAgent: config["agent_config"].get("number_of_citizen", 0),
+            FirmAgent: config["agent_config"].get("number_of_firm", 0),
+            GovernmentAgent: config["agent_config"].get("number_of_government", 0),
+            BankAgent: config["agent_config"].get("number_of_bank", 0),
+            NBSAgent: config["agent_config"].get("number_of_nbs", 0),
+        }
+        if agent_count.get(SocietyAgent, 0) == 0:
+            raise ValueError("number_of_citizen is required")
+
         # support MessageInterceptor
         if "message_intercept" in config:
             _intercept_config = config["message_intercept"]
@@ -319,6 +365,9 @@ class AgentSimulation:
                 "embedding_model", SimpleEmbedding()
             ),
             memory_config_func=config["agent_config"].get("memory_config_func", None),
+            memory_config_init_func=config["agent_config"].get(
+                "memory_config_init_func", None
+            ),
             **_message_intercept_kwargs,
             environment=environment,
         )
@@ -328,6 +377,9 @@ class AgentSimulation:
         ):
             await init_func(simulation)
         logger.info("Starting Simulation...")
+        llm_log_lists = []
+        mqtt_log_lists = []
+        simulator_log_lists = []
         for step in config["workflow"]:
             logger.info(
                 f"Running step: type: {step['type']} - description: {step.get('description', 'no description')}"
@@ -335,11 +387,17 @@ class AgentSimulation:
             if step["type"] not in ["run", "step", "interview", "survey", "intervene"]:
                 raise ValueError(f"Invalid step type: {step['type']}")
             if step["type"] == "run":
-                await simulation.run(step.get("days", 1))
+                llm_log_list, mqtt_log_list, simulator_log_list = await simulation.run(step.get("days", 1))
+                llm_log_lists.extend(llm_log_list)
+                mqtt_log_lists.extend(mqtt_log_list)
+                simulator_log_lists.extend(simulator_log_list)
             elif step["type"] == "step":
                 times = step.get("times", 1)
                 for _ in range(times):
-                    await simulation.step()
+                    llm_log_list, mqtt_log_list, simulator_log_list = await simulation.step()
+                    llm_log_lists.extend(llm_log_list)
+                    mqtt_log_lists.extend(mqtt_log_list)
+                    simulator_log_lists.extend(simulator_log_list)
             elif step["type"] == "pause":
                 await simulation.pause_simulator()
             elif step["type"] == "resume":
@@ -347,7 +405,7 @@ class AgentSimulation:
             else:
                 await step["func"](simulation)
         logger.info("Simulation finished")
-
+        return llm_log_lists, mqtt_log_lists, simulator_log_lists
     @property
     def enable_avro(
         self,
@@ -423,7 +481,7 @@ class AgentSimulation:
     async def _monitor_exp_status(self, stop_event: asyncio.Event):
         """监控实验状态并更新
 
-        Args:
+        - **Args**:
             stop_event: 用于通知监控任务停止的事件
         """
         try:
@@ -465,7 +523,7 @@ class AgentSimulation:
 
     async def init_agents(
         self,
-        agent_count: Union[int, list[int]],
+        agent_count: dict[type[Agent], int],
         group_size: int = 10000,
         pg_sql_writers: int = 32,
         message_interceptors: int = 1,
@@ -473,25 +531,44 @@ class AgentSimulation:
         social_black_list: Optional[list[tuple[str, str]]] = None,
         message_listener: Optional[MessageBlockListenerBase] = None,
         embedding_model: Embeddings = SimpleEmbedding(),
+        memory_config_init_func: Optional[Callable] = None,
         memory_config_func: Optional[dict[type[Agent], Callable]] = None,
         environment: Optional[dict[str, str]] = None,
     ) -> None:
-        """初始化智能体
-
-        Args:
-            agent_count: 要创建的总智能体数量, 如果为列表，则每个元素表示一个智能体类创建的智能体数量
-            group_size: 每个组的智能体数量，每一个组为一个独立的ray actor
-            pg_sql_writers: 独立的PgSQL writer数量
-            message_interceptors: message拦截器数量
-            memory_config_func: 返回Memory配置的函数，需要返回(EXTRA_ATTRIBUTES, PROFILE, BASE)元组, 每个元素表示一个智能体类创建的Memory配置函数
-            environment: 环境变量，用于更新模拟器的环境变量
         """
-        if not isinstance(agent_count, list):
-            agent_count = [agent_count]
+        Initialize agents within the simulation.
+
+        - **Description**:
+            - Asynchronously initializes a specified number of agents for each provided agent class.
+            - Agents are grouped into independent Ray actors based on the `group_size`, with configurations for database writers,
+              message interceptors, and memory settings. Optionally updates the simulator's environment variables.
+
+        - **Args**:
+            - `agent_count` (dict[Type[Agent], int]): Dictionary mapping agent classes to the number of instances to create.
+            - `group_size` (int, optional): Number of agents per group, each group runs as an independent Ray actor. Defaults to 10000.
+            - `pg_sql_writers` (int, optional): Number of independent PgSQL writer processes. Defaults to 32.
+            - `message_interceptors` (int, optional): Number of message interceptor processes. Defaults to 1.
+            - `message_interceptor_blocks` (Optional[List[MessageBlockBase]], optional): List of message interception blocks. Defaults to None.
+            - `social_black_list` (Optional[List[Tuple[str, str]]], optional): List of tuples representing pairs of agents that should not communicate. Defaults to None.
+            - `message_listener` (Optional[MessageBlockListenerBase], optional): Listener for intercepted messages. Defaults to None.
+            - `embedding_model` (Embeddings, optional): Model used for generating embeddings for agents' memories. Defaults to SimpleEmbedding().
+            - `memory_config_init_func` (Optional[Callable], optional): Initialization function for setting up memory configuration. Defaults to None.
+            - `memory_config_func` (Optional[Dict[Type[Agent], Callable]], optional): Dictionary mapping agent classes to their memory configuration functions. Defaults to None.
+            - `environment` (Optional[Dict[str, str]], optional): Environment variables to update in the simulation. Defaults to None.
+
+        - **Raises**:
+            - `ValueError`: If the lengths of `agent_class` and `agent_count` do not match.
+
+        - **Returns**:
+            - `None`
+        """
+        self.agent_count = agent_count
 
         if len(self.agent_class) != len(agent_count):
-            raise ValueError("agent_class和agent_count的长度不一致")
+            raise ValueError("The length of agent_class and agent_count does not match")
 
+        if memory_config_init_func is not None:
+            await memory_config_init(self)
         if memory_config_func is None:
             memory_config_func = self.default_memory_config_func  # type:ignore
 
@@ -505,7 +582,7 @@ class AgentSimulation:
         # 收集所有参数
         for i in range(len(self.agent_class)):
             agent_class = self.agent_class[i]
-            agent_count_i = agent_count[i]
+            agent_count_i = agent_count[agent_class]
             assert memory_config_func is not None
             memory_config_func_i = memory_config_func.get(
                 agent_class, self.default_memory_config_func[agent_class]  # type:ignore
@@ -706,10 +783,32 @@ class AgentSimulation:
         )
         await self.messager.start_listening.remote()  # type:ignore
 
+        agent_ids = set()
+        org_ids = set()
+        for group in self._groups.values():
+            ids = await group.get_economy_ids.remote()
+            agent_ids.update(ids[0])
+            org_ids.update(ids[1])
+        await self.economy_client.set_ids(agent_ids, org_ids)
+        for group in self._groups.values():
+            await group.set_economy_ids.remote(agent_ids, org_ids)
+
     async def gather(
         self, content: str, target_agent_uuids: Optional[list[str]] = None
     ):
-        """收集智能体的特定信息"""
+        """
+        Collect specific information from agents.
+
+        - **Description**:
+            - Asynchronously gathers specified content from targeted agents within all groups.
+
+        - **Args**:
+            - `content` (str): The information to collect from the agents.
+            - `target_agent_uuids` (Optional[List[str]], optional): A list of agent UUIDs to target. Defaults to None, meaning all agents are targeted.
+
+        - **Returns**:
+            - Result of the gathering process as returned by each group's `gather` method.
+        """
         gather_tasks = []
         for group in self._groups.values():
             gather_tasks.append(group.gather.remote(content, target_agent_uuids))
@@ -721,7 +820,20 @@ class AgentSimulation:
         keys: Optional[list[str]] = None,
         values: Optional[list[Any]] = None,
     ) -> list[str]:
-        """过滤出指定类型的智能体"""
+        """
+        Filter out agents of specified types or with matching key-value pairs.
+
+        - **Args**:
+            - `types` (Optional[List[Type[Agent]]], optional): Types of agents to filter for. Defaults to None.
+            - `keys` (Optional[List[str]], optional): Keys to match in agent attributes. Defaults to None.
+            - `values` (Optional[List[Any]], optional): Values corresponding to keys for matching. Defaults to None.
+
+        - **Raises**:
+            - `ValueError`: If neither types nor keys and values are provided, or if the lengths of keys and values do not match.
+
+        - **Returns**:
+            - `List[str]`: A list of filtered agent UUIDs.
+        """
         if not types and not keys and not values:
             return self._agent_uuids
         group_to_filter = []
@@ -744,12 +856,26 @@ class AgentSimulation:
             return filtered_uuids
 
     async def update_environment(self, key: str, value: str):
+        """
+        Update the environment variables for the simulation and all agent groups.
+
+        - **Args**:
+            - `key` (str): The environment variable key to update.
+            - `value` (str): The new value for the environment variable.
+        """
         self._simulator.update_environment(key, value)
         for group in self._groups.values():
             await group.update_environment.remote(key, value)
 
     async def update(self, target_agent_uuid: str, target_key: str, content: Any):
-        """更新指定智能体的记忆"""
+        """
+        Update the memory of a specified agent.
+
+        - **Args**:
+            - `target_agent_uuid` (str): The UUID of the target agent to update.
+            - `target_key` (str): The key in the agent's memory to update.
+            - `content` (Any): The new content to set for the target key.
+        """
         group = self._agent_uuid2group[target_agent_uuid]
         await group.update.remote(target_agent_uuid, target_key, content)
 
@@ -760,13 +886,30 @@ class AgentSimulation:
         content: Any,
         mode: Literal["replace", "merge"] = "replace",
     ):
-        """更新指定智能体的经济数据"""
+        """
+        Update economic data for a specified agent.
+
+        - **Args**:
+            - `target_agent_id` (int): The ID of the target agent whose economic data to update.
+            - `target_key` (str): The key in the agent's economic data to update.
+            - `content` (Any): The new content to set for the target key.
+            - `mode` (Literal["replace", "merge"], optional): Mode of updating the economic data. Defaults to "replace".
+        """
         await self.economy_client.update(
             id=target_agent_id, key=target_key, value=content, mode=mode
         )
 
     async def send_survey(self, survey: Survey, agent_uuids: list[str] = []):
-        """发送问卷"""
+        """
+        Send a survey to specified agents.
+
+        - **Args**:
+            - `survey` (Survey): The survey object to send.
+            - `agent_uuids` (List[str], optional): List of agent UUIDs to receive the survey. Defaults to an empty list.
+
+        - **Returns**:
+            - None
+        """
         survey_dict = survey.to_dict()
         _date_time = datetime.now(timezone.utc)
         payload = {
@@ -791,7 +934,16 @@ class AgentSimulation:
     async def send_interview_message(
         self, content: str, agent_uuids: Union[str, list[str]]
     ):
-        """发送采访消息"""
+        """
+        Send an interview message to specified agents.
+
+        - **Args**:
+            - `content` (str): The content of the message to send.
+            - `agent_uuids` (Union[str, List[str]]): A single UUID string or a list of UUID strings for the agents to receive the message.
+
+        - **Returns**:
+            - None
+        """
         _date_time = datetime.now(timezone.utc)
         payload = {
             "from": SURVEY_SENDER_UUID,
@@ -814,12 +966,37 @@ class AgentSimulation:
             await asyncio.sleep(3)
 
     async def extract_metric(self, metric_extractors: list[Callable]):
-        """提取指标"""
+        """
+        Extract metrics using provided extractors.
+
+        - **Description**:
+            - Asynchronously applies each metric extractor function to the simulation to collect various metrics.
+
+        - **Args**:
+            - `metric_extractors` (List[Callable]): A list of callable functions that take the simulation instance as an argument and return a metric or perform some form of analysis.
+
+        - **Returns**:
+            - None
+        """
         for metric_extractor in metric_extractors:
             await metric_extractor(self)
 
     async def step(self):
-        """Run one step, each agent execute one forward"""
+        """
+        Execute one step of the simulation where each agent performs its forward action.
+
+        - **Description**:
+            - Checks if new agents need to be inserted based on the current day of the simulation. If so, it inserts them.
+            - Executes the forward method for each agent group to advance the simulation by one step.
+            - Saves the state of all agent groups after the step has been completed.
+            - Optionally extracts metrics if the current step matches the interval specified for any metric extractors.
+
+        - **Raises**:
+            - `RuntimeError`: If there is an error during the execution of the step, it logs the error and rethrows it as a RuntimeError.
+
+        - **Returns**:
+            - None
+        """
         try:
             # check whether insert agents
             simulator_day = await self._simulator.get_simulator_day()
@@ -837,11 +1014,21 @@ class AgentSimulation:
             # step
             simulator_day = await self._simulator.get_simulator_day()
             simulator_time = int(await self._simulator.get_time())
-            logger.info(f"Start simulation day {simulator_day} at {simulator_time}, step {self._total_steps}")
+            logger.info(
+                f"Start simulation day {simulator_day} at {simulator_time}, step {self._total_steps}"
+            )
             tasks = []
             for group in self._groups.values():
                 tasks.append(group.step.remote())
-            await asyncio.gather(*tasks)
+            log_messages_groups = await asyncio.gather(*tasks)
+            llm_log_list = []
+            mqtt_log_list = []
+            simulator_log_list = []
+            for log_messages_group in log_messages_groups:
+                llm_log_list.extend(log_messages_group['llm_log'])
+                mqtt_log_list.extend(log_messages_group['mqtt_log'])
+                simulator_log_list.extend(log_messages_group['simulator_log'])
+            
             # save
             simulator_day = await self._simulator.get_simulator_day()
             simulator_time = int(await self._simulator.get_time())
@@ -850,14 +1037,15 @@ class AgentSimulation:
                 save_tasks.append(group.save.remote(simulator_day, simulator_time))
             await asyncio.gather(*save_tasks)
             self._total_steps += 1
-            if self.metric_extractor is not None:
-                print(f"total_steps: {self._total_steps}, excute metric")
+            if self.metric_extractors is not None:  # type:ignore
                 to_excute_metric = [
                     metric[1]
-                    for metric in self.metric_extractor
+                    for metric in self.metric_extractors  # type:ignore
                     if self._total_steps % metric[0] == 0
                 ]
                 await self.extract_metric(to_excute_metric)
+
+            return llm_log_list, mqtt_log_list, simulator_log_list
         except Exception as e:
             import traceback
 
@@ -868,7 +1056,26 @@ class AgentSimulation:
         self,
         day: int = 1,
     ):
-        """Run the simulation by days"""
+        """
+        Run the simulation for a specified number of days.
+
+        - **Args**:
+            - `day` (int, optional): The number of days to run the simulation. Defaults to 1.
+
+        - **Description**:
+            - Updates the experiment status to running and sets up monitoring for the experiment's status.
+            - Runs the simulation loop until the end time, which is calculated based on the current time and the number of days to simulate.
+            - After completing the simulation, updates the experiment status to finished, or to failed if an exception occurs.
+
+        - **Raises**:
+            - `RuntimeError`: If there is an error during the simulation, it logs the error and updates the experiment status to failed before rethrowing the exception.
+
+        - **Returns**:
+            - None
+        """
+        llm_log_lists = []
+        mqtt_log_lists = []
+        simulator_log_lists = []
         try:
             self._exp_info["num_day"] += day
             await self._update_exp_status(1)  # 更新状态为运行中
@@ -886,7 +1093,10 @@ class AgentSimulation:
                     current_time = await self._simulator.get_time()
                     if current_time >= end_time:  # type:ignore
                         break
-                    await self.step()
+                    llm_log_list, mqtt_log_list, simulator_log_list = await self.step()
+                    llm_log_lists.extend(llm_log_list)
+                    mqtt_log_lists.extend(mqtt_log_list)
+                    simulator_log_lists.extend(simulator_log_list)
             finally:
                 # 设置停止事件
                 stop_event.set()
@@ -895,7 +1105,7 @@ class AgentSimulation:
 
             # 运行成功后更新状态
             await self._update_exp_status(2)
-
+            return llm_log_lists, mqtt_log_lists, simulator_log_lists
         except Exception as e:
             error_msg = f"模拟器运行错误: {str(e)}"
             logger.error(error_msg)

pycityagent/survey/manager.py

@@ -8,10 +8,33 @@ from .models import Page, Question, QuestionType, Survey
 
 class SurveyManager:
     def __init__(self):
+        """
+        Initializes a new instance of the SurveyManager class.
+
+        - **Description**:
+            - Manages the creation and retrieval of surveys. Uses an internal dictionary to store survey instances by their unique identifier.
+
+        - **Attributes**:
+            - `_surveys` (dict[str, Survey]): A dictionary mapping survey IDs to `Survey` instances.
+        """
         self._surveys: dict[str, Survey] = {}
 
     def create_survey(self, title: str, description: str, pages: list[dict]) -> Survey:
-        """创建新问卷"""
+        """
+        Create a new survey with specified title, description, and pages containing questions.
+
+        - **Description**:
+            - Generates a unique ID for the survey, converts the provided page and question data into `Page` and `Question` objects,
+              and adds the created survey to the internal storage.
+
+        - **Args**:
+            - `title` (str): The title of the survey.
+            - `description` (str): A brief description of what the survey is about.
+            - `pages` (list[dict]): A list of dictionaries where each dictionary contains page information including elements which are question definitions.
+
+        - **Returns**:
+            - `Survey`: An instance of the `Survey` class representing the newly created survey.
+        """
         survey_id = uuid.uuid4()
 
         # 转换页面和问题数据
@@ -46,9 +69,28 @@ class SurveyManager:
         return survey
 
     def get_survey(self, survey_id: str) -> Optional[Survey]:
-        """获取指定问卷"""
+        """
+        Retrieve a specific survey by its unique identifier.
+
+        - **Description**:
+            - Searches for a survey within the internal storage using the provided survey ID.
+
+        - **Args**:
+            - `survey_id` (str): The unique identifier of the survey to retrieve.
+
+        - **Returns**:
+            - `Optional[Survey]`: An instance of the `Survey` class if found; otherwise, None.
+        """
         return self._surveys.get(survey_id)
 
     def get_all_surveys(self) -> list[Survey]:
-        """获取所有问卷"""
+        """
+        Get all surveys that have been created.
+
+        - **Description**:
+            - Retrieves all stored surveys from the internal storage.
+
+        - **Returns**:
+            - `list[Survey]`: A list of `Survey` instances.
+        """
         return list(self._surveys.values())