Percepta

Percepta Architecture Design Documentation

System Architecture Overview

Percepta adopts a World-first 5-layer architecture design to ensure system extensibility and long-term maintainability.

Architecture Layers

Layer 0: Simulation Engine

Responsibilities:

• Time progression
• Event scheduling
• Parallel processing (optional)

Core Class: SimulationEngine

Key Methods:

• initialize(): Initialize simulation
• step(): Execute one time step
• run(): Run simulation loop

---

Layer 1: World State

Responsibilities:

• Manage global world state
• Componentized design, supports dynamic extension

Core Classes:

• WorldState: World state main class
• WorldStateComponent: State component base class
• MarketState: Market state component
• PolicyState: Policy state component

Design Principles:

• World state consists of multiple pluggable components
• Each component independently manages its own state
• Components coordinate through the world state main class

---

Layer 2: Agent State

Responsibilities:

• Manage agent’s local state
• Agent state is a restricted subset of world state + private state

Core Classes:

• Agent: Agent base class
• AgentState: Agent state dataclass
• ConsumerAgent: Resident consumer agent

Design Principles:

• Agents cannot directly modify world state
• Agents can only trigger world changes through actions
• Agent state updates as world state changes

---

Layer 3: Perception

Responsibilities:

• Agent’s subjective perception of world state
• Use LLM (optional) for complex perception

Core Classes: LLMPerceptionService, OllamaService, SimplePerceptionService

Design Principles:

• LLM is only used for perception, does not participate in state transitions
• Automatically falls back to simple perception when LLM fails
• Perception results affect agent decisions but do not directly change the world

---

Layer 4: Decision

Responsibilities:

• Agent makes decisions based on perception
• Select actions

Implementation Location: Agent.decide() method

Design Principles:

• Decisions based on perception results and agent internal state
• Decision result is an action (Action)
• Actions do not directly change the world, but trigger state transitions

---

Layer 5: Interaction & Transition

Responsibilities:

• Execute state transitions
• Handle agent interactions
• Update world state and agent state

Core Function: transition()

Design Principles:

• Unified state transition interface
• Supports global transitions, interactions, agent state updates
• New mechanisms implemented by adding handlers, no need to modify core engine

---

Data Flow

1. Initialization
   WorldState + Agents → SimulationEngine

2. Each time step:
   a. Agent Perception (Layer 3)
      WorldState → Perception → Agent internal state
   
   b. Agent Decision (Layer 4)
      Perception + AgentState → Action
   
   c. State Transition (Layer 5)
      WorldState + Agents + Actions → WorldState' + Agents'
   
   d. Save Snapshot
      WorldState' + Agents' → Database

3. Continuous Evolution
   Repeat step 2 until stopped

---

Extension Mechanisms

Adding New World State Components

1. Inherit from WorldStateComponent
2. Implement to_dict(), from_dict(), update()
3. Add component to WorldState

Example:

class NetworkState(WorldStateComponent):
    def __init__(self):
        self.graph = nx.Graph()
    
    def to_dict(self):
        return {'graph': ...}
    
    def update(self, delta_time, **kwargs):
        # Update network state
        pass

# Usage
world = WorldState()
world.add_component('network', NetworkState())

---

Adding New Agent Types

1. Inherit from Agent base class
2. Implement perceive() and decide() methods
3. Define agent-specific state and behavior

Example:

class EntrepreneurAgent(Agent):
    def perceive(self, world_state, perception_service):
        # Perception logic
        pass
    
    def decide(self, perception, world_state):
        # Decision logic
        return {'type': 'invest', 'amount': 1000}

---

Adding New Interactions

Add logic to apply_interactions() in world/transitions/transition.py.

Example:

def apply_interactions(world_state, agents, actions):
    # Existing logic...
    
    # New: Enterprise hiring affects employment
    for agent in agents:
        if agent.state.role == 'entrepreneur':
            # Handle hiring logic
            pass
    
    return world_state, agents

---

Adding New Metrics

Add calculation methods in metrics/calculator.py.

Example:

@staticmethod
def calculate_gini_coefficient(agents):
    # Calculate Gini coefficient
    pass

---

Database Design

Table Structure

1. simulation_runs: Simulation run records
2. world_state_snapshots: World state snapshots
3. agent_snapshots: Agent state snapshots
4. policy_changes: Policy change records
5. llm_requests: LLM request records

Storage Strategy

• Save world state snapshot each time step
• Save agent snapshot every 10 steps (to avoid excessive data)
• Record all policy changes
• Store all timestamps with timezone information

---

Performance Optimization

1. LLM Perception Optimization:
   • Use LLM for only 10% of agents every 10 steps
   • Other agents use simple perception
2. Database Optimization:
   • Periodic saves, not every step
   • Use batch inserts
3. Frontend Updates:
   • 500ms polling interval
   • Chart data limited to 500 points

---

Security Considerations

1. API Authentication: Should add authentication in production environment
2. Input Validation: All API inputs should be validated
3. Error Handling: Comprehensive error handling and logging

---

Future Extension Directions

1. More Agent Types: Enterprises, banks, government, etc.
2. Network State: Network relationships between agents
3. Technology Diffusion: Spread of technological innovation
4. Regional Differences: Multi-region simulation
5. Distributed Simulation: Support for large-scale parallel processing