Metadata-Version: 2.4
Name: lamb-abm
Version: 0.1.0
Summary: A unified framework for building agent-based models with Large Language Model integration
Author-email: OASIS-Fudan Complex System AI Social Scientist Team <brishian20427@gmail.com>
Maintainer-email: OASIS-Fudan Complex System AI Social Scientist Team <brishian20427@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/Brishian427/LAMB
Project-URL: Repository, https://github.com/Brishian427/LAMB.git
Project-URL: Bug Tracker, https://github.com/Brishian427/LAMB/issues
Project-URL: Source Code, https://github.com/Brishian427/LAMB
Project-URL: Download, https://pypi.org/project/lamb-abm/#files
Keywords: agent-based modeling,large language models,simulation,complex systems,computational social science,artificial intelligence
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: matplotlib>=3.4.0
Requires-Dist: networkx>=2.6.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: tqdm>=4.62.0
Requires-Dist: pydantic>=1.8.0
Requires-Dist: typing-extensions>=4.0.0
Provides-Extra: llm
Requires-Dist: openai>=1.0.0; extra == "llm"
Requires-Dist: anthropic>=0.3.0; extra == "llm"
Requires-Dist: tiktoken>=0.4.0; extra == "llm"
Provides-Extra: visualization
Requires-Dist: plotly>=5.0.0; extra == "visualization"
Requires-Dist: seaborn>=0.11.0; extra == "visualization"
Requires-Dist: bokeh>=2.4.0; extra == "visualization"
Requires-Dist: ipywidgets>=7.6.0; extra == "visualization"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: isort>=5.10.0; extra == "dev"
Requires-Dist: flake8>=5.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pre-commit>=2.17.0; extra == "dev"
Requires-Dist: sphinx>=5.0.0; extra == "dev"
Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "dev"
Requires-Dist: nbsphinx>=0.8.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=5.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "docs"
Requires-Dist: nbsphinx>=0.8.0; extra == "docs"
Requires-Dist: myst-parser>=0.18.0; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=1.19.0; extra == "docs"
Provides-Extra: all
Requires-Dist: lamb-abm[dev,docs,llm,visualization]; extra == "all"
Dynamic: license-file

# LAMB: LLM Agent Model Base

[![PyPI version](https://img.shields.io/pypi/v/lamb-abm.svg)](https://pypi.org/project/lamb-abm/)
[![Python versions](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Build Status](https://github.com/Brishian427/LAMB/workflows/Tests/badge.svg)](https://github.com/Brishian427/LAMB/actions)
[![Development Status](https://img.shields.io/badge/status-development-orange.svg)](https://github.com/Brishian427/LAMB)

A unified framework for building agent-based models with Large Language Model integration, supporting multiple simulation paradigms and behavioral engines.

**Note**: This is a work-in-progress project by the OASIS-Fudan Complex System AI Social Scientist Team. Documentation and features are being actively developed.

## Installation

```bash
pip install lamb-abm
```

### Optional Dependencies

For LLM integration:
```bash
pip install lamb-abm[llm]
```

For full functionality including visualization:
```bash
pip install lamb-abm[all]
```

## Quick Start

```python
from lamb import ResearchAPI, SimulationConfig

# Create a simple grid simulation
api = ResearchAPI()
api.create_simulation(
    paradigm="grid",
    num_agents=100,
    engine_type="rule",
    max_steps=1000
)

# Run simulation
results = api.run_simulation()
print(f"Simulation completed with {len(results)} steps")
```

## Key Features

- **Multi-Paradigm Support**: Grid, Physics, and Network simulation paradigms
- **LLM Integration**: Seamless Large Language Model agent behavior
- **Composition Architecture**: Modular design for easy extension
- **High Performance**: Optimized for 10,000+ agents
- **Research Ready**: Built-in metrics, visualization, and analysis tools
- **Academic Focus**: Designed for social science and complexity research

## Core Concepts

### Paradigms
- **Grid**: Discrete space models (Sugarscape, Schelling)
- **Physics**: Continuous space models (Boids, Social Force)
- **Network**: Graph-based models (SIR, Opinion Dynamics)

### Engines
- **Rule Engine**: Traditional rule-based behavior
- **LLM Engine**: Large Language Model decision making
- **Hybrid Engine**: Combines multiple approaches

### Composition Pattern
LAMB uses a composition-based architecture where simulations are built by combining independent components (Environment, Agents, Engine, Executor) rather than inheritance hierarchies.

## Basic Usage

### Beginner: Simple Grid Simulation

```python
from lamb import ResearchAPI

api = ResearchAPI()
api.create_simulation(
    paradigm="grid",
    num_agents=50,
    engine_type="rule",
    max_steps=500
)

results = api.run_simulation()
```

### Intermediate: LLM-Powered Agents

```python
from lamb import ResearchAPI, SimulationConfig

config = SimulationConfig(
    paradigm="grid",
    num_agents=20,
    engine_type="llm",
    llm_config={
        "model": "gpt-3.5-turbo",
        "temperature": 0.7,
        "max_tokens": 150
    }
)

api = ResearchAPI()
api.create_simulation(config=config)
results = api.run_simulation()
```

### Advanced: Custom Model

```python
from lamb import ResearchAPI, GridAgent, GridEnvironment
from lamb.engines import RuleEngine

class CustomAgent(GridAgent):
    def decide(self, observation, engine):
        # Custom decision logic
        return Action(agent_id=self.agent_id, action_type="move")

# Build custom simulation
environment = GridEnvironment(dimensions=(100, 100))
agents = [CustomAgent(i, (i%10, i//10)) for i in range(100)]
engine = RuleEngine()

simulation = Simulation(environment, agents, engine)
results = simulation.run(max_steps=1000)
```

## Documentation

Documentation is currently being developed. For now, please refer to the examples in the `examples/` directory and the inline code documentation.

## Contributing

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

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- OASIS-Fudan Complex System AI Social Scientist Team
- The agent-based modeling community
- OpenAI for LLM API access
- Contributors and users

## Support

- Issues: [GitHub Issues](https://github.com/Brishian427/LAMB/issues)
- Discussions: [GitHub Discussions](https://github.com/Brishian427/LAMB/discussions)
