# LAMB: LLM Agent Model Base
[](https://pypi.org/project/lamb-abm/)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/Brishian427/LAMB/actions)
[](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)
Raw data
{
"_id": null,
"home_page": null,
"name": "lamb-abm",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "OASIS-Fudan Complex System AI Social Scientist Team <brishian20427@gmail.com>",
"keywords": "agent-based modeling, large language models, simulation, complex systems, computational social science, artificial intelligence",
"author": null,
"author_email": "OASIS-Fudan Complex System AI Social Scientist Team <brishian20427@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/81/47/51fdcc00638189da29fea47c121f0f4178344d1e1747e62405cda06a3151/lamb_abm-0.1.0.tar.gz",
"platform": null,
"description": "# LAMB: LLM Agent Model Base\r\n\r\n[](https://pypi.org/project/lamb-abm/)\r\n[](https://www.python.org/downloads/)\r\n[](https://opensource.org/licenses/MIT)\r\n[](https://github.com/Brishian427/LAMB/actions)\r\n[](https://github.com/Brishian427/LAMB)\r\n\r\nA unified framework for building agent-based models with Large Language Model integration, supporting multiple simulation paradigms and behavioral engines.\r\n\r\n**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.\r\n\r\n## Installation\r\n\r\n```bash\r\npip install lamb-abm\r\n```\r\n\r\n### Optional Dependencies\r\n\r\nFor LLM integration:\r\n```bash\r\npip install lamb-abm[llm]\r\n```\r\n\r\nFor full functionality including visualization:\r\n```bash\r\npip install lamb-abm[all]\r\n```\r\n\r\n## Quick Start\r\n\r\n```python\r\nfrom lamb import ResearchAPI, SimulationConfig\r\n\r\n# Create a simple grid simulation\r\napi = ResearchAPI()\r\napi.create_simulation(\r\n paradigm=\"grid\",\r\n num_agents=100,\r\n engine_type=\"rule\",\r\n max_steps=1000\r\n)\r\n\r\n# Run simulation\r\nresults = api.run_simulation()\r\nprint(f\"Simulation completed with {len(results)} steps\")\r\n```\r\n\r\n## Key Features\r\n\r\n- **Multi-Paradigm Support**: Grid, Physics, and Network simulation paradigms\r\n- **LLM Integration**: Seamless Large Language Model agent behavior\r\n- **Composition Architecture**: Modular design for easy extension\r\n- **High Performance**: Optimized for 10,000+ agents\r\n- **Research Ready**: Built-in metrics, visualization, and analysis tools\r\n- **Academic Focus**: Designed for social science and complexity research\r\n\r\n## Core Concepts\r\n\r\n### Paradigms\r\n- **Grid**: Discrete space models (Sugarscape, Schelling)\r\n- **Physics**: Continuous space models (Boids, Social Force)\r\n- **Network**: Graph-based models (SIR, Opinion Dynamics)\r\n\r\n### Engines\r\n- **Rule Engine**: Traditional rule-based behavior\r\n- **LLM Engine**: Large Language Model decision making\r\n- **Hybrid Engine**: Combines multiple approaches\r\n\r\n### Composition Pattern\r\nLAMB uses a composition-based architecture where simulations are built by combining independent components (Environment, Agents, Engine, Executor) rather than inheritance hierarchies.\r\n\r\n## Basic Usage\r\n\r\n### Beginner: Simple Grid Simulation\r\n\r\n```python\r\nfrom lamb import ResearchAPI\r\n\r\napi = ResearchAPI()\r\napi.create_simulation(\r\n paradigm=\"grid\",\r\n num_agents=50,\r\n engine_type=\"rule\",\r\n max_steps=500\r\n)\r\n\r\nresults = api.run_simulation()\r\n```\r\n\r\n### Intermediate: LLM-Powered Agents\r\n\r\n```python\r\nfrom lamb import ResearchAPI, SimulationConfig\r\n\r\nconfig = SimulationConfig(\r\n paradigm=\"grid\",\r\n num_agents=20,\r\n engine_type=\"llm\",\r\n llm_config={\r\n \"model\": \"gpt-3.5-turbo\",\r\n \"temperature\": 0.7,\r\n \"max_tokens\": 150\r\n }\r\n)\r\n\r\napi = ResearchAPI()\r\napi.create_simulation(config=config)\r\nresults = api.run_simulation()\r\n```\r\n\r\n### Advanced: Custom Model\r\n\r\n```python\r\nfrom lamb import ResearchAPI, GridAgent, GridEnvironment\r\nfrom lamb.engines import RuleEngine\r\n\r\nclass CustomAgent(GridAgent):\r\n def decide(self, observation, engine):\r\n # Custom decision logic\r\n return Action(agent_id=self.agent_id, action_type=\"move\")\r\n\r\n# Build custom simulation\r\nenvironment = GridEnvironment(dimensions=(100, 100))\r\nagents = [CustomAgent(i, (i%10, i//10)) for i in range(100)]\r\nengine = RuleEngine()\r\n\r\nsimulation = Simulation(environment, agents, engine)\r\nresults = simulation.run(max_steps=1000)\r\n```\r\n\r\n## Documentation\r\n\r\nDocumentation is currently being developed. For now, please refer to the examples in the `examples/` directory and the inline code documentation.\r\n\r\n## Contributing\r\n\r\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n## Acknowledgments\r\n\r\n- OASIS-Fudan Complex System AI Social Scientist Team\r\n- The agent-based modeling community\r\n- OpenAI for LLM API access\r\n- Contributors and users\r\n\r\n## Support\r\n\r\n- Issues: [GitHub Issues](https://github.com/Brishian427/LAMB/issues)\r\n- Discussions: [GitHub Discussions](https://github.com/Brishian427/LAMB/discussions)\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A unified framework for building agent-based models with Large Language Model integration",
"version": "0.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/Brishian427/LAMB/issues",
"Download": "https://pypi.org/project/lamb-abm/#files",
"Homepage": "https://github.com/Brishian427/LAMB",
"Repository": "https://github.com/Brishian427/LAMB.git",
"Source Code": "https://github.com/Brishian427/LAMB"
},
"split_keywords": [
"agent-based modeling",
" large language models",
" simulation",
" complex systems",
" computational social science",
" artificial intelligence"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c2839a94092f8f1811efdc4497298208fc245220c6f1b46b4629197ed42e1706",
"md5": "62631114c36a1a3d1b780b93cc14a255",
"sha256": "fe349a1a797312549419557e4c6a201a64f1ee8a3b65f1727fcabee65890985f"
},
"downloads": -1,
"filename": "lamb_abm-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "62631114c36a1a3d1b780b93cc14a255",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 141458,
"upload_time": "2025-10-28T01:23:09",
"upload_time_iso_8601": "2025-10-28T01:23:09.932261Z",
"url": "https://files.pythonhosted.org/packages/c2/83/9a94092f8f1811efdc4497298208fc245220c6f1b46b4629197ed42e1706/lamb_abm-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "814751fdcc00638189da29fea47c121f0f4178344d1e1747e62405cda06a3151",
"md5": "654006d523235cc255fb7b5837c12378",
"sha256": "a860a7bd061f3a80d57b9e52712f8da18d16943b063a5700ac837fbd8bcc9d20"
},
"downloads": -1,
"filename": "lamb_abm-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "654006d523235cc255fb7b5837c12378",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 152734,
"upload_time": "2025-10-28T01:23:11",
"upload_time_iso_8601": "2025-10-28T01:23:11.673372Z",
"url": "https://files.pythonhosted.org/packages/81/47/51fdcc00638189da29fea47c121f0f4178344d1e1747e62405cda06a3151/lamb_abm-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-28 01:23:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Brishian427",
"github_project": "LAMB",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "lamb-abm"
}
JSON
