Metadata-Version: 2.5
Name: agentsociety2
Version: 2.8.7
Summary: A modern, LLM-native agent simulation platform for social science research
Project-URL: Homepage, https://github.com/tsinghua-fib-lab/agentsociety
Project-URL: Documentation, https://agentsociety2.readthedocs.io/
Project-URL: Repository, https://github.com/tsinghua-fib-lab/agentsociety.git
Project-URL: Issues, https://github.com/tsinghua-fib-lab/agentsociety/issues
Project-URL: Changelog, https://github.com/tsinghua-fib-lab/agentsociety/blob/main/CHANGELOG.md
Author-email: Jun Zhang <zhangjun990222@gmail.com>, Boyuan Sun <sunboyuan0124@gmail.com>, Haoyu Huang <2253940186@qq.com>, Keming Zhang <kemingzhang@bupt.edu.cn>, Yuxin Liu <aph.xin@gmail.com>
Maintainer-email: Jun Zhang <zhangjun990222@gmail.com>, Boyuan Sun <sunboyuan0124@gmail.com>, Haoyu Huang <2253940186@qq.com>, Keming Zhang <kemingzhang@bupt.edu.cn>, Yuxin Liu <aph.xin@gmail.com>
License: Apache-2.0
License-File: LICENSE
Keywords: agents,artificial-intelligence,experiment,llm,multi-agent,reinforcement-learning,simulation,social-science
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: <3.14,>=3.11
Requires-Dist: aiohttp>=3.10.11
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: black>=25.12.0
Requires-Dist: duckdb>=1.4.0
Requires-Dist: elemental-xenon>=1.1.0
Requires-Dist: faiss-cpu>=1.7.0
Requires-Dist: fastapi>=0.128.0
Requires-Dist: geojson>=3.1.0
Requires-Dist: json-repair>=0.46.2
Requires-Dist: litellm>=1.83.7
Requires-Dist: mcp[cli]>=1.13.1
Requires-Dist: mem0ai>=1.0.5
Requires-Dist: networkx>=3.0
Requires-Dist: numpy>=1.20.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: plotly>=6.8.0
Requires-Dist: protobuf>=4.0.0
Requires-Dist: pycityproto>=2.4.5
Requires-Dist: pydantic>=2.10.4
Requires-Dist: pyproj>=3.6.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: ray>=2.0.0; sys_platform != 'win32'
Requires-Dist: requests>=2.32.5
Requires-Dist: scikit-learn>=1.8.0
Requires-Dist: scipy>=1.10.0
Requires-Dist: shapely>=2.0.6
Requires-Dist: sqlalchemy[asyncio]>=2.0.46
Requires-Dist: sqlmodel>=0.0.16
Requires-Dist: stringcase>=1.2.0
Requires-Dist: tiktoken>=0.8.0
Requires-Dist: uvicorn>=0.36.0
Requires-Dist: wsproto>=1.2.0
Provides-Extra: all
Requires-Dist: furo>=2024.8.6; extra == 'all'
Requires-Dist: httpx2>=2.0.0; extra == 'all'
Requires-Dist: linkify-it-py>=2.0.0; extra == 'all'
Requires-Dist: matplotlib>=3.10.0; extra == 'all'
Requires-Dist: missingno>=0.5.0; extra == 'all'
Requires-Dist: mypy>=1.14.0; extra == 'all'
Requires-Dist: myst-parser>=4.0.0; extra == 'all'
Requires-Dist: openai>=2.16.0; extra == 'all'
Requires-Dist: pandera>=0.22.0; extra == 'all'
Requires-Dist: pillow>=10.4.0; extra == 'all'
Requires-Dist: pre-commit>=3.8.0; extra == 'all'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'all'
Requires-Dist: pytest-cov>=5.0.0; extra == 'all'
Requires-Dist: pytest>=9.0.2; extra == 'all'
Requires-Dist: ruff>=0.11.13; extra == 'all'
Requires-Dist: seaborn>=0.13.2; extra == 'all'
Requires-Dist: sphinx-autobuild>=2024.9.19; extra == 'all'
Requires-Dist: sphinx-autodoc2>=0.5.0; extra == 'all'
Requires-Dist: sphinx-intl==2.3.2; extra == 'all'
Requires-Dist: sphinx>=7.0.0; extra == 'all'
Requires-Dist: statsmodels>=0.14.0; extra == 'all'
Requires-Dist: sweetviz>=2.3.0; extra == 'all'
Requires-Dist: torch>=2.9.1; extra == 'all'
Requires-Dist: tqdm>=4.67.3; extra == 'all'
Requires-Dist: ydata-profiling>=4.6.0; extra == 'all'
Provides-Extra: analysis
Requires-Dist: matplotlib>=3.10.0; extra == 'analysis'
Requires-Dist: missingno>=0.5.0; extra == 'analysis'
Requires-Dist: openai>=2.16.0; extra == 'analysis'
Requires-Dist: pandera>=0.22.0; extra == 'analysis'
Requires-Dist: pillow>=10.4.0; extra == 'analysis'
Requires-Dist: seaborn>=0.13.2; extra == 'analysis'
Requires-Dist: sweetviz>=2.3.0; extra == 'analysis'
Requires-Dist: tqdm>=4.67.3; extra == 'analysis'
Requires-Dist: ydata-profiling>=4.6.0; extra == 'analysis'
Provides-Extra: dev
Requires-Dist: httpx2>=2.0.0; extra == 'dev'
Requires-Dist: mypy>=1.14.0; extra == 'dev'
Requires-Dist: pre-commit>=3.8.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=9.0.2; extra == 'dev'
Requires-Dist: ruff>=0.11.13; extra == 'dev'
Provides-Extra: docs
Requires-Dist: furo>=2024.8.6; extra == 'docs'
Requires-Dist: linkify-it-py>=2.0.0; extra == 'docs'
Requires-Dist: myst-parser>=4.0.0; extra == 'docs'
Requires-Dist: sphinx-autobuild>=2024.9.19; extra == 'docs'
Requires-Dist: sphinx-autodoc2>=0.5.0; extra == 'docs'
Requires-Dist: sphinx-intl==2.3.2; extra == 'docs'
Requires-Dist: sphinx>=7.0.0; extra == 'docs'
Provides-Extra: eda
Requires-Dist: statsmodels>=0.14.0; extra == 'eda'
Provides-Extra: ml
Requires-Dist: torch>=2.9.1; extra == 'ml'
Description-Content-Type: text/markdown

# AgentSociety 2

<p align="center">
  <a href="./README.md">English</a> · <a href="./README_zh.md">中文</a>
</p>

<p align="center">
  <a href="https://github.com/tsinghua-fib-lab/AgentSociety/stargazers">
    <img src="https://img.shields.io/github/stars/tsinghua-fib-lab/AgentSociety?style=social" alt="GitHub Stars">
  </a>
  <a href="https://pypi.org/project/agentsociety2/">
    <img src="https://img.shields.io/pypi/v/agentsociety2.svg" alt="PyPI Version">
  </a>
  <a href="https://pypi.org/project/agentsociety2/">
    <img src="https://img.shields.io/pypi/pyversions/agentsociety2.svg" alt="Python Version">
  </a>
  <a href="https://github.com/tsinghua-fib-lab/AgentSociety/blob/main/LICENSE">
    <img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="License">
  </a>
</p>

<p align="center">
  <a href="https://agentsociety2.readthedocs.io/">
    <img src="https://img.shields.io/badge/docs-English-brightgreen" alt="English Docs">
  </a>
  <a href="https://agentsociety2.readthedocs.io/zh_CN/latest/">
    <img src="https://img.shields.io/badge/docs-%E4%B8%AD%E6%96%87-red" alt="Chinese Docs">
  </a>
</p>

> **AgentSociety 2** is a modern, LLM-native agent simulation platform designed for social science research and experimentation.

## Features

- **LLM-Native Design**: Built from the ground up for LLM-driven agents
- **Flexible Environment System**: Modular environment components with hot-pluggable tools
- **Multiple Reasoning Patterns**: CodeGen (default), ReAct, Plan-Execute, Two-Tier, and Search routers
- **Scalable Execution**: Agents are workspace-bound stateless records driven by Ray Tasks;
  env / LLM clients / trace / replay handles are passed behind a single `ServiceProxy`
- **Developer-Friendly**: Pythonic API with type hints and comprehensive documentation
- **Experiment Replay**: Catalog-driven JSONL replay with DuckDB-powered reads and distributed tracing
- **MCP Support**: Model Context Protocol integration for tool extensibility

## Installation

```bash
pip install agentsociety2
```

### Requirements

- Python >= 3.11
- An LLM API key (OpenAI, Anthropic, or any provider supported by LiteLLM)

## Quick Start

Before running the examples, set the LLM environment variables described in
[Configuration](#configuration). The package validates them when `agentsociety2`
is imported.

### Create Your First Agent

```python
import asyncio
from datetime import datetime
from pathlib import Path
from agentsociety2.env import CodeGenRouter
from agentsociety2.contrib.env import SimpleSocialSpace
from agentsociety2.society import AgentSociety

async def main():
    # Declare agent metadata (id / profile / config); agents are NOT instantiated here.
    # AgentSociety batch-creates their workspaces during init().
    agent_specs = [
        {
            "id": 1,
            "profile": {
                "name": "Alice",
                "age": 28,
                "personality": "friendly and curious",
                "bio": "A software engineer who loves hiking and reading.",
            },
            "config": {},
        }
    ]
    names = [(s["id"], s["profile"]["name"]) for s in agent_specs]

    # Create environment module with agent info
    social_env = SimpleSocialSpace(agent_id_name_pairs=names)

    # Create environment router (in-process CodeGenRouter; production uses an EnvRouterProxy Ray actor)
    env_router = CodeGenRouter(env_modules=[social_env])

    # Create the society
    society = AgentSociety(
        agent_specs=agent_specs,
        agent_class_name="PersonAgent",
        env_router=env_router,
        start_t=datetime.now(),
        run_dir=Path("run"),
    )

    # Initialize (batch-creates agent workspaces, binds the environment)
    await society.init()

    # Query (read-only)
    response = await society.ask("What's your favorite activity?")
    print(f"Agent: {response}")

    # Close the society
    await society.close()

if __name__ == "__main__":
    asyncio.run(main())
```

### Create a Custom Environment Module

```python
from agentsociety2.env import EnvBase, tool

class MyCustomEnvironment(EnvBase):
    """A custom environment module."""

    @tool(readonly=True, kind="observe")
    def get_weather(self, agent_id: int) -> str:
        """Get the current weather for an agent."""
        return "The weather is sunny and 25°C."

    @tool(readonly=False)
    def set_mood(self, agent_id: int, mood: str) -> str:
        """Change the mood of an agent."""
        return f"Agent {agent_id}'s mood is now {mood}."

# Use the custom module
from agentsociety2.env import CodeGenRouter

env_router = CodeGenRouter(env_modules=[MyCustomEnvironment()])
```

### Run a Complete Experiment

```python
import asyncio
from datetime import datetime
from pathlib import Path
from agentsociety2.env import CodeGenRouter
from agentsociety2.contrib.env import SimpleSocialSpace
from agentsociety2.society import AgentSociety

async def main():
    # Declare agent metadata
    agent_specs = [
        {"id": i, "profile": {"name": f"Player{i}", "personality": "friendly"}, "config": {}}
        for i in range(1, 4)
    ]
    names = [(s["id"], s["profile"]["name"]) for s in agent_specs]

    # Create environment router (replay is enabled by default -> run/replay/)
    env_router = CodeGenRouter(env_modules=[SimpleSocialSpace(agent_id_name_pairs=names)])

    # Create the society
    society = AgentSociety(
        agent_specs=agent_specs,
        agent_class_name="PersonAgent",
        env_router=env_router,
        start_t=datetime.now(),
        run_dir=Path("run"),
    )
    await society.init()

    # Query (read-only)
    answer = await society.ask("What are the names of all agents?")
    print(f"Answer: {answer}")

    # Intervene (read-write)
    result = await society.intervene("Set all agents' happiness to 0.8")
    print(f"Result: {result}")

    await society.close()

if __name__ == "__main__":
    asyncio.run(main())
```

## Core Concepts

### Agents

Agents are autonomous entities that interact with environments through LLM-powered reasoning:

- **AgentBase**: Abstract base class for all agents
- **PersonAgent**: Skills-based agent — a lightweight orchestrator whose capabilities are provided by a pluggable skill pipeline
- Agents support two interaction modes:
  - `ask(question, readonly=True)`: Query without side effects
  - `intervene(instruction)`: Make changes to the environment

#### Agent Skills

PersonAgent follows a **metadata-first, selected-only** model. Skills are self-contained
directories; the only built-in skill is `daily-guidance` (daily behavior / needs-decay
guidance). The old `observation / cognition / plan / memory` skills have been removed —
those capabilities are now expressed via custom skills + workspace state files + `ask_env`.

```
agent/skills/
└── daily-guidance/     # SKILL.md + scripts/daily_guidance.py (pre_step hook)
```

Each skill has:

- `SKILL.md` — YAML frontmatter (`name`, `description`, optional `script` / `hooks`) + behavior docs
- `scripts/*.py` — optional scripts. By default these run **in-process via an `entrypoint(argv, ctx)`**
  contract (millisecond, concurrency-safe), with dynamic-wrapper and subprocess fallbacks.

Skills follow metadata-first selection:

- the catalog exposes only name/description until activation
- execution is tool-loop driven (`activate_skill` / `read_skill_file` / `execute_skill_script`)
- `pre_step` / `post_step` lifecycle hooks are rendered into a dedicated `<skill_hooks>` block

Custom skills can be placed in `<workspace>/custom/skills/` and hot-loaded at runtime.

### Environment Modules

Environment modules encapsulate specific functionality through tools:

- **EnvBase**: Base class for creating custom modules
- **@tool decorator**: Register methods as discoverable tools
- Tool kinds:
  - `observe`: Single-parameter observation functions
  - `statistics`: No-parameter aggregation functions
  - Regular tools: Full read/write operations

### Routers

Routers mediate agent-environment interactions using different reasoning patterns:

- **ReActRouter**: Reasoning + Acting loop
- **PlanExecuteRouter**: Plan-first, then execute
- **CodeGenRouter**: Code generation based tool use
- **TwoTierReActRouter**: Two-level reasoning hierarchy
- **TwoTierPlanExecuteRouter**: Two-level planning hierarchy

### Storage

AgentSociety 2 currently has two persistence paths:

```python
from agentsociety2.storage import ReplayReader, ReplayWriter
from pathlib import Path

writer = ReplayWriter(Path("run/replay"))
await writer.init()

# Replay schema sidecar: run/replay/_schema.json

# Environment modules can register and write their own replay tables.
from agentsociety2.storage import ColumnDef, TableSchema
schema = TableSchema(
    name="custom_metrics",
    columns=[
        ColumnDef("metric_id", "INTEGER", nullable=False),
        ColumnDef("value", "REAL"),
    ],
    primary_key=["metric_id"],
)
await writer.register_table(schema)

reader = ReplayReader(Path("run/replay"))
print(reader.load_dataset_catalog())
reader.close()
```

- **ReplayWriter / ReplayReader**: write sharded JSONL replay datasets plus `_schema.json`
  metadata, then read them through DuckDB-backed views.
- **PersonAgent workspace**: stores per-agent local files under `run/agents/agent_xxxx/`, such as
  `config.json`, `AGENT.json`, `AGENT_MEMORY.md`, `state/*.json`, and `.runtime/logs/*.jsonl`.
- **Trace**: the `agentsociety2.trace` module writes distributed tracing spans (sharded writer +
  background-thread actor) for profiling steps and LLM calls.

Legacy SQLite tables like `agent_profile`, `agent_status`, and `agent_dialog` are kept only for compatibility when reading old experiment databases; new runs write `run/replay/` instead.

## Configuration

Set your LLM API credentials via environment variables. The examples below use the OpenAI API endpoint and `gpt-5.5`; other LiteLLM-supported providers can be used by changing the base URL and model id.

**Required Configuration**

```bash
# Default LLM (required - used for most operations)
export AGENTSOCIETY_LLM_API_KEY="your-api-key"
export AGENTSOCIETY_LLM_API_BASE="https://api.openai.com/v1"
export AGENTSOCIETY_LLM_MODEL="gpt-5.5"
```

**Optional Configuration**

For specialized tasks, you can configure separate LLM instances:

```bash
# Code Generation LLM (for code-related tasks)
# Falls back to default LLM if not set
export AGENTSOCIETY_CODER_LLM_API_KEY="your-coder-api-key"
export AGENTSOCIETY_CODER_LLM_API_BASE="https://api.openai.com/v1"
export AGENTSOCIETY_CODER_LLM_MODEL="gpt-5.5"

# Nano LLM (for high-frequency, low-latency operations)
# Falls back to default LLM if not set
export AGENTSOCIETY_NANO_LLM_API_KEY="your-nano-api-key"
export AGENTSOCIETY_NANO_LLM_API_BASE="https://api.openai.com/v1"
export AGENTSOCIETY_NANO_LLM_MODEL="gpt-5.5"

# Embedding Model (for text embeddings and semantic search)
# Falls back to default LLM if not set
export AGENTSOCIETY_EMBEDDING_API_KEY="your-embedding-api-key"
export AGENTSOCIETY_EMBEDDING_API_BASE="https://api.openai.com/v1"
export AGENTSOCIETY_EMBEDDING_MODEL="text-embedding-3-large"
export AGENTSOCIETY_EMBEDDING_DIMS="1024"

# Data directory (optional, default: ./agentsociety_data)
export AGENTSOCIETY_HOME_DIR="/path/to/your/data"
```

Or use a `.env` file:

```bash
# From the repository root:
cp .env.example .env
# Edit .env with your credentials before importing agentsociety2
```

> **Note**
> AgentSociety 2 validates `AGENTSOCIETY_LLM_API_KEY` at import time. Make sure it is set
> before importing `agentsociety2`, or load `.env` early in your entrypoint.

## Examples

The `examples/` directory contains ready-to-run examples:

- `basics/`: Basic agent and environment usage
- `games/`: Classic game theory simulations
  - Prisoner's Dilemma
  - Public Goods Game
  - Trust Game
  - Volunteer's Dilemma
  - Commons Tragedy
- `advanced/`: Advanced usage patterns
  - Custom environment modules
  - Multi-router setups
  - Experiment replay and analysis

## Documentation

- [English Documentation](https://agentsociety2.readthedocs.io/)
- [中文文档](https://agentsociety2.readthedocs.io/zh_CN/latest/)
- [API Reference](https://agentsociety2.readthedocs.io/en/latest/api.html)

## Development

For development guidelines, see [docs/development.rst](docs/development.rst).

### Contributing

We welcome contributions! Please see [CONTRIBUTING.md](../../CONTRIBUTING.md) for details.

## Citation

If you use AgentSociety 2 in your research, please cite:

```bibtex
@misc{piao2026agentsociety2,
  title        = {{AgentSociety} 2: An Integrated Research Environment for Executable Social Science},
  author       = {Jinghua Piao and Jun Zhang and Haoyu Huang and Keming Zhang and Jing Yi Wang and Xinran Zhao and Songwei Li and Boyuan Sun and Jiayi Chang and Fengli Xu and Chunyan Wang and Fang Zhang and Ke Rong and Jun Su and Tianguang Meng and Yi Liu and Qingguo Meng and Yu Wang and Yong Li},
  year         = {2026},
  eprint       = {2607.11895},
  archiveprefix= {arXiv},
  primaryclass = {cs.CY},
  doi          = {10.48550/arXiv.2607.11895},
  url          = {https://arxiv.org/abs/2607.11895},
}
```

Paper: [arXiv:2607.11895](https://arxiv.org/abs/2607.11895). Repository-wide citations: [CITATION.cff](../../CITATION.cff) · [citations.bib](../../citations.bib).

## License

Apache License 2.0 - see [LICENSE](LICENSE) for details.

## Acknowledgments

AgentSociety 2 builds upon excellent open-source projects:

- [litellm](https://github.com/BerriAI/litellm) - Unified LLM API
- [FastAPI](https://fastapi.tiangolo.com/) - Backend API framework
- [Pydantic](https://docs.pydantic.dev/) - Data validation

## Contact

- **Issues**: [GitHub Issues](https://github.com/tsinghua-fib-lab/agentsociety/issues)
- **Discussions**: [GitHub Discussions](https://github.com/tsinghua-fib-lab/agentsociety/discussions)

---

For the original AgentSociety (v1.x) focused on city simulation, see the [agentsociety package](https://pypi.org/project/agentsociety/).
