pycityagent 2.0.0a43__cp39-cp39-macosx_11_0_arm64.whl

pycityagent/workflow/tool.py

@@ -0,0 +1,240 @@
+import time
+from collections import defaultdict
+from collections.abc import Callable, Sequence
+from typing import Any, Optional, Union
+
+from mlflow.entities import Metric
+
+from ..agent import Agent
+from ..environment import (LEVEL_ONE_PRE, POI_TYPE_DICT, AoiService,
+                           PersonService)
+from ..workflow import Block
+
+
+class Tool:
+    """Abstract tool class for callable tools. Can be bound to an `Agent` or `Block` instance.
+
+    This class serves as a base for creating various tools that can perform different operations.
+    It is intended to be subclassed by specific tool implementations.
+    """
+
+    def __get__(self, instance, owner):
+        if instance is None:
+            return self
+        subclass = type(self)
+        if not hasattr(instance, "_tools"):
+            instance._tools = {}
+        if subclass not in instance._tools:
+            tool_instance = subclass()
+            tool_instance._instance = instance  # type: ignore
+            instance._tools[subclass] = tool_instance
+        return instance._tools[subclass]
+
+    def __call__(self, *args: Any, **kwds: Any) -> Any:
+        """Invoke the tool's functionality.
+
+        This method must be implemented by subclasses to provide specific behavior.
+        """
+        raise NotImplementedError
+
+    @property
+    def agent(self) -> Agent:
+        instance = self._instance  # type:ignore
+        if not isinstance(instance, Agent):
+            raise RuntimeError(
+                f"Tool bind to object `{type(instance).__name__}`, not an `Agent` object!"
+            )
+        return instance
+
+    @property
+    def block(self) -> Block:
+        instance = self._instance  # type:ignore
+        if not isinstance(instance, Block):
+            raise RuntimeError(
+                f"Tool bind to object `{type(instance).__name__}`, not an `Block` object!"
+            )
+        return instance
+
+
+class GetMap(Tool):
+    """Retrieve the map from the simulator. Can be bound only to an `Agent` instance."""
+
+    def __init__(self) -> None:
+        self.variables = []
+
+    async def __call__(self) -> Union[Any, Callable]:
+        agent = self.agent
+        if agent.simulator is None:
+            raise ValueError("Simulator is not set.")
+        return agent.simulator.map
+
+
+class SencePOI(Tool):
+    """Retrieve the Point of Interest (POI) of the current scene.
+
+    This tool computes the POI based on the current `position` stored in memory and returns
+    points of interest (POIs) within a specified radius. Can be bound only to an `Agent` instance.
+
+    Attributes:
+        radius (int): The radius within which to search for POIs.
+        category_prefix (str): The prefix for the categories of POIs to consider.
+        variables (list[str]): A list of variables relevant to the tool's operation.
+
+    Args:
+        radius (int, optional): The circular search radius. Defaults to 100.
+        category_prefix (str, optional): The category prefix to filter POIs. Defaults to LEVEL_ONE_PRE.
+
+    Methods:
+        __call__(radius: Optional[int] = None, category_prefix: Optional[str] = None) -> Union[Any, Callable]:
+            Executes the AOI retrieval operation, returning POIs based on the current state of memory and simulator.
+    """
+
+    def __init__(self, radius: int = 100, category_prefix=LEVEL_ONE_PRE) -> None:
+        self.radius = radius
+        self.category_prefix = category_prefix
+        self.variables = ["position"]
+
+    async def __call__(
+        self, radius: Optional[int] = None, category_prefix: Optional[str] = None
+    ) -> Union[Any, Callable]:
+        """Retrieve the POIs within the specified radius and category prefix.
+
+        If both `radius` and `category_prefix` are None, the method will use the current position
+        from memory to query POIs using the simulator. Otherwise, it will return a new instance
+        of SenceAoi with the specified parameters.
+
+        Args:
+            radius (Optional[int]): A specific radius for the AOI query. If not provided, defaults to the instance's radius.
+            category_prefix (Optional[str]): A specific category prefix to filter POIs. If not provided, defaults to the instance's category_prefix.
+
+        Raises:
+            ValueError: If memory or simulator is not set.
+
+        Returns:
+            Union[Any, Callable]: The query results or a callable for a new SenceAoi instance.
+        """
+        agent = self.agent
+        if agent.memory is None or agent.simulator is None:
+            raise ValueError("Memory or Simulator is not set.")
+        if radius is None and category_prefix is None:
+            position = await agent.memory.get("position")
+            resp = []
+            for prefix in self.category_prefix:
+                resp += agent.simulator.map.query_pois(
+                    center=(position["xy_position"]["x"], position["xy_position"]["y"]),
+                    radius=self.radius,
+                    category_prefix=prefix,
+                )
+            # * Map six-digit codes to specific types
+            for poi in resp:
+                cate_str = poi[0]["category"]
+                poi[0]["category"] = POI_TYPE_DICT[cate_str]
+        else:
+            radius_ = radius if radius else self.radius
+            return SencePOI(radius_, category_prefix)
+
+
+class UpdateWithSimulator(Tool):
+    def __init__(self) -> None:
+        pass
+
+    async def _update_motion_with_sim(
+        self,
+    ):
+        agent = self.agent
+        if agent._simulator is None:
+            return
+        if not agent._has_bound_to_simulator:
+            await agent._bind_to_simulator()  # type: ignore
+        simulator = agent.simulator
+        memory = agent.memory
+        person_id = await memory.get("id")
+        resp = await simulator.get_person(person_id)
+        resp_dict = resp["person"]
+        for k, v in resp_dict.get("motion", {}).items():
+            try:
+                await memory.get(k)
+                await memory.update(
+                    k, v, mode="replace", protect_llm_read_only_fields=False
+                )
+            except KeyError as e:
+                continue
+
+    async def __call__(
+        self,
+    ):
+        agent = self.agent
+        await self._update_motion_with_sim()
+
+
+class ResetAgentPosition(Tool):
+    def __init__(self) -> None:
+        pass
+
+    async def __call__(
+        self,
+        aoi_id: Optional[int] = None,
+        poi_id: Optional[int] = None,
+        lane_id: Optional[int] = None,
+        s: Optional[float] = None,
+    ):
+        agent = self.agent
+        memory = agent.memory
+        await agent.simulator.reset_person_position(
+            person_id=await memory.get("id"),
+            aoi_id=aoi_id,
+            poi_id=poi_id,
+            lane_id=lane_id,
+            s=s,
+        )
+
+
+class ExportMlflowMetrics(Tool):
+    def __init__(self, log_batch_size: int = 100) -> None:
+        self._log_batch_size = log_batch_size
+        # TODO: support other log types
+        self.metric_log_cache: dict[str, list[Metric]] = defaultdict(list)
+
+    async def __call__(
+        self,
+        metric: Union[Sequence[Union[Metric, dict]], Union[Metric, dict]],
+        clear_cache: bool = False,
+    ):
+        agent = self.agent
+        batch_size = self._log_batch_size
+        if not isinstance(metric, Sequence):
+            metric = [metric]
+        for _metric in metric:
+            if isinstance(_metric, Metric):
+                item = _metric
+                metric_key = item.key
+            else:
+                item = Metric(
+                    key=_metric["key"],
+                    value=_metric["value"],
+                    timestamp=_metric.get("timestamp", int(1000 * time.time())),
+                    step=_metric["step"],
+                )
+                metric_key = _metric["key"]
+            self.metric_log_cache[metric_key].append(item)
+        for metric_key, _cache in self.metric_log_cache.items():
+            if len(_cache) > batch_size:
+                client = agent.mlflow_client
+                await client.log_batch(
+                    metrics=_cache[:batch_size],
+                )
+                _cache = _cache[batch_size:]
+        if clear_cache:
+            await self._clear_cache()
+
+    async def _clear_cache(
+        self,
+    ):
+        agent = self.agent
+        client = agent.mlflow_client
+        for metric_key, _cache in self.metric_log_cache.items():
+            if len(_cache) > 0:
+                await client.log_batch(
+                    metrics=_cache,
+                )
+                _cache = []

pycityagent/workflow/trigger.py

@@ -0,0 +1,163 @@
+import asyncio
+from typing import Optional
+import socket
+from ..memory import Memory
+from ..environment import Simulator
+
+KEY_TRIGGER_COMPONENTS = [Memory, Simulator]
+
+
+class EventTrigger:
+    """Base class for event triggers that wait for specific conditions to be met."""
+
+    # 定义该trigger需要的组件类型
+    required_components: list[type] = []
+
+    def __init__(self, block=None):
+        self.block = block
+        if block is not None:
+            self.initialize()
+
+    def initialize(self) -> None:
+        """Initialize the trigger with necessary dependencies."""
+        if not self.block:
+            raise RuntimeError("Block not set for trigger")
+
+        # 检查所需组件是否都存在
+        missing_components = []
+        for component_type in self.required_components:
+            component_name = component_type.__name__.lower()
+            if not hasattr(self.block, component_name):
+                missing_components.append(component_type.__name__)
+
+        if missing_components:
+            raise RuntimeError(
+                f"Block is missing required components for {self.__class__.__name__}: "
+                f"{', '.join(missing_components)}"
+            )
+
+    async def wait_for_trigger(self) -> None:
+        """Wait for the event trigger to be activated.
+
+        Raises:
+            NotImplementedError: Subclasses must implement this method.
+        """
+        raise NotImplementedError
+
+
+class MemoryChangeTrigger(EventTrigger):
+    """Event trigger that activates when a specific key in memory changes."""
+
+    required_components = [Memory]
+
+    def __init__(self, key: str) -> None:
+        """Initialize the memory change trigger.
+
+        Args:
+            key (str): The key in memory to monitor for changes.
+        """
+        self.key = key
+        self.trigger_event = asyncio.Event()
+        self._initialized = False
+        super().__init__()
+
+    def initialize(self) -> None:
+        """Initialize the trigger with memory from block."""
+        super().initialize()  # 首先检查必需组件
+        self.memory = self.block.memory
+        asyncio.create_task(self.memory.add_watcher(self.key, self.trigger_event.set))
+        self._initialized = True
+
+    async def wait_for_trigger(self) -> None:
+        """Wait for the memory change trigger to be activated."""
+        if not self._initialized:
+            raise RuntimeError("Trigger not properly initialized")
+        await self.trigger_event.wait()
+        self.trigger_event.clear()
+
+
+class TimeTrigger(EventTrigger):
+    """Event trigger that activates periodically based on time intervals."""
+
+    required_components = [Simulator]
+
+    def __init__(
+        self,
+        days: Optional[int] = None,
+        hours: Optional[int] = None,
+        minutes: Optional[int] = None,
+    ) -> None:
+        """Initialize the time trigger with interval settings.
+
+        Args:
+            days (Optional[int]): Execute every N days
+            hours (Optional[int]): Execute every N hours
+            minutes (Optional[int]): Execute every N minutes
+
+        Raises:
+            ValueError: If all interval parameters are None or negative
+        """
+        if all(param is None for param in (days, hours, minutes)):
+            raise ValueError("At least one time interval must be specified")
+
+        # 验证参数有效性
+        for param_name, param_value in [
+            ("days", days),
+            ("hours", hours),
+            ("minutes", minutes),
+        ]:
+            if param_value is not None and param_value < 0:
+                raise ValueError(f"{param_name} cannot be negative")
+
+        # 将所有时间间隔转换为秒
+        self.interval = 0
+        if days is not None:
+            self.interval += days * 24 * 60 * 60
+        if hours is not None:
+            self.interval += hours * 60 * 60
+        if minutes is not None:
+            self.interval += minutes * 60
+
+        self.trigger_event = asyncio.Event()
+        self._initialized = False
+        self._monitoring_task = None
+        self._last_trigger_time = None
+        super().__init__()
+
+    def initialize(self) -> None:
+        """Initialize the trigger with necessary dependencies."""
+        super().initialize()  # 首先检查必需组件
+        self.memory = self.block.memory
+        self.simulator = self.block.simulator
+        # 启动时间监控任务
+        self._monitoring_task = asyncio.create_task(self._monitor_time())
+        self._initialized = True
+
+    async def _monitor_time(self):
+        """持续监控时间并在达到间隔时触发事件"""
+        # 第一次调用时直接触发
+        self.trigger_event.set()
+
+        while True:
+            try:
+                current_time = await self.simulator.get_time()
+
+                # 如果是第一次或者已经过了指定的时间间隔
+                if (
+                    self._last_trigger_time is None
+                    or current_time - self._last_trigger_time >= self.interval
+                ):
+                    self._last_trigger_time = current_time
+                    self.trigger_event.set()
+
+                await asyncio.sleep(5)  # 避免过于频繁的检查
+            except Exception as e:
+                print(f"Error in time monitoring: {e}")
+                await asyncio.sleep(10)  # 发生错误时等待较长时间
+
+    async def wait_for_trigger(self) -> None:
+        """Wait for the time trigger to be activated."""
+        if not self._initialized:
+            raise RuntimeError("Trigger not properly initialized")
+        await self.trigger_event.wait()
+        self.trigger_event.clear()

pycityagent-2.0.0a43.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 FIB LAB, Tsinghua University
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pycityagent-2.0.0a43.dist-info/METADATA

@@ -0,0 +1,235 @@
+Metadata-Version: 2.1
+Name: pycityagent
+Version: 2.0.0a43
+Summary: LLM-based城市环境agent构建库
+Author-email: Yuwei Yan <pinkgranite86@gmail.com>, Junbo Yan <yanjb20thu@gmali.com>, Jun Zhang <zhangjun990222@gmali.com>
+License: MIT License
+        
+        Copyright (c) 2024 FIB LAB, Tsinghua University
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+Project-URL: Homepage, https://github.com/tsinghua-fib-lab/pycityagent
+Project-URL: Repository, https://github.com/tsinghua-fib-lab/pycityagent.git
+Project-URL: Issues, https://github.com/tsinghua-fib-lab/pycityagent/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS :: MacOS X
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+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: grpcio<2.0.0,>=1.67.1
+Requires-Dist: matplotlib>=3.8.3
+Requires-Dist: networkx>=3.2.1
+Requires-Dist: numpy<2.0.0,>=1.20.0
+Requires-Dist: openai>=1.58.1
+Requires-Dist: Pillow<12.0.0,>=11.0.0
+Requires-Dist: protobuf<5.0.0,<=4.24.0
+Requires-Dist: pycitydata>=1.0.3
+Requires-Dist: pycityproto>=2.1.5
+Requires-Dist: requests>=2.32.3
+Requires-Dist: Shapely>=2.0.6
+Requires-Dist: PyYAML>=6.0.2
+Requires-Dist: zhipuai>=2.1.5.20230904
+Requires-Dist: gradio>=5.7.1
+Requires-Dist: mosstool>=1.3.0
+Requires-Dist: ray>=2.40.0
+Requires-Dist: aiomqtt>=2.3.0
+Requires-Dist: fastavro>=1.10.0
+Requires-Dist: pandavro>=1.8.0
+Requires-Dist: langchain-core>=0.3.28
+Requires-Dist: mlflow>=2.19.0
+Requires-Dist: psycopg[binary]>=3.2.3
+Requires-Dist: transformers>=4.47.1
+Requires-Dist: torch>=2.5.1
+Requires-Dist: faiss-cpu>=1.9.0.post1
+Requires-Dist: langchain-community>=0.3.13
+
+
+
+<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.
+
+---