Percepta

Percepta Project Structure

Directory Structure

Percepta/
├── README.md                 # Project description
├── QUICKSTART.md            # Quick start guide
├── PROJECT_STRUCTURE.md     # Project structure documentation (this file)
├── requirements.txt         # Python dependencies
├── .gitignore              # Git ignore file
├── .env.example            # Environment variables example
│
├── config/                 # Configuration files
│   └── config.yaml         # Main configuration file
│
├── core/                   # Layer 0: Simulation engine
│   ├── __init__.py
│   └── engine.py          # Simulation engine core
│
├── world/                  # World state and transitions
│   ├── __init__.py
│   ├── state/              # Layer 1: World state components
│   │   ├── __init__.py
│   │   ├── base.py        # State component base class
│   │   ├── market.py      # Market state
│   │   ├── policy.py      # Policy state
│   │   └── world.py       # World state main class
│   └── transitions/        # Layer 5: State transitions
│       ├── __init__.py
│       └── transition.py  # Unified state transition system
│
├── agents/                 # Layer 2: Agent components
│   ├── __init__.py
│   ├── base.py            # Agent base class
│   └── consumer.py        # Resident consumer agent
│
├── perception/             # Layer 3: LLM perception layer
│   ├── __init__.py
│   ├── base.py            # LLM perception base classes
│   ├── ollama_service.py  # Ollama Cloud service
│   └── simple_service.py  # Simple perception service
│
├── decision/               # Layer 4: Decision models
│   └── __init__.py
│
├── actions/               # Action definitions
│   └── __init__.py
│
├── network/               # Network and relationships
│   └── __init__.py
│
├── metrics/               # Metrics and observations
│   ├── __init__.py
│   └── calculator.py     # Metrics calculator
│
├── backend/               # Backend API
│   ├── __init__.py
│   ├── app.py            # Flask application
│   ├── database.py       # Database models and management
│   ├── simulation_manager.py  # Simulation manager
│   └── timezone_utils.py  # Timezone utilities
│
├── frontend/              # Frontend interface
│   ├── index.html        # Main page
│   ├── micro.html        # Micro observation page
│   ├── ollama_logs.html  # Ollama logs page
│   ├── db_viewer.html    # Database viewer page
│   ├── app.js           # Frontend logic
│   ├── micro.js         # Micro observation logic
│   ├── ollama_logs.js   # Ollama logs viewer
│   └── db_viewer.js     # Database viewer
│
├── scripts/               # Utility scripts
│   ├── init_db.py       # Database initialization
│   ├── migrate_timezone.py  # Timezone migration script
│   ├── test_system.py   # System test script
│   ├── view_ollama_logs.py  # View Ollama logs
│   ├── start.sh         # Startup script
│   └── run_tests.sh     # Test runner script
│
├── tests/                 # Test code
│   ├── test_agent.py    # Agent tests
│   └── test_world_state.py  # World state tests
│
├── examples/              # Example code
│   └── simple_simulation.py  # Simple simulation example
│
└── docs/                  # Documentation
    ├── API.md            # API documentation
    ├── ARCHITECTURE.md   # Architecture documentation
    ├── LLM_INTEGRATION.md  # LLM integration guide
    └── OLLAMA_SETUP.md   # Ollama setup guide

Core Module Descriptions

1. Simulation Engine (core/)

2. World State (world/)

3. Agent System (agents/)

4. LLM Perception (perception/)

5. Metrics Calculation (metrics/)

6. Backend API (backend/)

7. Frontend Interface (frontend/)

Data Flow

  1. Initialization: User sets initial conditions → Create world state and agents
  2. Continuous Evolution:
    • Each time step: Agent perception → Decision → Action
    • State transition: Global transition + Interactions + Agent state update
    • Save snapshots to database
    • Real-time frontend updates
  3. Policy Adjustment: User adjusts policy variables → Takes effect in real-time → Affects agent decisions

Extension Points

Adding New World State Components

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

Adding New Agent Types

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

Adding New Interactions

  1. Add logic to apply_interactions() in transition.py
  2. Define interaction rules

Adding New Metrics

  1. Add calculation methods in metrics/calculator.py
  2. Expose metric interfaces in API

Tech Stack