Extensible Multi-Agent Economic World Simulation Framework (Percepta)

Project Overview

An extensible multi-agent economic world simulation framework for simulating continuous decision-making, interactions, and emergent macro outcomes of large numbers of heterogeneous economic agents under dynamically evolving macro environments and institutional rules.

Core Goal: Observe how policies regulate resident consumption

System Architecture

• Layer 0: Simulation Engine (time progression/scheduling/parallel processing)
• Layer 1: World State (global world state, componentized)
• Layer 2: Agent State (individual local state, subset of world)
• Layer 3: Perception (LLM) - Ollama Cloud
• Layer 4: Decision (action selection)
• Layer 5: Interaction & Transition (interactions/state transitions)

Tech Stack

• Backend: Python 3.10+
• Database: PostgreSQL
• LLM: Ollama Cloud
• API: Flask
• Frontend: HTML/CSS/JavaScript (Chart.js for visualization)

Quick Start

Method 1: Using Startup Script (Recommended)

./scripts/start.sh

Method 2: Manual Startup

1. Create virtual environment: python3 -m venv venv && source venv/bin/activate
2. Install dependencies: pip install -r requirements.txt
3. Initialize database: python3 scripts/init_db.py
4. Start backend: python3 backend/app.py
5. Access frontend: http://localhost:5000

Run Tests

./scripts/run_tests.sh

Run Examples

python3 examples/simple_simulation.py

Configuration

Setting Up Configuration File

1. Copy the example configuration file:

   cp config/config.yaml.example config/config.yaml

2. Edit config/config.yaml and set your Ollama API key:

   ollama:
     api_key: "YOUR_API_KEY_HERE"  # Replace with your actual Ollama API key

3. Other configuration options:

   • All other settings in config.yaml are pre-configured and can be used as-is
   • You can modify database, simulation, world, server, and timezone settings as needed
   • The model field in ollama section sets the default LLM model (can be changed via frontend dropdown)

Note: The config/config.yaml file is excluded from Git to protect your API key. Only config/config.yaml.example (template file) is tracked in the repository.

Project Structure

Percepta/
│
├── core/            # Layer 0: Simulation engine
├── world/           # World state and transitions
│   ├── state/      # Layer 1: World state components
│   └── transitions/ # Layer 5: State transitions
├── agents/          # Layer 2: Agents and state components
├── perception/      # Layer 3: LLM perception layer
├── decision/        # Layer 4: Decision models
├── metrics/         # Metrics and observations
├── backend/         # API service + database
├── frontend/        # Web interface
├── config/          # Configuration files
├── scripts/         # Utility scripts
├── tests/           # Test code
├── examples/        # Example code
└── docs/            # Documentation

For detailed structure, see PROJECT_STRUCTURE.md

Documentation

• Quick Start Guide - Detailed installation and usage instructions
• Project Structure - Complete project structure documentation
• API Documentation - Complete RESTful API documentation
• Architecture Design - System architecture and extension guide

Research and Development Scenarios

• Policy and institutional evolution simulation
• Technology diffusion and structural transformation research
• Behavioral assumptions and macro outcome correlation analysis
• AI + Economics / Social Science interdisciplinary research
• How policies regulate resident consumption (core goal of this project)

Core Features

1. World-First Architecture: World state is primary, agents are participants in the world
2. Componentized Design: Easy to extend with new state components, agent types, interactions
3. Continuous Evolution: System runs continuously, updating state in real-time
4. Policy Regulation: Adjust policy variables in real-time, observe impact on consumption
5. Data Persistence: All state changes saved to PostgreSQL
6. Real-time Visualization: Web interface displays key metrics in real-time

Development Status

✅ Core simulation engine
✅ World state component system
✅ Agent system (consumer)
✅ LLM perception integration (Ollama Cloud)
✅ PostgreSQL data storage
✅ Web frontend interface
✅ RESTful API
✅ Test framework
✅ Example code
✅ Complete documentation

Contributing

Issues and Pull Requests are welcome!

License

MIT License