pycityagent 1.0.0__tar.gz → 2.0.0a1__tar.gz

pycityagent-2.0.0a1/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.1
+Name: pycityagent
+Version: 2.0.0a1
+Summary: LLM-based城市环境agent构建库
+License: MIT
+Author: Yuwei Yan
+Author-email: pinkgranite86@gmail.com
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: Pillow (==11.0.0)
+Requires-Dist: Requests (==2.32.3)
+Requires-Dist: Shapely (==2.0.6)
+Requires-Dist: aiohttp (==3.10.10)
+Requires-Dist: citystreetview (==1.2.4)
+Requires-Dist: dashscope (==1.14.1)
+Requires-Dist: geojson (==3.1.0)
+Requires-Dist: gradio (>=5.7.1,<6.0.0)
+Requires-Dist: grpcio (==1.67.1)
+Requires-Dist: matplotlib (==3.8.3)
+Requires-Dist: mosstool (==1.0.24)
+Requires-Dist: networkx (==3.2.1)
+Requires-Dist: numpy (>=1.20.0,<2.0.0)
+Requires-Dist: openai (==1.54.3)
+Requires-Dist: poetry (>=1.2.2)
+Requires-Dist: protobuf (<=4.24.0)
+Requires-Dist: pycitydata (==1.0.0)
+Requires-Dist: pycityproto (==2.0.7)
+Requires-Dist: pyyaml (>=6.0.2,<7.0.0)
+Requires-Dist: sidecar (==0.7.0)
+Requires-Dist: zhipuai (>=2.1.5.20230904,<3.0.0.0)
+Description-Content-Type: text/markdown
+
+
+
+<div style="text-align: center; background-color: white; padding: 20px; border-radius: 30px;">
+  <img src="./static/cityagent_logo.png" alt="CityAgent Logo" width="200" style="display: block; margin: 0 auto;">
+  <h1 style="color: black; margin: 0; font-size: 3em;">CityAgent: LLM Agents in City</h1>
+</div>
+
+
+# 🚀 CityAgent
+![License](https://img.shields.io/badge/license-MIT-green) &ensp;
+[![Online Documentation](https://img.shields.io/badge/docs-online-blue)](https://docs.fiblab.net/pycityagent) &ensp;
+
+
+CityAgent is an advanced framework specifically designed for building intelligent agents in urban simulation environments. With CityAgent, you can easily create and manage agents, enabling complex urban scenarios to be modeled and simulated efficiently.
+
+## 🌟 Features
+- **Modular Design**: Plug-and-play components for agent behavior.
+- **Urban Environment Simulation**: Built to simulate diverse urban scenarios.
+- **LLM Integration**: Connects to language models for enriched agent behavior.
+- **Flexible Configuration**: YAML-based configuration for easy customization.
+
+## 📑 Table of Contents
+
+1. [News](#news)
+2. [Framework](#framework)
+3. [Setup](#setup)
+4. [QuickStart](#quickstart)
+5. [Contributing](#contributing)
+6. [License](#license)
+
+<a id="news"></a>
+## 📰 News
+
+- 📢 **11.10** - Initial update is now live!
+- 📢 **2.x version is not compatible* with 1.x version**
+
+Stay tuned for upcoming updates!
+
+<a id="framework"></a>
+## 🛠️ Framework
+
+CityAgent is built with a multi-layered architecture that allows users to create and manage intelligent agents for urban environments in a scalable and flexible manner. The framework is divided into several key layers, each responsible for different functionalities as depicted in the diagram below:
+
+<img src="./static/framework.png" alt="CityAgent Framework Overview" width="600" style="display: block; margin: 20px auto;">
+
+### Architectural Layers
+- **Model Layer**: Handles agent configuration, task definitions, logging setup, and result aggregation.
+  - **Task Configuration**: Defines agent behaviors and objectives.
+  - **Unified Execution**: Centralized entry point for agent processes.
+
+- **Agent Layer**: Implements multi-head workflows to manage agent actions.
+  - **Memory**: Stores agent-related information, such as location and motion.
+    - **Static Profiles**: Maintains unchanging agent attributes.
+    - **Custom Data Pool**: Functions as a working memory.
+  - **Multi-Head Workflow**: Supports both normal and event-driven modes.
+    - **Reason Block**: Utilizes LLMs to determine decisions based on context and tools.
+    - **Route Block**: Chooses the best path based on defined criteria using LLMs or rules.
+    - **Action Block**: Executes actions as per defined contexts and tools.
+
+- **Message Layer**: Facilitates agent communication through peer-to-peer (P2P), peer-to-group (P2G), and group chats.
+
+- **Environment Layer**: Manages interaction with the urban environment.
+  - **Environment Sensing**: Reads data from the environment.
+  - **Interaction Handling**: Writes or modifies environmental states.
+  - **Message Management**: Handles incoming and outgoing agent messages.
+
+- **LLM Layer**: Provides configuration and integration for using LLMs in the agent's workflow.
+  - **Prompting & Execution**: Supports model invocation and monitoring.
+  - **Model Support**: Compatible with various LLMs, such as OpenAI, Qwen, Deepseek, etc.
+
+- **Tool Layer**: Provides additional utilities to the agents.
+  - **String Processing**: Handles parsing and formatting.
+  - **Result Analysis**: Parses responses in formats like JSON or dictionaries.
+  - **Data Storage & Retrieval**: Includes ranking and search tools.
+
+<a id="setup"></a>
+## ⚙️ Setup
+
+You can set up CityAgent in two different ways:
+
+### 1. From Scratch
+
+Follow these steps to set up CityAgent from scratch by cloning the repository. The project is built using Python and managed with Poetry.
+
+1. **Clone the Repository**
+   ```bash
+   git clone [This Repository]
+   ```
+2. **Navigate to the Project Directory**
+   ```bash
+   cd pycityagent
+   ```
+3. **Install Poetry** (if not installed)
+   ```bash
+   curl -sSL https://install.python-poetry.org | python3 -
+   ```
+4. **Install Dependencies**
+   ```bash
+   poetry install
+   ```
+5. **Activate the Virtual Environment**
+   ```bash
+   poetry shell
+   ```
+
+### 2. Install via pip
+
+This method is not yet available. Stay tuned for future updates!
+
+<a id="quickstart"></a>
+## 🚀 QuickStart
+
+Get started with CityAgent in just a few minutes!
+
+### 1. Config Configuration
+CityAgent uses a configuration file written in `.yaml` format to manage settings for various components. Below is a sample configuration file (`config_template.yaml`) that showcases the structure:
+
+```yaml
+llm_request:
+  text_request:
+    request_type: openai
+    api_key: <YOUR_API_KEY>
+    model: gpt-4o
+  img_understand_request:
+    request_type: none
+    api_key: none
+    model: none
+  img_generate_request:
+    request_type: none
+    api_key: none
+    model: none
+
+simulator_request:
+  simulator:
+    server: https://api-opencity-2x.fiblab.net:58081
+  map_request:
+    mongo_uri: <MONGO_URI>
+    mongo_db: llmsim
+    mongo_coll: map_beijing5ring_withpoi_0424
+    cache_dir: ./cache
+  route_request:
+    server: http://api-opencity-2x.fiblab.net:58082
+  streetview_request:
+    engine: baidumap / googlemap
+    mapAK: baidumap api-key (if you use baidumap engine)
+    proxy: googlemap proxy (if you use googlemap engine)
+```
+
+### 2. Example Usage
+To get started quickly, please refer to the `examples` folder in the repository. It contains sample scripts and configurations to help you understand how to create and use agents in an urban simulation environment.
+
+<a id="contributing"></a>
+## 🤝 Contributing
+We welcome contributions from the community!.
+
+<a id="license"></a>
+## 📄 License
+
+CityAgent is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.
+
+---
+
+Feel free to reach out if you have any questions, suggestions, or want to collaborate!
+
+---
+
+> **Follow us**: Stay updated with the latest news and features by watching the repository.
+
+---
+

pycityagent-2.0.0a1/README.md

@@ -0,0 +1,169 @@
+
+
+<div style="text-align: center; background-color: white; padding: 20px; border-radius: 30px;">
+  <img src="./static/cityagent_logo.png" alt="CityAgent Logo" width="200" style="display: block; margin: 0 auto;">
+  <h1 style="color: black; margin: 0; font-size: 3em;">CityAgent: LLM Agents in City</h1>
+</div>
+
+
+# 🚀 CityAgent
+![License](https://img.shields.io/badge/license-MIT-green) &ensp;
+[![Online Documentation](https://img.shields.io/badge/docs-online-blue)](https://docs.fiblab.net/pycityagent) &ensp;
+
+
+CityAgent is an advanced framework specifically designed for building intelligent agents in urban simulation environments. With CityAgent, you can easily create and manage agents, enabling complex urban scenarios to be modeled and simulated efficiently.
+
+## 🌟 Features
+- **Modular Design**: Plug-and-play components for agent behavior.
+- **Urban Environment Simulation**: Built to simulate diverse urban scenarios.
+- **LLM Integration**: Connects to language models for enriched agent behavior.
+- **Flexible Configuration**: YAML-based configuration for easy customization.
+
+## 📑 Table of Contents
+
+1. [News](#news)
+2. [Framework](#framework)
+3. [Setup](#setup)
+4. [QuickStart](#quickstart)
+5. [Contributing](#contributing)
+6. [License](#license)
+
+<a id="news"></a>
+## 📰 News
+
+- 📢 **11.10** - Initial update is now live!
+- 📢 **2.x version is not compatible* with 1.x version**
+
+Stay tuned for upcoming updates!
+
+<a id="framework"></a>
+## 🛠️ Framework
+
+CityAgent is built with a multi-layered architecture that allows users to create and manage intelligent agents for urban environments in a scalable and flexible manner. The framework is divided into several key layers, each responsible for different functionalities as depicted in the diagram below:
+
+<img src="./static/framework.png" alt="CityAgent Framework Overview" width="600" style="display: block; margin: 20px auto;">
+
+### Architectural Layers
+- **Model Layer**: Handles agent configuration, task definitions, logging setup, and result aggregation.
+  - **Task Configuration**: Defines agent behaviors and objectives.
+  - **Unified Execution**: Centralized entry point for agent processes.
+
+- **Agent Layer**: Implements multi-head workflows to manage agent actions.
+  - **Memory**: Stores agent-related information, such as location and motion.
+    - **Static Profiles**: Maintains unchanging agent attributes.
+    - **Custom Data Pool**: Functions as a working memory.
+  - **Multi-Head Workflow**: Supports both normal and event-driven modes.
+    - **Reason Block**: Utilizes LLMs to determine decisions based on context and tools.
+    - **Route Block**: Chooses the best path based on defined criteria using LLMs or rules.
+    - **Action Block**: Executes actions as per defined contexts and tools.
+
+- **Message Layer**: Facilitates agent communication through peer-to-peer (P2P), peer-to-group (P2G), and group chats.
+
+- **Environment Layer**: Manages interaction with the urban environment.
+  - **Environment Sensing**: Reads data from the environment.
+  - **Interaction Handling**: Writes or modifies environmental states.
+  - **Message Management**: Handles incoming and outgoing agent messages.
+
+- **LLM Layer**: Provides configuration and integration for using LLMs in the agent's workflow.
+  - **Prompting & Execution**: Supports model invocation and monitoring.
+  - **Model Support**: Compatible with various LLMs, such as OpenAI, Qwen, Deepseek, etc.
+
+- **Tool Layer**: Provides additional utilities to the agents.
+  - **String Processing**: Handles parsing and formatting.
+  - **Result Analysis**: Parses responses in formats like JSON or dictionaries.
+  - **Data Storage & Retrieval**: Includes ranking and search tools.
+
+<a id="setup"></a>
+## ⚙️ Setup
+
+You can set up CityAgent in two different ways:
+
+### 1. From Scratch
+
+Follow these steps to set up CityAgent from scratch by cloning the repository. The project is built using Python and managed with Poetry.
+
+1. **Clone the Repository**
+   ```bash
+   git clone [This Repository]
+   ```
+2. **Navigate to the Project Directory**
+   ```bash
+   cd pycityagent
+   ```
+3. **Install Poetry** (if not installed)
+   ```bash
+   curl -sSL https://install.python-poetry.org | python3 -
+   ```
+4. **Install Dependencies**
+   ```bash
+   poetry install
+   ```
+5. **Activate the Virtual Environment**
+   ```bash
+   poetry shell
+   ```
+
+### 2. Install via pip
+
+This method is not yet available. Stay tuned for future updates!
+
+<a id="quickstart"></a>
+## 🚀 QuickStart
+
+Get started with CityAgent in just a few minutes!
+
+### 1. Config Configuration
+CityAgent uses a configuration file written in `.yaml` format to manage settings for various components. Below is a sample configuration file (`config_template.yaml`) that showcases the structure:
+
+```yaml
+llm_request:
+  text_request:
+    request_type: openai
+    api_key: <YOUR_API_KEY>
+    model: gpt-4o
+  img_understand_request:
+    request_type: none
+    api_key: none
+    model: none
+  img_generate_request:
+    request_type: none
+    api_key: none
+    model: none
+
+simulator_request:
+  simulator:
+    server: https://api-opencity-2x.fiblab.net:58081
+  map_request:
+    mongo_uri: <MONGO_URI>
+    mongo_db: llmsim
+    mongo_coll: map_beijing5ring_withpoi_0424
+    cache_dir: ./cache
+  route_request:
+    server: http://api-opencity-2x.fiblab.net:58082
+  streetview_request:
+    engine: baidumap / googlemap
+    mapAK: baidumap api-key (if you use baidumap engine)
+    proxy: googlemap proxy (if you use googlemap engine)
+```
+
+### 2. Example Usage
+To get started quickly, please refer to the `examples` folder in the repository. It contains sample scripts and configurations to help you understand how to create and use agents in an urban simulation environment.
+
+<a id="contributing"></a>
+## 🤝 Contributing
+We welcome contributions from the community!.
+
+<a id="license"></a>
+## 📄 License
+
+CityAgent is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.
+
+---
+
+Feel free to reach out if you have any questions, suggestions, or want to collaborate!
+
+---
+
+> **Follow us**: Stay updated with the latest news and features by watching the repository.
+
+---

pycityagent-2.0.0a1/pycityagent/__init__.py

@@ -0,0 +1,8 @@
+"""
+Pycityagent: 城市智能体构建框架
+"""
+
+from .agent import Agent, CitizenAgent, InstitutionAgent
+from .environment import Simulator
+
+__all__ = ["Agent", "Simulator", "CitizenAgent", "InstitutionAgent"]

pycityagent-2.0.0a1/pycityagent/agent.py

@@ -0,0 +1,214 @@
+"""智能体模板类及其定义"""
+
+from abc import ABC, abstractmethod
+from datetime import datetime
+from enum import Enum
+from typing import Dict, List, Optional
+
+from .economy import EconomyClient
+from .environment import Simulator
+from .llm import LLM
+from .memory import Memory
+
+
+class AgentType(Enum):
+    """
+    Agent类型
+
+    - Citizen, Citizen type agent
+    - Institution, Orgnization or institution type agent
+    """
+
+    Unspecified = "Unspecified"
+    Citizen = "Citizen"
+    Institution = "Institution"
+
+
+class Agent(ABC):
+    """
+    Agent base class
+    """
+
+    def __init__(
+        self,
+        name: str,
+        type: AgentType = AgentType.Unspecified,
+        llm_client: Optional[LLM] = None,
+        economy_client: Optional[EconomyClient] = None,
+        simulator: Optional[Simulator] = None,
+        memory: Optional[Memory] = 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.
+            simulator (Simulator, optional): The simulator object. Defaults to None.
+            memory (Memory, optional): The memory of the agent. Defaults to None.
+        """
+        self._name = name
+        self._type = type
+        self._llm_client = llm_client
+        self._economy_client = economy_client
+        self._simulator = simulator
+        self._memory = memory
+        self._has_bound_to_simulator = False
+        self._interview_history: List[Dict] = []  # 存储采访历史
+
+    def set_memory(self, memory: Memory):
+        """
+        Set the memory of the agent.
+        """
+        self._memory = memory
+
+    def set_simulator(self, simulator: Simulator):
+        """
+        Set the simulator of the agent.
+        """
+        self._simulator = simulator
+
+    def set_economy_client(self, economy_client: EconomyClient):
+        """
+        Set the economy_client of the agent.
+        """
+        self._economy_client = economy_client
+
+    @property
+    def LLM(self):
+        """The Agent's LLM"""
+        if self._llm_client is None:
+            raise RuntimeError(
+                f"LLM access before assignment, please `set_llm_client` first!"
+            )
+        return self._llm_client
+
+    @property
+    def economy_client(self):
+        """The Agent's EconomyClient"""
+        if self._economy_client is None:
+            raise RuntimeError(
+                f"EconomyClient access before assignment, please `set_economy_client` first!"
+            )
+        return self._economy_client
+
+    @property
+    def memory(self):
+        """The Agent's Memory"""
+        if self._memory is None:
+            raise RuntimeError(
+                f"Memory access before assignment, please `set_memory` first!"
+            )
+        return self._memory
+
+    @property
+    def simulator(self):
+        """The Simulator"""
+        if self._simulator is None:
+            raise RuntimeError(
+                f"Simulator access before assignment, please `set_simulator` first!"
+            )
+        return self._simulator
+
+    async def generate_response(self, question: str) -> str:
+        """生成回答
+
+        基于智能体的记忆和当前状态，生成对问题的回答。
+
+        Args:
+            question: 需要回答的问题
+
+        Returns:
+            str: 智能体的回答
+        """
+        dialog = []
+
+        # 添加系统提示
+        system_prompt = f"你是一个名叫{self._name}的{self._type.value}。请以第一人称的方式回答问题,保持回答简洁明了。"
+        dialog.append({"role": "system", "content": system_prompt})
+
+        # 添加记忆上下文
+        if self._memory:
+            relevant_memories = await self._memory.search(question)
+            if relevant_memories:
+                dialog.append(
+                    {
+                        "role": "system",
+                        "content": f"基于以下记忆回答问题:\n{relevant_memories}",
+                    }
+                )
+
+        # 添加用户问题
+        dialog.append({"role": "user", "content": question})
+
+        # 使用LLM生成回答
+        if not self._llm_client:
+            return "抱歉，我现在无法回答问题。"
+
+        response = await self._llm_client.atext_request(dialog)  # type:ignore
+
+        # 记录采访历史
+        self._interview_history.append(
+            {
+                "timestamp": datetime.now().isoformat(),
+                "question": question,
+                "response": response,
+            }
+        )
+
+        return response  # type:ignore
+
+    def get_interview_history(self) -> List[Dict]:
+        """获取采访历史记录"""
+        return self._interview_history
+
+    @abstractmethod
+    async def forward(self) -> None:
+        """智能体行为逻辑"""
+        raise NotImplementedError
+
+
+class CitizenAgent(Agent):
+    """
+    CitizenAgent: 城市居民智能体类及其定义
+    """
+
+    def __init__(
+        self,
+        name: str,
+        llm_client: Optional[LLM] = None,
+        simulator: Optional[Simulator] = None,
+        memory: Optional[Memory] = None,
+    ) -> None:
+        super().__init__(
+            name,
+            AgentType.Citizen,
+            llm_client,
+            None,
+            simulator,
+            memory,
+        )
+
+
+class InstitutionAgent(Agent):
+    """
+    InstitutionAgent: 机构智能体类及其定义
+    """
+
+    def __init__(
+        self,
+        name: str,
+        llm_client: Optional[LLM] = None,
+        simulator: Optional[Simulator] = None,
+        memory: Optional[Memory] = None,
+    ) -> None:
+        super().__init__(
+            name,
+            AgentType.Institution,
+            llm_client,
+            None,
+            simulator,
+            memory,
+        )

pycityagent-2.0.0a1/pycityagent/economy/__init__.py

@@ -0,0 +1,5 @@
+from .econ_client import EconomyClient
+
+__all__ = [
+    "EconomyClient",
+]