Metadata-Version: 2.2
Name: agentsociety
Version: 1.0.0
Summary: LLM-based city environment agent building library
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/agentsociety
Project-URL: Repository, https://github.com/tsinghua-fib-lab/agentsociety.git
Project-URL: Issues, https://github.com/tsinghua-fib-lab/agentsociety/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.2.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: 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
Requires-Dist: pydantic>=2.10.4



<div style="text-align: center; background-color: white; padding: 20px; border-radius: 30px;">
  <img src="./static/agentsociety_logo.png" alt="AgentSociety Logo" width="200" style="display: block; margin: 0 auto;">
  <h1 style="color: black; margin: 0; font-size: 3em;">AgentSociety: LLM Agents in City</h1>
</div>


# 🚀 AgentSociety
![License](https://img.shields.io/badge/license-MIT-green) &ensp;
[![Online Documentation](https://img.shields.io/badge/docs-online-blue)](https://docs.fiblab.net/agentsociety) &ensp;


AgentSociety is an advanced framework specifically designed for building intelligent agents in urban simulation environments. With AgentSociety, 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

AgentSociety 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="AgentSociety 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 AgentSociety in two different ways:

### 1. From Scratch

Follow these steps to set up AgentSociety 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 agentsociety
   ```
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 AgentSociety in just a few minutes!

### 1. Config Configuration
AgentSociety 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:
  request_type: openai
  api_key: <YOUR_API_KEY>
  model: gpt-4o

simulator_request:
  simulator:
    server: https://api-opencity-2x.fiblab.net:58081
  map_request:
    file_path: ./cache/map_beijing5ring_withpoi_0424.pb
```

### 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

AgentSociety 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.

---
