Percepta

Percepta Quick Start Guide

Prerequisites

1. Python 3.10+
2. PostgreSQL (installed and running)
3. Ollama Cloud API Key (optional, for LLM perception)

Installation Steps

1. Install PostgreSQL

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install postgresql postgresql-contrib

# Start PostgreSQL service
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Create database
sudo -u postgres psql
CREATE DATABASE percepta_db;
CREATE USER postgres WITH PASSWORD 'postgres';
GRANT ALL PRIVILEGES ON DATABASE percepta_db TO postgres;
\q

2. Configure Environment Variables

Copy .env.example to .env and modify configuration:

cd /home/ubuntu/Percepta
cp .env.example .env
# Edit .env file, set database and Ollama configuration

3. Install Python Dependencies

cd /home/ubuntu/Percepta
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

4. Initialize Database

python3 scripts/init_db.py

5. Start System

# Method 1: Using startup script
./scripts/start.sh

# Method 2: Manual startup
source venv/bin/activate
python3 backend/app.py

6. Access Frontend

Open browser and visit: http://localhost:5000

Usage Instructions

Initialize Simulation

1. Set initial agent count (default 100)
2. Set base income (default 1000)
3. Click “Initialize Simulation”

Start Simulation

Click “Start” button, system begins continuous evolution.

Adjust Policy Variables

In the “Policy Variable Adjustment” panel, adjust in real-time:

• Tax Rate: Affects disposable income
• Subsidy Rate: Increases consumption capacity
• Consumption Stimulus: Directly increases consumption willingness
• Income Tax Rate: Affects after-tax income

Observe Metrics

System displays in real-time:

• Total consumption trends
• Price level
• Policy variable changes
• Consumption multiplier

System Architecture

• Layer 0: Simulation Engine (time progression)
• Layer 1: World State (world state components)
• Layer 2: Agent State (individual state)
• Layer 3: Perception (LLM perception, optional)
• Layer 4: Decision (decision making)
• Layer 5: Interaction & Transition (state transitions)

Core Features

1. Extensible World State: Easily add new state components through componentized design
2. Continuous Evolution: System runs continuously, updating state in real-time
3. Policy Regulation: Adjust policy variables in real-time, observe impact on resident consumption
4. Data Persistence: All state changes saved to PostgreSQL
5. Real-time Visualization: Web interface displays key metrics in real-time

Troubleshooting

Database Connection Error

Check:

• Is PostgreSQL service running: sudo systemctl status postgresql
• Is database configuration correct (.env or config/config.yaml)
• Database user permissions

Ollama API Error

If Ollama API is unavailable, system will automatically fall back to simple perception mode (without LLM).

Port Occupied

If port 5000 is occupied, modify port configuration in config/config.yaml.

Next Steps

• Add more agent types (enterprises, banks, etc.)
• Extend world state components (network state, technology diffusion, etc.)
• Add more policy tools
• Implement more complex interaction mechanisms